CICS Transaction Gateway Version 5.0
CICS Transaction Gateway Version 5.0
CICS Transaction Gateway Version 5.0
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
Search<br />
Translated Books<br />
Feedback<br />
<strong>CICS</strong> Web site<br />
Configuration Scenarios<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Windows Administration<br />
UNIX Administration<br />
z/OS Administration<br />
Programming Guide<br />
Programming Reference<br />
<strong>CICS</strong><br />
Java Programming Reference (HTML)<br />
Messages
Translated books<br />
The translated books are stand-alone PDF files, which are not included as part of<br />
this library file. They are available for download from the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> section of the <strong>CICS</strong> website.
Programming Reference (HTML)<br />
Unfortunately, you cannot link directly to the Programming Reference<br />
from this document; you will need to point your Web browser to:<br />
Operating System<br />
Solaris<br />
AIX<br />
HP-UX<br />
z/OS<br />
Windows<br />
Linux<br />
HTML file<br />
/opt/ctg/docs/en_US/html/javadoc/index.html<br />
/usr/lpp/ctg/docs/en_US/html/javadoc/index.html<br />
/opt/ctg/docs/en_US/html/javadoc/index.html<br />
ctg/docs/en_us/html/javadoc/index.html<br />
/docs/en_US/html/javadoc/index.html<br />
/opt/ctg/docs/en_US/html/javadoc/index.html<br />
You may find it useful to bookmark the HTML file.
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Windows Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6190-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Windows Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6190-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 295.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of the <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong>, program number 5724-D12. It will also apply to<br />
all subsequent versions, releases, and modifications until otherwise indicated in new editions.<br />
Vertical lines at the left side of the page indicate material that is new to this edition.<br />
© Copyright International Business Machines Corporation 1996, 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
|<br />
Contents<br />
About this book . . . . . . . . . . ix<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . . x<br />
Installation path . . . . . . . . . xii<br />
Programming language specific . . . . xii<br />
Operating system specific . . . . . . xii<br />
Syntax notation . . . . . . . . . . xii<br />
Summary of changes . . . . . . . . xv<br />
Chapter 1. Overview . . . . . . . . . 1<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides . . 3<br />
A <strong>Gateway</strong> daemon. . . . . . . . . 3<br />
The <strong>Gateway</strong> classes . . . . . . . . 3<br />
J2EE resource adapters . . . . . . . . 3<br />
A Client daemon . . . . . . . . . . 3<br />
The external access interfaces (ECI, EPI, ESI) 3<br />
A Terminal Servlet . . . . . . . . . 4<br />
Additional functions . . . . . . . . . 4<br />
3270 terminal emulation (<strong>CICS</strong>TERM) . . . 4<br />
3270 printer support (<strong>CICS</strong>PRNT) . . . . 5<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: local control . . 5<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: remote control 6<br />
Network security. . . . . . . . . . . 6<br />
Encryption . . . . . . . . . . . . 7<br />
Digital signatures and digital certificates . . 8<br />
Obtaining a digital certificate. . . . . . 9<br />
KeyRings and KeyStores . . . . . . . 9<br />
Authentication using SSL . . . . . . 10<br />
HTTPS . . . . . . . . . . . . . 12<br />
Security exits. . . . . . . . . . . 12<br />
Java technology . . . . . . . . . . . 12<br />
The Java language . . . . . . . . . 12<br />
Java applets . . . . . . . . . . . 13<br />
Java servlets . . . . . . . . . . . 13<br />
Java applications . . . . . . . . . 13<br />
JavaBeans . . . . . . . . . . . 14<br />
Firewalls . . . . . . . . . . . . 14<br />
Web servers . . . . . . . . . . . 15<br />
The J2EE resource adapters . . . . . . . 15<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses<br />
<strong>CICS</strong> . . . . . . . . . . . . . . 16<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading<br />
model . . . . . . . . . . . . . . 17<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request<br />
brokers. . . . . . . . . . . . . . 19<br />
Workload management . . . . . . . . 19<br />
Chapter 2. Planning your installation . . . 21<br />
Hardware requirements . . . . . . . . 22<br />
Supported software . . . . . . . . . 22<br />
Operating systems . . . . . . . . . 22<br />
Web browsers . . . . . . . . . . 22<br />
Telnet clients . . . . . . . . . . . 23<br />
JDK levels. . . . . . . . . . . . 23<br />
JSSE. . . . . . . . . . . . . . 23<br />
<strong>CICS</strong> Servers. . . . . . . . . . . 23<br />
Web servers . . . . . . . . . . . 24<br />
Application servers . . . . . . . . 24<br />
SNA communications . . . . . . . . 24<br />
TCP/IP communications . . . . . . . 24<br />
TCP62 communications . . . . . . . 24<br />
Compilers and application development<br />
tools . . . . . . . . . . . . . 25<br />
Screen readers . . . . . . . . . . 25<br />
Other tools . . . . . . . . . . . 25<br />
<strong>CICS</strong> server PTF requirements . . . . . . 25<br />
Terminal Signon capability . . . . . . 25<br />
Timeout support . . . . . . . . . 25<br />
Communication between the <strong>Gateway</strong> and<br />
<strong>CICS</strong> servers . . . . . . . . . . . . 26<br />
Restrictions on <strong>CICS</strong> for OS/400 . . . . 27<br />
Why use a particular protocol?. . . . . 28<br />
Server Code page support . . . . . . . 28<br />
Chapter 3. Installation . . . . . . . . 29<br />
Choosing what to install . . . . . . . . 29<br />
Microsoft Windows Installer Service . . . . 30<br />
Upgrading . . . . . . . . . . . . 30<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . 31<br />
Actions after installation . . . . . . . . 36<br />
Verify the system path . . . . . . . 36<br />
Creating Start Menu shortcuts . . . . . 36<br />
Maintaining or uninstalling the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> . . . . . . . . . 37<br />
Updating the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . 39<br />
Silent installation . . . . . . . . . . 39<br />
© Copyright IBM Corp. 1996, 2002 iii
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 4. Setting up communication with<br />
<strong>CICS</strong> servers . . . . . . . . . . . 41<br />
TCP/IP configuration . . . . . . . . . 41<br />
Next steps . . . . . . . . . . . 41<br />
TCP62 configuration . . . . . . . . . 42<br />
On z/OS . . . . . . . . . . . . 43<br />
On <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS . . 44<br />
On the workstation . . . . . . . . 44<br />
Firewall implications . . . . . . . . 44<br />
KeepAlive packets . . . . . . . . . 45<br />
Next steps . . . . . . . . . . . 45<br />
SNA configuration . . . . . . . . . . 45<br />
Configuring SNA . . . . . . . . . 46<br />
Named Pipes configuration . . . . . . . 50<br />
Data conversion. . . . . . . . . . . 50<br />
Chapter 5. Configuration . . . . . . . 51<br />
Before you start. . . . . . . . . . . 52<br />
Gather information. . . . . . . . . 52<br />
Log on with administrator privileges. . . 52<br />
Set the JVM . . . . . . . . . . . 52<br />
Set the time . . . . . . . . . . . 53<br />
Configure your programming environment 53<br />
Using the configuration tool . . . . . . 54<br />
Running the configuration tool on a<br />
different operating system . . . . . . 54<br />
The configuration tool interface . . . . 55<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings . . . . . . . . . . . . 58<br />
Configuring Client settings . . . . . . 71<br />
Configuring Server settings . . . . . . 76<br />
Configuring the Workload Manager . . . 84<br />
Trace settings . . . . . . . . . . 86<br />
Editing the configuration file . . . . . . 89<br />
J2EE setup and configuration . . . . . . 90<br />
Deploying <strong>CICS</strong> resource adapters . . . 90<br />
Tracing. . . . . . . . . . . . . 95<br />
Sample configuration and mapping files . . 96<br />
Keyboard mapping for <strong>CICS</strong>TERM . . . . 97<br />
Keyboard mapping file syntax . . . . . 97<br />
The keyboard mapping file . . . . . . 98<br />
Customizing the screen colors for <strong>CICS</strong>TERM 99<br />
Color mapping syntax . . . . . . . 100<br />
The color mapping file . . . . . . . 101<br />
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support . . . . . . . . . . 101<br />
Chapter 6. Network Security . . . . . 103<br />
Determining your use of SSLight or JSSE for<br />
the SSL and HTTPS protocols . . . . . . 104<br />
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
SSLight . . . . . . . . . . . . . 104<br />
Conflict with JSSE . . . . . . . . 104<br />
Maintaining your digital certificates for<br />
SSLight . . . . . . . . . . . . 104<br />
Using externally signed certificates under<br />
SSLight . . . . . . . . . . . . 105<br />
Using self-signed certificates under<br />
SSLight . . . . . . . . . . . . 110<br />
Java Secure Socket Extension (JSSE) . . . . 114<br />
Migration from SSLight . . . . . . . 114<br />
Installation . . . . . . . . . . . 114<br />
Maintaining your digital certificates for<br />
JSSE . . . . . . . . . . . . . 115<br />
Using externally signed certificates under<br />
JSSE . . . . . . . . . . . . . 115<br />
Using self-signed certificates under JSSE 120<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
SSL and HTTPS . . . . . . . . . . 124<br />
SSL and HTTPS configuration settings 124<br />
Specifying a client KeyRing or KeyStore 125<br />
Using the SSL and HTTPS protocols . . 125<br />
Network Provider Interface (NPI) . . . . 126<br />
Restrictions . . . . . . . . . . . 126<br />
Chapter 7. Client Security . . . . . . 127<br />
Overview . . . . . . . . . . . . 127<br />
Default connection settings . . . . . . 128<br />
Security popups . . . . . . . . . 128<br />
ECI security. . . . . . . . . . . . 129<br />
EPI terminal security. . . . . . . . . 129<br />
Password expiry management . . . . . 130<br />
Network Provider Interface (NPI) . . . . 130<br />
Signon capable and signon incapable<br />
terminals. . . . . . . . . . . . . 131<br />
Mainframe <strong>CICS</strong> servers . . . . . . 132<br />
TXSeries and <strong>CICS</strong> OS/2 servers. . . . 134<br />
<strong>CICS</strong>/400 servers . . . . . . . . . 134<br />
Chapter 8. Performance . . . . . . . 135<br />
Assessing system performance . . . . . 135<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration . . 136<br />
Java considerations . . . . . . . . . 138<br />
Other system factors . . . . . . . . . 138<br />
Tracing . . . . . . . . . . . . . 139<br />
Performance monitoring tools. . . . . . 140<br />
Chapter 9. Operating the <strong>Gateway</strong> . . . 141<br />
Before you start . . . . . . . . . . 141<br />
Starting the <strong>Gateway</strong>. . . . . . . . . 141<br />
Starting the <strong>Gateway</strong> with preset options 142
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Starting the <strong>Gateway</strong> with user-specified<br />
options . . . . . . . . . . . . 142<br />
Stopping the <strong>Gateway</strong> . . . . . . . . 144<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> icons . . . 144<br />
Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a<br />
Windows service . . . . . . . . . . 146<br />
Starting and stopping the service . . . 146<br />
Startup options for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> service . . . . . . . . . 146<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service and<br />
console messages . . . . . . . . . 147<br />
The ctgservice utility. . . . . . . . 147<br />
Running as a Windows service under<br />
Java 1.3.0 . . . . . . . . . . . 149<br />
Client daemon service . . . . . . . 149<br />
Administering your system . . . . . . 149<br />
Setting the <strong>Gateway</strong> trace . . . . . . 150<br />
Setting the JNI trace . . . . . . . . 150<br />
Querying trace settings . . . . . . . 150<br />
Parameters . . . . . . . . . . . 150<br />
Chapter 10. Operating the Client daemon 153<br />
The <strong>CICS</strong>CLI command . . . . . . . . 153<br />
Running the Client daemon as a Windows<br />
service . . . . . . . . . . . . . 153<br />
Service controls . . . . . . . . . 154<br />
Service startup parameters . . . . . . 155<br />
Starting and stopping the service . . . 155<br />
Starting the Client daemon service at<br />
Windows startup . . . . . . . . . 155<br />
The <strong>CICS</strong>CLI command . . . . . . . . 156<br />
Starting the Client daemon. . . . . . 156<br />
Starting connections with additional<br />
servers . . . . . . . . . . . . 157<br />
Stopping the Client daemon in a<br />
controlled manner . . . . . . . . 157<br />
Stopping the Client daemon immediately 157<br />
Restarting the Client daemon in a<br />
controlled manner . . . . . . . . 158<br />
Restarting the Client daemon<br />
immediately . . . . . . . . . . 158<br />
Starting client tracing . . . . . . . 158<br />
Specifying the trace components . . . . 158<br />
Stopping client tracing . . . . . . . 158<br />
Setting up security . . . . . . . . 158<br />
<strong>Version</strong> information . . . . . . . . 159<br />
Listing the connected servers . . . . . 159<br />
Disabling the display of messages . . . 159<br />
Enabling and disabling the display of<br />
pop-up messages . . . . . . . . . 159<br />
Displaying the command parameters . . 160<br />
The <strong>CICS</strong>CLI command and applications 160<br />
Alternative to <strong>CICS</strong>CLI.EXE . . . . . 160<br />
<strong>CICS</strong>CLI command reference . . . . . . 160<br />
Chapter 11. Terminal Emulation . . . . 167<br />
Summary of Terminal Emulation commands 167<br />
The <strong>CICS</strong>TERM command . . . . . . . 167<br />
Using <strong>CICS</strong>TERM. . . . . . . . . 168<br />
Stopping a terminal emulator . . . . . 169<br />
<strong>CICS</strong>TERM and user exits . . . . . . 169<br />
<strong>CICS</strong>TERM and RETURN TRANSID<br />
IMMEDIATE . . . . . . . . . . 169<br />
<strong>CICS</strong>TERM command reference . . . . . 169<br />
Terminal emulator preferences . . . . . 172<br />
The <strong>CICS</strong>PRNT command . . . . . . . 173<br />
Using <strong>CICS</strong>PRNT . . . . . . . . . 174<br />
<strong>CICS</strong>PRNT and user exits . . . . . . 175<br />
<strong>CICS</strong>PRNT and RETURN TRANSID<br />
IMMEDIATE . . . . . . . . . . 175<br />
<strong>CICS</strong>PRNT command reference . . . . . 175<br />
Chapter 12. Workload Manager . . . . 179<br />
Workload Manager overview . . . . . . 179<br />
Key concepts . . . . . . . . . . 180<br />
What the Workload Manager needs to know 181<br />
Load balancing algorithms . . . . . . . 183<br />
The round-robin algorithm. . . . . . 183<br />
The biasing algorithm . . . . . . . 183<br />
Workload Manager failure recovery . . . . 184<br />
Workload Manager implementation . . . . 184<br />
ECI implementation . . . . . . . . 184<br />
EPI implementation . . . . . . . . 185<br />
Workload Manager installation . . . . . 185<br />
Tracing the Workload Manager . . . . . 186<br />
Workload Manager programming<br />
requirements . . . . . . . . . . . 186<br />
Chapter 13. The Terminal Servlet program 187<br />
What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Terminal Servlet? . . . . . . . . . . 187<br />
Installing and configuring the Terminal<br />
Servlet . . . . . . . . . . . . . 189<br />
Configuring the Web server’s<br />
CLASSPATH and PATH settings . . . . 190<br />
Adding the Terminal Servlet to the Web<br />
server’s configuration . . . . . . . 190<br />
Configuring the servlet initialization<br />
parameters . . . . . . . . . . . 190<br />
Considering other configuration options 194<br />
Contents v
|<br />
Loading the Terminal Servlet . . . . . 195<br />
Using the Terminal Servlet. . . . . . . 195<br />
Connecting to <strong>CICS</strong> and starting a<br />
transaction . . . . . . . . . . . 195<br />
Invoking the Terminal Servlet . . . . . 195<br />
What happens next? . . . . . . . . 197<br />
Displaying screens and fields . . . . . 197<br />
Sending the screen back to <strong>CICS</strong>. . . . 199<br />
Setting the AID . . . . . . . . . 199<br />
Disconnecting . . . . . . . . . . 200<br />
Properties and parameters reference . . . 200<br />
Servlet configuration properties . . . . 201<br />
Page mapping properties . . . . . . 203<br />
Request parameters . . . . . . . . 204<br />
Displayable properties . . . . . . . 205<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web<br />
Interface . . . . . . . . . . . . . 206<br />
Chapter 14. Problem determination and<br />
problem solving. . . . . . . . . . 207<br />
Preliminary checks . . . . . . . . . 207<br />
What to do next . . . . . . . . . 208<br />
Problems with the <strong>Gateway</strong> daemon . . . 208<br />
Messages . . . . . . . . . . . 208<br />
Tracing . . . . . . . . . . . . 209<br />
Diagnosing common problems: <strong>Gateway</strong><br />
daemon . . . . . . . . . . . . 212<br />
Problems with the Client daemon . . . . 218<br />
Messages . . . . . . . . . . . 218<br />
Tracing . . . . . . . . . . . . 219<br />
Diagnosing common problems: Client<br />
daemon . . . . . . . . . . . . 227<br />
Program support . . . . . . . . . . 236<br />
Reporting problems . . . . . . . . 236<br />
Documenting problems . . . . . . . 237<br />
Locating and compiling information . . 238<br />
Submitting the documentation . . . . 239<br />
APARs and fixes . . . . . . . . . 239<br />
Chapter 15. Migration . . . . . . . . 241<br />
The configuration conversion tool . . . . 241<br />
Using the conversion tool . . . . . . 242<br />
Migrating from <strong>CICS</strong> Client <strong>Version</strong> 2 . . . 243<br />
Migrating from <strong>CICS</strong> Universal Client, or<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, <strong>Version</strong> 3 . . . 243<br />
TCP62 multiple server definitions . . . 243<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java . . 244<br />
Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong> 245<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> default settings 245<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> override settings 246<br />
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> actions 247<br />
Administration functions . . . . . . 248<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Lotus<br />
Notes . . . . . . . . . . . . . 248<br />
EPI beans provided in earlier versions of the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . . . . . . 248<br />
Appendix A. Data conversion between the<br />
Client daemon and a <strong>CICS</strong> server . . . 251<br />
Data conversion on Windows . . . . . . 251<br />
Supported conversions . . . . . . . . 252<br />
Appendix B. Hardware and software. . . 257<br />
Hardware requirements. . . . . . . . 257<br />
Supported software . . . . . . . . . 258<br />
Operating systems . . . . . . . . 258<br />
Web browsers . . . . . . . . . . 259<br />
Telnet clients . . . . . . . . . . 260<br />
JDK levels . . . . . . . . . . . 260<br />
JSSE . . . . . . . . . . . . . 260<br />
<strong>CICS</strong> Servers . . . . . . . . . . 261<br />
Web servers. . . . . . . . . . . 261<br />
Application servers . . . . . . . . 261<br />
SNA communications . . . . . . . 261<br />
TCP/IP communications . . . . . . 262<br />
TCP62 communications . . . . . . . 262<br />
Compilers and application development<br />
tools . . . . . . . . . . . . . 262<br />
Screen readers . . . . . . . . . . 263<br />
Other tools . . . . . . . . . . . 263<br />
GPL licence and copyright issues on<br />
Linux . . . . . . . . . . . . . 263<br />
The product library and related literature 265<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 265<br />
Sample configuration documents. . . . . 266<br />
Redbooks . . . . . . . . . . . . 267<br />
Other Useful Books . . . . . . . . . 267<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 267<br />
Microsoft ® Windows Family publications 268<br />
APPC-related publications . . . . . . 268<br />
TCP62–related publications . . . . . 269<br />
Obtaining books from IBM. . . . . . . 269<br />
Accessibility . . . . . . . . . . . 271<br />
Documentation . . . . . . . . . . 271<br />
Installation . . . . . . . . . . . . 271<br />
iKeyMan. . . . . . . . . . . . . 271<br />
Samples . . . . . . . . . . . . . 271<br />
Configuration tool accessibility . . . . . 271
|<br />
|<br />
|<br />
|<br />
|<br />
Components . . . . . . . . . . 271<br />
Keys . . . . . . . . . . . . . 272<br />
Customizing colors and fonts . . . . . 274<br />
Using help . . . . . . . . . . . 274<br />
Task Guide . . . . . . . . . . . 274<br />
Glossary . . . . . . . . . . . . 275<br />
Index . . . . . . . . . . . . . 287<br />
Notices . . . . . . . . . . . . . 295<br />
Trademarks . . . . . . . . . . . . 296<br />
Sending your comments to IBM . . . . 299<br />
Contents vii
viii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
About this book<br />
This book describes the planning, installation, configuration, and operation, of<br />
the IBM ® <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> product.<br />
You should be familiar with the operating system on which your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> runs, and also with Internet terminology.<br />
Summary of changes Read this for information on functional changes made in this<br />
version of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Chapter 1, “Overview” Read this for an overview of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and<br />
the functions it provides.<br />
Chapter 2, “Planning<br />
your installation”<br />
Chapter 3,<br />
“Installation”<br />
Chapter 4, “Setting up<br />
communication with<br />
<strong>CICS</strong> servers”<br />
Chapter 5,<br />
“Configuration”<br />
Chapter 6, “Network<br />
Security”<br />
Chapter 7, “Client<br />
Security”<br />
Chapter 8,<br />
“Performance”<br />
Chapter 9, “Operating<br />
the <strong>Gateway</strong>”<br />
Chapter 10,<br />
“Operating the Client<br />
daemon”<br />
Chapter 12, “Workload<br />
Manager”<br />
Read this for information on planning your installation,<br />
including the hardware and software you need to run <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to install <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Read this for information on how to set up communication<br />
links between <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers.<br />
Read this for information on how to configure your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to set up <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> to use the network security protocols SSL and<br />
HTTPS.<br />
Read this for information on how to provide a userid and<br />
password when connecting to a <strong>CICS</strong> server.<br />
Read this for information on how to tune your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, and other system components, to<br />
achieve the best possible performance.<br />
Read this for information on how to operate the <strong>Gateway</strong><br />
daemon.<br />
Read this for information on how to operate the Client<br />
daemon of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to use the Workload<br />
Manager part of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to distribute<br />
server workload.<br />
© Copyright IBM Corp. 1996, 2002 ix
Chapter 13, “The<br />
Terminal Servlet<br />
program”<br />
Chapter 14, “Problem<br />
determination and<br />
problem solving”<br />
Chapter 15,<br />
“Migration”<br />
Appendix A, “Data<br />
conversion between<br />
the Client daemon<br />
and a <strong>CICS</strong> server”<br />
The product library<br />
and related literature<br />
Read this for information on how to use the Terminal Servlet<br />
to access <strong>CICS</strong> 3270 applications using a Web browser.<br />
Read this for information on problem determination and<br />
problem solving.<br />
Read this if you are currently using an earlier version of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or <strong>CICS</strong> Universal Client.<br />
Read this for information on the conversion of character data<br />
as it passes between the Client daemon of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> and a <strong>CICS</strong> server.<br />
Read this for information on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
product library and related literature, and the various forms<br />
in which it is available.<br />
Accessibility Read this for information on the accessibility features of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Notices Read this for important information on the availability of<br />
IBM products and service in different countries, and also on<br />
issues concerning patents, licenses, and trademarks.<br />
Sending your<br />
comments to IBM<br />
Read this for information on how to send your comments to<br />
IBM.<br />
Conventions and terminology used in this book<br />
A number of parts, both internal and external to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, are used when creating a business solution using the product.<br />
Figure 1 on page xi shows some of the possible scenarios you will encounter,<br />
and the terminology used in each case.<br />
x <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Distributed platforms running in remote mode<br />
Java client<br />
application<br />
z/OS running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Distributed platforms running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
Client<br />
daemon<br />
Distributed platforms running non-Java applications<br />
Client<br />
application<br />
Client<br />
daemon<br />
z/OS running in remote mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Client<br />
daemon<br />
<strong>CICS</strong><br />
server<br />
<strong>CICS</strong><br />
server<br />
Figure 1. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses, with their associated terminology<br />
<strong>CICS</strong><br />
server<br />
The following explains the terms used in Figure 1:<br />
<strong>Gateway</strong> daemon<br />
Used only in remote mode, the <strong>Gateway</strong> daemon listens on protocols<br />
defined in CTG.INI for gateway requests from remote Java client<br />
applications. It issues these requests to the Client daemon on<br />
distributed platforms, and directly to <strong>CICS</strong> over the EXCI on z/OS ® .<br />
The <strong>Gateway</strong> daemon runs the protocol listener threads, the worker<br />
threads and the connection manager threads. It uses the GATEWAY<br />
section of CTG.INI (and on z/OS the ctgenvvar script) for its<br />
configuration.<br />
Client daemon<br />
The Client daemon (process cclclnt) exists only on distributed<br />
platforms. It manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending and receiving the<br />
appropriate flows from the <strong>CICS</strong> server to satisfy the application<br />
requests. It uses the CLIENT section of CTG.INI for its configuration.<br />
About this book xi
<strong>Gateway</strong> classes<br />
The interface for Java Client applications to connect to the <strong>Gateway</strong><br />
daemon. The <strong>Gateway</strong> classes, which are supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, must be in the classpath for Java Client<br />
applications to run.<br />
Client application<br />
A user application, written in a supported programming language<br />
other than Java, that communicates directly with the Client daemon.<br />
Java Client application<br />
A Java application, servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Installation path<br />
The term is used in file paths to represent the directory where<br />
you installed the product. The default installation locations for each operating<br />
system are shown in Table 1:<br />
Table 1. Default <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> installation locations<br />
Operating System Default installation location<br />
Windows ®<br />
c:\Program Files\IBM\IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
AIX ®<br />
/usr/lpp/ctg<br />
Linux, HP-UX, Solaris /opt/ctg<br />
z/OS A ctg subdirectory of the directory from which the<br />
installation was run. For example, if the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> was installed by the command<br />
ctginstall in the /usr/lpp directory, the<br />
is /usr/lpp/ctg<br />
Programming language specific<br />
The term C refers to both the C and C++ programming languages.<br />
Operating system specific<br />
Unless otherwise specified, the term Windows refers to Windows NT ® ,<br />
Windows 2000, and Windows XP.<br />
The term Windows 2000 Terminal Server means a server with the Terminal<br />
Services feature installed.<br />
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.<br />
Syntax notation<br />
The syntax of commands is shown in a standard way. This syntax, commonly<br />
known as railroad syntax, is described in Table 2 on page xiii. You interpret the<br />
syntax by following the arrows from left to right, and from top to bottom,<br />
xii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
along the main path line.<br />
Table 2. Command syntax conventions<br />
Symbol Meaning<br />
Required items appear on the main path line.<br />
►► AB ►◄<br />
►► A<br />
B<br />
C<br />
►►<br />
►►<br />
►►<br />
A B<br />
A<br />
B<br />
C<br />
A<br />
B<br />
C<br />
►► ▼ A<br />
►► ▼<br />
A<br />
B<br />
C<br />
B<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
Punctuation and uppercase<br />
characters<br />
Lowercase characters appearing<br />
like this<br />
If there is more than one required item to choose<br />
from, the items are stacked vertically. This is a set of<br />
alternatives—one of which you must specify.<br />
Optional items appear below the main path line.<br />
If there is more than one optional item to choose<br />
from, the items are stacked vertically below the<br />
main path line. This is a set of alternatives—one of<br />
which you may specify.<br />
If one item in a set of alternatives is the default, this<br />
item appears above the main path line and all other<br />
items are stacked vertically below the line.<br />
An arrow returning to the left above items on the<br />
main path line means that the items can be repeated.<br />
Such items may be either required or optional.<br />
An arrow returning to the left above a set of items<br />
means that more than one item can be selected or<br />
that a single item can be repeated.<br />
Note: For <strong>CICS</strong>, unless otherwise stated, this<br />
representation means only that more than one item<br />
can be selected.<br />
Code exactly as shown.<br />
Code your own text, as appropriate. For example,<br />
with FILE(name) you must specify FILE and ()<br />
unchanged, but are free to specify any valid text<br />
string for the name of your file.<br />
About this book xiii
xiv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Summary of changes<br />
The following functional changes have been made for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>:<br />
v The Windows XP operating system is supported.<br />
v The Binary Trace Formatter utility has been enhanced to format SNA and<br />
MPTN data structures within TCP62 data flows. See “Formatting the binary<br />
trace file” on page 222.<br />
v COBOL is supported.<br />
v A systems administration function allows you to set options for <strong>Gateway</strong><br />
and JNI traces, to start and stop these traces, and to query trace settings;<br />
see “Administering your system” on page 149. Using the CTG_JNI_TRACE<br />
environment variable to enable JNI tracing is supported only for migration<br />
purposes.<br />
v The way that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes log messages has changed:<br />
– Each message entry begins with the current date in the format<br />
month/day/year.<br />
– <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes error and warning messages to<br />
standard error (stderr), and information messages to standard output<br />
(stdout); see “Messages” on page 208.<br />
– A new gateway configuration setting, Log client connections and<br />
disconnections, controls whether <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes a<br />
message each time that a client application program connects to, or<br />
disconnects from, the <strong>Gateway</strong> daemon. See “Log client connections and<br />
disconnections” on page 61.<br />
v Some beans that were previously provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product are now, instead, included with the set of sample<br />
programs. See “EPI beans provided in earlier versions of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>” on page 248 for details.<br />
v Java Secure Socket Extension (JSSE) is supported.<br />
This gives 128 bit encryption capability and is IBM’s recommended solution<br />
for SSL. For compatibility with previous versions of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, this version supports both JSSE and SSLight. However, support<br />
for SSLight might be removed in a future release.<br />
This edition replaces SC34-5932.<br />
Vertical lines at the left side of the page indicate material that is new to this<br />
edition.<br />
© Copyright IBM Corp. 1996, 2002 xv
xvi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 1. Overview<br />
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides secure, easy access from Web<br />
browsers and network computers to <strong>CICS</strong> applications, using standard<br />
Internet protocols in a range of configurations. It is a robust and scalable<br />
complement to a Web server. You can implement it as an e-business connector<br />
for IBM WebSphere ® Application Server, which is a J2EE-compliant runtime<br />
environment for Java servlets. An API is provided that allows Java<br />
programmers to take advantage of features provided in J2EE-compliant<br />
runtime environments.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs on a wide variety of operating systems. On<br />
the Windows and UNIX ® operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
access many different types of <strong>CICS</strong> server. On z/OS <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> can access only <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS. See “Supported<br />
software” on page 22 for information on supported operating systems and<br />
<strong>CICS</strong> servers.<br />
On the Windows and UNIX operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
uses a Client daemon to route External Call Interface (ECI), External Presentation<br />
Interface (EPI), and External Security Interface (ESI) requests to a <strong>CICS</strong> server<br />
(see “The external access interfaces (ECI, EPI, ESI)” on page 3). On z/OS, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can route only ECI requests, and has no Client daemon.<br />
© Copyright IBM Corp. 1996, 2002 1
Overview<br />
Network<br />
computer<br />
Java-enabled<br />
browser<br />
Figure 2 shows how a web client can access <strong>CICS</strong> programs and data. Note<br />
that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is shown as installed on a Web server<br />
machine. This is necessary only if you are using the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> with Java applets or servlets.<br />
HTTP<br />
HTTPS<br />
SSL<br />
TCP<br />
HTTP<br />
Figure 2. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Server machine<br />
Web server<br />
<strong>CICS</strong><br />
<strong>Transaction</strong><br />
<strong>Gateway</strong><br />
Java application<br />
<strong>CICS</strong><br />
server<br />
Communication between <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the client application<br />
uses the following protocols:<br />
v Transmission control protocol/Internet protocol (TCP/IP) sockets<br />
v Hypertext Transfer Protocol (HTTP)<br />
v Secure Sockets Layer (SSL)<br />
v HTTP over SSL (HTTPS)<br />
TCP/IP sockets and SSL provide an efficient method of communication for<br />
intranet applications. Where firewalls exist, HTTP, and its secure alternative<br />
HTTPS, are effective communication protocols for internet applications. See<br />
“Network security” on page 6.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can manage many concurrent links to connected<br />
Web browsers. It can also control asynchronous conversations to multiple<br />
<strong>CICS</strong> servers. The multithreaded architecture of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
enables a single gateway to support multiple concurrently connected users.<br />
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
Local<br />
EPI<br />
ESI<br />
ECI
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
A <strong>Gateway</strong> daemon<br />
For security reasons, this is usually resident on a Web server workstation. It<br />
communicates with <strong>CICS</strong> applications running on <strong>CICS</strong> servers through ECI,<br />
EPI, or ESI.<br />
The <strong>Gateway</strong> classes<br />
This Java library includes classes that:<br />
v provide Application Programming Interfaces (APIs) for ECI, EPI, and ESI<br />
This allows communication between Java applications, or Java servlets, and<br />
the <strong>Gateway</strong> daemon.<br />
v allow client applications to communicate with transactions on a server and<br />
to handle 3270 data streams<br />
v allow your applications to use the SSL network security protocol<br />
J2EE resource adapters<br />
Use these to provide a J2EE-compliant interface to <strong>CICS</strong> for your applications.<br />
A Client daemon<br />
The Client daemon can support concurrent, ECI and EPI, calls to one or more<br />
<strong>CICS</strong> servers.<br />
The Client daemon can communicate with multiple <strong>CICS</strong> servers using a<br />
variety of protocols. See “Communication between the <strong>Gateway</strong> and <strong>CICS</strong><br />
servers” on page 26. Support for a protocol may be provided by one or more<br />
communication software products, so you can use the products best suited to<br />
your network environment. See “Supported software” on page 22.<br />
The way the client operates, and the servers and protocols used for<br />
communication, are defined in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization<br />
file. You can use the configuration tool to define these settings. See Chapter 5,<br />
“Configuration” on page 51.<br />
The external access interfaces (ECI, EPI, ESI)<br />
The external access interfaces allow non-<strong>CICS</strong> applications to access and<br />
update <strong>CICS</strong> resources by initiating <strong>CICS</strong> transactions, or by calling <strong>CICS</strong><br />
programs. When used in conjunction with the <strong>CICS</strong> communication facilities,<br />
they enable non-<strong>CICS</strong> programs to access and update resources on any <strong>CICS</strong><br />
system. This supports such activities as developing graphical user interface<br />
(GUI) front ends for <strong>CICS</strong> applications, and allows the integration of <strong>CICS</strong><br />
systems and non-<strong>CICS</strong> systems.<br />
These APIs are provided for both Java and non-Java programming languages.<br />
Chapter 1. Overview 3
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
External Call Interface (ECI)<br />
The ECI enables a non-<strong>CICS</strong> client application to call a <strong>CICS</strong> program<br />
synchronously, or asynchronously. It enables the design of new applications to<br />
be optimized for client/server operation, with the business logic on the server<br />
and the presentation logic on the client.<br />
External Presentation Interface (EPI)<br />
The EPI enables a non-<strong>CICS</strong> client application to act as a logical 3270 terminal<br />
and so control a <strong>CICS</strong> 3270 application. It enables modern technologies, such<br />
as graphical or multimedia interfaces, to be used with traditional <strong>CICS</strong> 3270<br />
applications.<br />
External Security Interface (ESI)<br />
ESI enables non-<strong>CICS</strong> client applications to invoke services provided by APPC<br />
password expiry management (PEM). This allows non-<strong>CICS</strong> applications to verify<br />
that a password matches that recorded by an external security manager (ESM)<br />
for a specified user ID. ESI also allows you to change passwords.<br />
For more information on the external access interfaces, see <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Reference.<br />
A Terminal Servlet<br />
This allows you to use a Web browser as an emulator for a 3270 <strong>CICS</strong><br />
application running on any <strong>CICS</strong> server. The Terminal Servlet can be used<br />
with a Web server, or servlet engine. The Terminal Servlet provides an<br />
alternative to using EPI. For information on supported Web servers, refer to<br />
“Supported software” on page 22.<br />
Additional functions<br />
3270 terminal emulation (<strong>CICS</strong>TERM)<br />
<strong>CICS</strong> 3270 terminal emulation enables a <strong>Gateway</strong> system to function as a 3270<br />
display for <strong>CICS</strong> applications, without needing a separate 3270 emulator<br />
product. Multiple <strong>CICS</strong> 3270 emulation sessions can run to one or more <strong>CICS</strong><br />
servers.<br />
You can use mapping files to customize the client emulator’s screen color<br />
attributes and keyboard settings, for example, to comply with company<br />
standard keyboard layouts.<br />
<strong>CICS</strong> Client terminal definitions (with some exceptions, see Table 5 on<br />
page 27) are autoinstalled at most <strong>CICS</strong> server systems, and do not have to be<br />
predefined at the server.<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Additional functions<br />
3270 printer support (<strong>CICS</strong>PRNT)<br />
<strong>CICS</strong> 3270 printer support allows you to define a printer terminal on a<br />
<strong>Gateway</strong> system. This enables <strong>CICS</strong> applications running on a server to send<br />
output to a printer attached to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You can send output to a physical printer attached, for example, to the LPT1<br />
port, or you can specify a command to process the data into a format more<br />
suitable for special-purpose printers.<br />
<strong>CICS</strong> 3270 printer support uses <strong>CICS</strong> 3270 terminal emulation functions. See<br />
Table 5 on page 27 for information on which <strong>CICS</strong> servers currently support<br />
<strong>CICS</strong> 3270 emulation and hence <strong>CICS</strong> 3270 client printer support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: local control<br />
Commands or icons are provided to:<br />
v Control the <strong>Gateway</strong> daemon<br />
You can:<br />
– Specify the TCP/IP port on which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> listens.<br />
– Specify an initial number of ConnectionManager threads<br />
– Specify a maximum number of ConnectionManager threads<br />
– Specify an initial number of Worker threads<br />
– Specify a maximum number of Worker threads<br />
– Enable standard tracing<br />
– Disable the reading of input from the console<br />
– Specify the file to which trace output is written<br />
– Enable full debug tracing<br />
– Specify the maximum size of the trace output file<br />
– Specify the maximum size of any data blocks that are shown in the trace<br />
– Enable the display of symbolic TCP/IP hostnames in messages<br />
– Specify the offset from which displays of any data blocks start<br />
– Enable Java exception stack tracing<br />
– Pass an argument to the JVM<br />
v Control the Client daemon<br />
You can:<br />
– Start or stop the client daemon<br />
– Turn client trace on or off<br />
– Specify the client components to be traced<br />
– Set up security by specifying user IDs and passwords for a <strong>CICS</strong> server<br />
– List connected servers<br />
– Enable and disable the display of messages<br />
– Perform controlled restarts of the client daemon<br />
v Control terminal emulation<br />
You can:<br />
– Start and stop the terminal emulator<br />
Chapter 1. Overview 5
|<br />
|<br />
|<br />
|<br />
|<br />
Additional functions<br />
– Specify the initial transaction<br />
– Define the terminal characteristics<br />
– Specify the name of the keyboard and screen color mapping files<br />
– Define the command used to process print requests<br />
– Specify the name of a file used for appending print requests<br />
v Control client printer operation<br />
You can:<br />
– Start and stop the client printer emulator<br />
– Specify the initial transaction to be run against the client printer<br />
– Define the printer terminal characteristics<br />
– Define the command used to process print requests<br />
– Specify the name of a file used for appending print requests.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: remote control<br />
You can:<br />
v Set the trace for the <strong>Gateway</strong> daemon<br />
v Set JNI trace<br />
v Query trace options<br />
Network security<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides comprehensive support for secure<br />
communication, which is critical to successful Internet operation. The secure<br />
network protocols SSL and HTTPS allow your client applications to<br />
communicate securely with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Network security<br />
and its implementation on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is discussed in detail in<br />
Chapter 6, “Network Security” on page 103; the following sections summarize<br />
the functions provided by SSL and HTTPS.<br />
The characteristics of secure communication are:<br />
Confidentiality<br />
The content of messages remains private as they pass over the<br />
Internet, or your intranet.<br />
Data exchanged between the client and the server is encrypted. Only<br />
your client (your application or servlet) and your server (the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>) can make sense of the data.<br />
Integrity<br />
Messages are not altered during transmission.<br />
Integrity guarantees that the message you sent reaches the recipient<br />
intact. Encryption and digital signatures ensure integrity.<br />
Accountability<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Network security<br />
The sender and the receiver both agree that the exchange took place.<br />
Accountability settles any disputes over whether the message was<br />
sent and received. Digital signatures ensure accountability, so that you<br />
can identify who is responsible if something goes wrong.<br />
Authenticity<br />
You know who you are talking to and you can trust that person.<br />
Authenticity requires verification of identities, so that you can be sure<br />
that others are who they say they are. Digital signatures and digital<br />
certificates ensure authenticity.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s implementation of the SSL protocol<br />
provides server authentication. This means that when a client<br />
establishes a connection with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, it must<br />
authenticate the server’s details. You can also enable client<br />
authentication. This means that the server will authenticate the client’s<br />
details.<br />
Encryption<br />
Encryption ensures confidentiality in transmissions sent over the Internet. In<br />
its simplest form, encryption is the scrambling of a message so that it cannot<br />
be read until it is unscrambled later by the receiver. The sender uses an<br />
algorithmic pattern, or key, to encrypt the message, and the receiver uses a<br />
decryption key to unscramble the message.<br />
Two kinds of key can be used for encryption:<br />
1. Symmetric keys<br />
The sender and receiver use the same key to encrypt and decrypt the<br />
message. The risk with symmetric keys is that you need a safe<br />
transportation method to use when sending your key to the people with<br />
whom you want to communicate.<br />
2. Asymmetric keys<br />
These consists of a pair of keys: a public key and a private key. Unlike<br />
symmetric keys, these are different from each other. The private key holds<br />
more of the secret encryption pattern than the public key.<br />
A sender sends its public key to anyone it wants to communicate with<br />
securely. It retains the private key and protects it with a password. Only<br />
the sender can decrypt a received message encrypted with its public key,<br />
because only it has the private key.<br />
Asymmetric key encryption is also known as public key encryption.<br />
SSL uses both asymmetric and symmetric key encryption. It uses public key<br />
(asymmetric) encryption as a safe way of sharing a symmetric key between<br />
server and client. This symmetric key is then used to encrypt and decrypt all<br />
Chapter 1. Overview 7
Network security<br />
data transferred on the SSL connection. This encryption protects the data from<br />
other parties that try to eavesdrop and ensures that private information, such<br />
as credit card numbers, can be transferred securely. See “Authentication using<br />
SSL” on page 10.<br />
Digital signatures and digital certificates<br />
A digital signature is a unique, mathematically computed, signature that<br />
ensures accountability.<br />
A digital certificate allows unique identification of an entity; it is essentially an<br />
electronic ID card, issued by a trusted third party. Digital certificates form part<br />
of the ISO authentication framework, also known as the X.509 protocol. This<br />
framework provides for authentication across networks.<br />
A digital certificate serves two purposes: it establishes the owner’s identity,<br />
and it makes the owner’s public key available. A digital certificate is issued by<br />
a certification authority (CA), for example VeriSign, or Thawte. It is issued for<br />
only a limited time, and when its expiry date has passed, it must be replaced.<br />
A digital certificate consists of:<br />
v The public key of the person being certified<br />
v The name and address of the person being certified, also known as the<br />
Distinguished Name (DN)<br />
v The digital signature of the CA<br />
v The issue date<br />
v The expiry date<br />
The Distinguished Name is the name and address of a person or organization.<br />
You enter your Distinguished Name as part of requesting a certificate. The<br />
digitally-signed certificate includes not only your own Distinguished Name,<br />
but the Distinguished Name of the CA, which allows verification of the CA.<br />
To communicate securely, the receiver in a transmission must trust the CA<br />
that issued the certificate that the sender is using. This means that, when a<br />
sender signs a message, the receiver must have the corresponding CA’s signer<br />
certificate and public key designated as a trusted root key. For example, your<br />
Web browser has a default list of signer certificates for trusted CAs. If you<br />
want to trust certificates from another CA, you must receive a certificate from<br />
that CA and designate it as a trusted root key.<br />
If you send your digital certificate containing your public key to someone<br />
else, what keeps that person from misusing your digital certificate and posing<br />
as you? The answer is: your private key.<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
Network security<br />
A digital certificate alone is not proof of anyone’s identity. The digital<br />
certificate allows verification only of the owner’s identity, by providing the<br />
public key needed to check the owner’s digital signature. Therefore, the digital<br />
certificate owner must protect the private key that belongs with the public key<br />
in the digital certificate. If the private key were stolen, anyone could pose as<br />
the legitimate owner of the digital certificate.<br />
Obtaining a digital certificate<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows you to obtain digital certificates in two<br />
ways. You can buy externally-signed certificates from a CA, or you can<br />
establish yourself as a CA to allow you to issue self-signed X.509 certificates.<br />
Externally-signed certificates are more suitable for Internet use, while<br />
self-signed certificates might be suitable for internal use within an<br />
organization.<br />
Buying a certificate from a certification authority<br />
If you plan to conduct commercial business on the Internet, buy a server<br />
certificate from a CA such as VeriSign or Thawte.<br />
When you submit a certificate request to a CA, they require you to prove who<br />
you are before they issue you a certificate. The approval process is necessary<br />
to protect you, your organization, and the CA. The CA will digitally sign your<br />
certificate request and return the unique certificate to you by e-mail.<br />
Issuing certificates yourself<br />
If you act as a CA, you can sign your own or anyone else’s certificate request.<br />
This is a good choice if you need the certificates only within your own<br />
organization, and not for external Internet commerce. You may choose to<br />
allow access to only a carefully controlled group of key people within your<br />
intranet.<br />
Your key people should have browsers, such as Netscape Navigator, that can<br />
receive your self-signed CA certificate and designate it as a trusted root. They<br />
can then trust your communications and share information safely.<br />
See Chapter 6, “Network Security” on page 103 for more information on<br />
obtaining digital certificates.<br />
KeyRings and KeyStores<br />
Digital certificates, public keys, private keys, and trusted root keys are kept in<br />
special types of file which the security protocols can use:<br />
v SSLight, System SSL, and HTTPS use Java class files called KeyRings<br />
v Java Secure Socket Extension (JSSE) uses files called KeyStores<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses KeyRings and KeyStores to hold information<br />
about certificates and keys on both the SSL server and SSL clients. See<br />
Chapter 1. Overview 9
Network security<br />
“SSLight” on page 104, and “Java Secure Socket Extension (JSSE)” on page 114,<br />
for information on how to create these files. The SSL and HTTPS protocols<br />
require access to these files to establish secure connections. See “Configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS” on page 124 for information<br />
on how to provide this access.<br />
Authentication using SSL<br />
SSL allows the client to authenticate the identity of the server. This is called<br />
server authentication.<br />
SSL <strong>Version</strong> 3 also allows the server to authenticate a client. This is called<br />
client authentication, and is used if the server needs to check who a client is<br />
before responding. If SSL client authentication is enabled, the server requests<br />
the client’s certificate whenever the client makes an SSL connection. The<br />
server validates the DN information in the client request against the DN<br />
information in the client’s certificate before serving the document.<br />
SSL uses public key (asymmetric) encryption for a security “handshake” when<br />
establishing a TCP/IP connection between the client and the server. Figure 3<br />
on page 11 illustrates SSL handshaking with server authentication. During the<br />
handshake, the client receives the server’s digital (X.509) certificate. The client<br />
authenticates the server, using a list of known CAs. Also, if the client requests<br />
a document protected by SSL client authentication, the server requests the<br />
client’s certificate. The client then generates a random symmetric key and<br />
encrypts it using server’s public key. SSL then uses the symmetric key to<br />
encrypt and decrypt all of the information in both the client request and the<br />
server response, including:<br />
v The URL the client is requesting<br />
v The contents of any form being submitted<br />
v Authentication information, such as user names and passwords<br />
v All data sent between the client and the server<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Client Server<br />
Client issues secure session request<br />
(https.//someserver.org/somedata.html)<br />
Server sends X.509 certificate containing server’s public key<br />
Client authenticates certificate against list of known CA’s<br />
(If CA is unknown browser can give user option to accept certificate at user’s risk)<br />
Client generates random symmetric key and encrypts it using server’s public key<br />
Client and server now both know the symmetric key<br />
and encrypt end-user data using symmetric key for duration of session<br />
Figure 3. SSL handshaking with server authentication<br />
Network security<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports the following implementations of SSL:<br />
SSLight<br />
An implementation of SSL that is written in pure Java.<br />
This protocol is supported for compatibility with previous<br />
versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for<br />
SSLight might be removed in a future release.<br />
JSSE<br />
Another Java implementation, that provides support for 128<br />
bit encryption.<br />
IBM recommends that you use JSSE in preference to SSLight.<br />
See “Migration from SSLight” on page 114, for more<br />
information.<br />
System SSL<br />
Chapter 1. Overview 11
Network security<br />
This implementation, which is written in native code, is<br />
supported only for SSL servers on z/OS. It supports hardware<br />
encryption technology available to the z/OS operating system.<br />
HTTPS<br />
HTTPS is a protocol that combines SSL and HTTP, and is used for handling<br />
secure transactions. You specify https:// as an anchor in HTML documents<br />
that link to documents protected by SSL. A client user can also open a URL by<br />
specifying https:// to request an SSL-protected document.<br />
Because HTTPS and HTTP are different protocols, and usually use different<br />
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests<br />
at the same time. This allows you to provide information to all users using no<br />
security, and specific information only to browsers which make secure<br />
requests. This is how retail companies on the Internet allow users to look<br />
through the merchandise without security, but then fill out order forms and<br />
send their credit card numbers using security.<br />
Security exits<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides exits that enable the user to define<br />
security operations such as public key encryption. They may also be used for<br />
data compression. Some example source files are provided in this directory:<br />
\samples\java\com\ibm\ctg\samples\security<br />
Java technology<br />
You can also use the security exits to authenticate an X.509 client certificate<br />
when client authentication is enabled.<br />
For more information, refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide book.<br />
This section discusses the Java language, including the types of program that<br />
can be developed, and the security implications.<br />
The Java language<br />
Java is an interpreted object-oriented language, similar to C++. It can be used<br />
to build programs that are independent of operating systems in both source<br />
and object form. Its unique operational characteristics, which span Web<br />
browsers as well as Web servers, enable new and powerful functions in<br />
Internet applications.<br />
To achieve operating system independence, the Java language allows no<br />
operations that are dependent on specific operating system. Also, it excludes<br />
some C++ functions such as a preprocessor, operator overloading, multiple<br />
inheritances, and pointers. All Java programming is encapsulated within<br />
classes, and the Java Development Kit (JDK) includes special classes that are<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
critical to assuring operating system independence, including GUI functions,<br />
input/output functions, and network communications.<br />
The Java compiler produces an intermediate bytecode format that is machine<br />
independent. This, in turn, is processed at run time by a Java interpreter. The<br />
interpreter also inspects the bytecode at run time to ensure its validity and<br />
safety to the machine environment. Because of the isolation the Java<br />
interpreter provides, it is sometimes referred to as a Java Virtual Machine<br />
(JVM).<br />
The Java language can be used to construct Java servlets, Java applets, and Java<br />
applications.<br />
Java applets<br />
Java applets are supported for compatibility with previous versions of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be removed in a<br />
future release. It is recommended that you use Java applications, or Java<br />
servlets, when developing new solutions.<br />
Java servlets<br />
Java servlets are small Java applications that run on a Web server machine,<br />
unlike Java applets, which are downloaded to a Web browser.<br />
Java servlets have become popular as a replacement for CGI (Common<br />
<strong>Gateway</strong> Interface) programs. The advantage of Java servlets over CGI<br />
applications is that they can execute more quickly since they are invoked as<br />
threads in a daemon process, meaning that they are persistent in memory and<br />
can fulfill multiple requests.<br />
Note that servlets must ensure references to the gateway objects are<br />
thread-safe.<br />
Java technology<br />
Java applications<br />
A Java application is a program that executes locally on a computer. It has<br />
operating system dependent capabilities in addition to those of an applet. It<br />
can access local files, create and accept general network connections, and call<br />
native C or C++ functions in machine-specific libraries.<br />
Java applications can use the <strong>CICS</strong>-provided Java classes to perform<br />
transaction processing in <strong>CICS</strong> systems. They can use the Java<strong>Gateway</strong> class<br />
to establish two kinds of connection:<br />
v A network gateway connection is a connection across a network to a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
v A local gateway enables a Java application to communicate directly with a<br />
<strong>CICS</strong> <strong>Transaction</strong> Server, without the need for a network.<br />
Chapter 1. Overview 13
Java technology<br />
JavaBeans <br />
When the connection between the application and the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> has been established, an application can use the ECIRequest class,<br />
for example, to do transaction processing.<br />
The JavaBeans API, developed by Sun Microsystems, allows you to write<br />
component software in Java. Components are self-contained, reusable software<br />
units that you can build into servlets using visual application builder tools.<br />
Any JDK <strong>Version</strong> 1.1-compliant browser or tool supports JavaBeans.<br />
JavaBeans components are called beans. Most builder tools allow you to<br />
maintain beans in a palette or toolbox. You can select a particular bean from<br />
the toolbox, drop it onto a form, modify its appearance and behavior, and<br />
define how it interacts with other beans. You can build your selected bean<br />
and other beans into a servlet, or new bean, without actually writing any<br />
code. For more information on JavaBeans, see the Sun Web site<br />
(www.java.sun.com).<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides EPI Java bean samples based on<br />
high-level EPI interfaces. These beans allow you easily to create Java<br />
programs that access data from existing <strong>CICS</strong> 3270 applications, without any<br />
programming. Using a bean composer tool, you can quickly and easily create<br />
new Java front-ends that can connect to <strong>CICS</strong>, run transactions, display data<br />
from 3270 screens, and send user input back to the <strong>CICS</strong> server. For more<br />
information, see the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Firewalls<br />
A current design consideration in the use of Java applet communication is the<br />
impact of firewalls. This is the term given to a configuration of software that<br />
prevents unauthorized traffic between a trusted network and an untrusted<br />
network. Firewalls are put in place to protect company assets from outside<br />
intrusion, but they can also limit legitimate communications. Firewalls have<br />
two functions:<br />
1. To restrict access to a server by outside users - inbound restrictions<br />
2. To limit the ability of users inside a firewall to perform certain network<br />
functions outside their firewall - outbound restrictions.<br />
A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration is well suited to avoid problems in<br />
the first area since the <strong>Gateway</strong> processor can be placed outside the firewall<br />
and be connected through the firewall to the <strong>CICS</strong> server. Outbound firewalls<br />
that users may have to contend with can be a problem. A large company<br />
might use a firewall to limit the types of connections and protocols that can<br />
be used.<br />
The use of Java on an intranet (a local implementation of the Internet) works<br />
very well since firewalls are typically not a factor. If you are designing<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Java technology<br />
applications to run over the Internet (rather than an intranet), determine<br />
whether your potential users are behind firewalls. If so, consider alternative<br />
processing for those users, such as executing the Java code as a Java servlet<br />
on the Web server. Also consider using HTTP and HTTPS protocols supported<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Authentication using SSL” on page 10 and<br />
“HTTPS” on page 12.<br />
Web servers<br />
A Web server is a software program that responds to information requests<br />
generated by Web browsers. When a request from a browser is received, the<br />
Web server processes the request to determine the action to take:<br />
v Return the requested document.<br />
v Deny the request.<br />
v Pass the request through for further processing by an external application.<br />
The request might be, for example, to a database to perform a search<br />
request, or to a more dynamic form of information delivery such as Lotus ®<br />
Domino .<br />
Communication between a Web server and an external application is<br />
transparent; you need to know only the URL of the Web server to direct a<br />
request to it. Also, all Web servers can handle requests from many browsers<br />
concurrently.<br />
Specialized servers can also be configured to limit access to a restricted set of<br />
users, or to provide security for purchase of goods or services.<br />
Web servers exist for almost every operating system and are available from<br />
many suppliers. For information on the Web servers supported by <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, see “Supported software” on page 22.<br />
The J2EE resource adapters<br />
An API in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java programmers to take<br />
advantage of features provided in J2EE-compliant runtime environments (e.g.<br />
IBM WebSphere Application Server). The J2EE resource adapter defines a<br />
standard architecture for connecting the Java 2 Platform, Enterprise Edition<br />
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as <strong>CICS</strong>.<br />
The resource adapter architecture defines a set of scalable, secure, and<br />
transactional mechanisms that enable the integration of EISs with application<br />
servers and enterprise applications.<br />
A proprietary application server, such as IBM WebSphere, can be extended to<br />
support the resource adapter architecture, and is then assured of a seamless<br />
Chapter 1. Overview 15
Introduction<br />
connectivity to multiple EISs. Similarly, a vendor provides a standard resource<br />
adapter that can connect any application server that supports the resource<br />
adapter architecture to an EIS.<br />
The resource adapter architecture defines a Common Client Interface (CCI) for<br />
EIS access. The CCI defines a client API for interacting with heterogeneous<br />
EISs. The resource adapter architecture enables a vendor such as IBM to<br />
provide a standard resource adapter to allow access to its product. This<br />
resource adapter connects to an application server and provides connectivity<br />
between the EIS, the application server, and the enterprise application.<br />
The Programming using J2EE chapter in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide describes the J2EE resource adapters. The chapter includes information<br />
on the J2EE samples which are provided.<br />
The samples.txt file, in the \samples subdirectory, provides<br />
additional information on the J2EE sample programs.<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses <strong>CICS</strong><br />
This section describes how <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java servlets to<br />
access <strong>CICS</strong> programs and data.<br />
1. The Web server loads and initializes the servlet. This could be when the<br />
Web server starts, or when the first request is made to the servlet by the<br />
Web browser or network computer.<br />
2. The servlet creates a Java<strong>Gateway</strong> object to connect to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. This establishes communication between the<br />
browser and the long running <strong>Gateway</strong> daemon process using Java’s<br />
sockets protocol.<br />
3. When a HTTP request from the Web browser or network computer<br />
invokes the servlet, the Web server calls its Service method with details<br />
of the request.<br />
4. The servlet creates an ECIRequest, EPIRequest, orESIRequest object,<br />
that contains ECI, EPI, or ESI calls, and sends it to the <strong>Gateway</strong> daemon<br />
using the Java<strong>Gateway</strong>.flow method.<br />
5. The <strong>Gateway</strong> daemon receives, and unpacks the request. The Client<br />
daemon makes corresponding ECI, EPI, or ESI calls to the <strong>CICS</strong> server.<br />
6. The <strong>CICS</strong> server processes the calls, including verification of the userid<br />
and password if required, and passes control and user data to the <strong>CICS</strong><br />
application program.<br />
7. When the <strong>CICS</strong> application program has finished processing, it returns<br />
control and data to <strong>CICS</strong>.<br />
8. The <strong>CICS</strong> server returns control and data to the Client daemon.<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
9. The <strong>Gateway</strong> daemon packs these results and returns them to the Java<br />
servlet.<br />
10. When the servlet receives the results, it generates a HTTP response to<br />
return to the Web browser.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a multithreaded model for handling<br />
network connections, and for assigning threads for requests from, and replies<br />
to, Java clients. The threading model uses the following objects:<br />
ConnectionManagers<br />
A ConnectionManager manages all the connections from a particular Java<br />
client. When it receives a request, it allocates a Worker thread from a pool of<br />
available Worker threads to execute the request.<br />
Workers<br />
A Worker is the object that actually executes a request from a Java client<br />
application. Each Worker object has its own thread, which is activated when<br />
there is some work to do. When a worker thread has finished processing it<br />
returns to the pool of available worker threads.<br />
You can set both the initial and maximum sizes of the resource pools for these<br />
objects; see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings” on page 58 for<br />
information on setting configuration parameters. You can also specify these<br />
limits when you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Starting the<br />
<strong>Gateway</strong> with user-specified options” on page 142.<br />
Table 3 shows thread limits that should be considered when setting the<br />
number of Connection Manager and Worker threads on the various operating<br />
systems:<br />
Table 3. Thread limits on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating systems<br />
Operating<br />
system<br />
System-wide limit of<br />
the maximum number<br />
of threads<br />
z/OS This may be restricted<br />
by the total number of<br />
MVS ® Task Control<br />
Blocks (one is created<br />
per UNIX System<br />
Services thread)<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses <strong>CICS</strong><br />
Process limit of the number of threads<br />
Governed by the UNIX System Services<br />
parameters: MAXTHREADS and<br />
MAXTHREADTASKS<br />
Windows No limit Limited by the amount of virtual memory<br />
available for the process (by default a<br />
thread has 1M of stack meaning that 2028<br />
threads can be created per process)<br />
Chapter 1. Overview 17
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
Table 3. Thread limits on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating systems (continued)<br />
Operating<br />
system<br />
System-wide limit of<br />
the maximum number<br />
of threads<br />
AIX 262 143 32 768<br />
HP-UX No limit (30 000 kernel<br />
threads)<br />
Linux Equal to the maximum<br />
number of processes<br />
Solaris No limit No limit<br />
Process limit of the number of threads<br />
30 000 (refer to Configurable Kernel<br />
Parameters in the SAM utility)<br />
1024 (refer to your LinuxThreads<br />
documentation for more information)<br />
For more information on the way Java allocates memory for threads, refer to<br />
“Performance issues” in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
book.<br />
The threading model is illustrated in the following figures:<br />
Figure 4. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for TCP/IP and SSL. These protocols have a persistent socket.<br />
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request brokers<br />
Figure 5. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for HTTP/HTTPS. These protocols do not have a persistent<br />
socket.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request brokers<br />
Some Web servers contain an object request broker (ORB) that conforms to the<br />
Object Management Group’s (OMG) Common Object Request Broker<br />
(CORBA) standard. If you have such a Web server, you can develop servlet<br />
objects that can be invoked from a remote browser using the CORBA Internet<br />
InterORB Protocol (IIOP). IIOP is transmitted to the browser using HTTP.<br />
Workload management<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a load balancing facility that allows the<br />
transaction workload to be distributed across multiple <strong>CICS</strong> regions or <strong>CICS</strong><br />
servers. For more information see “Configuring the Workload Manager” on<br />
page 84.<br />
Chapter 1. Overview 19
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 2. Planning your installation<br />
This chapter helps you to plan the installation of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> by listing the hardware and software that you need. For information<br />
about hardware and software requirements on all supported operating<br />
systems, see Appendix B, “Hardware and software” on page 257. The <strong>CICS</strong><br />
servers to which <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can connect are also listed.<br />
The Chapter consists of the following topics:<br />
“Hardware requirements” on page 22 Read this for information about the<br />
hardware you need to run your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (processor type,<br />
memory, disk space).<br />
“Supported software” on page 22 Read this for information about the<br />
software products that are supported for<br />
use with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“<strong>CICS</strong> server PTF requirements” on<br />
page 25<br />
“Communication between the <strong>Gateway</strong><br />
and <strong>CICS</strong> servers” on page 26<br />
Read this for information about APARs<br />
and PTFs (service updates) for <strong>CICS</strong><br />
servers.<br />
Read this for information about the<br />
communications protocols you can use to<br />
connect to your <strong>CICS</strong> servers.<br />
“Server Code page support” on page 28 Read this for information about data<br />
conversion between the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> and <strong>CICS</strong> servers.<br />
If you are using an earlier version of the product, or a <strong>CICS</strong> Universal Client,<br />
see Chapter 15, “Migration” on page 241 for a discussion of migration issues.<br />
See the product readme file for any late changes to hardware and software<br />
requirements.<br />
If you are installing from CD, the readme file is README.WIN in the root<br />
directory.<br />
If you have downloaded the product, the packaged file that you downloaded<br />
contains the product code and the readme file for your operating system.<br />
When you install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the file is copied into your<br />
installation directory as readme.txt.<br />
© Copyright IBM Corp. 1996, 2002 21
Hardware requirements<br />
Hardware requirements<br />
Table 4. Hardware requirements on Windows systems<br />
Processor Any processor capable of running the appropriate<br />
operating system and other prerequisite software.<br />
Network adapters To connect workstations to the LAN, you need a<br />
suitable adapter such as an ethernet adapter.<br />
Memory At least 64 MB.<br />
Disk space You need 30 MB of free disk space for your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (including documentation in US<br />
English only).<br />
Supported software<br />
The following products are supported.<br />
You need a further 30 MB for temporary files used<br />
during installation. At least 12 MB of this must be on<br />
your system partition.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v Windows XP Professional<br />
v Windows 2000 Professional with a minimum of Service Pack 1<br />
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a<br />
minimum of Service Pack 1<br />
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a<br />
v Windows NT Server V4.0 with a minimum of Service Pack 6a.<br />
Notes:<br />
– Windows NT 4 Terminal Server is not supported<br />
– The setting of multiple user interface languages, under Windows<br />
2000 MultiLanguage <strong>Version</strong>, is not supported.<br />
– If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> under load, and<br />
using remote protocols, it is strongly recommended that you use<br />
a server version, rather than a workstation version, of Windows.<br />
See “ConnectFailed exceptions when running under load” on<br />
page 216, for more information.<br />
Web browsers<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft ® Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
Telnet clients<br />
If you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> over telnet, certain telnet clients can<br />
cause problems with the display. For example, your telnet session might<br />
truncate message lines over a certain length. This is usually a problem with<br />
the telnet client that you are using, or the terminal type that you are going in<br />
as. Currently there is no solution to this problem.<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v IBM Java SDK 1.3 (service release 6)<br />
JSSE<br />
Supported software<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
Chapter 2. Planning your installation 23
|<br />
|<br />
|<br />
|<br />
|<br />
Supported software<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied.<br />
v <strong>CICS</strong> for MVS/ESA V4.1, with communication through SNA. (with APAR<br />
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for<br />
EPI emulation. APAR PN79262 is needed for DBCS support.<br />
v <strong>CICS</strong> for OS/400 ® V4.4<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for OS/2 ® V4.1 with CSD 3<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA 1.1.0 (with APAR PQ30170, for<br />
signon capable terminals, applied), or a minimum service level of 1.1.1<br />
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)<br />
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)<br />
v TXSeries V<strong>5.0</strong> (Windows, AIX)<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,<br />
AIX and Solaris.<br />
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.<br />
SNA communications<br />
Customers wishing to use SNA communications should install one of the<br />
following products:<br />
Windows operating systems<br />
Any one of:<br />
v IBM eNetwork Communications Server V6.1, with a minimum of<br />
service level 1<br />
v IBM eNetwork Personal Communications V<strong>5.0</strong>, with a minimum of<br />
service level 2<br />
v IBM eNetwork Personal Communications V5.5<br />
v Microsoft SNA Server V4.0 with a minimum of SP4<br />
TCP/IP communications<br />
TCP/IP support is provided by the operating system.<br />
TCP62 communications<br />
TCP62 support is provided by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
Compilers and application development tools<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following compilers and<br />
application development tools:<br />
Windows<br />
v IBM VisualAge ® COBOL V3.0<br />
v Microsoft Visual C++ V6.0<br />
v Microsoft Visual Basic V6.0<br />
v Microsoft Visual Basic Script (VBScript) V<strong>5.0</strong><br />
Note: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support use of the COM<br />
libraries with Microsoft <strong>Transaction</strong> Server (MTS), or the MTS<br />
component of COM+.<br />
Screen readers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with JAWS.<br />
Other tools<br />
These tools are available for viewing the PDF online documents:<br />
v Adobe Acrobat Reader V<strong>5.0</strong><br />
<strong>CICS</strong> server PTF requirements<br />
Supported software<br />
See the README file for the latest details on APARs and PTFs applicable to<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Terminal Signon capability<br />
<strong>CICS</strong> Servers require APAR fixes to support the terminal signon capability<br />
function available in this release; see “Supported software” on page 22 for<br />
details of the APAR relating to your <strong>CICS</strong> server. If the server does not have<br />
the required APAR applied and the ’-a’ option is not specified on <strong>CICS</strong>TERM,<br />
the installed terminal will give unpredictable results.<br />
Timeout support<br />
To provide complete support for timeouts, if you are using any TXSeries or<br />
<strong>Transaction</strong> Server on UNIX and Windows operating systems, it must include<br />
the appropriate PTF level; see “Supported software” on page 22 for details.<br />
If the server does not have the required APAR applied and the ’-a’ option is<br />
not specified on <strong>CICS</strong>TERM, this happens:<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> displays the message: CCL7053E Errors<br />
found while communicating with server<br />
v CCL3105 Inbound <strong>CICS</strong> datastream error (CTIN, 4, 0) is written to<br />
<strong>CICS</strong>CLI.LOG<br />
Chapter 2. Planning your installation 25
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Supported software<br />
v On the server, the message: ERZ042004E/0112: An invalid request was<br />
received from client is written to CSMT.out<br />
v console.msg includes this: ERZ014016E/0036: <strong>Transaction</strong> CTIN Abend A42B<br />
Communication between the <strong>Gateway</strong> and <strong>CICS</strong> servers<br />
You can use these protocols to communicate with <strong>CICS</strong> servers:<br />
TCP/IP Transmission Control Protocol/Internet Protocol (TCP/IP) is a<br />
widely used, robust, suite of protocols, particularly important<br />
in connecting heterogeneous networks.<br />
SNA The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses Advanced<br />
program-to-program communication (APPC) to provide SNA<br />
LU 6.2 communication. APPC is an implementation of the<br />
SNA LU 6.2 protocol that provides device-independent<br />
application-to-application communication over LU 6.2<br />
sessions.<br />
TCP62 TCP62 is a communications mechanism that allows<br />
connections from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to a <strong>Transaction</strong><br />
Server for z/OS region over an IP network. It uses IBM’s<br />
Multiprotocol Transport Networking (MPTN) protocol<br />
switching technology to send LU6.2 Systems Network<br />
Architecture (SNA) flows over an IP network.<br />
Local Named Pipe<br />
TXSeries (<strong>Version</strong> 4.3 or later) for Windows NT can use the<br />
Local Named Pipe protocol to communicate with a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> that is on the same computer. This<br />
provides a fast communications method independent of any<br />
network protocol.<br />
The protocols that you can use for the various client/server connections are<br />
shown in Table 5 on page 27. This table lists the protocols that you can use to<br />
connect your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to your <strong>CICS</strong> server. It also shows<br />
whether ECI, EPI emulation, and Autoinstall are supported for your<br />
combination of <strong>CICS</strong> server and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating system.<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Table 5. Protocols and functions supported. If a protocol or feature is supported by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> only on certain operating systems, the operating systems are listed. Otherwise, *<br />
means supported on Windows and all UNIX operating systems; V means not supported.<br />
SERVER TCP/IP SNA TCP62 ECI<br />
<strong>CICS</strong> for MVS/ESA<br />
V4.1<br />
<strong>CICS</strong> for OS/400<br />
V4.4<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for OS/2 V4.1<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS V1.2<br />
and V1.3<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA<br />
V1.1.0 and V1.1.1<br />
V<br />
*<br />
*<br />
V<br />
V<br />
<strong>CICS</strong>/VSE V2.3 V<br />
TXSeries V4.2<br />
(HP-UX)<br />
TXSeries V4.3 (AIX,<br />
Solaris, Windows )<br />
*<br />
*<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
* *<br />
EPI<br />
Emulation<br />
See note<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
ESI<br />
*<br />
* * * *<br />
V * * V<br />
* *<br />
V *<br />
V *<br />
Windows<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
AIX<br />
HP-UX<br />
Solaris<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
V * * V<br />
V * * V<br />
Note: EPI always incorporates <strong>CICS</strong> 3270 terminal emulation and <strong>CICS</strong> 3270<br />
client printer support.<br />
All servers support autoinstall. This means that you do not need to predefine<br />
the client to the <strong>CICS</strong> server; control table definitions are automatically<br />
created for the client at the <strong>CICS</strong> server. For <strong>CICS</strong>/VSE, autoinstall is possible<br />
via LU 6.2 single session only. This restriction does not affect <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA.<br />
Restrictions on <strong>CICS</strong> for OS/400<br />
The following restrictions apply:<br />
v DBCS languages are not supported.<br />
Communication protocols<br />
*<br />
Chapter 2. Planning your installation 27<br />
V<br />
V
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Communication protocols<br />
v Signon capable terminals are not supported.<br />
v You cannot start the CEDA transaction from a client terminal.<br />
v You cannot use PF1 to get <strong>CICS</strong> online help from a client terminal.<br />
Why use a particular protocol?<br />
As shown in table 5 some protocols can be used only for certain types of<br />
client/server connection.<br />
If you need to connect different types of networks, for example, Token Ring<br />
and Ethernet networks, consider using TCP/IP.<br />
TCP62 allows access to <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS over a TCP/IP<br />
network. Partner LU62 applications can communicate without complex SNA<br />
configuration definitions on the client, and without any changes to the LU62<br />
applications on the client or server. If you require easy client access to <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS over your TCP/IP network, use the TCP62<br />
support. For information on configuring TCP62, see “TCP62 configuration” on<br />
page 42.<br />
Server Code page support<br />
Some <strong>CICS</strong> servers do not support all of the code pages that are supported by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
If the code page of an ECI application is different from the code page of the<br />
server, data conversion must be performed at the <strong>CICS</strong> server. This applies for<br />
EBCDIC <strong>CICS</strong> servers such as <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS . For more<br />
information, see Appendix A, “Data conversion between the Client daemon<br />
and a <strong>CICS</strong> server” on page 251, the <strong>CICS</strong> server documentation, and the<br />
Redbook <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>.<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
Chapter 3. Installation<br />
This chapter describes how to install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It consists<br />
of the following:<br />
“Choosing what to install” Read this to find out what you can install.<br />
“Microsoft Windows Installer Service” on<br />
page 30<br />
“Installing the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>” on page 31<br />
Read this for information on the<br />
Microsoft Windows Installer Service.<br />
Read this for detailed instructions on how<br />
to install your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Actions after installation” on page 36 Read this for information on what you<br />
should do after you have installed the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Maintaining or uninstalling the <strong>CICS</strong> Read this for information on how to:<br />
<strong>Transaction</strong> <strong>Gateway</strong>” on page 37 v Change installed components<br />
v Repair installation errors<br />
v Uninstall the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
“Updating the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>” on page 39<br />
Read this to learn how to get updates and<br />
fixes for the product.<br />
Choosing what to install<br />
You can choose either a complete or custom installation.<br />
Complete<br />
Installs all components:<br />
v Program files<br />
v Development kit<br />
v Programming samples (installed to \samples\)<br />
v Toolkit<br />
v Documentation<br />
into the default installation directory (see Table 1 on page xii).<br />
Custom<br />
Allows you to select which components to install, and specify the target<br />
drive and directory.<br />
All shortcuts are created in the IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> folder in the<br />
Start –> Programs menu for all users.<br />
© Copyright IBM Corp. 1996, 2002 29
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Choosing what to install<br />
You can also choose to install IBM’s runtime environment for Java. You need<br />
Java to run the full <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> product, and the configuration<br />
tool. You do not need it to run only the Client daemon.<br />
Microsoft Windows Installer Service<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports the Microsoft Windows Installer Service,<br />
which offers the following features:<br />
v If the installation fails, the Microsoft Windows Installer Service can restore<br />
your system to its original state. However, it cannot restore files that have<br />
been removed during an upgrade from an earlier version.<br />
v If <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> becomes corrupted, the Microsoft Windows<br />
Installer Service can repair the problem. Follow the instructions in<br />
“Maintaining or uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>” on page 37.<br />
v You can add or remove components, or remove the whole installation.<br />
Upgrading<br />
Consult your Windows product documentation for full details of the Microsoft<br />
Windows Installer Service.<br />
Remove any beta versions of the product before installation.<br />
Currently installed product Upgrade type<br />
<strong>CICS</strong> Universal Client v<strong>5.0</strong> No upgrade. Uninstall the product before<br />
continuing.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> v4.00, 4.01 and Normal upgrade.<br />
4.02<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> v3 Copies the relevant INI files before<br />
uninstalling the older version and then<br />
installing <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> <strong>5.0</strong><br />
<strong>CICS</strong> Universal Client v3 Copies the relevant INI files before<br />
uninstalling the older version and then<br />
installing <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> <strong>5.0</strong><br />
<strong>Version</strong>s earlier than 3 No upgrade. Uninstall the product before<br />
continuing.<br />
The product will not install if the level of Windows is below that supported;<br />
see “Supported software” on page 22.<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
For these languages, the installation process uses the language specified in<br />
your system locale:<br />
v English<br />
v French<br />
v German<br />
v Italian<br />
v Japanese<br />
v Korean<br />
v Simplified Chinese<br />
v Spanish<br />
v Turkish<br />
Attention: If you are installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> onto a<br />
workstation that already has a <strong>CICS</strong> for Windows NT server installed, be<br />
aware that both products have some files of the same name. Ensure that the<br />
installation of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not affect the server. This is<br />
particularly important with respect to environment settings.<br />
To install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
1. Log on with administrator privileges. You may have Administrator<br />
privileges by being a member of the local Administrators group, or by<br />
being a domain Administrator.<br />
2. Ensure that you have applied any relevant Windows service packs. See<br />
“Supported software” on page 22 for details.<br />
3. Close down any other programs.<br />
4. Insert the CD into the drive. If installing from a network drive, connect<br />
to the drive.<br />
5. If you are installing on a Windows 2000 Terminal Server, put the terminal<br />
server into install mode before installing. From the Control Panel click<br />
Add/Remove Programs → Add New Programs. Click the CD or Floppy<br />
button. Click Next, then type d:\gateways\windows\setup, where d: is<br />
your CD or network drive.<br />
6. If you are not installing on a Windows 2000 Terminal Server, click Start →<br />
Run and then type d:\setup, where d: is your CD or network drive.<br />
7. A screen listing installation options is displayed:<br />
v Install IBM Java v1.3<br />
You need Java to run the full <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> product, and<br />
the configuration tool. You do not need it to run only the Client<br />
daemon. If you select this option, follow the onscreen prompts. When<br />
Chapter 3. Installation 31
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
installation is complete you return to this screen. To uninstall, click<br />
Start → Settings → Control Panel → Add/Remove Programs.<br />
v Install IBM CTG v<strong>5.0</strong><br />
Select this option to install the product.<br />
8. The installation process checks the operating system. It installs or<br />
upgrades the Microsoft Windows Installer Service if necessary (you may<br />
have to restart your system), and configures it to run correctly.<br />
9. A welcome screen is displayed. Click Next to display the Software<br />
License Agreement shown in Figure 6.<br />
Figure 6. Software license agreement<br />
Note: License files are stored in the \license<br />
subdirectory, in RTF format.<br />
10. To accept the license agreement and install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
check the I accept the terms in the license agreement radio button, then<br />
click Next.<br />
11. The Setup Type screen shown in Figure 7 on page 33 is displayed.<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Figure 7. Setup Type screen<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Select Complete or Custom as appropriate, and then click Next. Ifyou<br />
chose a complete installation, go to step 15. If you chose a custom<br />
installation, continue at step 12.<br />
12. If you chose a custom installation, the Custom Setup screen shown in<br />
Figure 8 on page 34 is displayed, with the Program Files option selected:<br />
Chapter 3. Installation 33
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Figure 8. Custom Setup screen<br />
v Click the icon next to each component to set installation options for the<br />
component.<br />
v Click the Space button for details of how much space is needed to<br />
install the components that you have chosen.<br />
v Click Change if you wish to install to a different location.<br />
Click Next to continue.<br />
13. The Install Option screen (Figure 9 on page 35) is displayed:<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Figure 9. Install Option screen<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Yes, I want to update the path<br />
Leave this option selected. If you clear this box you will have to<br />
update the path manually.<br />
Install the IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows service<br />
If you clear this box you cannot run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
as a service. If you are installing on a Windows Terminal Server,<br />
you are strongly recommended to install it as a service.<br />
Click Next.<br />
14. The COM Object Registration Option screen is displayed. Choose which<br />
type of COM object you want to register. You can register <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> COM API resources as either in process or out of<br />
process.<br />
In process This refers to .dll files, and is the default<br />
type.<br />
Out of process This refers to .exe files. Choose this for<br />
backward compatiblity with older <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> applications.<br />
Chapter 3. Installation 35
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Actions after installation<br />
Depending on your choice, either the in process or out of process libraries<br />
are installed; both versions are not installed. In process is the<br />
recommended choice, as it offers better performance and better support<br />
for multiple applications on the same machine. To change this option<br />
after installation, you must reinstall the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Click Next.<br />
15. (Resume here if you chose a complete installation in step 11 on page 32.)<br />
The Ready to Install the Program screen is displayed. Click Install to<br />
continue.<br />
16. The installation program keeps you informed of progress. When the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> has been successfully installed you are asked if you<br />
want to view the README file and run the configuration tool. (Both<br />
options are selected.) Click Finish to end the installation.<br />
Verify the system path<br />
Make sure that the path to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> executable files<br />
appears before any network directories in your PATH statements. If the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is to run as a Windows service, its environment is<br />
determined when the system is started and is formed from System<br />
environment variables only. The environment used by Windows services is<br />
established before the network drives are attached when Windows starts.<br />
Consequently, any directory in the system PATH that involves a network<br />
drive will not be available to Windows services.<br />
Also, Windows discards the remainder of a PATH if it finds a non-existent<br />
directory. You will have problems running your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> if<br />
network directories (or non-existent local directories) are in your system PATH<br />
before the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> executable files paths.<br />
A typical symptom of this problem is the appearance of a Service Control<br />
Manager dialog box indicating a return code of 0xc0000022 when you try to<br />
start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Creating Start Menu shortcuts<br />
When you install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Start Menu shortcuts are<br />
created for some of the tasks most commonly performed (see “The <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> icons” on page 144 for details). You can create additional<br />
shortcuts to perform the command functions that you use most frequently. For<br />
example, you might want to create a shortcut for:<br />
<strong>CICS</strong>CLI /s=servername /q<br />
to start a connection to a server used for testing applications.<br />
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
To create a Start Menu shortcut:<br />
1. Right-click one of the existing shortcuts on the Start Menu, for example<br />
Start Client.<br />
2. Select Create Shortcut from the menu.<br />
3. A new Start Menu shortcut, for example Start Client (2), appears on the<br />
menu. Right-click the new Start Menu shortcut.<br />
4. Select Properties from the menu.<br />
5. Change the settings for the new Start Menu shortcut under the Shortcut<br />
tab.<br />
6. Change the name for the new Start Menu shortcut under the General tab.<br />
7. Click OK to save the Start Menu shortcut properties.<br />
Maintaining or uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Actions after installation<br />
This section describes how to:<br />
v Change installed components<br />
v Repair installation errors<br />
v Completely remove the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
1. To maintain <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, run the setup file as described in<br />
“Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>” on page 31. Follow the<br />
instructions to step 8.<br />
2. Click Next to clear the welcome screen.<br />
3. The Program Maintenance screen shown in Figure 10 on page 38 is<br />
displayed:<br />
Chapter 3. Installation 37
Maintaining the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Figure 10. Program Maintenance screen<br />
Modify This displays the custom setup screen (see Figure 8 on<br />
page 34), from which you can change which components<br />
are installed.<br />
Repair This option repairs installation errors. Select it, then follow<br />
the prompts to repair any errors in your setup. The repair<br />
option fixes missing or corrupt files, shortcuts, and registry<br />
entries.<br />
Remove This removes the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> from your<br />
computer.<br />
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
Note: If you selected the Use Windows credentials for<br />
security option on the Server connection panel of<br />
the configuration tool, see “Use Windows<br />
credentials for security” on page 77 for important<br />
information about what you must do before you<br />
uninstall.
Updating the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
After installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you can update the product, or<br />
obtain corrective service software (“fixes”).<br />
For information about corrective service software, visit the Web site at<br />
www.ibm.com/software/ts/cics/ and follow the Support link.<br />
You install updated versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, or corrective<br />
service software using setup.exe, in the same way as for the initial installation.<br />
When you update with a newer version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
Setup retains any customized (*.ini) files from the older version.<br />
Silent installation<br />
You can use a silent installation to install the standard components of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> without going through any of the Setup screens. You run<br />
only the setup program; no user input is required.<br />
You must first install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on a workstation using<br />
the instructions in “Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>” on page 31.<br />
During installation, the following file is created on your workstation:<br />
\silent.txt<br />
This file contains instructions on how to install silently.<br />
Updating the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Chapter 3. Installation 39
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers<br />
After you have installed the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and set up your <strong>CICS</strong><br />
servers for communication, your next step is to set up the communication<br />
links between the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and your <strong>CICS</strong> servers. This<br />
chapter consists of the following:<br />
“TCP/IP configuration” Read this if you will use TCP/IP.<br />
“TCP62 configuration” on page 42 Read this if you will use TCP62.<br />
“SNA configuration” on page 45 Read this if you will use the Systems<br />
Network Architecture. (References to SNA<br />
mean the APPC implementation of SNA.)<br />
“Named Pipes configuration” on page 50 Read this if you will use Named Pipes to<br />
communicate with a TXSeries (<strong>Version</strong> 4.3<br />
or later) for Windows NT server that is<br />
on the same computer as your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Data conversion” on page 50 Read this for information on how data<br />
may be converted as it passes between<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a<br />
<strong>CICS</strong> server.<br />
A number of sample configuration documents provide step-by-step guidance<br />
on configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers for different<br />
scenarios. If one of the documents covers your desired configuration, simply<br />
follow the instructions in it. See “Sample configuration documents” on<br />
page 266.<br />
After you have set up your communications links, continue at Chapter 5,<br />
“Configuration” on page 51. This tells you how to make the required entries<br />
in the configuration file.<br />
TCP/IP configuration<br />
The TCP/IP stack on your local machine should already be correctly<br />
configured. Contact your system administrator if there are problems.<br />
Next steps<br />
1. Use the configuration tool to create a server definition; see “The<br />
configuration tool interface” on page 55.<br />
2. Configure the server definition (see “TCP/IP settings” on page 78):<br />
© Copyright IBM Corp. 1996, 2002 41
|<br />
|<br />
|<br />
|<br />
TCP/IP configuration<br />
Specify TCP/IP as the protocol.<br />
Enter the hostname or IP address of your <strong>CICS</strong> server.<br />
TCP62 configuration<br />
The TCP62 support for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows communication with<br />
<strong>CICS</strong> for MVS/ESA <strong>Version</strong> 4.1 and later over a TCP/IP network.<br />
On <strong>CICS</strong> for MVS/ESA <strong>Version</strong> 4.1 and <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS,<br />
you can use autoinstall to define SNA client connections. The advantage of<br />
autoinstall is that it allows you to use the same client configuration settings<br />
for all workstations without having to define multiple entries in VTAM ® and<br />
<strong>CICS</strong>. Autoinstall allows the Client Local LU name and CP name to be created<br />
from a template and IP address of the client machine.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> TCP62 communication supports only<br />
parallel-session SNA connections, not single-session connections. This has<br />
implications for your <strong>CICS</strong> VTAM configuration, as explained in “On z/OS”<br />
on page 43.<br />
TCP62 links to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support data synchronization<br />
levels (sync levels) 0 and 1.<br />
Enabling <strong>CICS</strong> on z/OS to communicate with a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
using TCP62 requires actions on z/OS, <strong>CICS</strong>, and the client workstation. This<br />
section outlines the steps you need to take. For more details, see “Sample<br />
configuration documents” on page 266, and “Redbooks” on page 267. You also<br />
need to make entries in the configuration file; see Chapter 5, “Configuration”<br />
on page 51.<br />
Table 6 shows the entries that you need to make. The values in the Example<br />
column are taken from the sample configuration documents.<br />
Table 6. Matching definitions for TCP62 on z/OS, <strong>CICS</strong>, and configuration file.<br />
z/OS <strong>CICS</strong> configuration tool Client workstation Example<br />
IP address - - 2.12.14.227<br />
DNSUFX - AnyNet ® domain<br />
name suffix<br />
hursley.ibm.com<br />
NETID - Partner LU name. The<br />
Partner LU name is<br />
NETID.APPL.<br />
ABC3XYZ4<br />
APPL Applid Partner LU name IYCKCTU1<br />
LOGMODE Modename Mode name LU62PS<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Table 6. Matching definitions for TCP62 on z/OS, <strong>CICS</strong>, and configuration file. (continued)<br />
z/OS <strong>CICS</strong> configuration tool Client workstation Example<br />
IP address mask for<br />
LU name template<br />
(optional)<br />
TCP/IP subnet mask FFFFFE00<br />
On z/OS<br />
Fully qualified CP<br />
name or template<br />
Local LU name or<br />
template<br />
TCP62 configuration<br />
ABC3XYZ4.PQRS1234<br />
CCLI****<br />
1. Define the TCP/IP address and hostname for the z/OS system in the MVS<br />
TCP/IP PROFILE.TCPIP and TCPIP.DATA data sets.<br />
2. Install a TCP major node, which defines the AnyNet interface between<br />
TCP/IP and VTAM. The important parameters are:<br />
DNSUFX<br />
The domain name suffix, for example hursley.ibm.com. You will enter<br />
this later in the AnyNet domain name suffix field in the configuration<br />
tool.<br />
TCPIPJOB<br />
The TCP/IP job name refers to the TCP/IP stack that VTAM AnyNet<br />
will use if multiple stacks are in use.<br />
For more information about how to install a major node, see the Guide to<br />
SNA over TCP/IP book, SC31-6527.<br />
3. To allocate cross-domain resource definitions (CDRSC) dynamically,<br />
specify DYNLU=YES as a startup option for VTAM. If you set this<br />
parameter, you do not have to define multiple static CDRSCs within<br />
VTAM. The CDRSC names are dynamically generated from the CP name<br />
and IP address mask for CP name client configuration settings, along with<br />
the IP address of the client machine.<br />
4. Specify the NETID for VTAM in your VTAM start procedure.<br />
5. Create the VTAM APPL definition. Because TCP62 supports only LU6.2<br />
parallel sessions, specify PARSESS=YES.<br />
6. Configure a VTAM LOGMODE.<br />
The MPTN (multiprotocol transport networking) function supplied with the<br />
OS/390 or z/OS Communications Server, to provide the SNA over TCP/IP<br />
capability (using AnyNet), is required to complement TCP62 in the client.<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 43
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
TCP62 configuration<br />
On <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
On <strong>CICS</strong>:<br />
1. Set the following SIT parameters:<br />
ISC=YES<br />
APPLID=IYCKCTU1<br />
AIEXIT=DFHZATDY<br />
where IYCKCTU1 is the VTAM APPL that you defined earlier.<br />
2. Install these groups:<br />
v DFHISC<br />
v DFHCLNT<br />
3. Define an SNA connection to the client workstation. (You can define the<br />
connection statically, or autoinstall it.)<br />
v On the MODENAME option of the SESSIONS definition, specify the<br />
same modename as your VTAM LOGMODE. You will also use this<br />
value in Mode name field of the configuration file.<br />
v On the MAXIMUM option of the SESSIONS definition, the first number<br />
refers to the Maximum logical SNA sessions field on the configuration<br />
tool; see “Maximum logical SNA sessions” on page 83. The default is 8;<br />
increase this if necessary. Specify the second value as 1, that is, that<br />
<strong>CICS</strong> is to have one contention winner. For example, MAXIMUM(8,1)<br />
means that the modeset is to support eight sessions, and that <strong>CICS</strong> has<br />
one contention winner.<br />
On the workstation<br />
If the domain name suffix is SNA.IBM.COM and the fully qualified partner LU<br />
name is NETID.LUA, TCP/IP must be able to resolve LUA.NETID.SNA.IBM.COM to<br />
the IP address of the server. Use one of the following methods to do this:<br />
v Supply the name and IP address to a TCP/IP domain name server<br />
v Place the name and IP addresses in the hosts file<br />
(%windir%\system32\drivers\etc\hosts) on the workstation<br />
Verify that TCP/IP is working correctly. In particular make sure the name<br />
formed from .. can<br />
be used to reach the server.<br />
Firewall implications<br />
You might experience problems when configuring a TCP62 connection<br />
through a firewall.<br />
For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to function correctly your firewall needs to<br />
be configured to permit UDP packets on the TCP62 port, which by default is<br />
set to 397; see “TCP62 port” on page 83.<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
KeepAlive packets<br />
When using <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, with the TCP62 protocol, KeepAlive<br />
packets can be sent to the <strong>CICS</strong> server to check its availability.<br />
KeepAlive packets are enabled by default.<br />
You can enable or disable the sending of KeepAlive packets using the Remote<br />
node inactivity poll interval setting in the configuration tool; see “Remote node<br />
inactivity poll interval” on page 83.<br />
Changing this inactivity poll value alters how frequently <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> sends KeepAlive packets. A higher interval value will result in less<br />
network traffic but <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will take longer to detect that a<br />
connection has been lost. With a lower value the opposite is true, lost<br />
connections are detected and there ish a greater amount of network traffic.<br />
Next steps<br />
1. Use the configuration tool to create a server definition using the TCP62<br />
protocol; see “The configuration tool interface” on page 55.<br />
2. Configure the server definition (see “TCP62 settings” on page 80).<br />
SNA configuration<br />
TCP62 configuration<br />
To set up communication over SNA, define the following in your SNA<br />
communications product:<br />
v The local node characteristics that are common to all SNA users at the<br />
workstation<br />
v A local logical unit (LU) for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v A partner logical unit (PLU) for each <strong>CICS</strong> server with which the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> will communicate<br />
v One or more modes to specify sets of session properties that are used in<br />
binding SNA sessions<br />
v A transaction program (TP) for the CRSR transaction. You need this if:<br />
– The <strong>CICS</strong> servers support terminal emulation, and<br />
– You require automatic transaction initiation (ATI) against the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> terminals.<br />
Note: The terms used to describe these definitions vary with the product used<br />
to provide SNA support. The terms used above are the ones used by<br />
IBM eNetwork Communications Server.<br />
SNA links to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support data synchronization<br />
levels (sync levels) 0 and 1.<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 45
Configuring SNA<br />
Configuring SNA<br />
The following sections summarize SNA configuration. Configuring SNA<br />
requires action on VTAM, <strong>CICS</strong>, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and one of<br />
the following:<br />
v eNetwork Personal Communications<br />
v eNetwork Communications Server<br />
v Microsoft SNA Server<br />
Table 7 shows the entries that you need to make. The values in the Example<br />
column are taken from the sample configuration documents.<br />
Table 7. Matching definitions for SNA<br />
VTAM <strong>CICS</strong> eNetwork Personal<br />
Communications<br />
NETID — First part of<br />
Partner LU name<br />
eNetwork<br />
Communications<br />
Server<br />
First part of<br />
Partner LU name<br />
Microsoft SNA<br />
Server<br />
configuration file Example<br />
Network Name Partner LU name ABC3XYZ4<br />
PU — CP Alias CP Alias Control Point<br />
Name<br />
— IYAMR004<br />
LU Netname Local LU name Local LU name LU Name Local LU name IYAMT040<br />
XID — Local Node ID Local Node ID Local Node ID — 05D 316DF<br />
Token Ring — Destination Destination Remote Network<br />
— 400045121088<br />
destination<br />
address<br />
address<br />
address<br />
Address<br />
APPL Applid Second part of<br />
Partner LU name<br />
Second part of<br />
Partner LU name<br />
Remote LU Name Partner LU name IYCKCTU1<br />
LogMode Modename Mode name Mode name Mode Name Mode name LU62PS<br />
Host<br />
system<br />
control<br />
point name<br />
— CP Name — — — —<br />
IBM eNetwork Communications Server<br />
Install eNetwork Communications Server client on a machine that contains the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, which in turn communicates with the <strong>CICS</strong> server<br />
through the eNetwork Communications Server machine.<br />
For information on installing and configuring eNetwork Communications<br />
Server, and eNetwork Communications Server clients, see the IBM eNetwork<br />
Communications Server Up and Running Guide.<br />
Run Configuration to configure Global Data and the LU6.2 Server List.<br />
Setting up the eNetwork Communications Server (server): Run SNA Node<br />
Configuration to configure SNA support, define a connection and the local<br />
LU, partner LU and mode specified in the configuration file. Configure the<br />
local LU to be independent.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Configuring SNA<br />
If using a eNetwork Communications Server SNA Client, ensure that the SNA<br />
API client use check box, in the Local LU 6.2 definition panel, is selected.<br />
To enable ATI against <strong>CICS</strong> Client terminals, define the transaction program<br />
CRSR on the eNetwork Communications Server, whether or not an eNetwork<br />
Communications Server SNA Client is being used:<br />
TP name CRSR<br />
Service TP No<br />
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE<br />
Program parameters CRSR<br />
Conversation type Mapped<br />
Synchronization level<br />
Conversation security required<br />
Any<br />
No<br />
Receive_Allocate timeout 0<br />
Incoming allocate timeout default<br />
TP instance limit 1<br />
PIP allowed No<br />
For SNA Client use Yes/No<br />
Dynamically loaded No<br />
Full duplex support No<br />
Setting up the eNetwork Communications Server Windows client: Run<br />
Configuration to configure Global Data and the LU6.2 Server List.<br />
To enable ATI against <strong>CICS</strong> Client terminals, define the transaction program<br />
CRSR on the SNA Client:<br />
TP name CRSR<br />
LU alias Alias of the local LU defined for the<br />
connection<br />
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE<br />
Program operation Attach Manager Started<br />
Program parameters CRSR<br />
Service TP No<br />
Attach Manager Started No<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 47
Configuring SNA<br />
The Attach Manager must be started.<br />
Configuration documentation: For step-by-step guidance on connecting<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, using<br />
eNetwork Communications Server, see “Sample configuration documents” on<br />
page 266.<br />
IBM eNetwork Personal Communications<br />
1. Run SNA Node Configuration to configure SNA support.<br />
2. Define a node, a device and a connection. Use an adjacent CP type of<br />
APPN Node or Back-Level LEN in the connection definition.<br />
3. Define the local LU, partner LU and mode specified in the configuration<br />
file. Configure the local LU to be independent.<br />
4. Start the node from SNA Node Operations before starting a connection<br />
from the Client daemon to a server that uses eNetwork Personal<br />
Communications.<br />
5. To enable ATI against <strong>CICS</strong> client terminals, define the transaction<br />
program CRSR:<br />
TP name CRSR<br />
Service TP No<br />
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE<br />
Program parameters CRSR<br />
Conversation type Mapped<br />
Synchronization level Any<br />
Conversation security required<br />
No<br />
Receive_Allocate timeout 0<br />
Incoming allocate timeout default<br />
TP instance limit 1<br />
PIP allowed No<br />
For SNA Client use Yes/No<br />
Dynamically loaded No<br />
Full duplex support No<br />
Running eNetwork Personal Communications: Start the IBM eNetwork<br />
Personal Communications node before you start a SNA connection from the<br />
Client daemon. The TCP62 protocol driver automatically starts the IBM<br />
Personal Communications node when a Client daemon TCP62 connection is<br />
48 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
started, if it is not already running. If the node is started automatically the<br />
default configuration file is used, if one exists. If the node is started manually<br />
and the TCP62 protocol is required, configure an AnyNet SNA/IP device,<br />
specifying the SNA domain name suffix in the Anynet domain name suffix<br />
setting in the configuration file.<br />
Configuration documentation: For step-by-step guidance on connecting<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, using<br />
eNetwork Communications Server, see “Sample configuration documents” on<br />
page 266.<br />
Microsoft SNA Server<br />
Install SNA Server client on a machine that contains the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, which in turn communicates with the <strong>CICS</strong> server through the SNA<br />
Server machine.<br />
For information on installing and configuring Microsoft SNA Server, and SNA<br />
Server clients, see the Microsoft SNA Server Installation Guide, and the Microsoft<br />
SNA Server Administration Guide.<br />
To allow workstations using the Windows SNA Client to communicate with<br />
other systems, define the LUs used by the client systems as Local APPC LUs<br />
to the SNA Server workstation.<br />
Setting up the SNA Server Windows client: On the SNA Server Windows<br />
client, enter the following:<br />
SNA client mode Remote<br />
Primary Server Name of the SNA Server workstation that the<br />
client systems using SNA Client will use. This<br />
computer name of the SNA Server is<br />
displayed in both the SNA Server Admin<br />
Servers and Connections window, and in the<br />
Network Settings control panel dialog box.<br />
To receive ATI on SNA Server Windows client terminals, run the CCLMSATI<br />
command to configure the SNA Server Client for the CRSR transaction. The<br />
syntax of the command is:<br />
CCLMSATI luname<br />
where luname is the LocalLU you are using.<br />
Configuring SNA<br />
If CRSR is already configured, the LocalLU setting changes to match the new<br />
value.<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 49
Configuring SNA<br />
Before you start the SNA Server Windows client, run SNABASE.EXE to start<br />
the SNA Server Client SnaBase. If you do not, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
cannot communicate with the SNA Server.<br />
Configuration documentation: More information on connecting <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, using SNA Server,<br />
is in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>. See also<br />
“Sample configuration documents” on page 266, for step-by-step guidance on<br />
configuration for specific scenarios.<br />
Named Pipes configuration<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can use the Windows Named Pipes protocol to<br />
communicate with TXSeries (<strong>Version</strong> 4.3 or later) for Windows NT servers that<br />
are on the same computer. This provides a fast communications method<br />
independent of any network protocol.<br />
Data conversion<br />
The following definitions are required:<br />
v The TXSeries server must have a Listener Definition for the NamedPipe<br />
protocol.<br />
v The NamedPipeName attribute must match the Named pipe name setting<br />
in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration. All other attributes can use<br />
their default values. Named pipe name must be 6 alphanumeric characters,<br />
for example, <strong>CICS</strong>CC.<br />
v The Named pipe name setting in the configuration file must match the<br />
NamedPipeName attribute in the TXSeries server Listener Definition. Use<br />
the configuration tool to select the Named pipe protocol, in the Server<br />
panel (see “Configuring Server settings” on page 76). This creates the<br />
correct settings in the configuration file including a LOCALNP Driver section<br />
with DriverName set to CCLCLPIP.<br />
The ECI and EPI allow non-<strong>CICS</strong> applications running in a client system to<br />
access <strong>CICS</strong> facilities and data managed by a <strong>CICS</strong> server system. Character<br />
data may have to be converted as it is passed between client and server; for<br />
example data is encoded in ASCII on a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system and<br />
in EBCDIC on a <strong>CICS</strong>/390 server system. Data conversion is performed by the<br />
server system. For more information on this see Appendix A, “Data<br />
conversion between the Client daemon and a <strong>CICS</strong> server” on page 251.<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 5. Configuration<br />
This chapter describes how to configure your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It<br />
consists of the following:<br />
“Before you start” on page 52 Read this for information on what to do<br />
before configuring the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
“Using the configuration tool” on page 54 Read this for general information on<br />
configuring the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, including:<br />
v How to change the default location of<br />
your configuration details<br />
v Using the Task Guide to define basic<br />
details about your <strong>CICS</strong> server and the<br />
protocols you will use<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings” on page 58<br />
“Configuring Client settings” on page 71<br />
“Configuring Server settings” on page 76<br />
“Configuring the Workload Manager” on<br />
page 84<br />
Read this if you want to allow non-<strong>CICS</strong><br />
applications written in Java to<br />
communicate with <strong>CICS</strong> servers.<br />
Read these sections if you want to set up<br />
communication with <strong>CICS</strong> servers.<br />
Read this for information on configuring<br />
the Workload Manager. The Workload<br />
Manager can help to improve<br />
performance by distributing work across<br />
<strong>CICS</strong> servers.<br />
“Editing the configuration file” on page 89 Read this if you prefer to edit the<br />
configuration file direct, rather than use<br />
the configuration tool.<br />
“Keyboard mapping for <strong>CICS</strong>TERM” on<br />
page 97<br />
“Customizing the screen colors for<br />
<strong>CICS</strong>TERM” on page 99<br />
“Preparing to use local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support” on page 101<br />
Read these sections if you intend to use<br />
<strong>CICS</strong>TERM.<br />
Read this for information on setting up<br />
your Java environment correctly.<br />
A number of sample configuration documents provide step-by-step guidance<br />
on configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers for different<br />
scenarios. If one of the documents covers your desired configuration, simply<br />
follow the instructions in it. See “Sample configuration documents” on<br />
page 266.<br />
© Copyright IBM Corp. 1996, 2002 51
Configuration<br />
Before you start<br />
See also:<br />
v IBM Redbooks (see “Redbooks” on page 267)<br />
v Chapter 4, “Setting up communication with <strong>CICS</strong> servers” on page 41<br />
This section covers some of the things you need to do before running the<br />
configuration tool. In particular, make sure that communication links with<br />
your <strong>CICS</strong> servers are correctly set up; see Chapter 4, “Setting up<br />
communication with <strong>CICS</strong> servers” on page 41.<br />
Note: You must restart the Client daemon and the <strong>Gateway</strong> daemon for any<br />
changes to the configuration file to take effect.<br />
Gather information<br />
Have the following information available:<br />
v The protocol you will use to connect to the <strong>CICS</strong> server (TCP/IP, TCP62,<br />
SNA, or Named Pipe)<br />
v The hostname or IP address of the server<br />
v The port number at the server to which the Client daemon should connect<br />
v The protocols you will use with the <strong>Gateway</strong> (TCP, SSL, HTTP and HTTPS)<br />
See Table 6 on page 42, and Table 7 on page 46, for information on matching<br />
definitions for TCP62 and SNA.<br />
Log on with administrator privileges<br />
Before you configure the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you must be logged onto<br />
the machine with Administrator privileges. You may have Administrator<br />
privileges by being a member of the local Administrators group, or by being a<br />
domain administrator.<br />
See “Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows service” on page 146<br />
for more information.<br />
Set the JVM<br />
Under Windows, it is acceptable to have more than one Java Virtual Machine<br />
(JVM) installed on a machine. If so, applications need to know which one to<br />
use. The ctgjava command allows you to view or alter the JVM used by the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Seeing which JVM is in use<br />
Issue this command to find out which JVM the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
set to use:<br />
ctgjava -v<br />
52 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Setting the JVM<br />
Issue this command to set the JVM that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses:<br />
ctgjava -s=jvmlocation<br />
where jvmlocation is the fully qualified pathname of the Java executable file.<br />
If the pathname contains spaces, enclose it in quotation marks. For example:<br />
ctgjava -s="C:\Program Files\IBM\Java13\bin\java.exe"<br />
Selecting a JVM automatically<br />
Issue this command to auto-configure the JVM for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>:<br />
ctgjava -a<br />
Set the time<br />
You must set your locale to match your timezone to get the right time. For<br />
example, if you set your locale to en_US, Java is set to the time in the United<br />
States.<br />
Configure your programming environment<br />
The Java Virtual Machine (JVM) uses the CLASSPATH environment variable<br />
to find classes, and zip or jar archives containing classes. To allow the JVM to<br />
access class files, you must specify the full path of directories containing class<br />
files or archives.<br />
To compile and run Java applications for use with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, add the full path of the following to the CLASSPATH environment<br />
variable:<br />
v ctgclient.jar<br />
v ctgserver.jar (if you are using a local gateway)<br />
v cfwk.zip (if you are using SSLight security)<br />
These archives are in the \classes subdirectory.<br />
Set the CLASSPATH<br />
Use a command like the following to set the CLASSPATH environment variable:<br />
set CLASSPATH=c:\ibmvaj\classes;\classes\ctgclient.jar;%CLASSPATH%<br />
Configuration<br />
This command makes the classes in directory c:\ibmvaj\classes, and in<br />
archive \ctgclient.jar, accessible by the JVM.<br />
You can also set and change the CLASSPATH environment variable from the<br />
Environment tab dialog in the System dialog in the Control Panel.<br />
Chapter 5. Configuration 53
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Use the following command to display the value of the CLASSPATH<br />
environment variable:<br />
set CLASSPATH<br />
Using the configuration tool<br />
Use the configuration tool to configure the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
To start the configuration tool, click the icon, or enter the ctgcfg command.<br />
The configuration tool uses the JVM specified by the ctgjava command; see<br />
“Set the JVM” on page 52.<br />
Task Guide<br />
The first time you run the configuration tool, you are asked if you want to<br />
use the Task Guide to define basic information about your system. The<br />
Task Guide allows you to enter details of your <strong>CICS</strong> servers, and enable<br />
the TCP and HTTP protocols for the Java gateway. You can change any of<br />
the settings you enter here later, through the configuration tool. You can<br />
bypass the Task Guide, and go straight to the configuration tool, by<br />
clicking No when asked if you want to use the Task Guide. You are<br />
recommended to use the Task Guide unless you use a screenreader; see<br />
“Accessibility” on page 271.<br />
For help in completing any of the screens on the Task Guide, refer to the<br />
online help, or the relevant section in “The configuration tool interface” on<br />
page 55.<br />
The configuration file<br />
Configuration details are stored by default in the CTG.INI file in the<br />
\bin subdirectory. IBM recommends that you use the<br />
configuration tool to update this file.<br />
You can specify a different path to the configuration file by setting the<br />
<strong>CICS</strong>CLI environment variable. (The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> log<br />
indicates the location of CTG.INI.) The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will not<br />
run if a configuration file is not found.<br />
The Task Guide also launches if it fails to find CTG.INI in the<br />
\bin subdirectory. If you specified a different location for<br />
the configuration file through the <strong>CICS</strong>CLI environment variable, and<br />
wish to edit an existing configuration file, click No when asked if you<br />
want to use the Task Guide. Once the configuration tool has launched,<br />
open your configuration file.<br />
Running the configuration tool on a different operating system<br />
You can use the configuration tool on any of the other <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> operating systems to generate a configuration file for your operating<br />
system. See Appendix B, “Hardware and software” on page 257 for other<br />
supported operating systems.<br />
54 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
1. Install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the workstation on which you want<br />
to run the configuration tool.<br />
2. To edit an existing configuration, copy CTG.INI to the \bin<br />
subdirectory on the workstation, using FTP in ASCII mode.<br />
3. Issue the following command:<br />
ctgcfg -PLAT WIN<br />
This makes the configuration tool run as if it is on your operating system.<br />
4. Make the required entries and click Save. This creates or updates the<br />
CTG.INI file.<br />
5. Use FTP in ASCII mode to transfer the file to your system.<br />
The configuration tool interface<br />
The screen has four input areas (described separately below):<br />
1. Menu bar<br />
2. Toolbar<br />
3. Tree structure<br />
4. Settings panel<br />
Configuration<br />
A fifth area, the status bar, shows which configuration file and operating<br />
system you are using. The status bar is display only.<br />
Chapter 5. Configuration 55
Configuration<br />
Figure 11. The configuration tool<br />
Tree structure<br />
The tree structure (see Figure 11) allows you to navigate through all of the<br />
settings in your configuration. The types of root node are as follows:<br />
Java <strong>Gateway</strong> Contains a subnode for each protocol that the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can use (TCP, SSL, HTTP, HTTPS and<br />
TCPAdmin).<br />
Client Contains a subnode for each of your server definitions.<br />
Workload Manager<br />
Contains two subnodes:<br />
Server Groups<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
Server groups are used to group together<br />
<strong>CICS</strong> server definitions with different port<br />
numbers. These server instances are used by<br />
the Workload Manager to balance workload<br />
across <strong>CICS</strong> servers. Each server group<br />
subnode contains the server definitions<br />
associated with that server group.
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Programs Contains a number of subnodes, one for each<br />
program associated with the Workload<br />
Manager. Each program subnode contains the<br />
server definitions with which the program is<br />
associated.<br />
Menu bar<br />
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.<br />
The File pulldown has the following options:<br />
New Creates a new configuration.<br />
Open Opens an existing configuration.<br />
Save Saves the current configuration. If a new configuration has<br />
been created, the file name is CTG.INI (in the<br />
\bin subdirectory).<br />
Save As Allows you to override the default path and name of the<br />
configuration file.<br />
Exit Exits the configuration tool. If you have made any alterations<br />
you are asked whether you want to save the configuration.<br />
The Edit pulldown has Cut, Copy and Paste options, which perform the<br />
standard text functions.<br />
The Tools pulldown has the following options:<br />
Trace Settings Displays the Trace Settings dialog.<br />
Task Guide Starts the Task Guide for creating new server definitions.<br />
New Server Defines a new server named A_Server, that uses the TCP<br />
protocol. Recommended for users of screenreaders and expert<br />
users; otherwise use the Task Guide option.<br />
Delete Server Deletes a server node from the tree structure.<br />
New Server Group<br />
Creates a new Server group for the Workload Manager.<br />
Delete Server Group<br />
Deletes a Server group subnode from the Workload Manager<br />
node.<br />
New Program Definition<br />
Allows you define a new program for biasing by the<br />
Workload Manager.<br />
Delete Program Definition<br />
Deletes a program subnode from the tree structure.<br />
Chapter 5. Configuration 57
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
The Settings pulldown has these options:<br />
Color Changes the background color on panels and fields. If you<br />
change the color, all fields (except check boxes and radio<br />
buttons) take on the same background color as the main<br />
panel.<br />
Font Changes the typeface, size, style and color of text.<br />
Any changes that you make to color and font settings are lost when you close<br />
the configuration tool.<br />
The Help pulldown has the following options:<br />
Context Help Displays online help information according to the current<br />
screen context, for example, for a particular configuration<br />
setting.<br />
Contents Displays the contents list for online help.<br />
Keys Help Displays information on keyboard alternatives, and other<br />
information to help users with a disability to use the software.<br />
See also “Accessibility” on page 271.<br />
Index Displays a subject index for online help.<br />
About Displays the version number and other information about the<br />
configuration tool.<br />
Toolbar<br />
The toolbar provides some of the functionality available from the menu bar in<br />
a set of icons. These icons have hover help, so that when you place the cursor<br />
over them, a text box describing the option appears.<br />
Settings panels<br />
When you select nodes in the tree structure, the relevant settings panel is<br />
displayed. The settings in these panels correspond to parameters in the<br />
CTG.INI file.<br />
On each settings panel there is an Undo Changes button that allows you to<br />
undo changes you have made.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings<br />
To display the <strong>Gateway</strong> Settings panel, select the <strong>Gateway</strong> node in the tree<br />
structure. The settings map to the parameters in the <strong>Gateway</strong> section of the<br />
CTG.INI file.<br />
Using the configuration tool, you can provide preset values for any parameter<br />
that can be specified using a <strong>Gateway</strong> command line option.<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
If a parameter defined using the configuration tool is specified via the<br />
associated command line option when the <strong>Gateway</strong> is started, the command<br />
line setting takes precedence.<br />
General <strong>Gateway</strong> settings<br />
See Figure 11 on page 56 for the screen layout. The general <strong>Gateway</strong> settings<br />
are:<br />
Initial number of Connection Manager threads: Enter the initial number of<br />
ConnectionManager threads. The default is 1.<br />
Set this to the normal number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients.<br />
You can override this setting with the ctgstart -initconnect command.<br />
Maximum number of Connection Manager threads: Enter the maximum<br />
number of ConnectionManager threads. The default is 100.<br />
This limits the maximum number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients. Set this to the maximum number of Java<strong>Gateway</strong><br />
objects that could be open at any one time from all the remotely-connected<br />
Java clients.<br />
You can override this setting with the ctgstart -maxconnect command.<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
ConnectionManager threads.<br />
For information on threading limits, see Table 3 on page 17.<br />
Configuration<br />
Initial number of Worker threads: Enter the initial number of Worker<br />
threads. The default is 1.<br />
Set this to the normal number of concurrent requests expected to be processed<br />
concurrently by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> daemon.<br />
You can override this setting with the ctgstart -initworker command.<br />
Maximum number of Worker threads: Enter the maximum number of<br />
Worker threads. The default is 100.<br />
This limits the maximum number of parallel ECI, ESI and EPI requests that<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can process. Set it to:<br />
v Less than or equal to maxconnect (for single Java<strong>Gateway</strong> programs)<br />
Chapter 5. Configuration 59
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
Worker threads.<br />
You can override this setting with the ctgstart -maxworker command.<br />
For information on threading limits, see Table 3 on page 17.<br />
Enable reading input from console: Select this check box to enable the<br />
reading of input from the console.<br />
Reading of input from the console is enabled by default.<br />
You can override this setting with the ctgstart -noinput command.<br />
Display TCP/IP hostnames: Select this check box to enable the display of<br />
TCP/IP hostnames in messages.<br />
This option allows you to choose how TCP/IP addresses are displayed in<br />
messages. By default, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> displays TCP/IP addresses<br />
in messages in numeric form. If you enable this option, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> uses the Domain Name System (DNS) to convert numeric TCP/IP<br />
addresses to symbolic TCP/IP hostnames in messages. This makes the<br />
messages easier to read.<br />
Note: Selecting this option might cause severe performance reduction on<br />
some systems.<br />
Let Java clients obtain generic ECI replies: Select this check box if you wish<br />
Java clients to be able to obtain generic ECI replies from the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Generic replies are those obtained using the Call_Type: ECI_GET_REPLY or<br />
ECI_GET_REPLY_WAIT. Specific replies are those obtained using the<br />
Call_Type: ECI_GET_SPECIFIC_REPLY or ECI_GET_SPECIFIC_REPLY_WAIT.<br />
This setting does not apply to local <strong>Gateway</strong>s.<br />
Validate Units of Work: Select this check box if you want the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to validate logical units of work (LUWs). This ensures<br />
that a LUW ID can be used only on the Java<strong>Gateway</strong> connection to which it<br />
was allocated. If you clear this check box, you disable validation:<br />
v LUWs can be accessed by any connection to the same remote <strong>Gateway</strong>.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> cannot clean up used LUWs when a<br />
connection is closed or breaks.<br />
The default is that LUW validation is enabled.<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Validate message qualifiers: Select this check box if you want the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to validate message qualifiers. This ensures that a<br />
message qualifier ID can be used only on the Java<strong>Gateway</strong> connection to<br />
which it was allocated. A message qualifier that has been assigned on an<br />
asynchronous call cannot be used by any connection using the same remote<br />
<strong>Gateway</strong> until the reply has been received.<br />
If you clear this check box, you disable validation:<br />
v ECI asynchronous calls tagged with a message qualifier on one connection<br />
can have a call of the GET_SPECIFIC_REPLY type made from another<br />
connection to the same remote gateway.<br />
v The same message qualifier can be used on an asynchronous call even if a<br />
reply with that message qualifier is still outstanding in the remote <strong>Gateway</strong>.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> cannot clean up used message qualifiers<br />
when a connection is closed or breaks. In some circumstances logical units<br />
of work (LUWs) will also not be cleaned up: because the <strong>Gateway</strong> cannot<br />
clean up the message qualifier, it cannot determine if the LUW is still<br />
active.<br />
The default is that message qualifier validation is enabled.<br />
Log client connections and disconnections: Select this check box if you want<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to write a message to the log each time that a<br />
client application program connects to, or disconnects from, the <strong>Gateway</strong><br />
daemon. The default is for these messages not to be written.<br />
Timeout for in-progress requests to complete (ms): Enter a value in<br />
milliseconds.<br />
When a Java-client program disconnects from the <strong>Gateway</strong>, the <strong>Gateway</strong> may<br />
still be processing requests on behalf of that program. If work is still in<br />
progress, the ConnectionManager that was managing requests on behalf of<br />
that Java-client waits for the requests to complete for up to the timeout<br />
period. If there are still requests in progress after the timeout has expired, the<br />
ConnectionManager continues its processing and marks itself as available for<br />
use by a new connection. The default timeout is 10 000 milliseconds, but you<br />
may enter a value to override the default.<br />
If this value is set to zero, the ConnectionManager does not wait for<br />
in-progress requests to complete.<br />
Worker thread available timeout (ms): Enter a value in milliseconds.<br />
Configuration<br />
When a ConnectionManager accepts a request, it must allocate a Worker<br />
thread to execute that request. If a Worker does not become available within<br />
Chapter 5. Configuration 61
Configuration<br />
Figure 12. TCP settings<br />
the timeout period, an error message is sent rejecting that request and the<br />
request is not executed. The default timeout is set to 10 000 milliseconds, but<br />
you can enter a value to override that default.<br />
If you set this value to zero, the request is rejected unless a Worker is<br />
immediately available.<br />
TCP protocol settings<br />
Select the TCP subnode to display the settings for TCP:<br />
Enable protocol handler: Select this check box to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for use with this protocol.<br />
Port: Enter the TCP/IP port number.<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
The default port for TCP/IP is 2006.<br />
You can override this setting with the ctgstart -port command.<br />
Handler wakeup timeout (ms): Enter a value in milliseconds.<br />
This setting controls how frequently the protocol handler wakes from<br />
accepting inbound connections. When it wakes, it checks to see whether the<br />
<strong>Gateway</strong> is being stopped, and so this value affects the time taken for the<br />
<strong>Gateway</strong> to shutdown cleanly. If you set this value to zero then the handler<br />
only wakes when a new connection is accepted, and so the <strong>Gateway</strong> will not<br />
shutdown cleanly until that time.<br />
Connection timeout (ms): Enter a value in milliseconds.<br />
When a new connection has been accepted, this value specifies how long the<br />
protocol handler waits for a ConnectionManager thread to become available.<br />
If a ConnectionManager thread does not become available within this time,<br />
then the connection is refused. If this value is set to zero, a connection is<br />
refused if a ConnectionManager is not immediately available.<br />
Idle timeout (ms): Enter a value in milliseconds.<br />
This setting specifies how long a connection is allowed to remain dormant.<br />
The idle timeout period is counted from when a request was last flowed<br />
down the connection. When the idle timeout has expired, the connection is<br />
disconnected, though if work is still in progress on behalf of the connection, it<br />
may be left connected. If this value is not set, or is set to zero, then idle<br />
connections will not be disconnected.<br />
Cleanup processing will only result after a timeout if the server has support<br />
for this function installed.<br />
Ping time frequency (ms): Enter a value in milliseconds.<br />
Configuration<br />
This value specifies how often a PING message is sent by the <strong>Gateway</strong> to an<br />
attached client to check that client is still active. If a PONG response has not<br />
been received by the time the next PING message is due to be sent, then the<br />
connection is disconnected. Again, if work is still in progress on behalf of the<br />
connection it may (depending on the drop working connections value setting)<br />
be left connected. If this value is not set, or is set to zero, then PING messages<br />
are not sent.<br />
Drop working connections: Select this check box to specify that a connection<br />
can be disconnected, due to an idle timeout or a PING/PONG failure even if<br />
work is still in progress on behalf of this connection.<br />
Chapter 5. Configuration 63
Configuration<br />
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this<br />
handler. The SO_LINGER setting specifies a delay value in seconds for closing<br />
a socket. If this value is not entered, or set to zero, then SO_LINGER is<br />
disabled for any sockets used by this protocol handler.<br />
If SO_LINGER is enabled, and data transmission has not finished, a Close call<br />
blocks the calling program until the data is transmitted or until the connection<br />
times out. If SO_LINGER is disabled, a Close call returns without blocking the<br />
caller and TCP/IP still tries to send the data. Normally this transfer is<br />
successful, but it cannot be guaranteed, because TCP/IP repeats the Send<br />
request for only a specified period of time.<br />
Require clients to use security classes: Select this check box if you wish<br />
your <strong>Gateway</strong> to accept only connections that use security classes.<br />
When a Java-client program connects to the <strong>Gateway</strong>, it can specify a pair of<br />
security classes for use on the connection. However, by default a <strong>Gateway</strong><br />
also accepts connections from programs that do not specify this pair of<br />
security classes.<br />
For more information on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security exits, see<br />
“Security exits” on page 12.<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Figure 13. SSL settings<br />
SSL protocol settings<br />
Configuration<br />
Select the SSL subnode to display the settings for SSL. The settings are the<br />
same as for TCP except that the default port is 8050, and SSL also has the<br />
following settings:<br />
Use client authentication: Select this check box to enable client<br />
authentication for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The default is that client<br />
authentication is disabled.<br />
When client authentication is enabled, any connection attempted to either the<br />
ssl: or https: handler requires the client to present its own Client Certificate<br />
(also known as a Digital ID).<br />
For information on how to obtain Client Certificates for the clients, see<br />
“Configuring your SSL clients” on page 108.<br />
Chapter 5. Configuration 65
Configuration<br />
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,<br />
or the server KeyStore name for JSSE.<br />
For a KeyRing, do not include the .class file extension in the classname.<br />
For a KeyStore, give either the full path name, or the relative path name of<br />
the file. Use either a forward slash (/) character, or double back slash (\\)<br />
characters, as a separator in the path name on all operating systems. For<br />
example:<br />
c:/mykeys/jsse/keystore.jks<br />
c:\\mykeys\\jsse\\keystore.jks<br />
The server KeyRing or KeyStore consists of a valid x.509 certificate that<br />
identifies this server to connecting clients. This KeyRing or KeyStore is<br />
generated using the SSL tools supplied with this product.<br />
For more information about SSL and its associated KeyRings or KeyStores, see<br />
Chapter 6, “Network Security” on page 103.<br />
KeyRing or Keystore password: Enter the password that you specified for<br />
the server KeyRing or KeyStore.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the password to the configuration file in a<br />
form that prevents a casual observer from easily reading it.<br />
66 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Figure 14. HTTP settings<br />
HTTP protocol settings<br />
Select the HTTP subnode to display the settings for HTTP. The settings are<br />
the same as for TCP.<br />
The default port for HTTP is 8080.<br />
Configuration<br />
Chapter 5. Configuration 67
Configuration<br />
Figure 15. HTTPS settings<br />
HTTPS protocol settings<br />
Select the HTTPS subnode to display the settings for HTTPS. The settings are<br />
the same as for HTTP except that HTTPS also has Use client authentication,<br />
KeyRing or Keystore name, and KeyRing or Keystore password settings. See<br />
“SSL protocol settings” on page 65 for details.<br />
The default port for HTTPS is 443. However, on some operating systems,<br />
processes require special privileges to access port numbers between 1 and<br />
1024. If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> without these required<br />
privileges, change the port number to a value greater than 1024.<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Figure 16. TCPAdmin settings<br />
TCPAdmin protocol settings<br />
Configuration<br />
Select the TCPAdmin subnode to display the settings for administration. The<br />
settings are the same as for TCP except for the following:<br />
v The default port is 2810<br />
v There is no Require clients to use security classes field.<br />
v TCPAdmin also has the following settings:<br />
Max dedicated connections: Enter a value specifying the maximum number<br />
of simultaneous dedicated client connections that can be made to the <strong>Gateway</strong><br />
administration handler.<br />
Authorized Hosts: Enter a host name or IP address in the entry field. Click<br />
Add to add the host to the Authorized Hosts list, below the entry field. Click<br />
Remove to remove all selected hosts from the Authorized Hosts list.<br />
Chapter 5. Configuration 69
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
If there are entries in the Authorized Hosts list, only those hosts are allowed<br />
to access the administration protocol handler. Be aware: If the list is empty, all<br />
hosts are allowed access.<br />
The default entry is 127.0.0.1, which represents the host on which the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is installed. IP address 127.0.0.1 and the host name<br />
localhost are considered to be different from the real IP address or host name<br />
of the system.<br />
For information about administering your system, see “Administering your<br />
system” on page 149.<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Configuring Client settings<br />
Figure 17. Client settings<br />
Select the Client node to display the Client Settings panel. The settings map<br />
to the parameters in the Client section of the CTG.INI file.<br />
Default Server<br />
Select the default server from the drop-down list.<br />
Applid<br />
Enter up to 8 characters, or leave this field with the default value of *.<br />
Configuration<br />
This value specifies the applid of the <strong>CICS</strong> Universal Client workstation in the<br />
form in which it will be autoinstalled as a system at the <strong>CICS</strong> server. The<br />
name must be unique within the <strong>CICS</strong> server system. The value of *<br />
automatically generates a name that is guaranteed to be unique.<br />
Chapter 5. Configuration 71
Configuration<br />
Note: If the client is to be autoinstalled to more than one <strong>CICS</strong> server, and if<br />
you enter a specific name for the applid, that name must be unique<br />
with respect to all servers it is connected to. If the name is not unique,<br />
then attempts to connect to a server may be rejected because another<br />
client has already been installed using the same name. If a name of * is<br />
used, the client may be known by a different unique name at each<br />
server.<br />
If the client is to communicate with a given server via SNA, this applid may<br />
be overridden at the time the client is installed at the server by the Local LU<br />
name for the client.<br />
Maximum buffer size<br />
Enter a number of kilobytes, in the range 4 through 32. The default is 32 KB.<br />
This value specifies the size of the transmission buffers in which application<br />
or terminal data will flow. The value should be large enough to cater for the<br />
largest possible COMMAREA or terminal input/output area (TIOA) to be<br />
used. The value does not include an overhead of 512 bytes needed by the<br />
clients for some protocols.<br />
Leave this setting at the default unless the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running on a machine that is short of memory.<br />
Terminal exit<br />
Enter a character string of between 1 and 4 characters. The default is EXIT.<br />
The string, when entered at a terminal emulator at any time and place where<br />
a transaction name can be entered, causes the terminal emulator to terminate.<br />
The string must not contain any blank characters.<br />
The string is case-sensitive. If a terminal emulator has uppercase translation in<br />
its <strong>CICS</strong> terminal definition, enter this string in uppercase.<br />
Maximum servers<br />
Enter a value in the range 1 through 256. The default is 10.<br />
This value specifies the maximum number of servers that can be accessed<br />
concurrently from the client.<br />
Maximum requests<br />
Enter a value in the range 1 through 10 000. The default is 256.<br />
This value specifies the maximum number of concurrent items that may be<br />
executing on the Client daemon, where an item is one of:<br />
v a terminal emulator<br />
72 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
v an EPI terminal<br />
v an ECI unit of work<br />
v an ESI unit of work<br />
It is used to detect runaway conditions where an application could, in error,<br />
submit an excessive number of requests to a server. The actual limit may be<br />
less than this setting if other operating system limits (for example, memory<br />
constraint or communication sessions), come into effect.<br />
Print command<br />
Enter a character string, from 1 to 256 characters long.<br />
The specified string is a command specific to the operating system under<br />
which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running. When a request to print is<br />
received, the Client daemon generates a temporary print file with a unique<br />
name.<br />
The parameter string is appended with the temporary file name, and the<br />
resultant command executed. This allows, for example, print requests to be<br />
copied to a file, directed to a local printer, formatted for inclusion into<br />
documentation, and so on.<br />
A command file may be necessary to act as an interface between the syntax of<br />
the invocation command defined here, and more general operating system<br />
syntax. For example, if the desired final command was COPY printfile LPT2, a<br />
simple command file would be required to reorder the parameters. It is the<br />
responsibility of the Print Command to delete the temporary print file after it<br />
has finished processing it.<br />
You may specify only a local executable in this field. UNC paths of the type<br />
\\User1\Share\Notepad.exe do not work, due to the system limitations of<br />
running executables that are installed on one machine on a different machine.<br />
See also the Print file description for more information.<br />
Print file<br />
Enter a character string, 1 to 256 characters long.<br />
Configuration<br />
This option applies only if you make no entry in the Print Command setting.<br />
The specified string identifies a file to which output from print requests<br />
received at the Client daemon is directed. Each print request is appended to<br />
the end of the current file.<br />
If both this setting and Print command are omitted, the default action is to<br />
direct the print data to LPT1.<br />
Chapter 5. Configuration 73
Configuration<br />
Note: This setting acts only as a default. The terminal and print emulators<br />
provide options to override this value.<br />
Codepage identifier override<br />
Enter a value indicating a Coded Character Set Identifier (CCSID) to override<br />
your local codepage identifier.<br />
Use this setting if your platform has been updated for Euro support, and the<br />
<strong>CICS</strong> Server has Euro support. For example, for Latin-1 countries, use a<br />
CCSID value of 858 to indicate that the codepage 850 includes Euro support.<br />
For codepage 1252, specify a CCSID value of 5348.<br />
Notes:<br />
1. Regardless of the value in the Codepage identifier override setting,<br />
cicsterm always displays characters based on the local codepage of the<br />
workstation.<br />
2. If you use the CCSID to change the codepage identifier, data that is<br />
already stored on the server may be modified when retrieved by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, if it includes characters for which the code points<br />
produce different characters.<br />
3. You do not have to supply a CCSID, as you can use the Use OEM<br />
codepage setting to provide support for Euro enabled codepages. Any<br />
value that you enter in the Codepage identifier override field overrides<br />
the codepage value generated using the Use OEM codepage setting. You<br />
might do this, for example, to switch back to codepage 850 or 1252 to<br />
indicate to the <strong>CICS</strong> server that the Euro should not be used.<br />
For more information on CCSIDs and data conversion, refer to Appendix A,<br />
“Data conversion between the Client daemon and a <strong>CICS</strong> server” on page 251.<br />
Server retry interval<br />
Enter a number of seconds. This is the time in seconds between attempts by<br />
the Client daemon to reconnect to a server. The default is 60 seconds.<br />
When the Client daemon becomes aware that a server to which it was<br />
connected is no longer active, it attempts to reconnect to the server 1 second<br />
after it becomes inactive. If it fails it keeps trying, at the interval specified<br />
here.<br />
Log file<br />
Enter the name of the log file to be used for problem diagnosis.<br />
If not specified, the log filename defaults to <strong>CICS</strong>CLI.LOG in the<br />
\bin subdirectory.<br />
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
IBM recommends that you specify a ctglog subdirectory in a directory to<br />
which all users have write access. For example, on Windows NT systems:<br />
C:\Winnt\Profiles\All Users\Application Data\ctglog<br />
or, Windows 2000 and Windows XP systems:<br />
C:\Documents and Settings\All Users\Application Data\ctglog<br />
Configuration<br />
All users can read the log file. In a Windows secured environment, if the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is running as a service, you may want to alter the<br />
permissions of this directory to prevent users writing to the log files.<br />
Enable popups<br />
Select this check box to enable the display of popup messages at startup.<br />
You can also change this setting dynamically by using the E and N options<br />
with the <strong>CICS</strong>CLI command; see “The <strong>CICS</strong>CLI command” on page 156.<br />
Use OEM codepage<br />
Select this check box if you want the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to call the<br />
Windows operating system OEM codepage function to get the codepage<br />
identifier (for example, 850). If the workstation is Euro enabled, then codepage<br />
850 is mapped to 858 within the client to indicate to the <strong>CICS</strong> Server that the<br />
Euro symbol can be used.<br />
If you do not select this check box, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses the<br />
Windows operating system ACP function to get the ASCII identifier (for<br />
example 1252). Use this to provide appropriate conversions for Latin-1,<br />
Japanese, Korean and Simplified Chinese systems. If the workstation is Euro<br />
enabled, codepage 1252 is mapped to codepage 5348.<br />
For more information on codepages and data conversion, refer to Appendix A,<br />
“Data conversion between the Client daemon and a <strong>CICS</strong> server” on page 251.<br />
Chapter 5. Configuration 75
Configuration<br />
Configuring Server settings<br />
Figure 18. Server settings<br />
Select a server in the tree structure to display the Server Settings panel. The<br />
settings map to the parameters in a Server section of the CTG.INI file.<br />
Server name<br />
Enter a name of between 1 and 8 characters. This provides a<br />
communications-protocol-independent name for the server, local to the Client<br />
daemon.<br />
Requests to access the server from ECI, EPI, ESI, or terminal emulators<br />
reference the server through this name.<br />
Description<br />
Enter a description for the server of between 1 and 60 characters. This<br />
description is optional.<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
The description is returned to applications running on the Client daemon by<br />
the <strong>CICS</strong>_EpiListSystems and <strong>CICS</strong>_EciListSystems functions.<br />
Initial transaction<br />
Enter a transaction identifier of between 1 and 128 characters.<br />
This string is case-sensitive and identifies the initial transaction (and any<br />
parameters) to be run when the terminal emulator connects to the server. If<br />
you do not enter anything, no initial transaction is run. The first four<br />
characters, or the characters up to the first blank in the string are taken as the<br />
transaction. The remaining data is passed to the transaction on its invocation.<br />
Model terminal definition<br />
Enter a string of between 1 and 16 characters.<br />
The string is case-sensitive and specifies the name of a model terminal<br />
definition at the server, identifying the characteristics of terminals to be<br />
autoinstalled from the client. If the model cannot be located at the server, or<br />
you do not enter anything, a default terminal definition is used. This default<br />
is server-specific.<br />
The interpretation of the Model terminal definition setting is server-specific.<br />
For example,for a TXSeries for AIX server, the value is 1 to 16 characters, and<br />
is the DevType for a <strong>CICS</strong> terminal definition entry to be used as the model.<br />
Use Windows credentials for security<br />
Select this check box if you want to use the Windows NT password for <strong>CICS</strong><br />
security.<br />
To use this feature, do the following from a command prompt:<br />
1. Change to directory<br />
\Program Files\Common Files\IBM\IBM Integrated Sign On<br />
2. Enter bthdinst -i <strong>CICS</strong>CLI<br />
3. Reboot.<br />
When uninstalling you must uninstall in the following sequence:<br />
1. Change to directory<br />
\Program Files\Common Files\IBM\IBM Integrated Sign On<br />
2. Enter bthdinst -u <strong>CICS</strong>CLI<br />
3. Reboot<br />
4. Uninstall in the usual way.<br />
For more information, refer to “Network Provider Interface (NPI)” on<br />
page 126.<br />
Configuration<br />
Chapter 5. Configuration 77
Configuration<br />
Use upper case security<br />
Select this check box to specify that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> converts to<br />
uppercase any userid or password from an ECI application or from a user<br />
prompt.<br />
With this setting selected, you can enter userids and passwords in either<br />
uppercase or lowercase. This setting is disabled by default.<br />
Network protocol<br />
Select from the drop-down list the protocol to be used for the server<br />
connection:<br />
v TCP/IP<br />
v SNA<br />
v TCP62<br />
v Named Pipe<br />
Protocol settings displayed on the panel change according to the protocol you<br />
select.<br />
TCP/IP settings<br />
Hostname or IP address: Enter the character or numeric TCP/IP identifier<br />
for the host on which the <strong>CICS</strong> server is running. For example,<br />
cicssrv2.company.com (hostname) or 192.113.36.200 (IP Address).<br />
Hostnames are mapped to IP addresses either by the name server or in the<br />
hosts system file. It is better to use a hostname in case the IP address<br />
changes.<br />
The hosts system file is in the %windir%\system32\drivers\etc directory.<br />
Port: Enter a numeric value in the range 0 through 65 535 defining the port<br />
number at the server to which the Client daemon should connect. The default<br />
value is 0.<br />
A value of 0 indicates that the services system file should be used to locate<br />
the port number for the <strong>CICS</strong> service using the TCP protocol.<br />
The services system file is in the %windir%\system32\drivers\etc directory.<br />
If no entry can be located in the services system file, a value of 1435 is<br />
assumed. This is the port assigned to the Client daemon in the TCP/IP<br />
architecture.<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Connection timeout: Enter a value in the range 0 through 3600, specifying<br />
the maximum time in seconds that establishing a connection is allowed to<br />
take; the default value of 0 means that no limit is set by the Client daemon.<br />
A timeout occurs if connection establishment takes longer than the specified<br />
time. The TCP/IP socket is closed and the return code passed back to the<br />
client application is either ECI_ERR_NO_<strong>CICS</strong> or <strong>CICS</strong>_EPI_ERR_FAILED.<br />
Cleanup processing happens after a timeout only if the server has support for<br />
this function installed.<br />
Send TCP/IP Keepalive packets: Select this check box if you want TCP/IP<br />
to periodically send KeepAlive packets to the server to check the connection.<br />
SNA settings<br />
Use LU alias names: Select this check box to use LU alias names.<br />
Selecting this setting enables you to specify the Partner LU name and Local<br />
LU name as aliases instead of real LU names.<br />
An alias is a short name that you can use instead of the full partner LU name.<br />
The SNA server maps these aliases to full partner LU names. This means, for<br />
example, that you can switch between servers, without stopping the Client<br />
daemon, by changing the name that an alias resolves to in the SNA server.<br />
The default is that LU alias names are not used.<br />
Partner LU name: Enter the LU Name of the server as it is known to the<br />
APPC configuration at the Client daemon.<br />
This must be an eight-character alias name.<br />
This can be a qualified 17-character name, for example, ABC3XYZ4.PQRS1234.<br />
Alternatively, you can enter an alias name, as long as Use LU alias names is<br />
selected.<br />
Local LU name: Enter the name of a local LU to be used when connecting to<br />
the server. The same LU can be used for all server connections.<br />
This must be an eight-character alias name.<br />
Configuration<br />
You can enter an alias name, provided that Use LU alias names is selected.<br />
Mode name: Enter between 1 and 8 characters specifying the mode name to<br />
be used when connecting to the server.<br />
Chapter 5. Configuration 79
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Enter * if you want the mode name to be filled with spaces.<br />
TCP62 settings<br />
hosts file: When configuring a TCP62 <strong>CICS</strong> server, you must also update the<br />
local hosts file. The path to the file is:<br />
%windir%\system32\drivers\etc\hosts<br />
The file maps IP addresses to host names. Keep each entry on a<br />
separate line. Entries are in this form:<br />
192.113.36.200 <strong>CICS</strong>A.NYEBO.myplace.ibm.com<br />
Each element of the entry is explained below:<br />
192.113.36.200<br />
The IP address of the <strong>CICS</strong> system. It must start in column<br />
one, and be separated from the rest of the entry by at least one<br />
space.<br />
<strong>CICS</strong>A.NYEBO<br />
The Partner LU name, in reverse order. In the example above,<br />
NYEBO.<strong>CICS</strong>A is the Partner LU name, as entered in the<br />
Configuration tool.<br />
myplace.ibm.com<br />
The Anynet domain name suffix.<br />
Multiple server definitions with identical combinations of Local LU, Partner<br />
LU, and Mode name are not permitted in CTG.INI in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>. This ensures that every connection that the <strong>CICS</strong> region<br />
and the network protocol see is represented by a unique server definition in<br />
the configuration file. Existing Client applications that use different server<br />
names to send requests to the same <strong>CICS</strong> region continue to work if a user<br />
exit is defined to redirect requests. A sample user exit that does this is<br />
provided; see \samples\samples.txt.<br />
Partner LU name: Enter the LU Name of the server as it is known to the<br />
SNA configuration at the client. This must be a qualified 17-character name,<br />
for example, ABC3XYZ4.PQRS1234.<br />
Local LU name or template: Enter a real LU name or a template for the<br />
name of a local LU to be used when connecting to the <strong>CICS</strong> server.<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
If you enter a template, you must fill in the IP address mask for LU name<br />
template (optional) field.<br />
A template contains replacement characters, that is, asterisks (*), and is used<br />
to generate an LU name dynamically. For example, a template of CTS8BC**<br />
indicates that a name must be dynamically generated to replace the two<br />
asterisks. An algorithm based on the template, IP address mask, and the<br />
workstation IP address, is used to create a unique Local LU name of, for<br />
example, CTS8BC38.<br />
To use a template you must configure your <strong>CICS</strong> server to install connections<br />
dynamically.<br />
With dynamic name generation for the Local LU name, you can use the same<br />
configuration on all <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machines because different<br />
Local LU names are generated on the basis of the IP address of the client<br />
machine. Therefore, you do not have to define multiple LUs within VTAM.<br />
If several hundred clients are to use dynamic LU name generation to connect<br />
to the <strong>CICS</strong> server, you should have more template replacement characters in<br />
your Local LU name, for example, CTS8****. In fact, <strong>CICS</strong> <strong>Transaction</strong> Server<br />
for z/OS uses the last four characters of the LU name as the connection name,<br />
so these characters must be unique.<br />
IP address mask for LU name template (optional): Enter an IP address mask<br />
in big-endian, that is, most significant byte first order. This must be a<br />
hexadecimal number, for example, FFFFFF80.<br />
This address mask is used in dynamic LU name generation. See the<br />
description of Local LU name or template for more information.<br />
This parameter is ignored if Local LU name is not a template. The default is<br />
00000000.<br />
Mode name: Enter between 1 and 8 characters specifying the mode name to<br />
be used when connecting to the server.<br />
Enter * if you want the mode name to default to TCP62.<br />
Configuration<br />
Use the Maximum logical SNA sessions, Maximum SNA RU size, and SNA<br />
pacing size settings to define the mode values specified for the Mode name<br />
on your <strong>CICS</strong> server.<br />
Chapter 5. Configuration 81
Configuration<br />
Common TCP62 settings<br />
Fully qualified CP name or template: Enter a fully-qualified CP name, or a<br />
template for the fully-qualified CP name, of the node to be started.<br />
If you enter a template, you must fill in the IP address mask for CP name<br />
(optional) field.<br />
A template contains replacement characters, that is, asterisks (*), and is used<br />
to generate a CP name dynamically. For example, a template of<br />
USIBMJKA.CP62**** indicates that a name must be dynamically generated to<br />
replace the four asterisks. An algorithm based on the template, IP address<br />
mask and the workstation IP address, is used to create a unique CP name of,<br />
for example, USIBMJKA.CP62AH38.<br />
With dynamic name generation for the CP name, you can use the same<br />
configuration on all <strong>CICS</strong> Client machines because different CP names are<br />
generated on the basis of the IP address of the client machine. Therefore, you<br />
do not have to define multiple CPs to VTAM.<br />
If several hundred clients are to use dynamic CP name generation, you should<br />
have more template replacement characters in your template, for example,<br />
USIBMJKA.CP******.<br />
The net ID part (the first part) of the template must not contain any template<br />
replacement characters.<br />
IP address mask for CP name (optional): Enter an IP address mask in<br />
big-endian, that is, most significant byte first order. This must be a<br />
hexadecimal number, for example, FFFF8080.<br />
This address mask is used in dynamic CP name generation. See the<br />
description of Fully qualified CP name or template for more information.<br />
This parameter is ignored if Fully qualified CP name or template is not a<br />
template. The default is 00000000.<br />
Anynet domain name suffix: Enter the AnyNet ® domain name suffix. This<br />
parameter is used with the partner (Partner LU name) to determine the IP<br />
address of the host associated with that LU.<br />
For example, if the domain name suffix is sna.ibm.com and the partner LU<br />
name is NETID.LUA a gethostbyname call is issued for hostname<br />
LUA.NETID.sna.ibm.com to obtain the IP address of the node that has the LU<br />
name NETID.LUA.<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
See “TCP62 settings” on page 80, for information on how IP addresses map to<br />
host names.<br />
TCP62 port: Enter a number between 0 and 65535 to set the port number on<br />
the server to which the Client daemon connects.<br />
The default value is 0. This means that the Client daemon uses port 397, the<br />
default port for the TCP/IP service MPTN.<br />
You must configure your <strong>CICS</strong> server with the same port number.<br />
Remote node inactivity poll interval: Enter a number of seconds between 0<br />
and 65535. The default value is 60 seconds. A value of 0 turns off polling.<br />
This configuration setting controls the time that the Client daemon waits<br />
before polling inactive connections.<br />
The Client daemon polls inactive connections by sending MPTN keepalive<br />
datagrams by User Datagram Protocol (UDP) to the <strong>CICS</strong> server. If the Client<br />
daemon receives no response after it has sent several datagrams, it closes the<br />
connection with <strong>CICS</strong>. For more information on MPTN keepalives, see an<br />
Anynet publication such as Anynet: Guide to SNA over TCPIP, SC31-8578-00.<br />
Advanced TCP62 settings<br />
Maximum logical SNA sessions: Enter a value in the range 1 through 255.<br />
The default value is 8.<br />
This parameter defines the maximum number of logical SNA sessions<br />
allowed. The number of concurrent transactions that can exist for a client is<br />
restricted by the number of client contention winners available on the session.<br />
For example, if the maximum number of sessions is 8, and the server has 1<br />
contention winner, the client is left with 7 contention winners. This allows 7<br />
concurrent transactions.<br />
Maximum SNA RU size: Enter a value in the range 256 through 4096. You<br />
are recommended to use the default value of 1024.<br />
This parameter specifies the maximum size of the request or response units<br />
sent over sessions.<br />
SNA pacing size: Enter a value in the range 0 through 63. You are<br />
recommended to use the default value of 8.<br />
Configuration<br />
This parameter specifies how many request units can be sent before receiving<br />
a pacing response.<br />
Chapter 5. Configuration 83
|<br />
|<br />
|<br />
Configuration<br />
Named pipe settings<br />
Named pipe name: Enter a name of up to six alphanumeric characters that<br />
match the NamedPipeName attribute specified by the TXSeries for Windows<br />
NT server in its Listener Definition.<br />
Configuring the Workload Manager<br />
To display the Workload Manager Settings panel, select the Workload<br />
Manager node in the tree structure. Most settings map to the parameters in<br />
the LOADMANAGER section of the CTG.INI file, although the Workload<br />
Manager also uses the REGION parameter in the SERVER section.<br />
It is recommended that you read Chapter 12, “Workload Manager” on<br />
page 179, before configuring the Workload Manager. That chapter explains<br />
important concepts, such as server groups, and the behaviour of the workload<br />
balancing algorithms.<br />
Enable the Workload Manager<br />
Select this check box to enable the Workload Manager. The default is that the<br />
Workload Manager is disabled.<br />
Round robin<br />
Select this radio button to select a round-robin algorithm for this server.<br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Biasing<br />
Select this radio button to select a biased algorithm for the Workload<br />
Manager.<br />
Configuration<br />
Region timeout (s)<br />
Enter a value in seconds between 0 and 3600. The default is 60 seconds.<br />
When a <strong>CICS</strong> server (region) is selected as the target of a client request, and<br />
that server is unavailable, the server is flagged as invalid, and is no longer<br />
included in the list of target regions for requests. The Region timeout (s) value<br />
specifies the number of seconds after which an invalid region can once more<br />
be included in the list of target regions.<br />
Two options on the Tools menu allow you to configure server groups and<br />
programs. These options are only enabled when you select the Workload<br />
Manager node.<br />
Configuring a server group<br />
This panel allows you to define which servers belong to a particular server<br />
group.<br />
To add a new server group, you select the New Server Group option, or click<br />
the New Server Group icon, and enter a name in the Server group name<br />
field.<br />
To change the members of a server group, select the server group from the<br />
tree selection.<br />
To add a server to a group, select from the Servers not in server group list on<br />
the right and then select the arrow button ().<br />
Configuring programs<br />
This panel allows you to define the workload management for a particular<br />
program. If the round-robin algorithm is selected, you define which servers<br />
are valid for the program. If the biasing algorithm is selected, you define<br />
which servers are used for biasing.<br />
Workload management for particular programs is available only for ECI, and<br />
not for EPI or <strong>CICS</strong>TERM.<br />
To add a new definition, you select the New Program Definition option, or<br />
click the New Program Definition icon, and enter a name in the Program<br />
name field.<br />
Chapter 5. Configuration 85
Configuration<br />
To change a definition, select the program from the tree selection.<br />
To disable workload management for the program, deselect the Manage<br />
workload for this program check box.<br />
If the round-robin algorithm is selected: To add a server to the list of<br />
servers for which the program is valid, select from the Servers not valid for<br />
this program list on the right and then select the arrow button ().<br />
If the biasing algorithm is selected: To add a server to the list of servers<br />
used for biasing, select from the Servers not used for biasing list on the right<br />
and then select the arrow button ().<br />
In the Bias value fields, you can enter a bias value for the server.<br />
In the Ratios fields, percentage bias values for each server are shown. This<br />
field contains Standby if the bias value is 0, which means use only if no other<br />
server is available.<br />
Manage workload for this program<br />
Select this check box if you want to enable load balancing for the selected<br />
program.<br />
If you disable load balancing for a particular program, the Workload Manager<br />
connects to the server specified in the ECI call, rather than randomly selecting<br />
a new server.<br />
Trace settings<br />
To configure the trace settings, select the Trace Settings option from the Tools<br />
menu.<br />
Trace Settings<br />
Select check boxes to specify the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and Client<br />
daemon components that will be traced when tracing is turned on.<br />
Trace everything<br />
All components.<br />
Client API level 1<br />
The client API layer (level 1).<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Client API level 2<br />
The client API layer (level 1 and 2).<br />
<strong>CICS</strong>CLI command line<br />
The cicscli command interface.<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRINT<br />
cicsterm and cicsprnt emulators.<br />
CPP classes<br />
The C++ class libraries.<br />
Client daemon<br />
The Client daemon.<br />
Transport layer<br />
Interprocess communication.<br />
<strong>Gateway</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
JNI Trace<br />
You cannot enable JNI trace through the configuration tool. Use one of<br />
the following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
Configuration<br />
where filename is the name of the file to which trace output is to be<br />
sent.<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin<br />
protocol handler (see “TCPAdmin protocol settings” on page 69). See<br />
“Administering your system” on page 149 for details of how to enable<br />
JNI trace dynamically.<br />
v For Java Client applications running in local mode, use Java to launch<br />
your application and set the system property gateway.T.setJNITFile, as<br />
shown in the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
Chapter 5. Configuration 87
Configuration<br />
Protocol drivers level 1<br />
Protocol drivers (for example, TCP). This traces data sent and received<br />
and provides supplementary information about failures.<br />
Protocol drivers level 2<br />
This traces internal flows through the protocol drivers and interactions<br />
with other software components. It is currently only supported by the<br />
CCLTCP62 protocol driver.<br />
Workload manager<br />
The Workload Manager.<br />
You can also use the M option with the cicscli command to specify trace<br />
components (excluding the <strong>Gateway</strong> daemon). This overrides any settings in<br />
the configuration file. For more information about the cicscli command, see<br />
“The <strong>CICS</strong>CLI command” on page 156.<br />
If you turn on tracing without specifying the components in either the cicscli<br />
command or in CTG.INI, a default set of components is traced:<br />
v Protocol drivers<br />
v The Client daemon<br />
v Client API level 1<br />
Selecting any of the check boxes in the configuration tool overrides the default<br />
set of components.<br />
<strong>Gateway</strong> trace file<br />
Enter the pathname of a trace file to which trace messages will be written, if<br />
tracing is enabled. If no path is specified, the trace is written as follows:<br />
\bin\ctg.trc<br />
IBM recommends that you place the trace file in a ctgtrace subdirectory of a<br />
directory to which all users have write access. For example, on Windows NT<br />
systems:<br />
C:\Winnt\Profiles\All Users\Application Data\ctgtrace<br />
or on Windows 2000 and Windows XP systems:<br />
C:\Documents and Settings\All Users\Application Data\ctgtrace<br />
Restrict read access to privileged groups, such as Administrators.<br />
You can also specify a trace file using the tfile option on the ctgstart<br />
command.<br />
The trace file is overwritten (not appended to) each time the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> starts.<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Performance: Turning on the <strong>Gateway</strong> trace has a significant impact on<br />
performance. It is not recommended that <strong>Gateway</strong> trace is<br />
enabled in a production environment.<br />
<strong>Gateway</strong> trace wrap size<br />
Enter a value in the range 0 through 1 000 000 kilobytes.<br />
This value specifies the size in kilobytes to which the gateway trace file will<br />
grow. Subsequent trace entries will continue to be written from the beginning<br />
of the file. The default value of 0 disables wrapping.<br />
Client trace file<br />
Enter the pathname of a trace file to which trace messages will be written, if<br />
tracing is enabled.<br />
You do not have to enter an extension for the filename, as a file of type .BIN<br />
is always generated (or .WRP if the trace file wraps).<br />
If no path is specified, the trace is written as follows:<br />
\bin\<strong>CICS</strong>CLI.BIN<br />
To minimise any performance impact, the trace file is written out in binary<br />
format. To read it, convert the file to ASCII using the cicsftrc command.<br />
For more information about tracing, see “Tracing” on page 209.<br />
Maximum Client wrap size<br />
Enter a value in the range 0 through 65 535 KB.<br />
This value specifies how large the trace file will grow on disk before<br />
wrapping. The default value of 0 disables wrapping.<br />
Editing the configuration file<br />
Although it is recommended that you use the configuration tool you can edit<br />
the configuration file direct.<br />
The configuration file has the following sections:<br />
1. GATEWAY<br />
2. CLIENT<br />
3. SERVER<br />
4. DRIVER<br />
5. LOADMANAGER<br />
Configuration<br />
Chapter 5. Configuration 89
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
For information on the properties in each section, refer to the descriptions of<br />
the corresponding settings in the configuration tool.<br />
The DRIVER section has no corresponding section in the configuration tool.<br />
The configuration tool automatically selects the correct protocol drivers.<br />
Each section has the format:<br />
SECTION sectioname [=value]<br />
# Comment describing the section<br />
property1=value<br />
property2=value<br />
...<br />
propertyN=value<br />
ENDSECTION<br />
Note: If you use the # character to denote a comment, either:<br />
v place it at the start of a line; or<br />
v precede it by a space or tab character<br />
because some valid names (for example modename) can start with the<br />
# character.<br />
J2EE setup and configuration<br />
This topic discusses the administration of <strong>CICS</strong> resource adapters. Two<br />
resource adapters are supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The<br />
\deployable directory contains an adapter for ECI (cicseci.rar),<br />
and one for EPI (cicsepi.rar).<br />
Any value set by the setExecuteTimeout method of the ECIInteractionSpec<br />
class is ignored; neither connector supports timeout. An alternative is to set<br />
the TIMEOUT parameter in the external <strong>CICS</strong> interface options table,<br />
DFHXCOPT. See the <strong>CICS</strong> External Interfaces Guide for more information.<br />
Deploying <strong>CICS</strong> resource adapters<br />
Before you can use a J2EE resource adapter in a server runtime environment<br />
you must supply parameters for its internal ManagedConnectionFactory class.<br />
In a managed environment you set these parameters when you deploy the<br />
resource adapter to your server. For instructions on how to do this consult<br />
your server’s documentation.<br />
<strong>CICS</strong> resource adapters are provided in standard resource adapter modules<br />
ready for deployment into a J2EE server environment. They can be packaged<br />
in J2EE applications along with other components such as Enterprise Beans,<br />
and used to create larger, more complex systems.<br />
90 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Deployment parameters for the ECI resource adapter<br />
Deployment parameters for the ECI resource adapter<br />
This section describes the available deployment parameters for the ECI<br />
resource adapter, and their effect on the final deployed resource adapter. The<br />
tools used to configure these parameters are server-specific. Not all<br />
parameters are required; the default value is shown where appropriate.<br />
ConnectionURL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with which the resource<br />
adapter will communicate. The URL takes the form<br />
protocol://address. These protocols are available:<br />
v tcp<br />
v http<br />
v ssl<br />
v local<br />
So, for example, you might specify a URL of tcp://ctg.business.com.<br />
For the local protocol simply specify local:.<br />
PortNumber<br />
The port to connect to where the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running. This parameter is not relevant if you are using the local<br />
protocol.<br />
ServerName<br />
The name of the <strong>CICS</strong> server to connect to for all interactions through<br />
this resource adapter. This is the name as defined in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file. To use multiple servers within<br />
an environment you must deploy several resource adapters, each with<br />
a different ServerName attribute set.<br />
TranName<br />
The name of the <strong>CICS</strong> <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run.<br />
TPNName<br />
The name of the <strong>CICS</strong> TPN <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run. Note that TPNName<br />
takes precedence if both TranName and TPNName are specified.<br />
UserName<br />
The <strong>CICS</strong> userid to be used if no other security credentials are<br />
available. See the J2EE section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide for more information.<br />
Password<br />
The password for the <strong>CICS</strong> userid defined above.<br />
ClientSecurity<br />
The fully qualified name of the ClientSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
Chapter 5. Configuration 91
Deployment parameters for the ECI resource adapter<br />
then no ClientSecurity class is used. For more information on what<br />
ClientSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
ServerSecurity<br />
The fully qualified name of the ServerSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ServerSecurity class is used. For more information on what<br />
ServerSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
KeyRingClass<br />
The fully qualified name of the SSL keyring class to use. This only<br />
applies when using the SSL protocol.<br />
KeyRingPassword<br />
The password for the class defined in KeyRingClass. Because it is<br />
linked to KeyRingClass, it is also optional, and applies only to the SSL<br />
protocol.<br />
TraceLevel<br />
The level of trace to be output by the resource adapter. For more<br />
details on trace levels and tracing see “Tracing” on page 95.<br />
As well as these user-definable properties, the ECI resource adapter has a set<br />
of predefined attributes that each deployed resource adapter will inherit.<br />
These properties are defined in the J2EE/CA specification and are as follows:<br />
<strong>Transaction</strong> Support<br />
The ECI resource adapter is defined as Local<strong>Transaction</strong>. If your<br />
server supports LastResourceOptimization, the resource adapter can<br />
participate in a global transaction, provided it is the only<br />
Local<strong>Transaction</strong> resource that has been enlisted.<br />
Re-Authentication Support<br />
The ECI resource adapter supports re-authentication. This is the<br />
ability to change the security credentials when a connection is<br />
requested from the server and an already existing one is allocated<br />
without having to disconnect and reconnect to the EIS. This improves<br />
performance.<br />
Deployment parameters for the EPI resource adapter<br />
The EPI resource adapter has the following deployment parameters. The tools<br />
used to configure these parameters are server-specific. Not all of these<br />
parameters are required; the default value is shown where appropriate.<br />
ConnectionURL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with which the resource<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Deployment parameters for the EPI resource adapter<br />
adapter will communicate. The URL takes the form<br />
protocol://address. These protocols are available:<br />
v tcp<br />
v http<br />
v ssl<br />
v local<br />
So, for example, you might specify a URL of tcp://ctg.business.com.<br />
For the local protocol simply specify local:.<br />
PortNumber<br />
The port to connect to where the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running. This parameter is not relevant if you are using the local<br />
protocol.<br />
ServerName<br />
The name of the <strong>CICS</strong> server to connect to for all interactions through<br />
this resource adapter. This is the name as defined in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file. To use multiple servers within<br />
an environment you must deploy several resource adapters, each with<br />
a different ServerName attribute set.<br />
UserName<br />
The <strong>CICS</strong> userid to be used if no other security credentials are<br />
available. See the J2EE section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide for more information.<br />
A LogonLogoff class is required if<br />
v The requested terminal is signon capable, or<br />
v The <strong>CICS</strong> Server does not support signon capable terminals (for<br />
example, <strong>CICS</strong> for OS/2)<br />
Password<br />
The password for the <strong>CICS</strong> userid defined above.<br />
ClientSecurity<br />
The fully qualified name of the ClientSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ClientSecurity class is used. For more information on what<br />
ClientSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
ServerSecurity<br />
The fully qualified name of the ServerSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ServerSecurity class is used. For more information on what<br />
ServerSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
Chapter 5. Configuration 93
Deployment parameters for the EPI resource adapter<br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
KeyRingClass<br />
The fully qualified name of the SSL keyring class to use. This only<br />
applies when using the SSL protocol.<br />
KeyRingPassword<br />
The password for the class defined in KeyRingClass. Because it is<br />
linked to KeyRingClass, it is also optional, and applies only to the SSL<br />
protocol.<br />
SignonType<br />
The EPI resource adapter allows you to define whether the terminals<br />
on <strong>CICS</strong> that are used by the resource adapter are signon capable or<br />
incapable. Acceptable values are:<br />
v 0 — Signon capable terminal (default)<br />
v 1 — Signon incapable terminal<br />
Encoding<br />
The Java Encoding to use when creating 3270 datastreams. The<br />
encoding will be converted to the appropriate CCSid. See the<br />
appendix in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
manual for a list of supported encodings. Ensure that your <strong>CICS</strong><br />
Server supports the CCSid from the given encoding.<br />
LogonLogoffClass<br />
The fully qualified name of the Java Class that provides the logic to<br />
Logon to a <strong>CICS</strong> Server using signon transactions. This property is<br />
mandatory for signon capable terminals and for <strong>CICS</strong> servers that do<br />
not support signon capability (such as <strong>CICS</strong> for OS/2).<br />
DeviceType<br />
The Terminal Model type, as defined in <strong>CICS</strong>, to be used by this<br />
resource adapter.<br />
ReadTimeout<br />
The maximum time a <strong>CICS</strong> server waits for a response from a user or<br />
J2EE component when taking part in a conversational transaction.<br />
Acceptable values for this parameter are:<br />
0 No timeout.<br />
1– 3600 Time in seconds.<br />
InstallTimeout<br />
The timeout value for terminal installation on <strong>CICS</strong>. The acceptable<br />
values for this parameter are as follows:<br />
0 No timeout.<br />
94 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Deployment parameters for the EPI resource adapter<br />
1– 3600 Time in seconds.<br />
TraceLevel<br />
The level of trace to be output by the resource adapter. For more<br />
details on trace levels and tracing see “Tracing”.<br />
As well as these user-definable properties, the EPI resource adapter has a set<br />
of predefined attributes that each deployed resource adapter will inherit.<br />
These properties are defined in the J2EE/CA specification and are as follows:<br />
<strong>Transaction</strong> Support<br />
The EPI resource adapter is nontransactional. It can be used within<br />
transactional contexts, but does not react to commit or rollback<br />
requests.<br />
Re-Authentication Support<br />
The EPI resource adapter supports re-authentication. This is the ability<br />
to change the security credentials when a connection is requested<br />
from the server and an already existing one is allocated, without<br />
having to disconnect and reconnect to the EIS. This improves<br />
performance. A LogonLogoff class is required if the terminal requested<br />
is SignonCapable, or if the <strong>CICS</strong> Server does not support signon<br />
capable terminals (such as <strong>CICS</strong> for OS/2).<br />
Tracing<br />
To help you in problem determination with any J2EE resource adapter<br />
applications that use the <strong>CICS</strong> resource adapters, a detailed tracing function is<br />
provided in both the ECI and EPI resource adapters. The <strong>CICS</strong> resource<br />
adapters support four levels of trace:<br />
0 No trace messages<br />
1 Exception tracing only (default level)<br />
2 Exception and method entry/exit trace messages<br />
3 Exception, method entry/exit and debug trace messages<br />
To provide more control over tracing, these system properties are available:<br />
com.ibm.connector2.cics.tracelevel<br />
This allows you to override the deployed trace level for the resource<br />
adapters without having to redeploy or deploy another <strong>CICS</strong> resource<br />
adapter.<br />
com.ibm.connector2.cics.dumpoffset<br />
The offset into a byte array that a hex dump will start at.<br />
com.ibm.connector2.cics.dumplength<br />
The maximum length of data displayed in a hex dump.<br />
Chapter 5. Configuration 95
Tracing<br />
com.ibm.connector2.cics.outputerr<br />
Declaring this directive sends trace output to standard error, if no<br />
other trace location has been specified either by the J2EE server, or by<br />
the application developer working in a nonmanaged environment. In<br />
other circumstances the provided logwriter takes precedence.<br />
Control of where trace is output is handled by the ConnectionManager being<br />
used by your environment. In a managed environment an option should be<br />
provided to allow you to set the path of the file that will be used for storing<br />
trace. Depending on how your environment allocates ConnectionManagers to<br />
resource adapters this file may contain messages from other resource adapters<br />
using the same ConnectionManager.<br />
When you deploy the <strong>CICS</strong> resource adapters into your environment, security<br />
restrictions are set up to allow access to the local file system for the purpose<br />
of writing trace files. The permissions used restrict access to this path:<br />
${user.home}${file.separator}IBM${file.separator}CTG${file.separator}-<br />
On Windows 2000, or Windows XP, this might map to:<br />
C:\Documents and Settings\Administrator\IBM\CTG\-<br />
On Windows NT this might map to:<br />
C:\Winnt\Profiles\Administrator\IBM\CTG\-<br />
Therefore, when setting the name and path of the trace file in your J2EE<br />
environment, use a location below this directory structure to store your trace.<br />
Otherwise the resource adapters will not have security permissions to write to<br />
the file.<br />
Sample configuration and mapping files<br />
The following files are supplied in the \bin subdirectory:<br />
ctgsamp.ini A sample configuration file. (The default<br />
configuration file name is CTG.INI.)<br />
cicskey.ini The keyboard mapping file. (A sample file<br />
cicskeysamp.ini is also provided.)<br />
cicscol.ini The color mapping file. (A sample file<br />
cicscolsamp.ini is also provided.)<br />
It is recommended that you create your own customized versions of these<br />
files with different names, because installation of service updates may<br />
overwrite the files and cause any customization to be lost.<br />
Reference your customized files through the following environment variables:<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
File Environment variable<br />
configuration file <strong>CICS</strong>CLI<br />
keyboard mapping file <strong>CICS</strong>KEY<br />
color mapping file <strong>CICS</strong>COL<br />
Use the System icon in the Control Panel to set these environment variables.<br />
Keyboard mapping for <strong>CICS</strong>TERM<br />
The keyboard mapping for terminal emulator operation is defined in a<br />
keyboard mapping file. A sample key mapping file is supplied with your<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>; see “Sample configuration and mapping files” on<br />
page 96 for details. It is recommended that you create your own customized<br />
mapping file.<br />
The keyboard mapping file can be specified by:<br />
v The -k option of the <strong>CICS</strong>TERM command, which identifies a keyboard<br />
mapping file with a particular terminal (see page “Keyboard mapping for<br />
<strong>CICS</strong>TERM”).<br />
v The <strong>CICS</strong>KEY environment variable. For example:<br />
SET <strong>CICS</strong>KEY=C:\CUSTOM\MYKEYS.INI<br />
See your operating system documentation for other ways of setting this<br />
environment variable.<br />
If you do not specify otherwise, a filename of cicskey.ini in the<br />
\bin subdirectory is assumed.<br />
You can change the keyboard mapping file at any time, although changes do<br />
not take effect until the next time the terminal emulator is started.<br />
Keyboard mapping file syntax<br />
This section describes the syntax of the keyboard mapping file. A statement<br />
must be provided for each key that is needed, because there are no default<br />
assignments (except for the alphabetic and numeric keys). There is no case<br />
sensitivity. Each binding must be on a separate line, and of the following<br />
form:<br />
Keyboard mapping file syntax<br />
►► BIND 3270function<br />
modifier+<br />
Sample configuration and mapping files<br />
key<br />
; comment<br />
#<br />
►◄<br />
Chapter 5. Configuration 97
Keyboard mapping for <strong>CICS</strong>TERM<br />
For example, to map the 3270 function EraseEof to the Ctrl+Delete keys<br />
pressed together the binding is as follows:<br />
bind EraseEof Ctrl+Delete ;erase to end of field<br />
The keyboard mapping file<br />
In the mapping file, 3270function can be any one of the following:<br />
backspace pa1 pf1 pf13<br />
backtab pa2 pf2 pf14<br />
clear pa3 pf3 pf15<br />
cursordown pf4 pf16<br />
cursorleft printscreen pf5 pf17<br />
cursorright reset pf6 pf18<br />
cursorselect tab pf7 pf19<br />
cursorup pf8 pf20<br />
delete ignore pf9 pf21<br />
enter pf10 pf22<br />
eraseeof pf11 pf23<br />
eraseinput pf12 pf24<br />
home<br />
insert<br />
newline<br />
The value of ignore is provided to permit unwanted control keys on the<br />
keyboard to be ignored. (Unexpected glyphs are not generated.)<br />
The Modifier can be any one of:<br />
Alt<br />
Ctrl<br />
Shift<br />
The Key can be any one of the keys shown in Table 8, (but some combinations<br />
of modifier+key are not supported — see “Key combinations” on page 99):<br />
Table 8. Keys that you can map<br />
Group Keys<br />
Escape key Escape<br />
Function keys f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12<br />
Numeric keys 0 1 2 3 4 5 6 7 8 9<br />
Alphabetic keys a b c d e f g h i j k l m<br />
n o p q r s t u v w x y z<br />
Tab key Tab<br />
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Table 8. Keys that you can map (continued)<br />
Group Keys<br />
Movement keys newline backspace<br />
insert home pageup<br />
delete end pagedown<br />
up left down right<br />
Keypad keys keypad/ keypad* keypadkeypad7<br />
keypad8 keypad9<br />
keypad4 keypad5 keypad6 keypad+<br />
keypad1 keypad2 keypad3<br />
keypad0 keypad. keypadenter<br />
In addition, the following key mappings are allowed:<br />
bind Clear Pause<br />
bind Reset Scroll Lock<br />
Keys specific to particular keyboards<br />
Some keys are specific to particular types of keyboard.<br />
The following additional key is unique to IBM keyboards:<br />
rightctrl<br />
Keyboard mapping for <strong>CICS</strong>TERM<br />
Key combinations<br />
The following combinations of modifier and key can be mapped:<br />
No modifier All keys available for mapping.<br />
Alt modifier Only function keys, numeric keys, movement<br />
keys, and alphabetic keys can be mapped.<br />
Ctrl modifier Only function keys, movement keys,<br />
alphabetic keys, tab key, and keypad keys can<br />
be mapped.<br />
Shift modifier Only function keys, numeric keys, tab key,<br />
and alphabetic keys can be mapped.<br />
Note: All modifier and key combinations that are not pre-empted by<br />
Windows can be mapped.<br />
Customizing the screen colors for <strong>CICS</strong>TERM<br />
Screen colors and attributes are defined in a color mapping file. A sample is<br />
provided for you to tailor; see “Sample configuration and mapping files” on<br />
page 96 for details. It is recommended that you create your own customized<br />
mapping file.<br />
Chapter 5. Configuration 99
Customizing the screen colors for <strong>CICS</strong>TERM<br />
The color mapping file can be identified by either of these methods:<br />
v The -c option of the <strong>CICS</strong>TERM command, which identifies a color<br />
mapping file with a particular server (see page “Customizing the screen<br />
colors for <strong>CICS</strong>TERM” on page 99).<br />
v The <strong>CICS</strong>COL environment variable: For example:<br />
SET <strong>CICS</strong>COL=C:\CUSTOM\MYCOLS.INI<br />
You can set this environment variable via the System icon in the Control<br />
Panel.<br />
If you do not specify otherwise, a filename of cicscol.ini in the<br />
\bin subdirectory is assumed.<br />
A color mapping file provides alternative representations in hardware<br />
environments where it is not possible exactly to replicate 3270 screen<br />
attributes, for example, blinking or underscore. The color mapping file<br />
therefore defines how 3270 screen attributes are emulated on the client<br />
hardware.<br />
The color mapping file is optional. However, for most hardware environments<br />
a mapping file is required if blinking or underscore support is required by the<br />
emulator.<br />
Notes:<br />
1. If the color mapping file specifies a mapping for an attribute, this mapping<br />
is used even if the hardware upon which the client is running actually<br />
supports the screen attribute.<br />
2. If an application requests a 3270 field to be displayed with, for example,<br />
underscore, and no emulation setting has been specified, and the hardware<br />
cannot display underscore, then the field is displayed without any<br />
highlighting at all.<br />
You can change the color mapping file at any time, although changes do not<br />
take effect until the next time the terminal emulator is started.<br />
Color mapping syntax<br />
The syntax of the color mapping file is as follows. Each binding must be on a<br />
separate line, in this form:<br />
Color mapping file syntax<br />
►► BIND 3270attrib fg_color<br />
The file is not case-sensitive.<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
/bg_color ; comment<br />
#<br />
►◄
The color mapping file<br />
In the color mapping file, 3270attrib can be any one of the following:<br />
normal_protected intensified_protected<br />
normal_unprotected intensified_unprotected<br />
default blinking_default underscored_default<br />
blue blinking_blue underscored_blue<br />
green blinking_green underscored_green<br />
cyan blinking_cyan underscored_cyan<br />
red blinking_red underscored_red<br />
magenta blinking_magenta underscored_magenta<br />
white blinking_white underscored_white<br />
yellow blinking_yellow underscored_yellow<br />
default_highlight<br />
operator_information_area<br />
Each of fg_color and bg_color (foreground color and background color) can be<br />
any one of the following:<br />
black light_gray<br />
blue light_blue<br />
brown yellow<br />
cyan light_cyan<br />
green light_green<br />
magenta light_magenta<br />
red light_red<br />
gray white<br />
If bg_color is omitted, a default value of black is taken.<br />
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
Customizing the screen colors for <strong>CICS</strong>TERM<br />
Before you can run an application that uses the local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support, ensure that you have correctly configured your<br />
environment. The following are required:<br />
1. A correctly configured Java environment<br />
A Java application that uses the local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
is a normal Java program, and so is executed with the standard JDK Java<br />
executable. Your environment must be correctly set so that the Java<br />
binaries, libraries, and classes can be found. Refer to the JDK<br />
documentation for the correct environment settings.<br />
2. The correct settings to allow the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> binaries to<br />
be found<br />
Chapter 5. Configuration 101
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> .class files need to be available. Set your<br />
CLASSPATH environment variable to include the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>’s ctgserver.jar and ctgclient.jar archives. Also, the relevant<br />
binaries must be available.<br />
Set your PATH environment variable to include the \bin<br />
subdirectory so that your application can find CTGJNI.DLL.<br />
To run the application: use the JDK java command with suitable options.<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 6. Network Security<br />
This chapter describes how to set up <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to use the<br />
network security protocols SSL and HTTPS. It also discusses some other<br />
security functions relevant to Windows. This chapter consists of the following:<br />
“Determining your use of SSLight or JSSE<br />
for the SSL and HTTPS protocols” on<br />
page 104<br />
“Maintaining your digital certificates for<br />
SSLight” on page 104<br />
“Using externally signed certificates<br />
under SSLight” on page 105<br />
“Using self-signed certificates under<br />
SSLight” on page 110<br />
Read this for information on how <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> determines whether<br />
you are using SSLight or JSSE.<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
SSLight.<br />
“Migration from SSLight” on page 114 Read this for information on migrating<br />
from SSLight to JSSE.<br />
“Installation” on page 114 Read this for information on installing<br />
JSSE.<br />
“Maintaining your digital certificates for<br />
JSSE” on page 115<br />
“Using externally signed certificates<br />
under JSSE” on page 115<br />
“Using self-signed certificates under JSSE”<br />
on page 120<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for SSL and HTTPS” on page 124<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
JSSE.<br />
Read this for information on how to<br />
configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
use the secure protocols.<br />
© Copyright IBM Corp. 1996, 2002 103
|<br />
|<br />
Security<br />
“Network Provider Interface (NPI)” on<br />
page 126<br />
Read this for information on how to<br />
signon to a <strong>CICS</strong> server with the same<br />
userid and password you use to logon to<br />
Windows NT.<br />
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> determines whether you wish to use SSLight or<br />
JSSE as follows:<br />
v If you pass a KeyRing class to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using SSLight.<br />
v If you pass a KeyStore file to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using JSSE.<br />
SSLight<br />
Conflict with JSSE<br />
SSLight might not function correctly if JSSE is installed on your system. If<br />
JSSE is installed, rename file gskikm.jar, intheJRE\EXT directory.<br />
Maintaining your digital certificates for SSLight<br />
iKeyMan<br />
Use the ctgikey command to invoke iKeyMan for certificate management.<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 105.<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 110.<br />
v Add certificates to your KeyRing files.<br />
v Change your KeyRing password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyRing.<br />
Distributing iKeyMan to client workstations<br />
Although you perform most of the KeyRing management on the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> machine, you might need to distribute the iKeyMan tool<br />
to clients connecting to your SSL server. The client machines must have the<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Maintaining your digital certificates for SSLight<br />
minimum level of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Java support; see “Supported<br />
software” on page 22. They might also require a script or command file to<br />
invoke the iKeyMan Java startup class.<br />
The following is an example of a command that you can use on Windows to<br />
invoke iKeyMan with the JDK or the JRE:<br />
java.exe -classpath<br />
"e:\ikeyman\cfwk.zip;e:\ikeyman\gsk5cls.jar;"<br />
-Dkeyman.javaOnly=true com.ibm.gsk.ikeyman.Ikeyman<br />
These examples assume that the client workstation has the following files in<br />
the ikeyman directory:<br />
v cfwk.zip<br />
v cfwk.sec<br />
v gsk5cls.jar<br />
v ikminit.properties<br />
All of these files are in the \classes subdirectory.<br />
Using iKeyman in DBCS environments<br />
If you have trouble running iKeyman in your locale, you can use this<br />
command to run it in English:<br />
java -classpath<br />
"c:\Program Files\IBM\IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>\classes\cfwk.zip;<br />
c:\Program Files\IBM\IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>\classes\gsk5cls.jar;"<br />
-Dkeyman.javaOnly=true -Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman<br />
Using externally signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyRing class<br />
2. Creating a certificate request<br />
3. Obtaining a digital certificate<br />
4. Receiving the digital certificate into the KeyRing<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyRings, or, in the case of HTTPS connections, the repository in<br />
Chapter 6. Network Security 105
Using externally signed certificates under SSLight<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyRing<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
The default location is the \bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 108.<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Using externally signed certificates under SSLight<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site and request a Test<br />
Server Certificate:<br />
a. Point your Web browser at: www.verisign.com and navigate to their<br />
request Test Server Certificate application pages.<br />
b. Open the certificate request file you created earlier, using an ASCII text<br />
editor.<br />
Figure 19 on page 108 shows an example of a certificate request.<br />
c. During the Test Server Certificate request process you will be asked to<br />
submit your CSR — Copy and paste the contents of the file into the<br />
text box in the Web page.<br />
d. Verify the contents of your certificate request and provide the personal<br />
details when requested.<br />
If you are requesting a full VeriSign Server ID, rather than a test<br />
version, these details are used to authenticate your application.<br />
e. VeriSign processes your enrollment and sends an e-mail to the address<br />
specified in your personal details.<br />
This e-mail contains your Test Server Certificate, and instructions on<br />
how to:<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
Chapter 6. Network Security 107
Using externally signed certificates under SSLight<br />
-----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u<br />
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC<br />
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP<br />
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF<br />
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx<br />
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH<br />
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq<br />
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh<br />
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW<br />
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY<br />
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ<br />
-----END NEW CERTIFICATE REQUEST-----<br />
Figure 19. Example certificate request<br />
4. Receive the Server Certificate into the server KeyRing<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyRing.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyRing MyServerKeyRing.class is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyRing class, or in the case of HTTPS, the browser certificate<br />
repository, must contain the signer certificate of the Server Certificate. In our<br />
example, the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following sections describes how to obtain a VeriSign Digital ID.<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Using externally signed certificates under SSLight<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the \bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyRing class<br />
using the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyRing class.<br />
3. Import the Client Certificate into the client KeyRing<br />
To import the #PKCS12 file containing the Client Certificate:<br />
Chapter 6. Network Security 109
Using externally signed certificates under SSLight<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Your client KeyRing MyClientKeyRing.class is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyRing classes<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyRing<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
The default location is the \bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
Using self-signed certificates under SSLight<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 108.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyRing class:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
Chapter 6. Network Security 111
Using self-signed certificates under SSLight<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the \bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Import the server’s signer certificate<br />
a. In iKeyMan select Add<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Using self-signed certificates under SSLight<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyRing need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyRing.class file with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support<br />
server authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyRing class also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
Chapter 6. Network Security 113
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under SSLight<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Migrating old self-signed certificates<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyRing class files, created with <strong>Version</strong> 3.0,<br />
using the iKeyMan tool.<br />
Restricting access to the server KeyRing<br />
The contents of the server KeyRing are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyRing class files have appropriate security access<br />
permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Java Secure Socket Extension (JSSE)<br />
Migration from SSLight<br />
To avoid possible conflicts between the different versions of iKeyMan used in<br />
SSLight and JSSE, IBM strongly recommends that you perform all migration<br />
actions before you install JSSE.<br />
To migrate from SSLight to JSSE:<br />
v Create new KeyStores and use these instead of existing KeyRing classes<br />
v Change existing security exits that implement the SSLightServerSecurity<br />
interface to implement the JSSEServerSecurity interface<br />
Installation<br />
See “Supported software” on page 22 for details of environments in which<br />
JSSE is supported.<br />
If you do not have a supported level of JSSE on your system, you need to<br />
install the version supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. JSSE support is<br />
included in two zip files supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
product:<br />
v ibm-jsse.zip<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v ibm-jce.zip<br />
Copy the zip files to the jre subdirectory of your Java installation directory<br />
on your system, and extract the archived files into this directory.<br />
You can find the Java root directory using the command ctgjava —v. This<br />
command displays a message like:<br />
CCL8810I Current JVM set to: ’C:\PROGRA~1\IBM\JRE\bin\jre.exe’<br />
In this example, the Java root directory is ’C:\PROGRA~1\IBM\JRE<br />
Maintaining your digital certificates for JSSE<br />
iKeyMan<br />
Use the following command to start the iKeyMan program:<br />
java com.ibm.ikeyman.Ikeyman<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 105.<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 110.<br />
v Add certificates to your KeyStore files.<br />
v Change your KeyStore password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyStore.<br />
Using externally signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyStore<br />
2. Creating a certificate request<br />
3. Obtaining a digital certificate<br />
4. Receiving the digital certificate into the KeyStore<br />
Installing JSSE<br />
Chapter 6. Network Security 115
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyStores, or, in the case of HTTPS connections, the repository in<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyStore<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 118.<br />
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site (www.verisign.com)<br />
and request a Test Server Certificate. You will be asked to paste in the<br />
contents of the certificate request file you created earlier (Figure 19 on<br />
page 108 shows an example of a certificate request) and agree to their<br />
licensing conditions. VeriSign will then send you a confirmation e-mail.<br />
This e-mail contains your Test Server Certificate, and instructions on how<br />
to:<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
Chapter 6. Network Security 117
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
4. Receive the Server Certificate into the server KeyStore<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyStore.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyStore MyServerKeyStore.jks is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyStore, or in the case of HTTPS, the browser certificate repository,<br />
must contain the signer certificate of the Server Certificate. In our example,<br />
the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following instructions describe how to obtain a VeriSign Digital ID.<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyStore using<br />
the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyStore.<br />
3. Import the Client Certificate into the client KeyStore<br />
To import the #PKCS12 file containing the Client Certificate:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Chapter 6. Network Security 119
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
Your client KeyStore MyClientKeyStore.jks is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyStores<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyStore<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
Using self-signed certificates under JSSE<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 118.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyStore:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
Chapter 6. Network Security 121
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Import the server’s signer certificate<br />
a. In iKeyMan select Add<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyStore need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyStore.jks file with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support server<br />
authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyStore also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Chapter 6. Network Security 123
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
Migrating old self-signed certificates<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyStore files, created with <strong>Version</strong> 3.0, using the<br />
iKeyMan tool.<br />
Restricting access to the server KeyStore<br />
The contents of the server KeyStore are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyStore files have appropriate security access permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
To use the SSL and HTTPS protocols, enable them using the configuration<br />
tool; see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings” on page 58. You<br />
can specify that either or both of the protocols is used. When you enable the<br />
protocols, by default, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> listens for SSL requests on<br />
port 8050, and for HTTPS requests on port 443.<br />
SSL and HTTPS configuration settings<br />
The following configuration settings are specific to the SSL and HTTPS<br />
protocols:<br />
KeyRing or KeyStore name Specifies the name of the server KeyRing or<br />
KeyStore.<br />
For a KeyRing, you must also add the<br />
classname to the CLASSPATH environment<br />
variable.<br />
If your KeyRing files are in directory<br />
e:\myKeyRings, you should specify the<br />
CLASSPATH entry as:<br />
e:\myKeyRings\.<br />
(with a trailing \. after the directory name).<br />
KeyRing or KeyStore password<br />
Specifies the password used to read the<br />
encrypted server KeyRing or KeyStore.<br />
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the<br />
password to the configuration file in a form<br />
that prevents a casual observer from easily<br />
reading it.<br />
Use client authentication Enables client authentication. The default is<br />
that only server authentication is enabled.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides two default KeyRing class files,<br />
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS<br />
connections under SSLight. Both KeyRings have been encrypted using the<br />
password default. Use them only in testing environments.<br />
Specifying a client KeyRing or KeyStore<br />
Your choice of secure protocol determines whether or not you need a<br />
KeyRing, or KeyStore, for both server and client:<br />
HTTPS<br />
Specify a KeyRing or KeyStore only in the server.<br />
SSL<br />
The SSL protocol requires you to specify KeyRings, or KeyStores for both the<br />
server and the client.<br />
For more information see SSL Java<strong>Gateway</strong>, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide.<br />
Using the SSL and HTTPS protocols<br />
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP<br />
protocols. To make a connection to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, your client<br />
application flows a request using the appropriate URL. For example, for SSL<br />
use a URL like:<br />
ssl://trans<strong>Gateway</strong>Machine:8050<br />
Similarly, for HTTPS:<br />
https://trans<strong>Gateway</strong>Machine:443<br />
For more information on the design and implementation of client-side<br />
programs, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> programming interface HTML pages.<br />
Chapter 6. Network Security 125
Network Provider Interface (NPI)<br />
Network Provider Interface (NPI)<br />
Network Provider Interface (NPI) allows you to signon to a <strong>CICS</strong> server using<br />
the same userid and password that you use to log on to Windows. The <strong>CICS</strong><br />
server authenticates and authorizes using your domain information. This is<br />
stored, encrypted, in memory. However, the security information remains<br />
synchronized only if you sign on to a <strong>CICS</strong> server that supports NPI.<br />
You enable NPI for each <strong>CICS</strong> server with the Use Windows credentials for<br />
security configuration setting. See “Use Windows credentials for security” on<br />
page 77 for more information.<br />
With NPI enabled, if <strong>CICS</strong> cannot obtain the userid and password when<br />
signing on, Windows opens a window to prompt you for the information.<br />
Restrictions<br />
If you run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows service, NPI works only<br />
if you assign a logon user account, not the system account, to the service.<br />
Windows allows the use of longer userids and passwords than those allowed<br />
by <strong>CICS</strong> servers. Therefore, to use NPI, you might need to use a shorter<br />
userid and password to logon to Windows.<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 7. Client Security<br />
Overview<br />
This chapter describes how to provide a userid and password when<br />
connecting to a <strong>CICS</strong> server. It consists of the following:<br />
“Overview” Read this for an overview of <strong>CICS</strong><br />
client/server security.<br />
“Default connection settings” on page 128 Read this for information on setting<br />
default values for userid and password.<br />
“ECI security” on page 129 Read this for information on providing a<br />
userid and password on an ECI request.<br />
“EPI terminal security” on page 129 Read this for information on providing a<br />
userid and password on an EPI request.<br />
“Signon capable and signon incapable<br />
terminals” on page 131<br />
Read this for information on signon<br />
capable and signon incapable terminals.<br />
<strong>CICS</strong> servers may require the Client daemon to supply a userid and password<br />
before they permit the following:<br />
v A client connection<br />
v Terminals to be installed<br />
v <strong>Transaction</strong>s to be run<br />
This depends on the server and protocol security settings. The userid and<br />
password are sent to the server in the FMH header of the transaction attach<br />
request for each conversation. A userid and password are also required when<br />
a signon transaction is invoked on a signon capable terminal. In this instance,<br />
the userid and password are flowed to the server as part of the 3270<br />
datastream.<br />
Because the Client daemon has no security manager, it does not support<br />
userid authentication. It is recommended that you configure your <strong>CICS</strong> server<br />
client connections so that incoming attach requests must specify a userid and<br />
password. For mainframe servers, specify AttachSec = Verify in the <strong>CICS</strong><br />
connection definition. AttachSec = Identify, which indicates that userid, but<br />
not password, are required, is not supported for client connections.<br />
Note: Userids and passwords must not contain DBCS characters.<br />
© Copyright IBM Corp. 1996, 2002 127
Client Security<br />
Default connection settings<br />
The Client daemon maintains a default userid and password for each server<br />
connection, which may be set by any of the following methods:<br />
v <strong>CICS</strong>CLI security commands:<br />
cicscli /c=servername /u=userid /p=password<br />
v From C use the ESI function <strong>CICS</strong>_SetDefaultSecurity. This call is not<br />
available from the Java APIs.<br />
v From C++, use the makeSecurityDefault method of the CclConn or<br />
CclTerminal class.<br />
v From COM, use the MakeSecurityDefault method of the Connect or<br />
Terminal COM class.<br />
v Through a Client daemon security popup.<br />
These default values are used when required on all subsequent transaction<br />
requests for that server, provided that no values have been passed on the ECI<br />
request itself, or have been set for the specific EPI terminal against which the<br />
transaction will run.<br />
Note: If the Client daemon is running in an environment where it survives<br />
user logoff, for example, as a Windows service, the default userid and<br />
password values entered by the currently logged on user are retained<br />
even when that user logs off, and are subsequently reused as required.<br />
Security popups<br />
The Client daemon will display a security popup to allow the user to enter a<br />
userid and password if ALL of the following are true:<br />
v Terminal Services is not enabled.<br />
v Popups are enabled in the initialization file (ctg.ini).<br />
v The client is not running as a service, or is running as a service that is<br />
enabled to interact with the desktop.<br />
v The server requires that a userid and password are flowed in the<br />
transaction attach request.<br />
v No default security has yet been set for the server connection or default<br />
security has been set but the settings produce a security error on the server,<br />
for example, password expired.<br />
v The transaction being invoked by the client is CCIN (client install) or CTIN<br />
(terminal install).<br />
v A terminal userid and password have not been supplied on a terminal<br />
install request.<br />
Values entered via a security popup, once verified, are used to set the default<br />
userid and password values for that server connection.<br />
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
ECI security<br />
Client Security<br />
Security popups are not displayed directly by ECI or EPI transaction requests,<br />
although they may be prompted by these requests, if the request causes a<br />
server connection to be established, or a terminal to be installed.<br />
An application may provide a userid and password on an ECI request and<br />
these values will override any default values set for the server connection as<br />
follows.<br />
v C programs:<br />
Set eci_userid and eci_password or eci_userid2 and eci_password2 in the<br />
ECI parameter block.<br />
v C++ programs:<br />
Set the userid and password parameters when constructing a server<br />
connection object - CclConn.<br />
v COM programs:<br />
Set the userid and password via the Details method on the Connect object.<br />
v Java client programs:<br />
Set the userid and password parameters when constructing an ECIRequest<br />
object.<br />
EPI terminal security<br />
The Client daemon also maintains a userid and password per installed<br />
terminal. These values will override any default values set for the server<br />
connection. They can be set by one of the following methods:<br />
v C programs:<br />
Set UserId and Password in the <strong>CICS</strong>_EpiAttributes_t structure on a<br />
<strong>CICS</strong>_EpiAddExTerminal call. Or, use the EPI function<br />
<strong>CICS</strong>_EpiSetSecurity. This call would typically be used to change the<br />
terminal security settings if, for example, the user’s password had expired.<br />
v C++ programs:<br />
Set the userid and password parameters when constructing a CclTerminal<br />
class object. Or, use the alterSecurity method of the CclTerminal class.<br />
v COM programs:<br />
Use the AlterSecurity method of the Terminal COM class. This can only be<br />
used for signon incapable created terminals.<br />
v Java client programs:<br />
– EPI Request Classes<br />
Set the userid and password parameters when constructing an<br />
EPIRequest object via the addTerminal or addTerminalAsync method.<br />
Or, use the alterSecurity method of the EPIRequest class.<br />
Chapter 7. Client Security 129
Client Security<br />
– EPI Support Classes<br />
Create a Terminal object using the default Constructor, then use<br />
setUserid and setPassword to set security, or create a Terminal object<br />
using the extended Constructor.<br />
– EPI Beans<br />
Set the Userid and Password properties on the extended terminal<br />
properties panel or programmatically by creating an EPI Terminal bean,<br />
get the terminal object it holds using getTerminal() and then use<br />
setUserid and setPassword.<br />
v Terminal Servlet<br />
Set pool@userid and pool@password. These settings apply to all terminals<br />
in the pool.<br />
Terminal security cannot be set when using the <strong>CICS</strong> CCF Connectors.<br />
Terminal security would normally only be required if using signon incapable<br />
terminals.<br />
Password expiry management<br />
For <strong>CICS</strong> clients the management of expired passwords can be handled by the<br />
ESI functions <strong>CICS</strong>_ChangePassword and <strong>CICS</strong>_VerifyPassword. Also,<br />
security popups will prompt specifically for any unknown userid, incorrect<br />
password, or expired password, after the user has initially entered a userid<br />
and password via a security popup.<br />
The ESI functions can be used only with <strong>CICS</strong> servers that support password<br />
expiry management (PEM). See “Supported software” on page 22, for<br />
information on supported servers. Refer to the documentation for your <strong>CICS</strong><br />
server for information on PEM support.<br />
To use PEM, the Client daemon must be connected to the <strong>CICS</strong> server over<br />
SNA or TCP62. An ESM, such as resource access control facility (RACF ® ), must<br />
also be available to the <strong>CICS</strong> server. ESI calls can be included within your ECI<br />
or EPI application. Only <strong>CICS</strong> servers returned by the <strong>CICS</strong>_EciListSystems<br />
and <strong>CICS</strong>_EpiListSystems functions are acceptable.<br />
Network Provider Interface (NPI)<br />
Network Provider Interface (NPI) allows you to sign on to a <strong>CICS</strong> server<br />
using the same userid and password that you use to log onto Windows. For<br />
more details refer to “Network Provider Interface (NPI)” on page 126.<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Signon capable and signon incapable terminals<br />
Client Security<br />
Signon capable terminals allow signon transactions, either <strong>CICS</strong>-supplied<br />
(CESN) or user-written, to be run, whereas signon incapable terminals do not<br />
allow these transactions to be run.<br />
If a terminal resource is installed as signon capable, the application or user is<br />
responsible for starting a signon transaction; the userid and password once<br />
entered are embedded in the 3270 data.<br />
v <strong>Transaction</strong>s started before the signon transaction will execute with the<br />
authorities granted to the default userid defined for the server. A check is<br />
also done against the userid associated with the connection to see whether<br />
the Client daemon itself has authority to access the resource.<br />
v <strong>Transaction</strong>s started after the signon transaction will execute with the<br />
authorities granted to the authenticated userid. For transactions attempting<br />
to access resources, security checking is done against the signed-on user’s<br />
userid and the userid associated with the connection. If a server supports<br />
signon timeout and a client terminal is left idle so that the timeout expires,<br />
the user is signed off without notification and the next transaction will run<br />
against the default userid.<br />
If the terminal resource is installed as signon incapable, the userid and<br />
password are authenticated for each transaction started for the terminal<br />
resource.<br />
Prior to <strong>Version</strong> 3.1.0 of Clients and <strong>Gateway</strong>s, whether a terminal was signon<br />
capable or not was dependant upon the server implementation. Client<br />
terminals installed on distributed <strong>CICS</strong> servers were signon capable and<br />
terminals installed on mainframe <strong>CICS</strong> and <strong>CICS</strong>/400 servers were signon<br />
incapable.<br />
In <strong>Version</strong> 3.1.0, extended EPI function was introduced to allow the signon<br />
capability of a terminal to be specified by one of the following methods.<br />
v C programs:<br />
Use <strong>CICS</strong>_EpiAddExTerminal and set the SignonCapability parameter in<br />
the <strong>CICS</strong>_EpiAttributes_t structure.<br />
v C++ programs:<br />
Set the signon capability parameter when constructing a CclTerminal class<br />
object.<br />
v COM programs:<br />
Use the SetTermDefns method of the Terminal COM class.<br />
v Java client programs:<br />
– EPI Request Classes<br />
Chapter 7. Client Security 131
Client Security<br />
Set the signon capability parameter when constructing an EPIRequest<br />
object via the addTerminal or addTerminalAsync method.<br />
– EPI Support Classes<br />
Create a Terminal object using the default Constructor, then use<br />
setSignonCapability, or create a Terminal object using the extended<br />
Constructor. If a terminal is in disconnected state (ie has been<br />
disconnected, or never connected) calling setSignonCapability allows you<br />
to change the signon capability for the terminal and changes the terminal<br />
type to extended. When you connect, you connect an extended terminal<br />
with that signon capability. If you setSignonCapability while a terminal<br />
is connected then it get’s saved away, it does not alter the connected<br />
setting.<br />
– EPI Beans<br />
Set the SignonCapability property on the extended terminal properties<br />
panel, or programmatically by creating an EPI Terminal bean, get the<br />
terminal object it holds using getTerminal() and then use<br />
setSignonCapability.<br />
v Terminal Servlet<br />
Assign the appropriate Signon capability string to the Servlet Property<br />
pool@signonCapability. These settings apply to all terminals in the pool.<br />
The signon capability of the installed terminal is returned in the terminal<br />
attributes. This will be set to SIGNON_UNKNOWN if the server does not<br />
return a signon capability parameter in the terminal install (CTIN) response.<br />
The signon capability of a terminal cannot be specified when using the <strong>CICS</strong><br />
CCF Connectors. If you are using this interface, the EPI functionality available<br />
is unchanged from <strong>Version</strong> 3.0.x, that is, you cannot specify a userid and<br />
password per terminal, or specify the signon capability.<br />
To use any of the extended EPI functionality, you must ensure that you have<br />
applied the relevant server APAR; see “<strong>CICS</strong> server PTF requirements” on<br />
page 25.<br />
Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Programming Guide for further information.<br />
Mainframe <strong>CICS</strong> servers<br />
These servers support both signon capable and incapable terminals, provided<br />
that they are at the prerequisite maintenance level; see “<strong>CICS</strong> server PTF<br />
requirements” on page 25. A terminal install request that does not specify any<br />
signon capability, for example from <strong>CICS</strong>_EpiAddTerminal, will result in a<br />
signon incapable terminal being installed.<br />
For signon capable terminals:<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Client Security<br />
v Use the <strong>CICS</strong>_EpiAddExTerminal call specifying a SignonCapability of<br />
<strong>CICS</strong>_EPI_SIGNON_CAPABLE.<br />
v You do not need to set the userid and password fields on the<br />
<strong>CICS</strong>_EpiAddExTerminal call or use <strong>CICS</strong>_EpiSetSecurity, provided that<br />
you specify UseDfltUser = Yes in the <strong>CICS</strong> connection definition on the<br />
server.<br />
v A userid and password entered through a signon transaction are flowed to<br />
the server as part of the 3270 datastream and they will therefore appear in a<br />
client trace.<br />
It is recommended that you specify UseDfltUser = Yes in the <strong>CICS</strong><br />
CONNECTION definition, or ensure that the system administrator sets a<br />
default connection userid and password for the client. Otherwise, the add<br />
terminal request may fail with an EPI_ERR_SECURITY return code.<br />
v Before the user has signed on, transactions will run under the default<br />
userid for the <strong>CICS</strong> server. After signon, transactions will run under the<br />
signed-on userid.<br />
For signon incapable terminals without terminal security:<br />
v Use the <strong>CICS</strong>_EpiAddTerminal call<br />
v A connection userid and password will be required regardless of the setting<br />
of the UseDfltUser in the <strong>CICS</strong> connection definition on the server.<br />
v <strong>Transaction</strong>s will run under the userid specified in the corresponding FMH<br />
attach request.<br />
For signon incapable terminals with terminal security:<br />
v Use the EpiAddExTerminal call specifying a SignonCapability of<br />
<strong>CICS</strong>_EPI_SIGNON_INCAPABLE.<br />
v Set the userid and password fields on the <strong>CICS</strong>_EpiAddExTerminal call.<br />
v Specify UseDfltUser = No in the <strong>CICS</strong> connection definition on the server<br />
to enforce security.<br />
v Use <strong>CICS</strong>_EpiSetSecurity in conjunction with <strong>CICS</strong>_VerifyPassword and<br />
<strong>CICS</strong>_ChangePassword to change the security settings for an existing<br />
terminal.<br />
v The userid and password are flowed to the server in the FMH of the attach<br />
request and will not appear in a client trace.<br />
v <strong>Transaction</strong>s will run under the userid specified in the corresponding FMH<br />
attach request.<br />
If you wish to use one of the APIs that does not support the new EPI<br />
functionality, then you can use CRTE through a middle tier system to get<br />
signon capable terminal-like functionality.<br />
Chapter 7. Client Security 133
Client Security<br />
TXSeries and <strong>CICS</strong> OS/2 servers<br />
These servers do not support the signon capability parameter in a terminal<br />
install (CTIN) request but will tolerate it if the required APAR is applied; see<br />
“<strong>CICS</strong> server PTF requirements” on page 25. A terminal install request will<br />
always result in a signon capable terminal being installed, regardless of the<br />
signon capability requested.<br />
<strong>CICS</strong>/400 servers<br />
These servers do not support the signon capability parameter in a terminal<br />
install (CTIN) request . A terminal install request will result in a signon<br />
incapable terminal being installed, regardless of the signon capability<br />
requested.<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 8. Performance<br />
This chapter helps you to:<br />
v understand the factors that affect <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> performance<br />
v achieve the best performance from your system<br />
“Assessing system performance” Read this for an overview of the things to<br />
consider when assessing the performance<br />
of your system.<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
configuration” on page 136<br />
Read this for information on <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
parameters which affect performance.<br />
“Java considerations” on page 138 Read this for information on Java factors<br />
which affect performance.<br />
“Other system factors” on page 138 Read this for information on other system<br />
factors which affect performance.<br />
“Tracing” on page 139 Read this for information on using tracing<br />
to measure performance.<br />
“Performance monitoring tools” on<br />
page 140<br />
Read this for information on performance<br />
monitoring tools.<br />
Assessing system performance<br />
To assess the overall performance of your system you need to understand<br />
how all system components, including <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, affect<br />
performance. These system components might include:<br />
v browser<br />
v routers and firewalls<br />
v WebServer or Web Application Server<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v <strong>CICS</strong> server<br />
The information you collect to assess performance should include:<br />
v processor loading<br />
v data transfer rates<br />
v response times<br />
Response times are particularly useful indicators. They help you to<br />
understand which system components most affect performance.<br />
© Copyright IBM Corp. 1996, 2002 135
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
IBM has chosen default values for configuration and tuning to give a<br />
compromise between:<br />
v limiting the system resources used by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> after it<br />
has started<br />
v giving <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> the flexibility to handle increases in<br />
workload<br />
The following factors affect performance; you might need to alter the default<br />
configuration to suit your system environment:<br />
Connection Manager threads<br />
If the value specified for Initial number of Connection Manager<br />
threads is too high, your system will waste resources managing the<br />
threads that are not needed.<br />
The design of your applications determines the number of Connection<br />
Manager threads you need. Incoming connections to <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> could be from a servlet, with each copy of the servlet issuing<br />
its own ECI requests, but sharing a single Connection Manager<br />
thread. Alternatively, the application could create a pool of<br />
connections, and ECI requests could be issued onto any connection<br />
from the pool.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new Connection Manager thread,<br />
and TCP/IP connection, each time a Java client side application<br />
creates a new Java<strong>Gateway</strong> object. This means that system<br />
performance is better if your applications issue many ECI requests<br />
using the same Java<strong>Gateway</strong> object, and from within the same thread,<br />
than if they create a new Java<strong>Gateway</strong> object for each request.<br />
Flowing multiple requests through the same Java<strong>Gateway</strong> object also<br />
reduces the system resources required to create, and to destroy,<br />
Java<strong>Gateway</strong> objects.<br />
If the number of threads needed by applications exceeds the value<br />
specified for Maximum number of Connection Manager threads,<br />
each new request that requires a Connection Manager thread must<br />
wait until a thread becomes available. If the waiting time exceeds the<br />
value specified in the Connection timeout parameter, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> refuses the connection.<br />
Worker threads<br />
Worker threads handle outbound connections between <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> and your <strong>CICS</strong> server. The design of your<br />
applications, and the workload that you need to support, affects the<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
number of Worker threads you need: the longer your <strong>CICS</strong><br />
transactions remain in process, the more Worker threads you need to<br />
maintain a given transaction rate.<br />
v If the value specified for Initial number of Worker threads is too<br />
high, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to manage threads<br />
that it does not need<br />
v If the value is too low, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to<br />
search for available Worker threads.<br />
When using ECI to call the same <strong>CICS</strong> program, you can estimate the<br />
number of Worker threads you need to support a given workload by<br />
multiplying the following values:<br />
v number of transactions per second passing through <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong><br />
v average transaction response time through <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> in seconds<br />
Communication protocols<br />
Your choice of protocol depends on the nature of your client<br />
applications. However, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does considerably<br />
more processing to handle the HTTP and HTTPS protocols than it<br />
does to handle the TCP and SSL protocols. In addition, when using<br />
HTTP or HTTPS, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new TCP/IP<br />
connection with each client request. For better performance, use TCP<br />
or SSL in preference to HTTP or HTTPS where possible.<br />
Display TCP/IP hostnames<br />
Selecting this option might cause severe performance reduction on<br />
some systems. See “Display TCP/IP hostnames” on page 60.<br />
Timeout values<br />
It is unlikely that you can improve performance by changing the<br />
default timeout values. However, you may need to change them for<br />
particular applications. Refer to “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> settings” on page 58 for more information on these and all<br />
other configuration parameters.<br />
Connection logging<br />
The gateway configuration setting, Log client connections and<br />
disconnections, controls whether or not <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
writes a message each time that a client application program connects<br />
to, or disconnects from, the <strong>Gateway</strong> daemon. The default is for these<br />
messages not to be written. Selecting this setting can significantly<br />
reduce performance, especially in a system where client application<br />
programs connect and disconnect frequently. See “Log client<br />
connections and disconnections” on page 61.<br />
Chapter 8. Performance 137
Java considerations<br />
Java considerations<br />
Other system factors<br />
Maximum Java heap size<br />
If your system requires large numbers of Connection Manager threads<br />
you might need to increase the heap size to improve performance; see<br />
also “java.lang.OutOfMemory exception” on page 217. How you set<br />
the heap size depends on your JVM. Refer to the documentation for<br />
your JVM for more information.<br />
Just-In-Time (JIT) compiler<br />
Use the java -version command to find whether or not the JIT is<br />
enabled; it is enabled by default in JDK 1.3.1. Performance<br />
immediately after a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has started might be<br />
relatively slow because of JIT overheads. The JIT threshold is 2000 on<br />
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to<br />
run 2000 times before it is ’JITed‘. Refer to your JVM documentation<br />
for information on JIT techniques.<br />
Java<strong>Gateway</strong> objects<br />
Performance is better if you flow multiple requests using the same<br />
Java<strong>Gateway</strong> object than if you create a new Java<strong>Gateway</strong> object with<br />
each request. Each time you create, and destroy, a new Java<strong>Gateway</strong><br />
object you use additional system resources for:<br />
v creation and destruction of the object itself<br />
v creation and destruction of any associated sockets<br />
v garbage collection<br />
ECI COMMAREA size<br />
The size of the ECI COMMAREA has a large effect on performance. If<br />
you make the COMMAREA larger, you need more system resources<br />
to process it, and your response times are longer. Refer to <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for information on how to<br />
specify COMMAREA parameters in ECI requests.<br />
The setCommareaOutboundLength method, which is part of the<br />
EciRequest object, is particularly important to performance. The<br />
amount of data that an application sends in the COMMAREA flow to<br />
<strong>CICS</strong> may be small , and the amount of data expected from <strong>CICS</strong> in<br />
return may be unknown. To improve performance significantly, and<br />
reduce network loading:<br />
v Use the setCommareaOutboundLength method to ensure that you<br />
send only the required data in the outbound flow to <strong>CICS</strong>, and not<br />
the full Commarea_Length.<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Tracing<br />
Other system factors<br />
<strong>CICS</strong> removes any null data from the COMMAREA in the return<br />
flow, and the Client daemon automatically pads out the nulls and<br />
returns the full COMMAREA to the application.<br />
v Use the getInboundDataLength method to show the amount of<br />
non-null data returned.<br />
v Do not use the deprecated setCommareaInboundLength method<br />
because it prevents automatic commarea null stripping.<br />
<strong>CICS</strong> server transactions<br />
The design of your <strong>CICS</strong> server transactions affects the performance of<br />
your system. The response time through <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
might increase if your transactions:<br />
v need to wait for shared resources, for example data sets or<br />
applications, to become available<br />
v make remote links to other <strong>CICS</strong> systems<br />
v are unnecessarily complex<br />
Refer to the Performance and Tuning documentation for your <strong>CICS</strong><br />
server system for information on how to get the best performance.<br />
Synchronous or asynchronous ECI calls<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has to do less processing to handle a<br />
synchronous ECI call than to handle an equivalent asynchronous call.<br />
Also, synchronous ECI calls create fewer network flows than<br />
asynchronous calls. This means that synchronous ECI calls give better<br />
performance than asynchronous calls.<br />
Extended logical units of work<br />
Take care when extending a logical unit of work across multiple<br />
program link calls that may span a long time period (for example,<br />
user thinking time). The logical unit of work holds various locks, and<br />
other <strong>CICS</strong> resources, on the server. This may cause delays to other<br />
users who are waiting for the same locks and resources.<br />
Also, each logical unit of work occupies one <strong>CICS</strong> non-facility task for<br />
the duration of its execution. This means that you must define enough<br />
free tasks in the <strong>CICS</strong> server to service the maximum expected<br />
number of concurrent calls.<br />
Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more<br />
information.<br />
IBM does not recommend the use of the full <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace<br />
to monitor performance in a production environment. This is because the<br />
trace itself significantly decreases performance.<br />
Chapter 8. Performance 139
Tracing<br />
Where possible, try to measure response times, without using tracing, through<br />
the different parts of your system, to find where delays are happening. For<br />
example, you could measure response times at the client application, and also<br />
through <strong>CICS</strong> and WebSphere.<br />
Performance monitoring tools<br />
Performance Monitor (perfmon)<br />
This utility is available on Windows. Refer to the documentation for<br />
your operating system for more information.<br />
Refer also to the performance and tuning documentation for WebSphere, SNA,<br />
TCP/IP, <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, and TXSeries.<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 9. Operating the <strong>Gateway</strong><br />
This chapter describes how to operate the <strong>Gateway</strong> daemon of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It consists of the following:<br />
“Before you start” Read this for information on the<br />
privileges that a user needs to operate<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Starting the <strong>Gateway</strong>” Read this for information on starting<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Stopping the <strong>Gateway</strong>” on page 144 Read this for information on stopping<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a<br />
Windows service” on page 146<br />
Read this for information on running<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows<br />
service<br />
“Administering your system” on page 149 Read this for information on setting the<br />
<strong>Gateway</strong> and JNI traces, and querying<br />
trace settings.<br />
Before you start<br />
To operate <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you must log in either as an<br />
administrator, or as a user with the following privileges:<br />
v network access through TCP/IP<br />
v read access to file CTG.INI<br />
v read access to the directory in which you installed <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
Starting the <strong>Gateway</strong><br />
You start the <strong>Gateway</strong> at the operating system command prompt of the<br />
computer on which you have installed it.<br />
First, set your working directory to the \bin subdirectory.<br />
You can start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> in two ways:<br />
v “Starting the <strong>Gateway</strong> with preset options” on page 142<br />
v “Starting the <strong>Gateway</strong> with user-specified options” on page 142.<br />
© Copyright IBM Corp. 1996, 2002 141
|<br />
Starting the <strong>Gateway</strong> with preset options<br />
To start the <strong>Gateway</strong> with predefined options: Type ctgstart at the command<br />
prompt and press Enter, or select the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> icon. This<br />
command runs the <strong>Gateway</strong> with the JVM specified by the ctgjava command.<br />
When you start the <strong>Gateway</strong> like this the values you configured using the<br />
configuration tool are used. (see “Using the configuration tool” on<br />
page 54).The gateway will not start without a valid INI file.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used for TCP/IP:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345<br />
Starting the <strong>Gateway</strong> with user-specified options<br />
The user-definable options on the start command are:<br />
-port=port_number<br />
-initconnect=number<br />
-maxconnect=number<br />
-initworker=number<br />
-maxworker=number<br />
-trace<br />
-noinput<br />
-tfile=pathname<br />
-x<br />
-tfilesize=number<br />
-truncationsize=number<br />
-dnsnames<br />
-dumpoffset=number<br />
-stack<br />
-jargument to pass to the JVM<br />
where:<br />
-port<br />
Specifies the TCP/IP port number which the gateway will listen on.<br />
-initconnect<br />
Specifies an initial number of ConnectionManager threads.<br />
-maxconnect<br />
Specifies a maximum number of ConnectionManager threads. If you set<br />
this value to -1, no limits are applied to the number of<br />
ConnectionManager threads.<br />
-initworker<br />
Specifies an initial number of Worker threads.<br />
-maxworker<br />
Specifies a maximum number of Worker threads. If you set this value to<br />
-1, no limits are applied to the number of ConnectionManager threads.<br />
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
-trace<br />
Enables standard tracing (see “Tracing” on page 209). By default, the trace<br />
output shows only the first 128 bytes of any data blocks (for example the<br />
COMMAREA, or network flows). Other useful information, including the<br />
value of the CLASSPATH variable, and the codepage, is shown at the top of<br />
the trace output.<br />
If you used the configuration tool to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
the default destination for the trace output is file ctg.trc in the<br />
\bin subdirectory. Otherwise, trace output is written to<br />
stderr.<br />
-noinput<br />
Disables the reading of input from the console.<br />
-tfile=pathname<br />
If tracing is enabled, trace output is written to the file specified in<br />
pathname. This overrides the default destination for trace output (see the<br />
-trace option).<br />
-x Enables full debug tracing (see “Tracing” on page 209). By default, the<br />
trace output shows the whole of any data blocks (for example the<br />
COMMAREA, or network flows). It also displays more information about<br />
the internal <strong>Gateway</strong> processing than the standard trace. See the -trace<br />
and -tfile options for information on the destination for trace output.<br />
Debug tracing significantly decreases performance.<br />
-tfilesize=number<br />
Specifies the maximum size, in kilobytes, of the trace output file.<br />
-truncationsize=number<br />
The value number specifies the maximum size of any data blocks that are<br />
shown in the trace. You can use this option with either the -trace or -x<br />
options to override the default size. Any positive integer is valid. If you<br />
specify a value of 0, then no data blocks are shown in the trace.<br />
-dnsnames<br />
Enables the display of symbolic TCP/IP hostnames in messages. See<br />
“Display TCP/IP hostnames” on page 60 for more information.<br />
-dumpoffset=number<br />
The value number specifies the offset from which displays of any data<br />
blocks start. If the offset is greater than the total length of data to be<br />
displayed, an offset of 0 is used.<br />
-stack<br />
Enables Java exception stack tracing (see “Tracing” on page 209). Java<br />
exceptions are traced, including those which are expected during normal<br />
operation of the <strong>Gateway</strong>. No other trace output is created. See the -trace<br />
and -tfile options for information on the destination for trace output.<br />
Chapter 9. Operating the <strong>Gateway</strong> 143
|<br />
|<br />
|<br />
|<br />
-j Pass an argument to the JVM. For example, -j-D= sets a<br />
JVM system property. See the JVM command line interpreter help for<br />
guidance in using this switch. This replaces the -X switch used in versions<br />
of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> prior to <strong>5.0</strong>.<br />
To override the startup defaults type ctgstart at the command prompt,<br />
followed by the start-up options you require, and press Enter. Options<br />
specified on the command line override those specified using the configuration<br />
tool.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used for TCP/IP:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345<br />
To get help on the startup options, enter:<br />
ctgstart -?<br />
Stopping the <strong>Gateway</strong><br />
To stop the <strong>Gateway</strong>:<br />
v If you did not start the <strong>Gateway</strong> with the -noinput option, you can stop it<br />
by typing the correct character and pressing the Enter key in the <strong>Gateway</strong><br />
console session. The allowable characters may be localized for your country;<br />
the default characters allowed are the Q or - characters.<br />
You can determine which characters will stop the <strong>Gateway</strong> by simply<br />
pressing the Enter key in the <strong>Gateway</strong> console session. A message like the<br />
following is displayed:<br />
CCL6508I: Type Q or - to stop the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v If you used the -noinput option, you must stop the <strong>Gateway</strong> process using<br />
some other method, for example:<br />
– Enter Ctrl-C in the <strong>Gateway</strong> console session<br />
– Use theWindows Task Manager<br />
Note: If you try to close the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> console window by<br />
using either the ’X’ close-window icon, or the Close menu item, a Full<br />
thread dump is produced. This is an effect common to all Java<br />
applications, including the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> icons<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supplied with the following Start Menu<br />
shortcuts:<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Starts the <strong>Gateway</strong> daemon according to the definitions in the<br />
configuration file.<br />
This is equivalent to the command CTGSTART<br />
The Client daemon is automatically run when this icon is<br />
used.<br />
Start Client Starts the Client daemon according to the definitions in the<br />
configuration file.<br />
This is equivalent to the command <strong>CICS</strong>CLI /s /w<br />
Stop Client Stops the Client daemon.<br />
This is equivalent to the command <strong>CICS</strong>CLI /x /w<br />
Client Status Lists connected servers.<br />
This is equivalent to the command <strong>CICS</strong>CLI /l /w<br />
Config Tool Runs the configuration tool which provides a graphical user<br />
interface for editing the configuration file.<br />
<strong>CICS</strong> Terminal<br />
Starts a 3270 terminal emulation session according to<br />
definitions in the configuration file.<br />
This is equivalent to the command <strong>CICS</strong>TERM /s<br />
<strong>CICS</strong> Printer Displays help information for <strong>CICS</strong> print terminal emulation.<br />
This is equivalent to the command <strong>CICS</strong>PRNT /?<br />
iKeyMan This runs the IBM Key Management program which allows<br />
you to modify your key database content.<br />
Documentation<br />
Opens up the PDF Documentation library file which contains<br />
the manuals relating to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Programming Reference<br />
Opens the Java Programming Reference HTML in your default<br />
browser.<br />
ReadMe Displays the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Readme file in your<br />
default text file viewer.<br />
See “Creating Start Menu shortcuts” on page 36 for instructions on how to<br />
create additional Start Menu shortcuts<br />
Chapter 9. Operating the <strong>Gateway</strong> 145
Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows service<br />
When you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the daemon process is installed<br />
as a Windows service. Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows<br />
service has several advantages:<br />
v You can have the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service started automatically at<br />
Windows startup, without having to log on to the computer.<br />
v You can log off from Windows and keep <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
running, thereby avoiding restarting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and its<br />
connection to <strong>CICS</strong> when you log on to Windows again.<br />
v Relevant messages associated with running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a<br />
service are recorded in the Application log and System log of the Windows<br />
Event Viewer when the service is started and stopped.<br />
IBM recommends that you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service as either<br />
System (Administrator), or as a user with the log on as a service right in a<br />
secured environment.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is registered as a Windows service during<br />
installation. After installation, the Services dialog box in the Control Panel<br />
contains the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service.<br />
There is also a utility, ctgservice, that allows you to remove and install the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service.<br />
Windows Client daemon is also registered as a Windows service during<br />
installation, for more information, see “Client daemon service” on page 149.<br />
Starting and stopping the service<br />
To start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service, select the service in the<br />
Services dialog box, and select Start. A message is displayed and the service is<br />
started.<br />
To stop the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service, select the service in the<br />
Services dialog box, and select Stop. A message is displayed and the service is<br />
stopped.<br />
Startup options for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service<br />
IBM recommends that you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service<br />
automatically at Windows startup, so that it is always running.<br />
Note: You must have Administrator authority to configure service startup.<br />
To specify automatic startup on Windows NT:<br />
1. Select the service in the services dialog.<br />
146 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
2. Select Startup in the Services dialog box. The Service panel is then<br />
displayed.<br />
3. Select the Automatic radio button, and make sure that the System<br />
Account radio button is selected.<br />
The Service panel also allows you to specify a Manual startup for the service,<br />
and to disable the service.<br />
To specify automatic startup on Windows 2000 and Windows XP :<br />
1. Select the service in the services dialog.<br />
2. From the menu bar select Action –> Properties.<br />
3. Change the Startup type to Automatic.<br />
4. Select the Log On tab.<br />
5. Make sure that the Local System Account radio button is selected.<br />
The Service panel also allows you to specify a Manual startup for the service,<br />
and to disable the service.<br />
For more information on services and their configuration, refer to the<br />
Windows documentation.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service and console messages<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service reports only standard Windows service<br />
messages to the system application log.<br />
Like other Windows services, when the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service is<br />
running, no console output is available. This means that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> trace and debug messages will not be available as console output.<br />
However, you can overcome this problem by specifying the ctgstart -tfile<br />
option, which allows redirection of trace messages to a text file.<br />
When installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service, you should ensure<br />
that the -noinput command line option is passed. By default, the <strong>Gateway</strong><br />
checks Standard.in() for keyboard input (such as ″Q″ to stop the <strong>Gateway</strong>).<br />
The default setting will throw an exception in the <strong>Gateway</strong> code, as<br />
Standard.in() is not available when running as a service.<br />
The ctgservice utility<br />
The ctgservice utility allows you to install and remove the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> service, and pass startup options to the ctgstart command.<br />
The ctgservice utility uses the JVM specified by the ctgjava command, see “Set<br />
the JVM” on page 52.<br />
The syntax of ctgservice is as follows:<br />
Chapter 9. Operating the <strong>Gateway</strong> 147
|<br />
ctgservice [-i] [-r] [-c] [?]<br />
[-ACTGParam1 -ACTGParam2...]<br />
where:<br />
-i Installs the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service.<br />
-r Removes the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service.<br />
-c Runs the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a console application, that is, the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will run in a console window as it does when<br />
started with the ctgstart command. If you do not specify this option, you<br />
will not see any console messages.<br />
-? Displays help information for ctgservice.<br />
-A Specifies an option to be passed to the ctgstart command. All ctgstart<br />
command line options can be passed. Each option must be prefixed with<br />
-A. Note that the -noinput option is always required when running the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a service. This prevents standard input from<br />
being read by the Java application, which could cause an exception.<br />
The following is a typical example of a ctgservice command:<br />
ctgservice -i<br />
-A-noinput -A-x -A-tfile="e:\the<strong>Gateway</strong>\myTrace.txt"<br />
This example would install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and specify the<br />
-noinput, -x and -tfile options for the ctgstart command.<br />
Note: Because the Windows service runs under the system account, it may<br />
not have sufficient access privileges to write to a network file. If this is<br />
so, then any pathname that you specify in the -tfile option must be for<br />
a local file.<br />
You can test the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and ctgstart options by running<br />
the service in ″console″ mode. The service must already be installed on the<br />
system. The command ctgservice -c will then run the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> in the console window (identical in operation to running the normal<br />
ctgstart script), using the values it was installed with. These values are stored<br />
statically in the Windows registry.<br />
Note: If you find that the message:<br />
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> error: 0,<br />
Cannot create Java Virtual Machine<br />
is displayed when you run ctgservice, this is probably because you<br />
have a JVM referenced in the PATH setting before the JVM required by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Make sure that your PATH setting<br />
148 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
includes the bin directory of the supported level of Java that you are<br />
using, before any other JVM references.<br />
Running as a Windows service under Java 1.3.0<br />
Java 1.3.0 does not survive a Windows logoff, and so any Java applications<br />
running cease at logoff. This is a known issue, and affects the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. To overcome it, pass the -j-Xrs parameter to Java when<br />
running the application. If you used the <strong>Gateway</strong> Installer to install the<br />
Windows services, the <strong>Gateway</strong> service will be set up to run with this flag<br />
and the services will work correctly. However, if you install the <strong>Gateway</strong><br />
service manually, using the ctgservice command, you must include the -j-Xrs<br />
parameter:<br />
ctgservice -i -A-j-Xrs<br />
Client daemon service<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service requires that the Client daemon service<br />
is installed and started, therefore:<br />
v Starting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service (via the Control Panel)<br />
results in the Client daemon service starting.<br />
v Stopping the Client daemon service (via the Control Panel) results in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> service also stopping.<br />
Administering your system<br />
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on<br />
page 69), you can perform the following administrative functions without<br />
having to restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
v Set the <strong>Gateway</strong> trace<br />
v Set JNI trace<br />
v Query the current trace settings<br />
You execute the Java archive ctgadmin.jar from a command prompt to set<br />
trace or to query trace settings. You can administer the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> remotely from a workstation that has this JAR file and the supported<br />
level of Java; you do not need to install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the<br />
workstation. See “TCPAdmin protocol settings” on page 69 for details of how<br />
to define which hosts have permission to administer your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
The following sections describe the commands. Parameters are not case<br />
sensitive; those in brackets are optional.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier than version <strong>5.0</strong>.<br />
Earlier versions cause the administration program to lock. If this<br />
happens, terminate the process, for example by pressing Ctrl+C.<br />
Chapter 9. Operating the <strong>Gateway</strong> 149
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
Setting the <strong>Gateway</strong> trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]<br />
[-tfilesize=number] [-tlevel=number]<br />
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]<br />
See “Parameters” for an explanation of parameters.<br />
Setting the JNI trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address<br />
-a=setjnitrace -tfile=path [-tlevel=number]<br />
See “Parameters” for an explanation of parameters.<br />
Querying trace settings<br />
From a command prompt, issue the following command:<br />
Parameters<br />
java -jar ctgadmin.jar -ctg=address -a=qtrace<br />
See “Parameters” for an explanation of parameters.<br />
ctg Mandatory. Specifies the <strong>Gateway</strong> which is to be<br />
administered. You can specify either a hostname, for example<br />
tcp://myserver:2810, or an IP address, for example<br />
tcp://127.0.0.1:2810. In these examples, 2810 is the port you<br />
specified for TCPAdmin; see “TCPAdmin protocol settings” on<br />
page 69.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier<br />
than version <strong>5.0</strong>. Earlier versions cause the<br />
administration program to lock. If this happens,<br />
terminate the process, for example by pressing<br />
Ctrl+C.<br />
a Mandatory. Defines the action to take. Permitted values are:<br />
v setgwtrace to control <strong>Gateway</strong> tracing<br />
v setjnitrace to control JNI tracing<br />
v qtrace to determine what trace settings are active<br />
tfile Specifies the output file for <strong>Gateway</strong> or JNI tracing, for<br />
example ./tracefile.trc. Do not specify the same file for<br />
<strong>Gateway</strong> and JNI trace output.<br />
<strong>Gateway</strong> tracing<br />
If you do not specify a value for this tag, trace output is<br />
sent to the console.<br />
150 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
JNI tracing<br />
You must specify a value for this tag. If you do not, an<br />
error is displayed.<br />
tlevel Specifies the trace level. Permitted values are:<br />
<strong>Gateway</strong> tracing:<br />
0 Off. No trace information is output.<br />
1 Exception tracing. Only exceptions are traced.<br />
Equivalent to ctgstart -stack; see “Starting the<br />
<strong>Gateway</strong> with user-specified options” on page 142.<br />
2 Trace exceptions, and entry and exit of methods.<br />
3 Trace exceptions, some internals, and entry and<br />
exit of methods (equivalent to ctgstart -trace).<br />
4 Full debug tracing (all trace points, equivalent to<br />
ctgstart -x).<br />
JNI tracing:<br />
0 Off. No trace information is output.<br />
1 On.<br />
tfilesize Specifies the maximum size, in kilobytes, of the trace output<br />
file, for example 50000.<br />
dumpoffset Specifies the offset from which displays of any data blocks<br />
start, for example 512. If the offset is greater than the total<br />
length of data to be displayed, an offset of 0 is used. You<br />
cannot use this together with the fulldatadump parameter.<br />
truncationsize Specifies the byte at which to stop the hex dump, for example<br />
2000. It defines the end point, not the number of bytes to<br />
display. So if on a dump of size 40 you set the dumpoffset to<br />
11, and the truncationsize to 25, you will see 15 bytes (from<br />
11 to 25).<br />
You cannot use this together with the fulldatadump parameter.<br />
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in<br />
truncationsize.<br />
Chapter 9. Operating the <strong>Gateway</strong> 151
Administering your system<br />
152 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 10. Operating the Client daemon<br />
This chapter describes how to operate the Client daemon. It consists of the<br />
following:<br />
“The <strong>CICS</strong>CLI command” Read this for an introduction to the Client<br />
daemon command.<br />
“Running the Client daemon as a<br />
Windows service”<br />
Read this for information on running the<br />
Client daemon as a Windows service<br />
“The <strong>CICS</strong>CLI command” on page 156 Read this for information on using the<br />
<strong>CICS</strong>CLI command to control the Client<br />
daemon.<br />
“<strong>CICS</strong>CLI command reference” on<br />
page 160<br />
Read this for a detailed reference to the<br />
<strong>CICS</strong>CLI command.<br />
The <strong>CICS</strong>CLI command<br />
The <strong>CICS</strong>CLI command is used to start and stop the Client daemon, check the<br />
availability of servers, and set other options..<br />
The Client daemon starts automatically when you invoke any of the client<br />
functions, such as EPI, ECI, or 3270 terminal emulation. You do not need to<br />
use the <strong>CICS</strong>CLI command to start the Client daemon explicitly.<br />
You must explicitly terminate any server connections initiated by ECI calls. To<br />
do this, use the <strong>CICS</strong>CLI -x=servername or <strong>CICS</strong>CLI -i=servername command.<br />
See “<strong>CICS</strong>CLI command reference” on page 160.<br />
Running the Client daemon as a Windows service<br />
You can run the Client daemon as a Windows service. This has several<br />
advantages:<br />
v You can choose to start the Client daemon automatically at Windows<br />
startup, without having to log on to the computer.<br />
v You can log off from Windows and keep the Client daemon running. This<br />
avoids the need to restart the Client daemon and its connection to <strong>CICS</strong><br />
when you log on to Windows again.<br />
v Error messages associated with running the Client daemon as a service are<br />
recorded in the Application log and System log, of the Windows Event Viewer,<br />
when the service is started and stopped.<br />
© Copyright IBM Corp. 1996, 2002 153
Running the Client daemon as a Windows service<br />
It is recommended that you start the Client daemon as a service if running<br />
under Windows 2000 Terminal Services. This is because, if a user’s application<br />
starts the Client daemon, and that user then logs off, the Client daemon<br />
process terminates.<br />
The Client daemon is registered as a Windows service during installation.<br />
After installation, the Services dialog box in the Control Panel contains the<br />
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and IBM <strong>CICS</strong> Universal Client services.<br />
Service controls<br />
You can use the Windows service API functions to pass service control<br />
requests to the Client daemon service. Refer to your Windows documentation<br />
for further details about how to do this.<br />
The control requests that you can pass to the Client daemon service are<br />
defined in the cicsserv.h file in the \ include subdirectory.<br />
The following are the control requests that you can pass to the Client daemon<br />
service.<br />
Control Request Description<br />
<strong>CICS</strong>_SRV_STOP Stops the Client daemon. This also stops the<br />
service.<br />
<strong>CICS</strong>_SRV_STOP_IMMEDIATE<br />
Forces the Client daemon to terminate<br />
immediately. This also stops the service.<br />
<strong>CICS</strong>_SRV_LIST Lists the servers to which the Client daemon<br />
is currently connected.<br />
<strong>CICS</strong>_SRV_DISK_TRACE_ON<br />
Starts writing trace information to the<br />
<strong>CICS</strong>CLI.BIN file in the \bin<br />
subdirectory.<br />
<strong>CICS</strong>_SRV_DISABLE_POPUP<br />
Suppresses error and security popups for the<br />
Client daemon.<br />
<strong>CICS</strong>_SRV_ENABLE_POPUP Activates error and security popups for the<br />
Client daemon.<br />
<strong>CICS</strong>_SRV_QUIET Suppresses all Client daemon messages.<br />
In addition to these control requests, you can also pass standard Windows<br />
requests to the service, such as: SERVICE_CONTROL_STOP,<br />
SERVICE_CONTROL_PAUSE, SERVICE_CONTROL_CONTINUE, and<br />
SERVICE_CONTROL_INTERROGATE.<br />
154 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Service startup parameters<br />
If you run the Client daemon as a service, you can use the Windows service<br />
control panel to pass parameters to the service when starting from the dialog.<br />
The following parameters are valid:<br />
-S[=server] Starts the Client daemon, and optionally connects to a server.<br />
-D[=size] Enables service tracing, and optionally sets a size limit.<br />
-U[=userid] Sets the userid to be used with a server.<br />
-P[=password] Sets the password to be used with a server.<br />
-N Suppresses error and security popups for the Client daemon.<br />
-R[=filename] Redirects all output for the Client daemon to the specified file.<br />
Starting and stopping the service<br />
To start the Client daemon service, select the service in the Services dialog<br />
box, and select Start. A message displays and the service starts.<br />
To stop the Client daemon service, select the service in the Services dialog<br />
box, and select Stop. A message displays and the service stops.<br />
Starting the Client daemon service at Windows startup<br />
You can choose to start the Client daemon service automatically at Windows<br />
startup.<br />
To specify automatic startup:<br />
Running the Client daemon as a Windows service<br />
Windows 2000 and Windows XP<br />
1. Log in as a user with Administrator authority.<br />
2. Open the Services dialog box, right-click the IBM <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> service, and select Properties.<br />
3. Change Startup type to Automatic.<br />
4. Select the Log On tab, and make sure that the Local System account radio<br />
button is selected.<br />
Windows NT<br />
1. Log in as a user with Administrator authority.<br />
2. Open the Services dialog box and select the IBM <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> service.<br />
3. Select Startup... in the Services dialog box; the Service panel is displayed.<br />
4. Select the Automatic radio button.<br />
5. Make sure that the System Account radio button is selected.<br />
Chapter 10. Operating the Client daemon 155
|<br />
|<br />
|<br />
|<br />
Running the Client daemon as a Windows service<br />
The Service panel also allows you to specify a Manual startup for the service,<br />
and to disable the service.<br />
For more information on services and their configuration, refer to your<br />
Windows documentation.<br />
The <strong>CICS</strong>CLI command<br />
The following table shows the functions that you can perform with the<br />
<strong>CICS</strong>CLI command, and the parameters associated with each function:<br />
Function Parameters<br />
Start the Client daemon, and start communication with <strong>CICS</strong><br />
servers<br />
-s<br />
Stop the Client daemon -i and -x<br />
Restart the Client daemon -j and -y<br />
Start client tracing -d<br />
Stop client tracing -o<br />
Specify the client components to be traced -m<br />
Set up security -c, -u, and -p<br />
List connected <strong>CICS</strong> servers -l<br />
Enable the display of pop-up messages -e<br />
Disable the display of pop-up messages -n<br />
Wait for confirmation before completion -w<br />
Display information about the version and build level of the Client<br />
daemon<br />
-v<br />
The following sections provide examples of using the <strong>CICS</strong>CLI command. Full<br />
details of the command syntax are in “<strong>CICS</strong>CLI command reference” on<br />
page 160.<br />
Starting the Client daemon<br />
To start the Client daemon, enter:<br />
<strong>CICS</strong>CLI -s<br />
or use the Start Client shortcut.<br />
To start the Client daemon and start communication with a <strong>CICS</strong> server, enter:<br />
<strong>CICS</strong>CLI -s=servername<br />
where servername is the name of a <strong>CICS</strong> server.<br />
156 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Starting connections with additional servers<br />
To start a connection to a <strong>CICS</strong> server when the Client daemon is already<br />
running, enter:<br />
<strong>CICS</strong>CLI -s=servername<br />
where servername is the name of a <strong>CICS</strong> server.<br />
Note: If you change and reinstall the the <strong>CICS</strong> connection definition, you<br />
must stop and restart the connection.<br />
Stopping the Client daemon in a controlled manner<br />
To stop the Client daemon for all connected servers, after all outstanding units<br />
of work have completed, enter:<br />
<strong>CICS</strong>CLI -x<br />
or use the Stop Client shortcut.<br />
To terminate the session with a particular server, enter:<br />
<strong>CICS</strong>CLI -x=servername<br />
where servername is the name of a <strong>CICS</strong> server. This stops only the session<br />
with the named server; it does not stop the Client daemon or connections to<br />
other servers.<br />
Note:<br />
If you want to stop and restart the Client daemon, you must first stop<br />
the <strong>Gateway</strong> daemon. Failure to do so causes both the <strong>Gateway</strong><br />
daemon and the Client daemon to behave unpredictably. When the<br />
<strong>Gateway</strong> daemon has stopped, you can stop and restart the Client<br />
daemon before restarting the <strong>Gateway</strong> daemon.<br />
Stopping the Client daemon immediately<br />
To stop the Client daemon for all connected servers, without completing<br />
outstanding units of work, enter:<br />
<strong>CICS</strong>CLI -i<br />
To terminate the session with a particular server, enter:<br />
<strong>CICS</strong>CLI -i=servername<br />
The <strong>CICS</strong>CLI command<br />
where servername is the name of a <strong>CICS</strong> server. This stops only the session<br />
with the named server; it does not stop the Client daemon or connections to<br />
other servers.<br />
Chapter 10. Operating the Client daemon 157
The <strong>CICS</strong>CLI command<br />
Restarting the Client daemon in a controlled manner<br />
To stop the Client daemon for all connected servers, after all outstanding units<br />
of work have completed, and then start it again, enter:<br />
<strong>CICS</strong>CLI -y<br />
<strong>CICS</strong>CLI -y is equivalent to <strong>CICS</strong>CLI -x followed by <strong>CICS</strong>CLI -s. This does not<br />
re-establish server connections.<br />
Restarting the Client daemon immediately<br />
To stop the Client daemon for all connected servers, without completing<br />
outstanding units of work, and then start it again, enter:<br />
<strong>CICS</strong>CLI -j<br />
<strong>CICS</strong>CLI -j is equivalent to <strong>CICS</strong>CLI -i followed by <strong>CICS</strong>CLI -s. This does not<br />
re-establish server connections.<br />
Starting client tracing<br />
To start tracing the Client daemon, enter:<br />
<strong>CICS</strong>CLI -d<br />
To trace the Client daemon from the startup sequence, enter the -s and -d<br />
parameters together.<br />
The Client daemon writes trace entries to the <strong>CICS</strong>CLI.BIN file in the<br />
\bin subdirectory. New trace entries overwrite any existing<br />
entries in the trace file. If required, make a backup copy of the old trace file<br />
before you start tracing.<br />
Use the <strong>CICS</strong>FTRC utility to format the trace file.<br />
Specifying the trace components<br />
To specify which client components to trace, enter, for example:<br />
<strong>CICS</strong>CLI -m=TRN,API.2<br />
For information on which components you can trace, see “<strong>CICS</strong>CLI command<br />
reference” on page 160.<br />
Stopping client tracing<br />
To stop tracing the Client daemon, enter:<br />
<strong>CICS</strong>CLI -o<br />
Setting up security<br />
You can use the following commands after first starting the Client daemon.<br />
To set a userid to use when accessing server servername, enter:<br />
<strong>CICS</strong>CLI -c=servername -u=userid<br />
158 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
where userid is the userid and servername is the servername.<br />
To set a password to use when accessing server servername, enter:<br />
<strong>CICS</strong>CLI -c=servername -p=password<br />
where password is the password and servername is the name of the server.<br />
You can enter the -u and -p parameters together.<br />
<strong>Version</strong> information<br />
To display information about the version and build level of your Client<br />
daemon, enter the command<br />
<strong>CICS</strong>CLI -v<br />
The Client daemon displays information similar to Figure 20:<br />
CCL8001I <strong>CICS</strong>CLI - <strong>CICS</strong> Client Control Program<br />
CCL0002I (C) Copyright IBM Corporation 1994, 2002. All rights reserved.<br />
CCL8029I <strong>CICS</strong> Client for Windows <strong>Version</strong> <strong>5.0</strong> Service Level 00<br />
CCL8074I Build Level ’c000-20020510a’<br />
CCL8025I The <strong>CICS</strong> Client has not been started<br />
CCL8023I <strong>CICS</strong>CLI performed no action<br />
Figure 20. <strong>Version</strong> and build level information for the Client daemon<br />
Listing the connected servers<br />
To list all the servers being used by the Client daemon, and their status, enter:<br />
<strong>CICS</strong>CLI -l<br />
or use the Client Status shortcut.<br />
The <strong>CICS</strong>CLI control program displays information similar to Figure 21:<br />
CCL8001I <strong>CICS</strong>CLI - <strong>CICS</strong> Client Control Program<br />
CCL0002I (C) Copyright IBM Corporation 1994,2002. All rights reserved.<br />
CCL8041I The <strong>CICS</strong> client is using the following servers:<br />
CCL8042I Server ’<strong>CICS</strong>WIN’ (using ’TCP/IP’ to ’<strong>CICS</strong>WIN’) is available<br />
Figure 21. Example list of <strong>CICS</strong> servers<br />
Disabling the display of messages<br />
To disable the display of all messages output with the command, enter, for<br />
example:<br />
<strong>CICS</strong>CLI -s -q<br />
Enabling and disabling the display of pop-up messages<br />
To disable the display of pop-up messages, enter:<br />
<strong>CICS</strong>CLI -n<br />
The <strong>CICS</strong>CLI command<br />
Chapter 10. Operating the Client daemon 159
The <strong>CICS</strong>CLI command<br />
To enable the display of pop-up messages again, enter:<br />
<strong>CICS</strong>CLI -e<br />
You can specify the -n parameter together with the -s parameter.<br />
The display of pop-up messages is enabled by default.<br />
Displaying the command parameters<br />
To display the parameters of the <strong>CICS</strong>CLI command, enter:<br />
<strong>CICS</strong>CLI -?<br />
The <strong>CICS</strong>CLI command and applications<br />
You can call <strong>CICS</strong>CLI from within applications, if this is supported by the<br />
programming language. You can therefore enter <strong>CICS</strong>CLI at the command<br />
line, then run an application to call <strong>CICS</strong>CLI with additional parameters.<br />
Alternative to <strong>CICS</strong>CLI.EXE<br />
<strong>CICS</strong>CLIW.EXE performs the same functions as <strong>CICS</strong>CLI. However, it is a<br />
Windows program that issues all of its messages into a dialog box, rather than<br />
the command prompt. Use it if you want the Client daemon to behave in the<br />
same way as the <strong>CICS</strong> Client for Windows 3.11 v2.<br />
<strong>CICS</strong>CLI command reference<br />
To conform with other popular syntax conventions, the dash (-) may be<br />
replaced with the forward slash (/) character. The commands and options are<br />
not case-sensitive.<br />
All options of the form -x=variable may contain spaces in the variable part, if<br />
it is enclosed in double quotes. Double quotes within variables must be<br />
entered as \″ , that is with a backslash preceding the double quote.<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page x.<br />
<strong>CICS</strong>CLI Command Syntax<br />
160 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
►► <strong>CICS</strong>CLI -s<br />
-s=servername -d -m -n<br />
-d=nnn -m=components<br />
-o<br />
-d<br />
-d=nnn<br />
-m<br />
-m=components<br />
-x<br />
-x=servername<br />
-i<br />
-i=servername<br />
-l<br />
-j<br />
-y<br />
-c=servername<br />
-u=userid -p=password<br />
-u -p<br />
-e<br />
-n<br />
-?<br />
The <strong>CICS</strong>CLI command<br />
The options are:<br />
-c=servername Identifies the name of the server to which security information<br />
in the form of a userid and password is to be associated.<br />
Some <strong>CICS</strong> servers require the user to provide security<br />
information to the server before interacting with the server.<br />
The Client daemon prompts the user at the workstation for a<br />
userid and password, unless these have already been<br />
provided via <strong>CICS</strong>CLI (see the descriptions of the -u and -p<br />
options).<br />
-d=[nnn] Starts debug tracing for the Client daemon. If tracing is<br />
required while the Client daemon is starting up, this option<br />
may be specified along with the -s option.<br />
nnn is the maximum size of data areas to be traced in bytes.<br />
The range is 1 through 32 767 bytes, and the default value is<br />
512 bytes.<br />
The Client daemon writes trace entries to the <strong>CICS</strong>CLI.BIN file<br />
in the \bin subdirectory. New trace entries<br />
overwrite any existing entries in the trace file. If required,<br />
make a backup copy of the old trace file before you start<br />
tracing.<br />
Use the <strong>CICS</strong>FTRC utility to format the trace file. The resulting<br />
file, <strong>CICS</strong>CLI.TRC, is an ASCII file that you can read with a text<br />
editor. For more information see “Formatting the binary trace<br />
file” on page 222.<br />
-q<br />
-w<br />
Chapter 10. Operating the Client daemon 161<br />
►◄
The <strong>CICS</strong>CLI command<br />
-e Enables the display of Client daemon error and security<br />
messages in pop-up windows.<br />
-i Stops the Client daemon immediately. The options<br />
-i=servername and -i operate as for -x=servername and -x<br />
respectively but the Client daemon does not wait for<br />
outstanding units of work to complete. Stopping the Client<br />
daemon in this way may result in a loss of data at connected<br />
servers.<br />
-j Stops the Client daemon immediately and then restarts it.<br />
A restart involves shutting down the Client daemon, waiting<br />
for it to shut down, and then starting it again. <strong>CICS</strong>CLI -j is<br />
equivalent to <strong>CICS</strong>CLI -i followed by <strong>CICS</strong>CLI -s. Server<br />
connections are not re-established when the Client daemon is<br />
restarted.<br />
Using -y is the preferred way of restarting the Client daemon.<br />
-l Causes a list of all connected servers to be displayed. For each<br />
server, the netname of the server as it is known to the Client<br />
daemon is also displayed, as well as the state of the<br />
connection to the server and the connection protocol.<br />
-m=[components]<br />
Specifies a comma-separated list of identifiers for components<br />
that will be traced when tracing starts. You can specify any of<br />
the following components:<br />
ALL All components<br />
API.1 The client API layer (level 1). This gives basic<br />
API tracing.<br />
API.2 The client API layer (level 1 and 2). This gives<br />
level 1 plus additional parameter tracing.<br />
API Synonymous with API.1<br />
CCL The Client daemon<br />
CPP The C++ class libraries<br />
CLI The <strong>CICS</strong>CLI command interface<br />
DEF The default components, that is the API, CCL,<br />
and DRV.1 components<br />
DRV Synonymous with DRV.1<br />
DRV.1 Protocol driver tracing level 1. This traces data<br />
sent and received and provides supplementary<br />
information about failures.<br />
162 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
The <strong>CICS</strong>CLI command<br />
DRV.2 Protocol driver tracing level 2. This traces<br />
internal flows through the protocol drivers<br />
and interactions with other software<br />
components. It is currently supported only by<br />
the CCLTCP62 protocol driver.<br />
EMU <strong>CICS</strong>TERM and <strong>CICS</strong>PRNT emulators<br />
LMG The Workload Manager<br />
SER The Client daemon Windows service<br />
TRN Interprocess communication<br />
For guidance on when to use the tracing options, see<br />
“Choosing which components to trace” on page 221.<br />
The -m parameter does not start tracing in the Client daemon;<br />
it simply specifies the components to trace. You cannot use -m<br />
while the Client daemon is not running, so you must specify<br />
the -s parameter before you use -m.<br />
If you specify -m with no parameters, a list of the possible<br />
component identifiers is displayed, with an ’x’ beside each<br />
component that it is currently enabled for tracing.<br />
You can also specify settings for trace components using the<br />
configuration tool (see “Trace settings” on page 86 in the<br />
Configuration chapter for details). Any component tracing<br />
specified using <strong>CICS</strong>CLI overrides that specified using the<br />
configuration tool. If component tracing is not specified either<br />
by the <strong>CICS</strong>CLI command or by using the configuration tool,<br />
a default set of components is traced, namely: DRV.1, CCL,<br />
and API. Any component tracing specified using the<br />
configuration tool overrides the default set of components.<br />
For the API and DRV components, you can specify the level<br />
of information to trace. For example components API or API.1<br />
specify that basic API-related information is traced before and<br />
after ECI and EPI calls. Component API.2 specifies that<br />
additional API trace entries are produced in addition to those<br />
of level 1.<br />
Note that the <strong>CICS</strong>CLI -d=nnn command is used to set the<br />
maximum size of the data areas to be traced. The trace data<br />
may be truncated if you set nnn lower than the size of data<br />
expected.<br />
Chapter 10. Operating the Client daemon 163
The <strong>CICS</strong>CLI command<br />
-n Disables the display of Client daemon error and security<br />
messages in pop-up windows.<br />
Any messages that would have been logged are still logged.<br />
-o Stops tracing if it is already active.<br />
-p=password Sets the current password to be used when accessing the<br />
server specified by the -c parameter. (Or by the -s parameter.)<br />
This password is used if the server requires a password (and<br />
userid) before running transactions on the client’s behalf.<br />
For ECI applications, any userid and password specified in<br />
the ECI parameter block overrides values set via the <strong>CICS</strong>CLI<br />
command.<br />
Specifying -p or -p= (that is, no password is specified) resets<br />
the associated password to a null value.<br />
-q Disables the display of all messages output with the <strong>CICS</strong>CLI<br />
command.<br />
-s Starts the Client daemon. No attempt is made to initiate<br />
communication with a server unless -s=servername is specified.<br />
In this case, the Client daemon also connects to the server<br />
using information specified in the configuration file. The<br />
servername must exist in the configuration file.<br />
-u=userid Sets the current userid to be used when accessing the server<br />
specified by the -c parameter. (Or by the -s parameter.) This<br />
userid is used if the server requires a userid (and password)<br />
before running transactions for the Client daemon.<br />
For ECI applications, any userid and password specified in<br />
the ECI parameter block overrides values set via the <strong>CICS</strong>CLI<br />
command.<br />
Specifying -u or -u= (that is, no userid is specified) resets the<br />
associated userid to a null value.<br />
-v Displays information about the version and build level of the<br />
Client daemon.<br />
-w Prompts the user, before the command completes, to press the<br />
Enter key, to confirm that messages output to the screen (both<br />
informational and error) have been read.<br />
-x Stops the Client daemon in a controlled manner. If<br />
-x=servername is specified, then when all outstanding units of<br />
work on the specified server have completed, the connection<br />
to the server is terminated. If other server connections are<br />
active, these remain unchanged.<br />
164 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
The <strong>CICS</strong>CLI command<br />
If -x is specified without a servername, the Client daemon<br />
waits for all outstanding units of work to complete, terminates<br />
all connections to servers, and ends the control process. Using<br />
-x or -x=servername is the preferred way of stopping the Client<br />
daemon.<br />
-y Restarts the Client daemon in a controlled manner.<br />
A restart involves shutting down the Client daemon, waiting<br />
for it to shut down, and then starting it up again. <strong>CICS</strong>CLI -y<br />
is equivalent to <strong>CICS</strong>CLI -x followed by <strong>CICS</strong>CLI -s. Server<br />
connections are not re-established when the Client daemon is<br />
restarted.<br />
Using -y is the preferred way of restarting the Client daemon.<br />
-? Causes the command syntax to be displayed.<br />
Note: The -f parameter is no longer supported. See “Using the configuration<br />
tool” on page 54 for information on how to specify a configuration file.<br />
Chapter 10. Operating the Client daemon 165
The <strong>CICS</strong>CLI command<br />
166 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 11. Terminal Emulation<br />
This chapter describes how to use the <strong>CICS</strong>TERM and <strong>CICS</strong>PRNT programs.<br />
It consists of the following:<br />
“Summary of Terminal Emulation<br />
commands”<br />
“<strong>CICS</strong>TERM command reference” on<br />
page 169<br />
“Terminal emulator preferences” on<br />
page 172<br />
Read this for a summary of the<br />
commands explained in this chapter.<br />
Read this for a detailed reference to the<br />
<strong>CICS</strong>TERM command.<br />
Read this for information on setting<br />
preferences for the terminal emulator.<br />
“The <strong>CICS</strong>PRNT command” on page 173 Read this for information on using the<br />
<strong>CICS</strong>PRNT command to control 3270<br />
printer terminal emulation.<br />
“<strong>CICS</strong>PRNT command reference” on<br />
page 175<br />
Summary of Terminal Emulation commands<br />
Read this for a detailed reference to the<br />
<strong>CICS</strong>PRNT command.<br />
<strong>CICS</strong>TERM<br />
This command starts a terminal emulation session with particular<br />
options.<br />
<strong>CICS</strong>PRNT<br />
This command starts a printer terminal session with particular<br />
options.<br />
The <strong>CICS</strong>TERM command<br />
The <strong>CICS</strong>TERM command controls 3270 terminal emulation. You can start<br />
emulator sessions, specify terminal emulator characteristics, and the names of<br />
the keyboard mapping and color mapping files.<br />
You can have multiple terminal emulation sessions running simultaneously.<br />
The <strong>CICS</strong>TERM command detects whether the hardware on which the Client<br />
daemon is running is enabled for double-byte character set (DBCS) display. If<br />
it is, the emulator can display DBCS characters.<br />
For <strong>CICS</strong>TERM emulators, the maximum screen size is 27 rows by 132<br />
columns. This is because the Client daemon supports the ASCII-7 subset of<br />
© Copyright IBM Corp. 1996, 2002 167
The <strong>CICS</strong>TERM command<br />
the 3270 data stream architecture, which supports only 12 bit addressing. For<br />
more information, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Note: Some uses of servers and protocols require a model terminal definition<br />
for the emulator that explicitly specifies that the Client daemon wants<br />
to display DBCS.<br />
Using <strong>CICS</strong>TERM<br />
The following table shows the functions that you can perform with the<br />
<strong>CICS</strong>TERM command, and the parameters associated with each function:<br />
Function Parameters<br />
Start a 3270 terminal emulator -s and -r<br />
Specify the initial transaction -t<br />
Specify the name of the keyboard mapping file -k<br />
Specify the name of the color mapping file -c<br />
Define the 3270 terminal emulator characteristics -n and -m<br />
Specify a terminal emulator that is signon incapable -a<br />
Determine the print file processing -p<br />
Specify a file to which print files are appended -f<br />
<strong>CICS</strong>TERM command once with all the parameters you require.<br />
The following is an example of a <strong>CICS</strong>TERM command:<br />
<strong>CICS</strong>TERM -s=<strong>CICS</strong>OS2 -t=CESN -k=mykeys.ini -c=mycols.ini<br />
-n=cicsv123 -f=clprint.txt -q<br />
In this example:<br />
-s=<strong>CICS</strong>OS2 Specifies that a 3270 terminal emulator is started for the server<br />
<strong>CICS</strong>OS2.<br />
-t=CESN Specifies that the initial transaction is CESN.<br />
-k=mykeys.ini Specifies that the keyboard mapping file is named as<br />
mykeys.ini.<br />
-c=mycols.ini Specifies that the color mapping file is named as mycols.ini.<br />
-n=cicsv123 Specifies that the 3270 terminal emulator characteristics are<br />
defined by the terminal definition cicsv123.<br />
-f=clprint.txt Specifies that the print file will be appended to the file<br />
clprint.txt.<br />
168 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
-q Specifies that the display of messages output by the command<br />
is disabled.<br />
All parameters of <strong>CICS</strong>TERM are optional. That is, you can enter the<br />
<strong>CICS</strong>TERM command without any parameters, and defaults are taken from<br />
the configuration file. This is equivalent to using the <strong>CICS</strong> Terminal shortcut.<br />
Full details of the parameters are given in “<strong>CICS</strong>TERM command reference”.<br />
Stopping a terminal emulator<br />
To stop a terminal emulator, enter, from an empty terminal screen, the string<br />
specified by the Terminal exit configuration setting, and press Enter. The<br />
default string is EXIT<br />
<strong>CICS</strong>TERM and user exits<br />
You can use <strong>CICS</strong>TERM to drive EPI user exits.<br />
The EPI user exits, and how <strong>CICS</strong>TERM can use them, are described in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
<strong>CICS</strong>TERM and RETURN TRANSID IMMEDIATE<br />
When an application running from a <strong>CICS</strong>TERM session issues either of the<br />
commands:<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)<br />
the transaction named in the TRANSID option starts straight away without<br />
any user input. When the INPUTMESSAGE option is specified, the contents of<br />
the data-area are passed to the new transaction, and the screen is not updated<br />
with the data-area contents.<br />
Issuing these EXEC <strong>CICS</strong> commands from <strong>CICS</strong>TERM does not result in the<br />
StartTranExit or ReplyExit user exits being driven. See <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide for more information.<br />
<strong>CICS</strong>TERM command reference<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page x.<br />
<strong>CICS</strong>TERM Command Syntax<br />
►► <strong>CICS</strong>TERM<br />
-s = servername -t=initialtransid<br />
-s -t<br />
-r=servername<br />
-r<br />
The <strong>CICS</strong>TERM command<br />
Chapter 11. Terminal Emulation 169<br />
►
The <strong>CICS</strong>TERM command<br />
►<br />
►<br />
-k=keyfile -c=colorfile -m=modelname -a<br />
-c -m<br />
-n=netname -p=printcmd -q -?<br />
-f=printfile -w<br />
The options are:<br />
-a Specifies that the terminal emulator is not signon capable. By default,<br />
<strong>CICS</strong>TERM creates terminal emulators that are signon capable.<br />
For more information on signon capability, see <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide.<br />
-c=colorfile<br />
Identifies the name of a color mapping file to be used with the<br />
emulator; see “Customizing the screen colors for <strong>CICS</strong>TERM” on<br />
page 99 for more details. If you omit this parameter, the environment<br />
variable <strong>CICS</strong>COL is assumed to identify the color mapping file. If<br />
<strong>CICS</strong>COL is not defined, a filename of cicscol.ini in the<br />
\bin subdirectory is assumed.<br />
If the parameter is specified as -c=, that is, the color mapping filename<br />
is omitted, the emulator runs without any color definitions.<br />
-f=printfile<br />
Specifies the name of a file to which the output of print requests is<br />
appended. If the name of the file contains embedded blanks, it must<br />
be surrounded by double quotes (“). Any double quotes within the<br />
name of the file must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is provided, the Print command<br />
or Print file configuration settings define the command, file, or<br />
default action to take with print requests.<br />
-k=keyfile<br />
Identifies the name of a keyboard mapping file to be used with the<br />
emulator; see “Keyboard mapping for <strong>CICS</strong>TERM” on page 97 for<br />
more details. If this parameter is omitted, the environment variable<br />
<strong>CICS</strong>KEY is assumed to identify the key mapping file. If <strong>CICS</strong>KEY is<br />
not defined, a filename of cicskey.ini in the \bin<br />
subdirectory is assumed.<br />
-m=modelname<br />
Specifies the name of a Model terminal definition, as known at the<br />
server to which the emulator is to connect, to be used to define the<br />
terminal characteristics. If neither this parameter nor -n=netname is<br />
specified, any Model terminal definition value from the configuration<br />
170 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
►<br />
►◄
The <strong>CICS</strong>TERM command<br />
file is used. If no Model terminal definition value has been specified<br />
in the configuration file, the server’s default terminal definition is<br />
assumed.<br />
If the parameter is specified as -m= (that is, the modelname is<br />
omitted), any Model terminal definition value specified in the<br />
configuration file is ignored, and the server’s default terminal<br />
definition is assumed.<br />
This option is case sensitive.<br />
-n=netname<br />
Specifies the name of a particular terminal definition at the server that<br />
this emulator is to be installed as. The precise interpretation of<br />
netname varies between servers. For example, on <strong>CICS</strong> for OS/2 it<br />
references a termid defined in the <strong>CICS</strong> tables, but on TXSeries for<br />
AIX it is a netname.<br />
This option is case sensitive.<br />
-p=printcmd<br />
Specifies an operating system command used to process the<br />
temporary print file generated when print requests are received by the<br />
terminal emulator. If the command contains embedded blanks, then<br />
the command must be enclosed by double quotes (“). Any double<br />
quotes within the command must be entered as backslash double<br />
quote (\“).<br />
If neither of the -f or -p parameters is specified, the Print command or<br />
Print file setting in the configuration file defines the command, file, or<br />
default action to take with print requests.<br />
The temporary print file is post-processed by appending the filename<br />
to the command, and executing the resultant command. Thus print<br />
output may simply be copied to a local printer, copied into a<br />
permanent file, processed further for inclusion into a document, and<br />
so on. If the temporary file is to be processed by a print command,<br />
the command is responsible for deleting the temporary file.<br />
-q Disables the display of all messages output by the command.<br />
-s=servername or -r=servername<br />
Specifies the name of the server that the terminal emulator is to be<br />
connected to. This servername must correspond to an entry in the<br />
configuration file. You can specify -s, or -r, but not both.<br />
If neither parameter is specified, the first server entry in the<br />
configuration file is used.<br />
If the parameter is specified as -s or -r (that is, no servername is<br />
provided) then, if the configuration file identifies more than one<br />
Chapter 11. Terminal Emulation 171
The <strong>CICS</strong>TERM command<br />
potential server to which the Client daemon can connect, the user is<br />
prompted to select from a list of available servers. These prompts are<br />
generated even if the -q parameter is specified.<br />
If there is only one potential server identified in the configuration file,<br />
that server is used and the user is not prompted.<br />
-t=initialtransid<br />
Identifies the initial transaction to be invoked for this terminal. If this<br />
option is omitted, any initial transaction specified in the configuration<br />
file is run. The string may be up to 128 characters long, specifying<br />
both a transaction name, and parameters to be passed to the<br />
transaction. The transaction name is the first four characters or the<br />
characters up to the first blank in the string. The rest of the string is<br />
the parameter data.<br />
If the parameter is specified as -t= (that is, the initialtransid is<br />
omitted), any initial transaction specified in the configuration file is<br />
ignored.<br />
This option is case sensitive.<br />
Note: Be careful that transactions that you specify either here or in<br />
the configuration file do not require terminal input to complete.<br />
-w Prompts the user, before the command completes, to press the Enter<br />
key, to confirm that messages output to the screen (both informational<br />
and error) have been read.<br />
-? Causes the parameter syntax to be listed; any other options specified<br />
are ignored.<br />
Terminal emulator preferences<br />
The terminal emulator allows you to choose a font, by clicking Settings →<br />
Font. IftheSettings → Save on exit menu option is selected, your choices are<br />
stored in <strong>CICS</strong>TERM.INI, for use in future sessions. A copy of <strong>CICS</strong>TERM.INI<br />
is created for each Windows user account as follows:<br />
On Windows NT:<br />
c:\profiles\username\Application Data\IBM\CTG\<strong>CICS</strong>TERM.INI<br />
On Windows 2000 and Windows XP the location is typically as follows:<br />
c:\Documents and Settings\username\Application Data\IBM\CTG\<strong>CICS</strong>TERM.INI<br />
where username represents your Windows logon name.<br />
172 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Terminal emulator preferences<br />
If you share a computer with others, or are a user of multiple computers on a<br />
network, your preferences will be used whenever and wherever you launch<br />
terminal emulator. This functionality is provided by means of Windows<br />
roaming user support.<br />
The <strong>CICS</strong>TERM.INI file is not erased when you uninstall <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. Therefore, when you re-install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the<br />
settings from the old <strong>CICS</strong>TERM.INI files are used by the emulator.<br />
The terminal emulator has a menu bar with File and Settings menus.<br />
The commands on the File menu are:<br />
Print Prints the emulator screen. This has the same effect as pressing the<br />
Print Screen key.<br />
Exit Stops the terminal emulator.<br />
The commands on the Settings menu are:<br />
Font Opens a standard Windows dialog box that allows you to<br />
select any of the fixed-pitch fonts installed on your system.<br />
Select a font, font style, and size, and then select OK. The<br />
terminal window is then resized according to your font<br />
selection.<br />
Autosize Specifies that the size of TrueType fonts is adjusted according<br />
to the size of the terminal window. That is, when you<br />
maximize, minimize, or drag the borders to resize the<br />
window, the font is resized to match the new window size.<br />
This command has no effect if the current font is not a<br />
TrueType font.<br />
Save on Exit Specifies that the current font, terminal window size and<br />
terminal position will be saved when you close the terminal<br />
window. The settings are saved in the <strong>CICS</strong>TERM.INI file, as<br />
explained at the start of this section.<br />
The <strong>CICS</strong>PRNT command<br />
The <strong>CICS</strong>PRNT command controls 3270 printer terminal emulation.<br />
An application running on a server can direct output to a printer in one of<br />
two ways:<br />
1. An application running from a terminal can initiate printing by sending a<br />
map or data with the PRINT indicator set<br />
2. A user can start a 3270 Print Terminal Emulator, at a client, using the<br />
<strong>CICS</strong>PRNT command. A 3270 Print Terminal Emulator must be started for<br />
Chapter 11. Terminal Emulation 173
The <strong>CICS</strong>PRNT command<br />
a netname or model terminal definition predefined in the server’s terminal<br />
tables. Output is directed to such a device by starting a transaction against<br />
the printer device.<br />
For <strong>CICS</strong>PRNT emulators, the maximum screen size is 27 rows by 132<br />
columns. This is because the Client daemon supports the ASCII-7 subset of<br />
the 3270 data stream architecture, which supports only 12 bit addressing. For<br />
more information, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Note: At client workstations you can use the PrintScreen key, as defined by<br />
the keyboard mapping file. However, any lines that contain only null<br />
characters are not printed. For a ‘blank’ line to be printed, it must<br />
contain at least one space character.<br />
Using <strong>CICS</strong>PRNT<br />
The following table shows the functions that you can perform with the<br />
<strong>CICS</strong>PRNT command, and the parameters associated with each function:<br />
Function Parameters<br />
Start a 3270 print terminal emulator -s and -r<br />
Specify the initial transaction -t<br />
Define the 3270 printer terminal emulator characteristics -n and -m<br />
Determine the print file processing -p<br />
Specify a file to which print files are appended -f<br />
Wait for confirmation before completing -q<br />
Inhibit all ouput messages -q<br />
Issue one print job per transaction -j<br />
You issue the <strong>CICS</strong>PRNT command once with all the parameters you require.<br />
The following is an example of a <strong>CICS</strong>PRNT command:<br />
<strong>CICS</strong>PRNT -s=<strong>CICS</strong>OS2 -n=P123 -t=XPRT -f=clprint.txt -q<br />
In this example:<br />
-s=<strong>CICS</strong>OS2 Specifies that a 3270 print terminal emulator is started for the<br />
server <strong>CICS</strong>OS2.<br />
-n=P123 Specifies that the 3270 print terminal emulator characteristics<br />
are defined by the terminal definition P123 (in the terminal<br />
control table for <strong>CICS</strong> for OS/2 in this case.)<br />
-t=XPRT Specifies that the initial transaction is XPRT.<br />
174 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
-f=clprint.txt Specifies that the print file to which print requests are<br />
appended is clprint.txt.<br />
-q Specifies that the display of messages output by the command<br />
is disabled.<br />
All parameters of <strong>CICS</strong>PRNT are optional, except that you must specify either<br />
-n=netname or -m=modelname. That is, you can enter the <strong>CICS</strong>PRNT command<br />
with just the -n or the -m parameter, or both, and defaults for other<br />
parameters are taken from the configuration file. Full details of the parameters<br />
are given in “<strong>CICS</strong>PRNT command reference”.<br />
If the system upon which the Client daemon is running supports DBCS, it is<br />
assumed that the printer attached to the processor also supports DBCS.<br />
Conversely, if the system does not support DBCS, the Client daemon will not<br />
send DBCS data to the printer.<br />
The <strong>CICS</strong>PRNT process runs as a minimized window, and the window can be<br />
enlarged to view the current status of the printer. You can use an action<br />
available from a pulldown menu to terminate the print function.<br />
<strong>CICS</strong>PRNT and user exits<br />
You can use <strong>CICS</strong>PRNT to drive EPI user exits.<br />
The EPI user exits, and how <strong>CICS</strong>PRNT can use them, are described in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
<strong>CICS</strong>PRNT and RETURN TRANSID IMMEDIATE<br />
Unlike <strong>CICS</strong>TERM, <strong>CICS</strong>PRNT does not support the commands:<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)<br />
For more information, refer to “<strong>CICS</strong>TERM and RETURN TRANSID<br />
IMMEDIATE” on page 169.<br />
<strong>CICS</strong>PRNT command reference<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page x.<br />
<strong>CICS</strong>PRNT Command Syntax<br />
►► <strong>CICS</strong>PRNT<br />
-s=servername -t=initialtransid -j<br />
-s -t<br />
-r=servername<br />
-r<br />
The <strong>CICS</strong>PRNT command<br />
Chapter 11. Terminal Emulation 175<br />
►
The <strong>CICS</strong>PRNT command<br />
► -m=modelname<br />
-n=netname -p=printcmd -q -?<br />
-f=printfile -w<br />
The options are:<br />
-f=printfile<br />
Specifies the name of a file to which the output of print requests is<br />
appended. If the name of the file contains embedded blanks, it must<br />
be surrounded by double quotes (“). Any double quotes within the<br />
name of the file must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is provided, the Print command<br />
or Print file setting in the configuration file defines the command, file,<br />
or default action to take with print requests.<br />
-j Specifies that <strong>CICS</strong>PRNT should concatenate all EXEC <strong>CICS</strong> SEND<br />
PRINT commands issued on a server transaction into a single print<br />
job. This print job is issued when the transaction terminates.<br />
Otherwise <strong>CICS</strong>PRNT will generate a separate print job for every<br />
EXEC <strong>CICS</strong> SEND PRINT command issued for a server transaction.<br />
-m=modelname<br />
Specifies the name of a model terminal definition, as known at the<br />
server to which the 3270 Print Terminal emulator is to connect, to be<br />
used to define the terminal characteristics. If this parameter is not<br />
specified, any Model terminal definition value from the configuration<br />
file is used. If no Model terminal definition value has been specified<br />
in the configuration file, the server’s default terminal definition is<br />
assumed.<br />
You must specify either the -m or the -n option, or both.<br />
This option is case-sensitive<br />
-n=netname<br />
Specifies the name of a particular terminal definition at the server that<br />
this 3270 Print Terminal emulator is to be installed as. The precise<br />
interpretation of netname varies between servers. For example, on<br />
TXSeries for AIX it is a netname.<br />
You must specify either the -m or the -n option, or both.<br />
This option is case-sensitive.<br />
-p=printcmd<br />
Specifies a command used to process the temporary print file<br />
generated when print requests are received by the terminal emulator.<br />
If the command contains embedded blanks, then the command must<br />
176 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
-j<br />
►◄
e surrounded by double quotes (“). Any double quotes within the<br />
command must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is specified, the Print command or<br />
Print file setting in the configuration file defines the command, file, or<br />
default action to take with print requests.<br />
The temporary print file is post-processed by appending the filename<br />
to the command, and executing the resultant command. Thus print<br />
output may simply be copied to a local printer, copied into a<br />
permanent file, processed further for inclusion into a document, and<br />
so on. If the temporary file is to be processed by a print command,<br />
the command is responsible for deleting the temporary file.<br />
-q Disables the display of all messages output by the command.<br />
-s=servername or -r=servername<br />
Specifies the name of the server that the printer is to be connected to.<br />
This servername must correspond to an entry in the configuration file.<br />
You can specify -s, or -r, but not both.<br />
If neither parameter is specified, the first server entry in the<br />
configuration file is used.<br />
If the parameter is specified as -s or -r (that is, no servername is<br />
provided) then, if the configuration file identifies more than one<br />
potential server to which the Client daemon can connect, the user is<br />
prompted to select from a list of available servers. These prompts are<br />
generated even if the -q parameter is specified.<br />
If there is only one potential server identified in the configuration file<br />
that server is used and the user is not prompted.<br />
-t=initialtransid<br />
Identifies the initial transaction to be invoked for this printer. If this<br />
option is omitted, any initial transaction specified in the configuration<br />
file is run. The string may be up to 128 characters long, specifying<br />
both a transaction name, and parameters to be passed to the<br />
transaction. The transaction name is the first four characters or the<br />
characters up to the first blank in the string. The rest of the string is<br />
the parameter data.<br />
If the parameter is specified as -t= (that is, the initialtransid is<br />
omitted), any initial transaction specified in the configuration file is<br />
ignored.<br />
Note: Be careful that transactions that you specify either here or in<br />
the configuration file do not require terminal input to complete.<br />
This option is case-sensitive.<br />
The <strong>CICS</strong>PRNT command<br />
Chapter 11. Terminal Emulation 177
The <strong>CICS</strong>PRNT command<br />
-w Prompts the user, before the command completes, to press the Enter<br />
key, to confirm that messages output to the screen (both informational<br />
and error) have been read.<br />
-? Causes the parameter syntax to be listed; any other options specified<br />
are ignored.<br />
178 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
Chapter 12. Workload Manager<br />
This chapter discusses how to use the Workload Manager to improve<br />
performance. It consists of the following:<br />
“Workload Manager overview” Read this to learn what the Workload<br />
Manager can do, and for an explanation<br />
of key terms.<br />
“What the Workload Manager needs to<br />
know” on page 181<br />
Read this to learn what information you<br />
must supply to the Workload Manager.<br />
“Load balancing algorithms” on page 183 Read this to learn about the two types of<br />
load balancing that are available.<br />
“Workload Manager failure recovery” on<br />
page 184<br />
“Workload Manager implementation” on<br />
page 184<br />
“Workload Manager installation” on<br />
page 185<br />
“Tracing the Workload Manager” on<br />
page 186<br />
“Workload Manager programming<br />
requirements” on page 186<br />
Read this to learn what the Workload<br />
Manager does if a <strong>CICS</strong> region becomes<br />
unavailable.<br />
Read this if you are writing user exit<br />
programs, and want to know how the<br />
Workload Manager will interact with your<br />
code.<br />
Read this for information on installation.<br />
Read this if you want to trace the<br />
Workload Manager.<br />
Read this for information on standards<br />
applicable to programs that use the<br />
Workload Manager.<br />
For details of how to configure the Workload Manager see “Configuring the<br />
Workload Manager” on page 84.<br />
Workload Manager overview<br />
The Workload Manager is designed to handle various problems when the<br />
Client daemon is used to connect with one or more <strong>CICS</strong> servers (<strong>CICS</strong><br />
regions):<br />
v How to get round the restriction on the number of clients that a single<br />
<strong>CICS</strong> server can accommodate on a particular port.<br />
v How to distribute work across available, equivalent <strong>CICS</strong> regions.<br />
v How to favor one region over another (biasing).<br />
v How to handle requests that fail to reach a target <strong>CICS</strong> region.<br />
© Copyright IBM Corp. 1996, 2002 179
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Workload Manager<br />
The Workload Manager resolves these problems and others by dynamically<br />
selecting target regions and ports based upon criteria that you configure.<br />
Key concepts<br />
It is essential to understand the following concepts:<br />
Regions<br />
A region is a physical instance of a <strong>CICS</strong> server, for example, TXSeries<br />
for Windows NT or AIX. This includes the programs and resource<br />
definitions for that region.<br />
Programs<br />
<strong>CICS</strong> programs are executable units that can be started within a <strong>CICS</strong><br />
region. A particular <strong>CICS</strong> program might be available on multiple<br />
<strong>CICS</strong> regions. The Workload Manager has a list of <strong>CICS</strong> regions on<br />
which the program is defined (program affinity).<br />
TCP/IP address<br />
An address that uniquely identifies a machine on a particular<br />
network. Each machine may have many threads of execution running<br />
simultaneously; a TCP/IP port uniquely identifies a particular thread<br />
of execution.<br />
TCP/IP port<br />
A numeric TCP/IP end-point in the range of 0-65535. This port<br />
number is defined in the configuration file (CTG.INI) file for each<br />
instance of a server definition.<br />
The number of client requests that can be handled on a particular port<br />
varies with the <strong>CICS</strong> server platform. For example, a TXSeries for AIX<br />
or TXSeries for Windows NT may handle client requests via a number<br />
of ports, but only about 250 client requests can be handled per port.<br />
You might need to define multiple server instances.<br />
Server instance<br />
An entry in CTG.INI that corresponds to an instance of a <strong>CICS</strong> server.<br />
For a particular <strong>CICS</strong> region there may be multiple instances of <strong>CICS</strong><br />
server definitions, each with different port numbers. The names<br />
provided by the Server name configuration setting (Server=servername<br />
in the configuration file) are used in the actual ECI requests. In the<br />
Workload Manager section of the configuration tool, the server<br />
instances are gathered together in Server Groups.<br />
In <strong>CICS</strong> Universal Client <strong>Version</strong> 3.0 this was known as a Listener.<br />
Server Group<br />
The configuration tool uses Server Groups to group together server<br />
instances. A Server Group can correspond to one <strong>CICS</strong> region on a<br />
server, or to several physical servers.<br />
180 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The first time an instance of the Client daemon makes a request, it<br />
selects a server instance from the group at random. For the duration<br />
of the life of that Client daemon instance, all subsequent requests to<br />
that Server Group are sent to the same server instance.<br />
An ECI program can be associated with a Server Group. The<br />
Workload Manager assumes that the program exists on all server<br />
instances in the Server Group.<br />
Workload management<br />
The ability of the Workload Manager to select a suitable <strong>CICS</strong> server<br />
as a target for a client request. The load balancing algorithms try to<br />
spread the workload over various server instances on a particular<br />
region (via random selection) and they allow the user to effectively<br />
specify a bias for the selection of a particular region. Known inactive<br />
regions are not considered for selection.<br />
Note: Apart from TCP/IP, other supported protocols can be used to<br />
communicate with <strong>CICS</strong> servers. For example, SNA can be used, and in<br />
this case the server instances can be identified by Logical Units (LU),<br />
rather than by TCP/IP ports.<br />
What the Workload Manager needs to know<br />
This section discusses how <strong>CICS</strong> server instances relate to the <strong>CICS</strong> regions,<br />
and the information required by the Workload Manager to perform its load<br />
management.<br />
The following table illustrates knowledge that the Workload Manager must<br />
have. Specifically, the Client daemon must be able to correlate server instances<br />
against the regions to which they belong.<br />
<strong>CICS</strong> Region Server instance<br />
REGION1 <strong>CICS</strong>1<br />
<strong>CICS</strong>2<br />
<strong>CICS</strong>3<br />
REGION2 <strong>CICS</strong>4<br />
<strong>CICS</strong>5<br />
REGION3 <strong>CICS</strong>6<br />
Workload Manager<br />
The Client daemon can connect to a specific region through only one server<br />
instance. So, in the example, a Client daemon can connect to a region using<br />
one of the following groups of servers:<br />
v <strong>CICS</strong>1, <strong>CICS</strong>2, <strong>CICS</strong>3<br />
v <strong>CICS</strong>4, <strong>CICS</strong>5<br />
Chapter 12. Workload Manager 181
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Workload Manager<br />
v <strong>CICS</strong>6<br />
For example, connections from a specific Client daemon to <strong>CICS</strong>2, <strong>CICS</strong>4, and<br />
<strong>CICS</strong>6 are valid. Connections to <strong>CICS</strong>1, <strong>CICS</strong>3, and <strong>CICS</strong>5 are also valid, but<br />
not desirable because <strong>CICS</strong>1 and <strong>CICS</strong>3 belong to the same region.<br />
As mentioned previously, if a TCP/IP <strong>CICS</strong> region needs to service a large<br />
number of clients, it might need to define multiple server instances, each with<br />
its own port number. From a client perspective, each server definition<br />
represents a uniquely targetable <strong>CICS</strong> region instance.<br />
For example, if a port can handle 200 concurrent clients and there are 8000<br />
clients, 40 ports are needed to support all clients. If the clients can distribute<br />
their connections across these ports, this would optimally result in 200 clients<br />
per port. Using a random distribution model, it is statistically possible for the<br />
distribution to be 210 clients on one port and only 190 on another (assuming<br />
200 on the remainder). This would result in a set of client failures. The<br />
solution is to increase the number of ports available. For example, increasing<br />
the number of ports to 50 would result in a randomly even distribution of 160<br />
clients/ports. The random selection algorithm would now have to deviate by<br />
25% to exceed 200 clients on one port.<br />
As a port can handle only a relatively small number of concurrent client<br />
connections, balancing the distribution of server instances across all the clients<br />
is vital. In the example, if all clients selected <strong>CICS</strong>2 as the connection to<br />
REGION1, it is likely that the port for <strong>CICS</strong>2 would quickly be overloaded,<br />
resulting in failures. If all clients need to access REGION2, 50% should use<br />
<strong>CICS</strong>4, and 50% should use <strong>CICS</strong>5.<br />
Not all <strong>CICS</strong> programs need be available on all possible <strong>CICS</strong> regions. The<br />
Workload Manager knows the name of the program that the client request is<br />
for, and can select, from a subset of all regions, those regions on which a<br />
particular program is defined. The Workload Manager also has knowledge of<br />
a set of regions to which undefined programs may be routed.<br />
For example:<br />
Program Region Average Elapsed Time<br />
PROG1 REGION1<br />
REGION2<br />
REGION3<br />
PROG2 REGION1<br />
REGION3<br />
PROG3 REGION2 5<br />
182 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
10<br />
20<br />
15<br />
20<br />
10
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Workload Manager<br />
This data can be used both to monitor application execution, and to provide<br />
input to workload management algorithms.<br />
To sum up, the Workload Manager must know:<br />
v Which regions the Client daemon can connect to<br />
v The server instances that belong to each region<br />
v The programs that can run in each region<br />
You supply this information using the configuration tool which produces the<br />
appropriate entries in the configuration file; see “Configuring the Workload<br />
Manager” on page 84.<br />
Load balancing algorithms<br />
You can select a round-robin algorithm or a biasing algorithm for load<br />
balancing. You select an algorithm using the configuration tool; see<br />
“Configuring the Workload Manager” on page 84.<br />
The round-robin algorithm<br />
The round-robin algorithm assumes that all <strong>CICS</strong> regions are equally valid for<br />
selection. In the round-robin algorithm, when the Client daemon is initially<br />
started, it reads from the configuration file a list of all possible <strong>CICS</strong> regions<br />
to which any ECI request can be sent.<br />
The Workload Manager also records the last region selected. When a new ECI<br />
or EPI request is made, the next region in the list is selected as the target, and<br />
the Workload Manager advances the next region indicator. When it reaches<br />
the last region it loops around to the first one.<br />
The biasing algorithm<br />
The biasing algorithm provides a way of balancing workload by specifying<br />
that workload distribution should favor particular regions. For example, if<br />
there are two regions with a bias of 75 and 25, program requests are sent in a<br />
ratio of 3:1 to the first region.<br />
If a region fails, the internal biasing calculation changes. If two regions are<br />
available, one with a bias of 100 and the other with a bias of 0, all requests<br />
are sent to the first region. If the first region becomes unavailable, all requests<br />
are directed to the second region. A bias value of 0 is a special case, meaning<br />
use only if no other region is available.<br />
Another way of looking at biasing is:<br />
probability a region will be selected = bias for region<br />
----------------total<br />
bias for all regions<br />
Chapter 12. Workload Manager 183
|<br />
|<br />
|<br />
|<br />
Workload Manager<br />
The biasing algorithm works only for ECI calls. If you try to run an EPI<br />
application whilst the biasing algorithm is selected, the round-robin algorithm<br />
is used instead.<br />
Workload Manager failure recovery<br />
If a request to route an ECI call to a particular region fails, indicating that the<br />
region is no longer available, the region is removed from the list of available<br />
regions.<br />
If a request fails to reach the target <strong>CICS</strong> region the Workload Manager tries<br />
again, this time sending it to a different region that it knows is available. The<br />
region that failed is removed from the list of active regions. It is added back<br />
after a period of time which you specify in the Region timeout (s) field in the<br />
configuration tool. If the region fails again, the process is repeated.<br />
Workload Manager implementation<br />
The Workload Manager is invoked during ECI and EPI calls from the Client<br />
daemon, and implements ECI and EPI user exit functions. These ECI and EPI<br />
exit functions are accessed during processing at a number of points during the<br />
execution of a request. They are described in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide.<br />
The exit is implemented as a re-entrant multi-threaded Dynamic Load Library<br />
(DLL). This exit (code) is dynamically loaded by each client application that<br />
executes. The DLL executes in the process address space of the ECI-calling<br />
application rather than the Client daemon.<br />
ECI implementation<br />
The Workload Manager is implemented as a Windows DLL called<br />
cclmecix.dll. This DLL contains implementations for the following functions:<br />
<strong>CICS</strong>_EciInitializeExit<br />
Initialize the exit. Called once per process at the first ECI call. This<br />
function builds the list of available regions and other attributes.<br />
<strong>CICS</strong>_EciExternalCallExit1<br />
Called at the start of an ECI call. This function is passed a reference to<br />
the ECI parameter block and may change the value of the<br />
eci_system_name field to select an alternate <strong>CICS</strong> server. The value of<br />
this field may be a Server name. This function selects the correct<br />
target <strong>CICS</strong> server for each ECI client request. This function involves<br />
workload management algorithms.<br />
<strong>CICS</strong>_EciSystemIdExit<br />
If on return from the <strong>CICS</strong>_EciExternalCallExit1, the ECI request fails<br />
to reach the target <strong>CICS</strong> server, either because of communication<br />
184 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Workload Manager<br />
failure or a <strong>CICS</strong> server failure, <strong>CICS</strong>_EciSystemIdExit is called to<br />
select an alternate <strong>CICS</strong> server target. The function flags that a <strong>CICS</strong><br />
server is no longer available and should be removed from the list of<br />
selectable <strong>CICS</strong> servers. The workload management algorithm is then<br />
re-executed to select the next <strong>CICS</strong> server to be targeted by the Client<br />
daemon.<br />
EPI implementation<br />
The Workload Manager is implemented as a Windows DLL called<br />
cclmepix.dll. This DLL contains implementations for the following functions:<br />
<strong>CICS</strong>_EpiInitializeExit<br />
Initialize the exit. Called once per process at the first EPI call. This<br />
function builds the list of available regions and other attributes.<br />
<strong>CICS</strong>_AddTerminalExit<br />
Selects a <strong>CICS</strong> server.<br />
<strong>CICS</strong>_EpiSystemIdExit<br />
<strong>CICS</strong>_EpiSystemIdExit is called to select an alternate <strong>CICS</strong> server<br />
target. The function flags that a <strong>CICS</strong> server is no longer available and<br />
should be removed from the list of selectable <strong>CICS</strong> servers. The<br />
workload management algorithm is then re-executed to select the next<br />
<strong>CICS</strong> server to be targeted by the Client daemont.<br />
Instead of using the supplied Workload Manager you can write your own<br />
user exits that implement the ECI and EPI functions, and these exits can be<br />
driven by the <strong>CICS</strong>TERM and <strong>CICS</strong>PRNT commands. Information on<br />
producing such exits is given in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide book.<br />
When the Workload Manager is activated for a <strong>CICS</strong>TERM/<strong>CICS</strong>PRNT<br />
command, it determines which server the Client daemon should connect to.<br />
The Workload Manager server selection overrides any server specified with<br />
the <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT command.<br />
Workload Manager installation<br />
When you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the ECI Exit DLL (cclmecix.dll)<br />
and the EPI Exit DLL (cclmepix.dll) are installed into the \bin<br />
subdirectory.<br />
Once installed, the exit is used by succeeding ECI client calls without<br />
modification to any currently existing ECI program.<br />
The supplied load management DLLs can coexist with any user-written DLLs.<br />
With the exception of <strong>CICS</strong>_EciSetProgramAliasExit, user-written DLLs are<br />
called after the load management DLLs.<br />
Chapter 12. Workload Manager 185
Workload Manager<br />
Tracing the Workload Manager<br />
You can enable tracing for the Workload Manager in two ways:<br />
1. By selecting Workload Manager in the Trace section of the configuration<br />
tool.<br />
2. By specifying LMG on the <strong>CICS</strong>CLI -m command.<br />
This command overrides the configuration setting.<br />
By default, tracing of the Workload Manager is not enabled.<br />
Workload Manager programming requirements<br />
To invoke the Workload Manager correctly, the eci_version field in the<br />
ECI_PARMS control block passed to the <strong>CICS</strong>_ExternalCall function must be<br />
ECI_VERSION_1A or later.<br />
The Workload Manager ensures that all calls in an extended Logical Unit of<br />
Work (LUW) are routed to the same <strong>CICS</strong> server.<br />
186 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 13. The Terminal Servlet program<br />
This chapter describes how to use the Terminal Servlet to access <strong>CICS</strong> 3270<br />
applications using a Web browser.<br />
v “What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet?” tells you what a<br />
servlet is, and in particular what the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal<br />
Servlet does.<br />
v “Installing and configuring the Terminal Servlet” on page 189 discusses how<br />
you install and configure the Terminal Servlet.<br />
v “Using the Terminal Servlet” on page 195 describes what you can do with<br />
the Terminal Servlet, and how to invoke it from your Web pages.<br />
v “Properties and parameters reference” on page 200 provides a complete<br />
reference to the servlet properties you can specify for the Terminal Servlet.<br />
v “Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong>” on page 245 describes what<br />
you need to do to migrate from Windows running the <strong>CICS</strong> Internet<br />
<strong>Gateway</strong> to using the Terminal Servlet.<br />
v “<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web Interface” on page 206 describes<br />
how HTML templates generated for use by the <strong>CICS</strong> Web Interface can be<br />
used by the Terminal Servlet.<br />
It is advisable to read through all of this chapter before configuring and using<br />
the Terminal Servlet.<br />
What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet?<br />
Servlets are Java programs that run on a Web server machine, inside a<br />
Java-enabled Web server or servlet engine, for example, WebSphere<br />
Application Server (see Figure 22 on page 189). Java servlets have become<br />
popular as alternatives to Common <strong>Gateway</strong> Interface (CGI) programs—the<br />
Terminal Servlet is a replacement for the <strong>CICS</strong> Internet <strong>Gateway</strong> shipped with<br />
IBM <strong>CICS</strong> Clients <strong>Version</strong> 2, which was a CGI program.<br />
A servlet can be loaded automatically when the Web server is started, or<br />
loaded when the first client request for the services of the servlet is made.<br />
Unlike CGI programs, servlets are persistent, that is, once they are loaded<br />
they stay running, waiting for additional client requests.<br />
Being Java programs, servlets are portable across operating systems. And,<br />
because the servlet interface is a standard, they can be used with different<br />
Web servers on different platforms.<br />
© Copyright IBM Corp. 1996, 2002 187
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
The Terminal Servlet allows you to access <strong>CICS</strong> 3270 applications using a Web<br />
browser. You create Web pages that invoke the Terminal Servlet to start a<br />
<strong>CICS</strong> transaction, display screen information sent from a <strong>CICS</strong> server, and<br />
send screens back to <strong>CICS</strong>.<br />
The Terminal Servlet can:<br />
v Behave like a simple terminal emulator.<br />
The <strong>CICS</strong> screen is displayed in the browser as part of an HTML form.<br />
When you press one of the buttons in the form, the form is submitted and<br />
data is sent to <strong>CICS</strong>.<br />
v Substitute data from a <strong>CICS</strong> screen into HTML template files.<br />
An HTML template file is used to determine how <strong>CICS</strong> data appears in the<br />
browser. The Terminal Servlet replaces variables in the HTML template file<br />
with <strong>CICS</strong> screen information, and the resulting output is sent to the<br />
browser. For more information, see “Using variable substitution” on<br />
page 198.<br />
v Using server-side includes, incorporate variable information in a Web<br />
page, or drive a terminal emulator without user interaction.<br />
Server-side includes are statements in an HTML file (.shtml) that are<br />
processed by the Web server before the Web page is returned to the<br />
browser. For example, you can use a server-side include to invoke the<br />
Terminal Servlet to display the value of fields in a <strong>CICS</strong> screen. For more<br />
information, see “Invoking the servlet with a server-side include” on<br />
page 197.<br />
v Map <strong>CICS</strong> screens to Web pages.<br />
Using the page mapping properties of the Terminal Servlet, you can<br />
associate particular Web pages with particular <strong>CICS</strong> screens. For example,<br />
you can specify the Web page to be displayed when the terminal is idle,<br />
and no transaction is running. For more information, see “Page mapping<br />
properties” on page 203.<br />
Like EPI programming, the Terminal Servlet allows you to create new front<br />
ends to existing <strong>CICS</strong> transactions. However, it also allows you to exploit the<br />
power, flexibility, and platform-independence of Java programming.<br />
Note: The Terminal Servlet does not support DBCS fields in 3270 data<br />
streams.<br />
188 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Workstation<br />
Java-enabled browser<br />
HTTP<br />
<strong>Gateway</strong> server<br />
Web server / servlet engine<br />
Servlet<br />
<strong>Gateway</strong> daemon<br />
Client daemon<br />
TCP62<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for OS/390<br />
<strong>CICS</strong> server<br />
Installing and configuring the Terminal Servlet<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Figure 22. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> using Terminal Servlet invoked by URL<br />
This section discusses how to install the Terminal Servlet on the Web server<br />
machine, and set the initialization parameters of the Terminal Servlet.<br />
The procedure for installing and configuring the Terminal Servlet will vary<br />
according to the Web server. However, you will need to do at least the<br />
following:<br />
v Configure the Web server’s CLASSPATH and PATH settings<br />
v Add the Terminal Servlet to the Web server’s configuration<br />
v Configure the servlet initialization parameters<br />
v Consider other configuration options, such as security, logging, and<br />
whether the Web server can process server-side includes.<br />
Chapter 13. The Terminal Servlet program 189
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Examples of installing and configuring the Terminal Servlet on a particular<br />
Web server are available in the sample configuration documents. See “Sample<br />
configuration documents” on page 266. The principles described should also<br />
apply to other Web servers.<br />
Refer to the documentation for your Web server for information on installing<br />
and configuring servlets.<br />
Configuring the Web server’s CLASSPATH and PATH settings<br />
You must ensure that the two <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> jar files,<br />
ctgclient.jar and ctgserver.jar, are in the Web server’s classpath.<br />
If you do not make the correct classpath settings, you may get a message to<br />
the effect that you cannot update the servlet, and that the class<br />
com.ibm.ctg.servlet.TerminalServlet cannot be loaded.<br />
You must also ensure that the \bin subdirectory is in the Web<br />
server’s path.<br />
Adding the Terminal Servlet to the Web server’s configuration<br />
To add the Terminal Servlet to the Web server’s configuration, you must<br />
provide a Servlet Name and associate this servlet instance with the Terminal<br />
Servlet class, which is com.ibm.ctg.servlet.TerminalServlet.<br />
You can configure more than one instance of the Terminal Servlet. Each of<br />
them would have a different Servlet Name, but would refer to the same<br />
Servlet Class. In fact, you must create a different Terminal Servlet instance for<br />
each <strong>CICS</strong> server that you want to connect to. Each instance of the Terminal<br />
Servlet may use different initialization parameters, and this can be useful<br />
when configuring for different <strong>CICS</strong> servers.<br />
Configuring the servlet initialization parameters<br />
After adding the Terminal Servlet to the Web server’s configuration, you must<br />
set up the initialization parameters for the Terminal Servlet.<br />
The following sections give some insight into how the Terminal Servlet works,<br />
which will help you in setting appropriate servlet initialization parameters.<br />
The Terminal Servlet now supports signon capable terminals. For information<br />
on the full set of initialization parameters available, including those to provide<br />
this type of terminal, refer to “Properties and parameters reference” on<br />
page 200.<br />
190 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
As a starting point consider setting some of the following parameters:<br />
Table 9. Servlet initialization parameters<br />
Parameter name Notes<br />
servlet@propertyFile The servlet can load configuration information from a<br />
properties file. A sample servlet.properties file is<br />
supplied, in the<br />
\samples\terminalservlet subdirectory.<br />
To use a properties file, set this parameter to the full<br />
path name of the properties file you want the Terminal<br />
Servlet to load. If you specify a properties file then you<br />
may want to use this file for all other servlet<br />
parameters. In this case, servlet@propertyFile is the<br />
only parameter that you need to set.<br />
servlet@extendedLogging The servlet writes logging information, for example,<br />
error messages, to the standard servlet log. Set this<br />
property to true to write more information to the log<br />
file. You may find this helpful when first configuring<br />
the servlet, but it should be turned off once the servlet<br />
is set up correctly.<br />
pool@maxTerminals Set this property to the maximum allowable number of<br />
connections to the <strong>CICS</strong> server. You should ensure that<br />
the <strong>CICS</strong> server has sufficient free tasks to handle this<br />
number of concurrent connections. You should also<br />
ensure that the <strong>CICS</strong> Client Maximum requests<br />
configuration setting is at least as large as this property.<br />
pool@serverName Each instance of the Terminal Servlet can connect to<br />
only one <strong>CICS</strong> server. This gives you more control of<br />
resource usage and security. Set this property to the<br />
name of the required <strong>CICS</strong> server, as defined by the<br />
appropriate Server name setting in your configuration.<br />
If this property is not set, the default <strong>CICS</strong> server is<br />
used.<br />
pool@gatewayUrl Set this property if you want the servlet to connect over<br />
the network to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Apart from the name of the property file, all the servlet properties can either<br />
be loaded from a properties file or set as servlet initialization parameters.<br />
Initialization parameters override properties file entries.<br />
The servlet property names are not case sensitive.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Terminal pooling<br />
The Terminal Servlet uses a pool of terminals, and the servlet configuration<br />
properties allow you to control the behavior of the terminal pool. The default<br />
Chapter 13. The Terminal Servlet program 191
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
behavior is that a new terminal is connected to <strong>CICS</strong> whenever a user requires<br />
one, up to the pool@maxTerminals limit. When the user has finished with the<br />
terminal, it is disconnected.<br />
If the pool@minTerminals property is set, this number of terminals is<br />
connected to <strong>CICS</strong> when the servlet starts, and up to that number may be<br />
connected to <strong>CICS</strong> but not in use at any time. This allows new users to be<br />
allocated a terminal immediately, without waiting for a connection.<br />
Setting the pool@reusingTerminals property allows terminals to be reused,<br />
that is, when a user session ends, the terminal may be allocated to a new user<br />
instead of being disconnected. This property has no effect if<br />
pool@minTerminals is 0. Any transaction running on the terminal is ended<br />
and the screen is cleared, before it is reused. However, if a user has signed on<br />
to <strong>CICS</strong> (using CESN for example), the terminal will still be signed on when it<br />
is reused. For this reason, do not set this property unless you are sure it is<br />
suitable for your environment.<br />
The pool@idleTimeout property allows terminals that have been allocated to<br />
a user to be released if they have not been used for the specified timeout<br />
period. This property defaults to 0, that is, no timeout.<br />
Using a display request with the values: pool@connectedTerminals,<br />
pool@freeTerminals, and pool@terminalsInUse, you can query the number of<br />
terminals that are connected, free, or in use for a particular instance of the<br />
Terminal Servlet.<br />
Page mappings<br />
Page mappings tell the Terminal Servlet what Web page to display for a<br />
particular <strong>CICS</strong> screen or terminal state.<br />
The servlet’s choice of which page to display is based on the current page<br />
mapping settings, the current screen handler class, and the state of the<br />
terminal.<br />
The Terminal Servlet first looks at the page mapping properties to see if there<br />
is a specific page set for the current state of the session, as follows:<br />
Session State Page Mapping Property<br />
an error has occurred page@error<br />
the terminal is idle - no transaction is<br />
running<br />
page@idle<br />
the terminal has been disconnected page@disconnected<br />
there is a screen handler for the current Page mapping for the class name of the<br />
screen<br />
screen handler<br />
192 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
If no specific page is found, the page identified by the page mapping property<br />
page@default is used. If this is not set, an error message is displayed instead.<br />
The value of a page mapping property can be set in two ways:<br />
1. A URL, for example:<br />
http://webserver/index.html<br />
2. A template file to be loaded for variable substitution. This must start with<br />
″file://″, for example:<br />
file://d:/pages/template.html<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
If you set the servlet@templateDir property, template filenames can be<br />
specified relative to the template directory.<br />
Example settings for page mapping properties are as follows:<br />
page@error=http://server/errors.html<br />
page@idle=http://server/idle.html<br />
page@disconnected=/ctglab/html/servlet/epissam.html<br />
page@default=file://epissam1.html<br />
To set a page mapping for a particular screen, you must create a Screen<br />
Handler bean that can recognize that screen. Then, you must set the<br />
pool@handlerPath property to ensure that the Screen Handler bean is loaded<br />
by the Terminal Servlet. If, for example, you have created a Screen Handler<br />
bean called MAP1ScreenHandler in a package called testmaps, then the page<br />
mapping property for that screen handler is:<br />
page@testmaps.MAP1ScreenHandler.<br />
The name of the class is case sensitive. As for the standard page mappings,<br />
you set the property to the name of the Web page to display, for example:<br />
page@testmaps.MAP1ScreenHandler=http://server/test.html<br />
A page mapping can also be set in a request parameter to the Terminal<br />
Servlet, in which case it applies only to that request and overrides any page<br />
mappings associated with the instance of the servlet being used. You can<br />
query the current setting of a page mapping with an appropriate request (see<br />
“Displayable properties” on page 205).<br />
Screen Handler beans and terminal disconnection<br />
For a terminal to be disconnected successfully, it must exit from running<br />
transactions. The Terminal Servlet’s default behavior for achieving this is to<br />
send the AID (Attention identifier) PF3 key to <strong>CICS</strong>. However, if you will be<br />
running transactions for which this will not work, you should create one or<br />
more Screen Handler beans that know how to exit the relevant screens.<br />
Chapter 13. The Terminal Servlet program 193
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
You can generate Screen Handler beans automatically from BMS maps using<br />
the BMS Map Conversion Utility (BMSMapConvert) supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, or you can write your own classes. For information<br />
about Screen handlers and how to create them, see the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide book.<br />
To load screen handlers into the servlet, set the pool@handlerPath property.<br />
The handler path can include .jar files, .zip files and directories, although<br />
sub-directories will not be searched. For example, in the servlet properties file<br />
you might add:<br />
pool@handlerPath=d:\handlers\handlers.jar;d:\handlers\test<br />
to load screen handler classes from a .jar file and from a directory. See the<br />
sample properties file for more information on setting this property.<br />
You can also specify a default screen handler (using the property<br />
pool@defaultHandler), which is used to exit from a screen if no other screen<br />
handler recognizes it. The sample default screen handler is<br />
com.ibm.ctg.epi.DefaultScreenHandler, which sends the AID PF3 to <strong>CICS</strong>.<br />
Any screen handler bean that can be loaded from the classpath or from the<br />
handler path can be used as the default screen handler.<br />
The servlet will not keep trying to exit a running transaction indefinitely. The<br />
property pool@exitRetryLimit controls how many attempts it makes to exit<br />
the transaction. The default value of this property is 10, but you should<br />
ensure it is large enough for your environment. If the servlet finds there is<br />
still a transaction running on the terminal after this many attempts to exit, the<br />
terminal is assumed to be ‘dead’ and it will not be disconnected or allocated<br />
to a user. The only way to discard dead terminals is to unload the servlet,<br />
stop and restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and load the servlet again.<br />
If you have configured the servlet properly and provided Screen handler<br />
beans, you should not have any dead terminals.<br />
Considering other configuration options<br />
Other configuration options that you should consider are:<br />
v Security<br />
You may need to control access to the Terminal Servlet.<br />
v Logging<br />
The Terminal Servlet writes log information to the standard servlet log. You<br />
can set logging on or off.<br />
v Session tracking<br />
You should configure the Terminal Servlet to use session tracking.<br />
v Server-side includes<br />
194 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
You may wish to configure your Web server to process server-side includes.<br />
Loading the Terminal Servlet<br />
After you have configured the Terminal Servlet and saved the settings, you<br />
must load it. You can choose whether to load it immediately, or each time<br />
your Web server starts up.<br />
Using the Terminal Servlet<br />
If you have not configured the Terminal Servlet properly, error messages are<br />
displayed when the Web server attempts to load the Terminal Servlet. For<br />
more information refer to the Terminal Servlet section in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: <strong>Gateway</strong> Messages book.<br />
This section describes how to use the Terminal Servlet. It describes the<br />
different ways in which the Terminal Servlet can be invoked, and also how to<br />
develop the Web pages that use the Terminal Servlet.<br />
Sample files are provided in the \samples\terminalservlet<br />
subdirectory. File samples.txt describes the samples.<br />
Connecting to <strong>CICS</strong> and starting a transaction<br />
An instance of the Terminal Servlet can only connect to one <strong>CICS</strong> server. For<br />
each <strong>CICS</strong> server that you want to allow access to, you will have created an<br />
instance of the servlet. You might also have created instances of the servlet<br />
that have different initialization parameters.<br />
To start a transaction on the <strong>CICS</strong> server, you must invoke the Terminal<br />
Servlet with a suitable request.<br />
Invoking the Terminal Servlet<br />
There are three ways to invoke the Terminal Servlet:<br />
v by URL<br />
v with an HTML form<br />
v with a server-side include.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
In each case, you need to know the name of the servlet instance that you<br />
want to use, and you pass the servlet one or more request parameters that tell<br />
it what action to take. The parameter names and values are the same in all<br />
cases, but the way you specify them is different.<br />
To start a transaction on the <strong>CICS</strong> server, the parameters you must provide<br />
are:<br />
Chapter 13. The Terminal Servlet program 195
Using the Terminal Servlet<br />
Parameter Name Parameter Value<br />
request send<br />
transaction the transaction ID of the transaction you want started.<br />
Note however that ATI transactions cannot be started for the<br />
Terminal Servlet.<br />
The servlet will allocate a terminal to the user, if it is required.<br />
The full set of request parameters are listed in “Request parameters” on<br />
page 204.<br />
Invoking the servlet by URL<br />
To invoke a servlet instance called TerminalServlet, link to the URL:<br />
http://your_webserver/servlet/TerminalServlet<br />
where your_webserver is the hostname of your Web server and /servlet/ is the<br />
location of your servlet engine (or the context for the servlet).<br />
You can encode request parameters in the URL in the form of a query string,<br />
for example:<br />
http://your_webserver/servlet/TerminalServlet?request=send&transaction=CECI<br />
You should use this method of invoking the servlet when you do not need the<br />
user to enter any information.<br />
Invoking the servlet with an HTML form<br />
With this method, you create an HTML form in a Web page. For example:<br />
<br />
(Tags to place text entry areas, buttons, and other prompts go here)<br />
<br />
is a form that would invoke the servlet called TerminalServlet. The METHOD<br />
can be GET or POST. The various elements of the form have names and<br />
values, and these are sent to the servlet when the form is submitted. If you<br />
know you want to set a particular request parameter, add it as a hidden item<br />
in the form, for example: . Hidden inputs are always sent to the servlet. In general, the<br />
name of a form element is the name of a request parameter, and its value is<br />
the value of the request parameter.<br />
This is the only way to send user-entered information to the servlet.<br />
The supplied sample, epissam3.html, illustrates the HTML form method; see<br />
the samples.txt file on the product CD.<br />
196 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Invoking the servlet with a server-side include<br />
A server-side include is processed by the Web server before the Web page is<br />
sent to the user. The servlet is invoked, and any output it generates is<br />
included in the Web page in place of the server-side include tags. The user<br />
only sees the servlet output in the Web page.<br />
In the HTML source, a WebSphere server-side include of the servlet looks like<br />
this:<br />
<br />
<br />
<br />
<br />
<br />
A server-side include can be used to add variable information to a Web page,<br />
or to drive a terminal to perform some action whenever a Web page is<br />
displayed, without any user involvement.<br />
You can add as many server-side includes to a Web page as you wish, but<br />
note:<br />
v Server-side includes in one page may be processed in parallel. You can<br />
therefore not be sure in which order they are performed, although usually<br />
this is the order in which they occur in the source.<br />
v The servlet stores session information that allows it to access the terminal<br />
allocated to a user. If the user session is invoked by a server-side include,<br />
subsequent server-side includes in the same page will not be able to access<br />
the session information. Once the page has been sent to the user, the<br />
session is established, and a page with multiple server-side includes will<br />
work correctly.<br />
The supplied sample<br />
\samples\terminalservlet\epissam2.shtml illustrates the<br />
server-side include method.<br />
What happens next?<br />
When the servlet has been invoked from a form or by linking to a URL, some<br />
output must be sent back to the browser. To decide what should be displayed<br />
to the user, the servlet uses the page mapping properties that you have set up,<br />
see “Page mappings” on page 192.<br />
Displaying screens and fields<br />
There are two ways to include <strong>CICS</strong> screen information in a Web page:<br />
v server-side includes<br />
v variable substitution.<br />
You can mix the two approaches if you want to.<br />
Using the Terminal Servlet<br />
Chapter 13. The Terminal Servlet program 197
Using the Terminal Servlet<br />
Using server-side includes<br />
Your Web server must be configured to process server-side includes. You<br />
create SHTML pages that contain server-side includes that invoke the servlet.<br />
The output from the servlet is inserted into the page in place of the<br />
server-side include.<br />
For example, to display the screen, as part of an HTML form, using<br />
WebSphere:<br />
<br />
<br />
<br />
or to display the contents of the 22nd field on the screen, using WebSphere:<br />
<br />
<br />
<br />
Using variable substitution<br />
You create HTML template files that the servlet will load. The servlet replaces<br />
variables in the file with <strong>CICS</strong> screen information, and the resulting output is<br />
sent to the browser. You use page mapping properties to tell the servlet what<br />
template file to load (see “Page mappings” on page 192).<br />
For example, a template file for the CESN signon screen might look like:<br />
<br />
<br />
<strong>CICS</strong> Signon<br />
<br />
<br />
<strong>CICS</strong> Signon<br />
<br />
<br />
<br />
Userid: <br />
Password: <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
where the variables are &USERID; and &PASSWORD;. You can identify fields<br />
by number - to use names for fields, as in this example, you must have a<br />
Screen Handler bean which can recognize the screen and set fields by name.<br />
Page mapping property values can be the names of HTML template files or<br />
any URL. So that the servlet knows that a page mapping property identifies<br />
198 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
an HTML template, you should set it to the value file://template_filename, for<br />
example: file://d:/html/templates/test.html.<br />
What can be displayed?<br />
Any piece of information that can be displayed by a server-side include can<br />
also be used for variable substitution, and vice-versa. The variable name used<br />
in a template is the same as the value of the display parameter in the<br />
server-side include.<br />
Generally, you can display:<br />
v The screen, as part of an HTML form<br />
v A field - identified by number, or by name, if you have a Screen Handler<br />
bean for it<br />
v Servlet configuration settings<br />
v The number of terminals that are currently connected, in use, and free.<br />
The full set of properties that can be displayed is listed in “Properties and<br />
parameters reference” on page 200.<br />
Sending the screen back to <strong>CICS</strong><br />
To send the screen back to <strong>CICS</strong> you must invoke the servlet with the request<br />
parameter set to ″send″. You do not need to provide a transaction parameter -<br />
it is ignored if a transaction is already running. To update the screen with<br />
new information before sending it back to <strong>CICS</strong>, you specify further request<br />
parameters that identify the fields (by name or number) and what they should<br />
be set to.<br />
For example, the following WebSphere server-side include:<br />
<br />
<br />
<br />
<br />
<br />
<br />
sets the fields named USERID and PASSWORD to the values given, and then<br />
send the screen to <strong>CICS</strong>. In an HTML form, you might use the form element<br />
. When the user<br />
submits the form, the request parameter USERID is set to the value that they<br />
entered.<br />
Setting the AID<br />
The default AID is Enter.<br />
Using the Terminal Servlet<br />
To set the AID from an HTML form, include a Submit button, specified like<br />
this:<br />
Chapter 13. The Terminal Servlet program 199
Using the Terminal Servlet<br />
.<br />
If the user presses the button, the servlet is sent the request parameter<br />
″DFH_PF3″ with the value ″Exit″ (which the servlet ignores). The AID is set to<br />
PF3. In a,WebSphere server-side include, you could set the AID like this:<br />
<br />
<br />
<br />
<br />
<br />
The full set of request parameters is listed in see “Properties and parameters<br />
reference”.<br />
Disconnecting<br />
When the servlet has allocated a terminal to a user, it is retained until:<br />
v The servlet is invoked with the parameter ″request″ set to ″disconnect″<br />
v The user’s session on the Web server expires<br />
v If the pool@idleTimeout property has been set, the terminal is<br />
automatically disconnected if it is not accessed for the specified period of<br />
time.<br />
v The <strong>CICS</strong> Client is stopped<br />
v The connection to the <strong>CICS</strong> server is lost - or the server goes down<br />
v The servlet is unloaded by the Web server.<br />
You should try to explicitly release terminals when they are no longer<br />
required.<br />
Note that when a user has established a session with the servlet and been<br />
allocated a terminal, any instance of the servlet to which the user has access<br />
can continue the session. The same terminal is used until the user disconnects<br />
or the session is ended for some other reason. The page mappings and other<br />
properties used for any particular request are those set for the instance of the<br />
servlet that is processing the request.<br />
Properties that can be set as request parameters, for example, page mappings,<br />
override the settings for the servlet, but usually only apply to the current<br />
request, and do not affect requests by other users or subsequent requests by<br />
the same user.<br />
Properties and parameters reference<br />
This section describes the Terminal Servlet properties<br />
200 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Properties and parameters reference<br />
Servlet configuration properties<br />
In general, these properties can be specified either in a properties file or as<br />
servlet initialization parameters when you configure the Web server. The<br />
names are not case sensitive. Values given as servlet initialization parameters<br />
override settings loaded from a properties file. Apart from the servlet@debug<br />
and servlet@extendedLogging properties, these settings cannot be changed<br />
while the servlet is running. However, using the request parameter display,<br />
you can query the current settings of a property, see “Displayable properties”<br />
on page 205.<br />
servlet@debug<br />
If set to true, turns tracing on for all instances of the servlet. You can<br />
turn tracing on or off while the servlet is running, and output is<br />
directed to standard output. Note that turning tracing on seriously<br />
impacts performance!<br />
servlet@extendedLogging<br />
If set to true, turns extended logging on. Output is directed to the<br />
servlet log.<br />
servlet@propertyFile<br />
The full path name of a properties file to load. This property can only<br />
usefully be set as a servlet initialization parameter.<br />
servlet@templateDir<br />
The name of a directory from which HTML template files can be<br />
loaded. Setting this property prevents users from viewing files that<br />
are not in the template directory or its subdirectories. If you do not set<br />
this property, the servlet can load any file on the Web server that it<br />
has access to.<br />
pool@defaultHandler<br />
The screen handler to use to exit screens when no specific handler is<br />
found. If you set this to be one of the Screen Handlers loaded from<br />
the Screen Handler path, make sure that the handler path is set before<br />
the default handler.<br />
pool@deviceType<br />
The terminal model definition to use. If this property is not set, the<br />
default is used.<br />
pool@encoding<br />
Allows you to specify the Java Encoding to be used. Refer to<br />
″Appendix A. Java encodings″ in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference book for further details on this.<br />
pool@exitRetryLimit<br />
The number of times that the servlet will try to exit a running<br />
transaction during terminal disconnection. This prevents the servlet<br />
looping, if a screen cannot be exited.<br />
Chapter 13. The Terminal Servlet program 201
Properties and parameters reference<br />
pool@gatewayUrl<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> that the servlet should<br />
connect to. The default is to use a local <strong>Gateway</strong>, that is local://.<br />
pool@handlerPath<br />
The path from which Screen Handler beans are loaded. You can<br />
include directories, .jar files, and .zip files, but subdirectories are not<br />
searched.<br />
pool@idleTimeout<br />
The maximum time in seconds to allow a terminal to be left idle<br />
before it is automatically disconnected. The default value is 0,<br />
meaning no timeout.<br />
pool@installTimeout<br />
The maximum time in seconds to allow a terminal to install before<br />
failing. The valid range is 0 to 3600. The default value is 0, meaning<br />
no timeout<br />
pool@maxTerminals<br />
The maximum number of terminals that can be connected to <strong>CICS</strong><br />
concurrently. The default value is 5.<br />
pool@minTerminals<br />
The number of terminals that should be kept connected to <strong>CICS</strong> when<br />
not in use. The default value is 0.<br />
pool@password<br />
Specifies the password to be associated with a signon incapable<br />
terminal at the time of creation.<br />
pool@readTimeout<br />
The maximum time in seconds to allow for conversational<br />
transactions before timing out.. Valid range is 0 to 3600. A value of 0<br />
meaning no timeout.<br />
pool@reusingTerminals<br />
If set to true, released terminals are kept connected for the next user.<br />
The default behavior is to disconnect terminals when a user session<br />
ends. You must also set pool@minTerminals for this property to have<br />
any effect.<br />
pool@serverName<br />
The name of the <strong>CICS</strong> server to connect to. If this property is not set,<br />
the default <strong>CICS</strong> server, as defined in your configuration is used.<br />
pool@signonCapability<br />
Specifies signon capability for extended terminals. Valid entries are<br />
EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE.<br />
202 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Properties and parameters reference<br />
pool@pool@userid<br />
Specifies the userid to be associated with a signon incapable terminal<br />
at the time of creation.<br />
screen@coloring<br />
If set to true, colored fields are displayed in the color indicated in the<br />
3270 datastream.<br />
Due to the limitations of HTML, unprotected fields cannot be colored<br />
and always appear as black text on a white background.<br />
If the property is not specified. the Terminal Servlet displays the<br />
screen with black text on a white background.<br />
screen@cursoring<br />
If set to true, JavaScript sets the screen cursor position. The default<br />
setting is false.<br />
screen@NeutralColor<br />
Specifies the HTML color to which the screen handler will translate<br />
the neutral 3270 color.<br />
screen@stripBlanks<br />
If set to true, the Web Browser formats the field text.<br />
screen@stripEmptyRows<br />
If set to true, the screen handler removes screen rows that do not<br />
contain data.<br />
screen@TrimFields<br />
If set to true, the screen handler removes excess white space from the<br />
start and end of any input fields.<br />
Page mapping properties<br />
Page mappings associate Web pages with particular screens or terminal states.<br />
Page mappings can be specified in a properties file, or as servlet initialization<br />
parameters, when you configure the Web server. However, using the request<br />
parameter display, you can query the current settings of a page mapping, see<br />
“Displayable properties” on page 205.<br />
Standard page mapping properties Value<br />
page@disconnected The page to show when the terminal is<br />
disconnected.<br />
page@error The page to show when an error occurs<br />
page@idle The page to show when the terminal is<br />
idle, that is, no transaction is running<br />
page@default The page if no other page is specified.<br />
page@screen The page to show for this screen.<br />
Chapter 13. The Terminal Servlet program 203
Properties and parameters reference<br />
Request parameters<br />
These parameters are set only when a request is made. You can also specify<br />
any other property that can be set on a request, for example:<br />
servlet@extendedLogging.<br />
Parameter name Parameter value<br />
request Set to ″send″ to send a screen to <strong>CICS</strong> or ″disconnect″ to<br />
end a session<br />
If required, a new terminal session is started.<br />
display The name of a property that can be displayed, see<br />
“Displayable properties” on page 205.<br />
translateText Set to ″true″ to translate the characters and & to<br />
< > and & respectively. This is used when<br />
text is displayed.<br />
transaction The transaction ID of a transaction to be started. This is<br />
only used if the request is ″send″ and the terminal state<br />
is idle.<br />
ATI transactions cannot be started for the Terminal<br />
Servlet.<br />
transactionData Additional parameters to pass to a transaction. This is<br />
only used if the request is ″send″ and the terminal state<br />
is idle, and a transaction was specified.<br />
DFH_CURSOR The field where the screen cursor should be placed, as a<br />
field index (a number), or the name of the field, if a<br />
screen handler bean is available for the current screen.<br />
DFH_ENTER,<br />
DFH_CLEAR, DFH_PA1 -<br />
3, DFH_PF1 - 24<br />
This parameter name must be in upper case.<br />
The value is ignored.<br />
Use one of these parameters to specify the AID key to<br />
be sent to <strong>CICS</strong>. This must be in upper case.<br />
A field index The text to be set in the field.<br />
Use to set the contents of a field when you know the<br />
field index.<br />
usingSession Set to false if no terminal session is required.<br />
204 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
If this parameter is set, any terminal used for this<br />
request is discarded after use.
Parameter name Parameter value<br />
matchOnIdle Set to false by default.<br />
Properties and parameters reference<br />
Normally the servlet only attempts to find a<br />
ScreenHandler for the current screen when the terminal<br />
state is ‘client’, that is, a conversational or<br />
pseudo-conversational transaction is expecting a<br />
response. Setting this property to true causes the servlet<br />
to check the current ScreenHandler every time the<br />
screen changes regardless of the state. You may want to<br />
do this if you have transactions that use BMS maps, but<br />
which are not conversational or pseudo-conversational.<br />
If you have a large number of ScreenHandlers, the<br />
servlet may run more slowly when this property is set<br />
to true. For this reason, the default value is false.<br />
In addition, if a Screen Handler bean is available for the current screen, you<br />
can set any properties on that bean by specifying them in the request. For<br />
beans generated by BMSMapConvert, the field names defined in the BMS<br />
map are properties that can be set to the required text in the field.<br />
Displayable properties<br />
The following table shows the values that can be specified for the ″display″<br />
request parameter or used for variable substitution, see “Using variable<br />
substitution” on page 198.<br />
Display values Displays<br />
none Nothing. Use to suppress output from a<br />
server-side include.<br />
screen The screen - as part of an HTML form.<br />
errorMessage If an error has occurred, the error<br />
message.<br />
errorCause If an error has occurred, further<br />
information about the error.<br />
DFH_CURSOR The name of the field where the cursor is,<br />
if it can be determined, otherwise the<br />
field index.<br />
a field index The field text<br />
a screen handler property name The value of the property if it can be<br />
determined.<br />
any of the servlet configuration properties The value of the property for the current<br />
listed above<br />
servlet instance.<br />
Chapter 13. The Terminal Servlet program 205
Properties and parameters reference<br />
Display values Displays<br />
any page mapping property The value of the property for the current<br />
servlet instance.<br />
any request parameter, except for<br />
″request″ and ″display″<br />
The value of the property for the current<br />
request.<br />
pool@connectedTerminals The current number of connected<br />
terminals, for this servlet instance.<br />
pool@freeTerminals The current number of connected<br />
terminals that are not in use, for this<br />
servlet instance.<br />
pool@terminalsInUse The current number of terminals allocated<br />
to users, for this servlet instance.<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web Interface<br />
The <strong>CICS</strong> Web Interface, included in <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
<strong>Version</strong> 1.2 and above, is a collection of transactions and programs supporting<br />
direct access to <strong>CICS</strong> transaction processing services from Web browsers.<br />
If you have generated HTML templates for use by the <strong>CICS</strong> Web Interface,<br />
they can also be used as HTML templates by the Terminal Servlet. You will<br />
have to make some changes to invoke the servlet instead of the <strong>CICS</strong> Web<br />
Interface, but the format is basically the same.<br />
To use the template file:<br />
1. Copy the template file to a directory on the Web server.<br />
2. Edit it to change the action to /servlet/TerminalServlet and add<br />
a hidden element with name ″request″ and the value ″send″.<br />
3. Generate a Map class and Screen Handler bean for the BMS map that the<br />
HTML template refers to.<br />
4. Compile the generated Java source files.<br />
5. Copy the compiled class files to a suitable directory on the Web server.<br />
6. Set the servlet property pool@handlerPath so that it will load the new<br />
classes.<br />
7. Set a page mapping property to associate the new Screen Handler bean<br />
with the HTML template file.<br />
206 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 14. Problem determination and problem solving<br />
Preliminary checks<br />
Most problems in a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system are caused by one of<br />
the following:<br />
v User errors<br />
v Programming errors<br />
v Configuration errors.<br />
Before investigating a problem, check whether there is an obvious cause:<br />
v Has the system run successfully before now?<br />
v Have you made any changes to the configuration of the system or added<br />
new features or programs?<br />
v Is your CLASSPATH environment variable set correctly?<br />
See “Configure your programming environment” on page 53 for<br />
information on setting CLASSPATH.<br />
The CLASSPATH is displayed at the top of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace output. See “Starting the <strong>Gateway</strong> with user-specified options” on<br />
page 142 for information on starting the <strong>Gateway</strong> daemon with tracing<br />
enabled.<br />
v Is the environment configured correctly?<br />
Refer to the documents listed under “Sample configuration documents” on<br />
page 266.<br />
v Can the Client daemon connect to the <strong>CICS</strong> server?<br />
Use the command:<br />
<strong>CICS</strong>CLI -s=servername<br />
followed by the command:<br />
<strong>CICS</strong>CLI -l<br />
If the connection is good, this command returns the name of the server you<br />
specified in servername.<br />
v Are there any messages explaining the failure?<br />
See “Messages” on page 208.<br />
v Are there any Java exceptions?<br />
See “Java exceptions” on page 216.<br />
v Does the problem occur only at certain times?<br />
© Copyright IBM Corp. 1996, 2002 207
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problem determination<br />
This might be because the system is heavily loaded at those times; See<br />
“java.lang.OutOfMemory exception” on page 217 for more information.<br />
v Can you re-create the failure?<br />
What to do next<br />
If you think the problem is with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see<br />
“Diagnosing common problems: <strong>Gateway</strong> daemon” on page 212, or<br />
“Diagnosing common problems: Client daemon” on page 227 as appropriate.<br />
Here you will find information on diagnosing common configuration and<br />
other errors, as well as advice on the documentation you need to collect in<br />
specific situations.<br />
See “Program support” on page 236 for information on how to contact IBM.<br />
See “Documenting problems” on page 237 for the information that you will be<br />
asked to provide.<br />
If you think the problem is in another product, follow the problem<br />
determination procedures provided with that product. For <strong>CICS</strong> servers, see<br />
the <strong>CICS</strong> Problem Determination Guide.<br />
Problems with the <strong>Gateway</strong> daemon<br />
Messages<br />
The <strong>Gateway</strong> daemon writes log messages to standard output (stdout) orto<br />
standard error (stderr). If <strong>Gateway</strong> daemon tracing is enabled, it also writes<br />
log messages to the trace output file.<br />
Messages have the format:<br />
CCLnnnnt: <br />
where nnnn is a number, and t is one of:<br />
I for information messages, written to standard output<br />
E for error messages, written to standard error<br />
W for warning messages, written to standard error<br />
To redirect all <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> messages to standard error,<br />
regardless of their type, you can use a command like the following:<br />
ctgstart 1>&<br />
Refer to the documentation for your operating system for more information<br />
on redirecting output.<br />
See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for an explanation of all <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> messages.<br />
208 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Tracing<br />
There are three main levels of <strong>Gateway</strong> daemon and application tracing:<br />
Stack tracing Trace entries are written only when a Java<br />
exception occurs. They can help to determine<br />
the source of the exception. Use this when it is<br />
important to maintain performance. See<br />
Figure 23.<br />
Standard tracing Java exceptions and the main <strong>Gateway</strong><br />
daemon functions and events are traced. By<br />
default, the <strong>Gateway</strong> daemon displays only<br />
the first 128 bytes of any data blocks (for<br />
example the COMMAREA, or network flows)<br />
in the trace.<br />
Debug tracing Java exceptions and the main <strong>Gateway</strong><br />
daemon functions and events are traced in<br />
greater detail than with stack or standard<br />
tracing. By default, the <strong>Gateway</strong> daemon fully<br />
outputs any data blocks in the trace. Use this<br />
only when performance is not important or if<br />
standard tracing did not give enough<br />
information to solve the problem.<br />
10:38:12:262: main:S-C: java.io.IOException<br />
10:38:12:263: main:S-C: at com.ibm.gskssl.SSLSocketImpl.socketCreate(Native Method)<br />
10:38:12:264: main:S-C: at com.ibm.gskssl.SSLSocketImpl.create(SSLSocketImpl.java:133)<br />
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:109)<br />
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:73)<br />
10:38:12:266: main:S-C: at com.ibm.ctg.server.GskSslHandler.initialize(GskSslHandler.java:487)<br />
10:38:12:266: main:S-C: at com.ibm.ctg.server.JGate.main(JGate.java:941)<br />
Figure 23. Sample Java stack trace.<br />
<strong>Gateway</strong> daemon tracing<br />
You can start tracing in the <strong>Gateway</strong> daemon process, or in the user<br />
application that makes calls to the <strong>Gateway</strong> daemon (see“Application tracing”<br />
on page 210 for more information). The following explains how to start<br />
tracing in the <strong>Gateway</strong> daemon process.<br />
Use options on the ctgstart command to enable and control tracing in the<br />
<strong>Gateway</strong> daemon. For example, to enable the standard trace, use this<br />
command when starting the <strong>Gateway</strong> daemon:<br />
ctgstart -trace<br />
To enable the debug trace, use this command:<br />
Problems with the <strong>Gateway</strong> daemon<br />
Chapter 14. Problem determination and problem solving 209
Problems with the <strong>Gateway</strong> daemon<br />
ctgstart -x<br />
If you used the configuration tool to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the<br />
default destination for trace output is the ctg.trc file in the<br />
\bin subdirectory. Otherwise, trace output is written to stderr.<br />
You can override the default destination for trace output by using the ctgstart<br />
-tfile option. For example, the command:<br />
ctgstart -x -tfile pathname<br />
starts the <strong>Gateway</strong> daemon with debug tracing enabled and writes the trace<br />
output to the file specified by pathname.<br />
If the <strong>Gateway</strong> daemon is running as a Windows service: Either:<br />
v Configure the <strong>Gateway</strong> daemon to enable tracing whenever it is started. See<br />
“Using the configuration tool” on page 54.<br />
v Use the -A option on the ctgservice command to pass tracing options to the<br />
ctgstart command. See “Running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as a Windows<br />
service” on page 146.<br />
Performance considerations: Tracing, especially debug tracing, decreases<br />
performance. The following changes were made in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
version 4.0 to reduce the effect of tracing on performance:<br />
v Trace output is not written to stderr if you used the -tfile option to specify<br />
a trace output file.<br />
v Only the first line of any data block in the trace output is time-stamped.<br />
v The -truncationsize and -dumpoffset options allow you to limit the size of<br />
any data blocks that are written in the trace.<br />
v The -tfilesize option allows you to limit the size of the trace output file.<br />
For more information on starting the <strong>Gateway</strong> daemon with trace options, see<br />
“Starting the <strong>Gateway</strong>” on page 141.<br />
For more information on performance considerations, see Chapter 8,<br />
“Performance” on page 135.<br />
Application tracing<br />
You can enable tracing in the application in two ways. Either use a Java<br />
directive when you start the JVM, or add calls to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> tracing API. Use the -D option on the java command to specify Java<br />
directives. The tracing API comprises several static methods in the T class of<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See ″Tracing in Java client programs″ in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide book for further information.<br />
When using Internet Explorer, the stderr data stream is written to the Java<br />
console. To enable the Java console, in Internet Explorer version 5, you select<br />
210 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Tools —> Internet Options —> Advanced, then check the box next to Java<br />
console enabled. You can then view the console by selecting View —> Java<br />
Console.<br />
JNI tracing<br />
You cannot enable JNI trace through the configuration tool. Use one of the<br />
following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
Problems with the <strong>Gateway</strong> daemon<br />
where filename is the name of the file to which trace output is to be sent.<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin protocol<br />
handler (see “TCPAdmin protocol settings” on page 69). See “Administering<br />
your system” on page 149 for details of how to enable JNI trace<br />
dynamically.<br />
v For Java Client applications running in local mode, use Java to launch your<br />
application and set the system property gateway.T.setJNITFile, as shown in<br />
the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
J2EE Tracing<br />
Refer to “Tracing” on page 95 for information on using the tracing function<br />
provided with the ECI and EPI resource adapters.<br />
Servlet tracing and logging in WebSphere<br />
IBM WebSphere Application Server provides the Advanced Administrative<br />
Console to simplify the tasks associated with managing applications.<br />
To enable servlet tracing in WebSphere do the following:<br />
1. Configure WebSphere to send standard output and standard error to a file<br />
of your choice:<br />
In the Administrative Console, select the application server in which you<br />
want to enable tracing. Under the General tab there are text-entry boxes<br />
labelled Standard output and Standard error. You can type filenames in<br />
these boxes to override the default destinations.<br />
2. Enable tracing in the application:<br />
Chapter 14. Problem determination and problem solving 211
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problems with the <strong>Gateway</strong> daemon<br />
v For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet, use the<br />
servlet@debug property to enable tracing.<br />
For more information see “Properties and parameters reference” on<br />
page 200.<br />
v For user-written applications, use Java directives to enable tracing. You<br />
can type these in the Command line arguments box in the<br />
Administrative Console. Use the same format for Java directives as in a<br />
java command line call. For example, to enable full debug tracing, type<br />
-Dgateway.T=on as the first command line argument.<br />
See ″Tracing in Java client programs″ in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide book for further information on Java directives for<br />
tracing.<br />
3. Click on the Apply button, to update the WebSphere settings, and run the<br />
servlet.<br />
When a servlet runs, WebSphere writes logging information to the same<br />
destination as standard output. This information includes start times, stop<br />
times, and any error messages. For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal<br />
Servlet, use the servlet@extendedLogging property to enable extended<br />
logging. If you enabled extended logging, the Terminal Servlet writes to the<br />
log every time it receives a request. This can provide useful information for<br />
diagnosing problems but it reduces performance.<br />
You can enable both tracing, and extended logging, while the Terminal Servlet<br />
is running. For more information on Terminal Servlet properties see<br />
“Properties and parameters reference” on page 200.<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
Problems running the configuration tool<br />
Task Guide loses focus<br />
Under some JVMs on the Windows and UNIX operating systems, you<br />
might have problems when entering the name for a new server in the<br />
Task Guide. If the text box loses focus after each key press, click the Next<br />
button to move onto the next panel and then click the Back button to<br />
return. You should now be able to input text normally. This is a JVM<br />
problem.<br />
Chinese, Japanese or Korean characters do not display correctly<br />
To display Chinese, Japanese or Korean characters correctly on the<br />
Windows operating system, set the system locale to Chinese, Japanese or<br />
Korean. If characters still do not display correctly, install the relevant<br />
world type font package. You can download world type font packages<br />
from the following site:<br />
212 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
http://www.ibm.com/developerworks/java/jdk/linux130/<br />
The <strong>Gateway</strong> daemon fails to find Turkish configuration settings<br />
When you run the configuration tool under a Turkish locale for the first<br />
time, by default the configuration settings are saved in file CTG.INI.ini.<br />
Rename the file to CTG.INI to allow the <strong>Gateway</strong> daemon to find the<br />
settings automatically. You only have to do this once, when the<br />
configuration tool is first run.<br />
The configuration tool fails to launch under Turkish and the Solaris 1.3.0<br />
JVM<br />
This is a known problem with the Solaris 1.3.0 JVM and has been raised<br />
under SunBugs 4380798 and 4346718. A workaround is detailed under<br />
SunBug 4380798 in the Sun Java Bug Database; to access this, go to<br />
http://java.sun.com/, follow the link to Online Support and search the<br />
Bug Database for 4380798.<br />
Problems running the configuration tool in Turkish under the HP-UX JREs<br />
Running the tool under HP-UX JRE 1.3 results in messages saying that<br />
fonts are not found. Despite this, Turkish characters display correctly.<br />
Codepage problems<br />
A <strong>Gateway</strong> daemon trace shows the codepage in which the JVM is running. It<br />
is displayed in the System Properties section at the top of the trace. Refer to<br />
Appendix A, “Data conversion between the Client daemon and a <strong>CICS</strong><br />
server” on page 251 for information on finding the codepage that the Client<br />
has sent to the server.<br />
If a process locks<br />
To determine where the lock is happening, enable tracing in the application,<br />
in the <strong>Gateway</strong> daemon, and in the Client daemon. See “Tracing” on page 209<br />
for information on tracing the <strong>Gateway</strong> daemon and the application. See<br />
“Tracing” on page 219 for information on tracing the Client daemon, and<br />
“Diagnosing common problems: Client daemon” on page 227 for information<br />
on how to determine whether the lock is in the Client daemon or the server. If<br />
the lock is in the <strong>Gateway</strong> daemon, contact your IBM support organization<br />
and provide them with the <strong>Gateway</strong> daemon trace.<br />
See “The Client daemon stops responding” on page 232, for information on<br />
what to do if the Client daemon is not responding.<br />
Problems when the <strong>Gateway</strong> daemon is running as a Windows service<br />
If the <strong>Gateway</strong> daemon does not start, or clients cannot connect to it, when it<br />
is running as a Windows service, it may be because input from the console is<br />
enabled. Entries like those in Figure 24 on page 214 indicate that the <strong>Gateway</strong><br />
daemon is trying to read from the console:<br />
Chapter 14. Problem determination and problem solving 213
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
11:37:58:472 : main: S-C: -> [ServerMessages: getKeys] ()<br />
11:37:58:472 : main: S-C:
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
You specify the name of the server KeyRing class in the KeyRing classname<br />
field in the SSL protocol settings panel in the configuration tool. Do not<br />
include the directory or file extension when you specify the KeyRing class<br />
name. The CLASSPATH should include an entry for the directory that<br />
contains the KeyRing class.<br />
In a user application: The API call<br />
SslJava<strong>Gateway</strong>.setKeyRing("ClientKeyRingName", "thePassword"); fails with<br />
the following error in a user application:<br />
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing<br />
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This<br />
file is supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
JSSE:<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore name to<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, but the class does not load, or cannot be found,<br />
the <strong>Gateway</strong> daemon assumes that you are using JSSE and not SSLight.<br />
iKeyMan locks with ″class not found″ exception: A message like the following is<br />
received by the application:<br />
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException<br />
This happens if the IBM Java Cryptography Extension (JCE) package is not<br />
installed. Ensure that you have installed the JCE supplied with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> in the ibm-jce.zip file. See “Installation” on page 114.<br />
Application receives an ″access denied″ exception: A message like the following is<br />
received by the application:<br />
java.io.IOException: CCL6651E: Unable to connect to the <strong>Gateway</strong>.<br />
[address = killerb2b, port = 8050]<br />
[java.security.AccessControlException: access denied<br />
(java.io.FilePermission f:/jssekeys/testclient.jks read)]<br />
This happens if your application does not have permission to read from the<br />
file system containing the keystore. See Using ECI, EPI, and ESI with a Java 2<br />
Security Manager, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, for more<br />
information.<br />
KeyStore name not recognized: Java interprets the back slash (\) character as a<br />
parameter delimitter. If you used the back slash character as a directory<br />
separator when entering the path name of the KeyStore file during<br />
configuration, Java cannot recognize the name. Use either a forward slash (/)<br />
character, or double back slash (\\) characters, as a separator in the path<br />
name on all operating systems. For example:<br />
Chapter 14. Problem determination and problem solving 215
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
c:/mykeys/jsse/keystore.jks<br />
c:\\mykeys\\jsse\\keystore.jks<br />
Java exceptions<br />
If the application or the <strong>Gateway</strong> daemon does not handle an exception, then<br />
the Java Virtual Machine (JVM) will write a Java stack dump. The destination<br />
for the dump output depends on your JVM implementation; check your Java<br />
documentation for more information.<br />
Disable the Just-In-Time (JIT) compiler to increase the information written to<br />
the Java stack dump. This information might include the line of Java source<br />
code where the exception happened. How you disable the JIT compiler<br />
depends on your JVM implementation; check your Java documentation for<br />
more information.<br />
Figure 25 shows a sample Java stack dump taken with the JIT compiler<br />
disabled.<br />
Exception in thread "main" java.lang.OutOfMemoryError<br />
at java.lang.Thread.start(Native Method)<br />
at com.ibm.ctg.server.ThreadManager.createObject(ThreadManager.java:345)<br />
at com.ibm.ctg.server.ThreadManager.(ThreadManager.java:131)<br />
at com.ibm.ctg.server.ManagedResources.(ManagedResources.java:106)<br />
at com.ibm.ctg.server.JGate.main(JGate.java:895)<br />
Figure 25. Sample Java stack dump<br />
If the <strong>Gateway</strong> daemon handles an exception, a Java stack dump is written<br />
only if tracing is enabled. Try to re-create the problem with tracing enabled.<br />
This should help to show you what was happening before the exception<br />
occured. See “Tracing” on page 209 for more information on tracing.<br />
ConnectFailed exceptions when running under load: Workstation versions<br />
of Windows restrict the number of open requests that can be queued against a<br />
socket. This might lead to intermittent Java ConnectFailed exceptions when<br />
running under load. This is especially likely when using HTTP, because this<br />
protocol opens and closes sockets frequently.<br />
Using a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same workstation:<br />
If you intend to use a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same<br />
workstation, remove ctgclient.jar and ctgserver.jar from the CLASSPATH<br />
setting. If you do not remove them, you are likely to receive the following<br />
error when running applications:<br />
ERROR: java.io.IOException:<br />
CCL6664E: Unable to load relevant class to support the tcp protocol<br />
216 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
The reason for the error is that Java searches the CLASSPATH environment<br />
variable before downloading classes across the network. If the required class<br />
is local, Java attempts to use it. However, using class files from the local file<br />
system breaks Java application security rules; therefore an exception is raised.<br />
Java security exceptions<br />
A message like the following is issued when using the ECI or EPI interfaces in<br />
a Java 2 Security Manager environment:<br />
java.security.AccessControlException: access denied (java.util.PropertyPermission * read,write)<br />
This might mean that your application program is trying to perform a task<br />
that is protected by the Security Manager. Refer to ″Using ECI and EPI with a<br />
Java 2 Security Manager″, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, for<br />
information on security permissions required by programs running in this<br />
environment.<br />
java.lang.OutOfMemory exception<br />
If this happens after the <strong>Gateway</strong> daemon has been running for a long time,<br />
then it could be caused by a memory leak. If it happens only when the<br />
<strong>Gateway</strong> daemon is heavily loaded, then there might be too many threads<br />
active for the available Java Virtual Machine (JVM) memory.<br />
Memory leak: Run a memory usage monitor against the <strong>Gateway</strong> daemon<br />
process. If there is a memory leak, the amount of memory used by the<br />
<strong>Gateway</strong> daemon increases over time. Make sure that all user applications<br />
that connect to the <strong>Gateway</strong> daemon close the Java<strong>Gateway</strong>() connection<br />
object when they have finished using it. If this does not resolve the problem,<br />
run the <strong>Gateway</strong> daemon debug trace and contact your IBM support<br />
organization. You can use the ctgstart -tfilesize option to limit the size of the<br />
trace output file. You can also use the ctgstart -truncationsize option to reduce<br />
to zero the size of any data blocks that will be displayed in the trace. This will<br />
reduce the effect on performance.<br />
Too many threads: You can estimate the amount of virtual memory that is<br />
required by the JVM as follows. Add together:<br />
v the number of Connection Manager threads<br />
v the number of Worker threads<br />
v the number of background threads in use by Java<br />
v the number of different network protocols in use<br />
Then multiply this total by the size of the Java stack allocated to each thread<br />
by the JVM.<br />
In this calculation, assume that the number of active Java background threads<br />
is about five. Refer to your Java documentation for a more accurate value. You<br />
set the maximum numbers of Connection Manager threads and Worker<br />
Chapter 14. Problem determination and problem solving 217
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
threads when you configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See “General<br />
<strong>Gateway</strong> settings” on page 59 for more information.<br />
The way that Java allocates memory depends on your JVM implementation.<br />
Most JVMs allow you to control memory allocation by setting limits on the<br />
sizes of the Java stack and the Java heap.<br />
For more information on thread limits see Table 3 on page 17. For more<br />
information on Java memory allocation refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide and to your Java documentation.<br />
Using Java debugging tools to debug user applications<br />
The IBM Java SDK 1.3 for Windows NT includes file readme.devkit.ibm.html,<br />
which is installed in the \docs subdirectory. This file describes<br />
some of the debugging tools, such as jdb which are supplied with Java. These<br />
tools can be useful for debugging application programs.<br />
Programs using beans included in earlier versions of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
See “EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>”<br />
on page 248 for information on beans that are now provided only as sample<br />
programs.<br />
Problems with the Client daemon<br />
Messages<br />
There are two types of message in the Client daemon:<br />
1. Messages displayed to the user<br />
2. Errors written to the Client daemon error log and trace file.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages book explains all of these<br />
messages.<br />
Error log messages<br />
Any errors on the client workstation that are not caused by incorrect use of<br />
the API are written to the Client daemon error log.<br />
The error log (which has a default name of <strong>CICS</strong>CLI.LOG) is an ASCII text file<br />
that you can browse using a standard text editor.<br />
Help information for all messages is provided in two ASCII text files in the<br />
\bin subdirectory. You can view these using any standard text<br />
editor:<br />
CCLMSG.HLP Help for the end user messages, in the<br />
language you chose at installation time.<br />
218 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Problems with the Client daemon<br />
CCLLOG.HLP Help for the trace and log messages. This is<br />
provided in English only.<br />
Errors resulting from incorrect use of the APIs simply result in error return<br />
codes to the application. It is the responsibility of the application to notify the<br />
end user of the error and provide guidance on corrective actions.<br />
Pop-up messages<br />
Errors generated from within the Client daemon are displayed in a pop-up<br />
window. You must click on OK in the pop-up window before the Client<br />
daemon can continue processing. There may be times when you do not want<br />
messages to appear in pop-up windows, for example, if you leave the Client<br />
daemon running unattended overnight. To disable the display of pop-up<br />
messages, enter the following command:<br />
<strong>CICS</strong>CLI -n<br />
When the display of pop-up messages is disabled, the messages are still<br />
written to the Client daemon error log. To re-enable the display of pop-up<br />
messages, enter the following command.<br />
<strong>CICS</strong>CLI -e<br />
You can specify the -n parameter together with the -s parameter. The display<br />
of pop-up messages is enabled by default.<br />
Tracing<br />
The Client daemon tracing is a very useful problem determination tool for<br />
communication problems. You can use the trace functions to collect detailed<br />
information on the execution of a certain function or transaction. A trace can<br />
show you how the execution of a particular activity is affected by, for<br />
example, the execution of other tasks in a <strong>CICS</strong> system. Each trace entry has a<br />
time stamp, which provides information on the time taken to perform certain<br />
activities.<br />
You can specify which components of the Client daemon you want to trace.<br />
You control this with the <strong>CICS</strong>CLI -m command, (see “<strong>CICS</strong>CLI command<br />
reference” on page 160), or by specifying a list of components using the<br />
configuration tool.<br />
The output from the trace function is a binary trace file called, by default,<br />
<strong>CICS</strong>CLI.BIN in the \bin subdirectory. You can specify a<br />
different name for this file, using the configuration tool. However, you cannot<br />
change the .BIN extension. Using the Maximum Client wrap size<br />
configuration setting, you can specify that the binary trace file should wrap<br />
into a second trace file, and you can also specify the maximum size of these<br />
files.<br />
Chapter 14. Problem determination and problem solving 219
Problems with the Client daemon<br />
To read the trace, run the <strong>CICS</strong>FTRC utility to convert the binary file or files<br />
into a text file. This text file is called <strong>CICS</strong>CLI.TRC by default. The default trace<br />
files are:<br />
<strong>CICS</strong>CLI.BIN The binary trace file produced by running the<br />
Client daemon trace.<br />
<strong>CICS</strong>CLI.WRP The second binary trace file if wrapping of<br />
client trace is enabled.<br />
<strong>CICS</strong>CLI.TRC The name of the text trace file produced when<br />
the binary trace file is converted to a text file<br />
using the <strong>CICS</strong>FTRC utility.<br />
<strong>CICS</strong>CLI.BAK The backup file of the binary trace file. A<br />
backup file is produced from any existing<br />
.BIN file when you turn tracing on.<br />
See “Formatting the binary trace file” on page 222 for information on the trace<br />
conversion utility.<br />
Starting and stopping Client daemon tracing<br />
To start Client daemon tracing, enter the <strong>CICS</strong>CLI command with the -d<br />
option, for example:<br />
<strong>CICS</strong>CLI -d=nnn<br />
where nnn is optional, and is the maximum size in bytes of the data areas to<br />
be traced. (The default value is 512.)<br />
Note: It is recommended that you set at least -d=1000 to ensure that all<br />
relevant data is included in the trace before sending it to your support<br />
organization.<br />
If you need to trace the Client daemon immediately from startup, you can<br />
specify the -s and -d parameters together in the same <strong>CICS</strong>CLI command. For<br />
example, the following command starts the connection to a <strong>CICS</strong> server with<br />
the name <strong>CICS</strong>TCP, enables the trace function, and sets the maximum data<br />
area size to be traced to 128 bytes:<br />
<strong>CICS</strong>CLI -s=<strong>CICS</strong>TCP -d=128<br />
You can specify which components are to be traced when you start tracing.<br />
See “<strong>CICS</strong>CLI command reference” on page 160 for details.<br />
To stop Client daemon tracing, enter the <strong>CICS</strong>CLI command with the -o<br />
option, for example:<br />
<strong>CICS</strong>CLI -o<br />
220 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Problems with the Client daemon<br />
The trace is also automatically stopped if you stop the Client daemon by<br />
using the <strong>CICS</strong>CLI -x command.<br />
Choosing which components to trace<br />
ALL This option traces everything. It is the<br />
preferred option; use it if performance allows,<br />
and consider using the binary formatting tool<br />
to filter information. See “Formatting the<br />
binary trace file” on page 222 for details.<br />
API.1 and API.2 These trace the boundary between the user<br />
application or Java classes, and the Client<br />
daemon. Switching on API.2 automatically<br />
switches on API.1 as well.<br />
DRV.1 and DRV.2 The protocol drivers trace the boundary<br />
between the Client daemon and the network<br />
protocol. Specify the DRV.1 and API<br />
components if you are not sure whether a<br />
problem is inside the Client daemon, and you<br />
want to minimize the impact on performance,<br />
for example when trying to determine a<br />
performance problem.<br />
You can also specify these components to help<br />
to determine which product is causing the<br />
system to lock up.<br />
CCL This component traces the main Client<br />
daemon process. Specify the API and CCL<br />
components if you believe that the problem is<br />
within the Client daemon.<br />
TRN The TRN component traces the internal<br />
interprocess transport between Client<br />
processes. Use it if entries in the Client log<br />
refer to functions such as FaarqGetMsg,<br />
FaarqPutMsg, or FaarqStart. TRN is the most<br />
verbose tracing component.<br />
Wrapping the Client daemon trace<br />
You can control the size of the binary trace file by specifying that it wraps<br />
into a second trace file. You turn on wrapping of trace using the Maximum<br />
Client wrap size configuration setting, where you specify the maximum size<br />
of the wrapping trace (in kilobytes). If this value is 0 (the default), wrapping<br />
trace is not turned on.<br />
Chapter 14. Problem determination and problem solving 221
Problems with the Client daemon<br />
When wrapping trace is turned on, two files (called <strong>CICS</strong>CLI.BIN and<br />
<strong>CICS</strong>CLI.WRP) are used. Each file can be up to half the size of the Maximum<br />
Client wrap size value.<br />
Formatting the binary trace file<br />
You use the Binary Trace Formatter utility <strong>CICS</strong>FTRC to convert the binary trace<br />
file <strong>CICS</strong>CLI.TRC to ASCII text. The utility has the following parameters:<br />
-m=list of components<br />
Specifies that only trace points from the listed components are written to<br />
the text file. The components you can specify are the same as for <strong>CICS</strong>CLI<br />
-m. If -m is not specified, all trace points in the binary trace are written to<br />
the text file.<br />
-w[=filename]<br />
Indicates that there are two binary trace files to format and then<br />
concatenate (that is, the binary files were created with a wrapping trace).<br />
If no filename is specified with the -w parameter, <strong>CICS</strong>FTRC assumes that<br />
the name of the second trace file is <strong>CICS</strong>CLI.WRP.<br />
-n Indents entry and exit points in the test trace file to make it more<br />
readable. By default, indentation is turned off.<br />
-d Specifies detailed trace formatting. If you are using EPI calls, <strong>CICS</strong>TERM<br />
or <strong>CICS</strong>PRINT, an approximation of the screen layout will be included in<br />
the trace.<br />
-i=filename<br />
Specifies the name of the input (binary) trace file, which is <strong>CICS</strong>CLI.BIN by<br />
default.<br />
-o=filename<br />
Specifies the name of the output (text) trace file. If no -o parameter is<br />
specified, the name of the text trace file is assumed to be <strong>CICS</strong>CLI.TRC.<br />
-f Overwrite any existing files.<br />
-s Do summary trace formatting. Summary trace formatting is driven from a<br />
text file (CCLSUMTR.TXT) which is read in at initialization time. This<br />
defines the set of trace points for which you want summary tracing, and<br />
the type of trace point. As DetailFormat reaches each trace point, if it is<br />
one of the ones read in from this file, a line is generated in the summary<br />
file. Use as requested by your IBM support organization; see “Program<br />
support” on page 236.<br />
The formatter can produce a summary of API calls that the user program<br />
makes, and show the progress of the calls through the Client daemon. Specify<br />
the API.2 component to produce a summary trace. Figure 26 on page 223<br />
222 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
shows an example. (The layout of your trace may be different, depending on<br />
the contents of CCLSUMTR.TXT.)<br />
-->Sample of API summary trace taken with API.2 and DRV options.<br />
[Process ,Thread ] Time ▌API Summary▐ ▌CCLCLNT▐ Summary ▌Comms Summary▐<br />
=============================================================================================================<br />
...<br />
...<br />
...<br />
[000000bf,0000017c] 12:08:32.190 --->[7315] CCL3310 ECI Call type ECI_SYNC, UOW=0<br />
[00000089,000000a4] 12:08:32.290 ▌-S->▐[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=89<br />
[000000bf,0000017c] 12:08:32.330 [7391] CCL1040 using slot = Slotp->Ctrl.ConvId = 6<br />
[000000bf,0000017c] 12:08:32.350 [7099] CCL1037 Sync ECI call, so waiting for a reply...<br />
[00000089,00000063] 12:08:32.400 ▌[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.551 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,00000168] 12:08:32.581
Problems with the Client daemon<br />
Command = Erase/Write, so clearing main screen<br />
Command2 = Read Modified<br />
WCC = 0x32 ( Free Kbd,80 char)<br />
Set Buffer Address to (1,2)<br />
Insert Cursor @ (1,2)<br />
Set Buffer Address to (1,1)<br />
Start Field Extended (Unprotected,Alphanumeric,Display,not-pen-detectable,Foreground Colour Green)<br />
Data:’’<br />
Insert Cursor @ (1,3)<br />
Set Buffer Address to (2,1)<br />
Data : ’User ’<br />
.....<br />
.....<br />
.....<br />
.....<br />
Set Buffer Address to (24,49)<br />
Start Field Extended (Autoskip (Prot+Num),Display,not-pen-detectable,Foreground Colour Turquoise)<br />
Data : ’9’<br />
Set Buffer Address to (24,51)<br />
Start Field Extended (Unprotected,Alphanumeric,Intense,pen-detectable,Foreground Colour Red)<br />
Data : ’Messages ’<br />
1 2 3 4 5 6 7 8<br />
12345678901234567890123456789012345678901234567890123456789012345678901234567890<br />
>+----------------------------------------------------------------------------------+<br />
01| - |<br />
02| uSTATUS. . :uEnter one of the following: |<br />
03| u |<br />
04| uABend EXtract READPrev WAit |<br />
05| uADdress FEpi READQ WRITE |<br />
06| uALlocate FOrmattime RECeive WRITEQ |<br />
07| uASKtime FREE RELease Xctl |<br />
08| uASSign FREEMain RESetbr |<br />
09| uBif Getmain RETRieve |<br />
10| uCAncel Handle RETUrn |<br />
11| uCHange IGnore REWrite |<br />
12| uCONNect INquire SENd |<br />
13| uCONVerse ISsue SET |<br />
14| uDELAy LInk SIGNOFf |<br />
15| uDELETE LOad SIGNON |<br />
16| uDELETEQ PErform START |<br />
17| uDEQ POP STARTBr |<br />
18| uDUmp POSt SUspend |<br />
19| uENDbr PUsh SYncpoint |<br />
20| uENQ READ Unlock |<br />
21| uENTer READNext Verify |<br />
22| u |<br />
23| uPFu1-Help u2-HEX u3-End u4-EIB u5-Variables |<br />
24| u6-User u9-Messages |<br />
+----------------------------------------------------------------------------------+<br />
| 1BþC000 SKNIGHTS |<br />
+----------------------------------------------------------------------------------+<br />
12345678901234567890123456789012345678901234567890123456789012345678901234567890<br />
1 2 3 4 5 6 7 8<br />
Figure 27. Screen capture from a formatted trace file<br />
224 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
Problems with the Client daemon<br />
The formatter lists the commands which built the screen, and shows an<br />
approximation of the screen.<br />
In <strong>Version</strong> <strong>5.0</strong> of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the Binary Trace Formatter utility<br />
has been enhanced to format SNA and MPTN data structures within TCP62<br />
data flows.<br />
Client daemon trace analysis<br />
The Client daemon trace file records detailed information on all actions taken<br />
during the execution of a particular activity. You can use this information in<br />
your problem determination activities, and to help understand how the Client<br />
daemon performs a particular function, for example, establishing a connection<br />
to a <strong>CICS</strong> server.<br />
If you cannot interpret the trace yourself, you should contact your IBM<br />
support organization and forward the unformatted binary trace file.<br />
Some sample traces are shown in “Sample Client daemon trace” on page 226.<br />
Format of trace entries<br />
The entries in the Client daemon trace file have the following format:<br />
time [process id,thread id] [number] component trace message<br />
data<br />
where:<br />
time<br />
The time the entry was written, to millisecond accuracy.<br />
[process id, thread id]<br />
Process id is a unique number that the operating system uses to identify a<br />
process. Thread id is a unique number that the operating system uses to<br />
identify a thread within a particular process.<br />
[number]<br />
A number to aid your support organization in the diagnosis of serious<br />
problems.<br />
[component]<br />
The component of the product to which this entry applies.<br />
trace message<br />
The trace message number and text. These trace messages are explained in<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages.<br />
data<br />
Some trace entries include a dump of key data blocks in addition to the<br />
trace message.<br />
Chapter 14. Problem determination and problem solving 225
Problems with the Client daemon<br />
Sample Client daemon trace: Figure 28 shows the trace information recorded<br />
during the successful connection of a Client daemon to a <strong>CICS</strong> server using<br />
the TCP/IP protocol. The trace was generated using the commands:<br />
<strong>CICS</strong>CLI -s=cicstcp -d<br />
<strong>CICS</strong>CLI -o<br />
The trace was generated for an AIX Client daemon but is applicable to other<br />
Client daemons.<br />
17:03:57.580 [0000080c,00000908] [1007] TRC:▌CCL1042▐ *** <strong>CICS</strong> Client for AIX v<strong>5.0</strong> Service Level 00 - service trace started ***<br />
17:03:57.590 [0000080c,00000908] [2183] CCL:▌CCL2048▐ Maximum trace data size set to 512<br />
17:03:57.600 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:03:58.612 [0000080c,00000908] [2030] CCL:CCL2106 Comms Event : LINK-UP<br />
17:03:58.622 [0000080c,00000908] [2019] DRV:CCL2055 Connection with server established (linkID=1)<br />
17:03:58.622 [0000080c,00000908] [2035] CCL:CCL2109 Send server TCS data<br />
17:03:58.632 [0000080c,00000908] [3214] CCL:▌CCL3251▐ Comms Allocate request (LinkId=1, Tran=’CCIN’)<br />
17:03:58.632 [0000080c,00000908] [3217] CCL:▌CCL3238▐ Comms Allocate completed (LinkId=1, ConvId=1, Rc=0)<br />
17:03:58.632 [0000080c,00000908] [2127] CCL:CCL2143 CommsBegin - OK<br />
17:03:58.632 [0000080c,00000908] [3100] CCL:▌CCL3113▐ CCIN install request: ApplId=’* ’, Codepage=819<br />
...<br />
...<br />
...<br />
17:04:00.625 [0000080c,00000908] [3102] CCL:▌CCL3114▐ CCIN install response: ApplId=’@0Z8AAAA’, Codepage=8859-1, Rc=0<br />
17:04:00.625 [0000080c,00000908] [3241] CCL:CCL3255 Comms Complete request (ConvId=1)<br />
17:04:00.635 [0000080c,00000908] [3244] CCL:CCL3246 Comms Complete completed (ConvId=1, Rc=0)<br />
17:04:00.635 [0000080c,00000908] [3218] CCL:CCL3252 Comms Deallocate request (ConvId=1)<br />
17:04:00.645 [0000080c,00000908] [3221] CCL:CCL3239 Comms Deallocate completed (ConvId=1, Reason=0, Rc=0)<br />
17:04:00.645 [0000080c,00000908] [2042] CCL:CCL2114 Processed TCS Reply - Server connected<br />
17:04:00.645 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:04:00.655 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:04:00.664 [0000080c,00000908] [1004] TRC:▌CCL1043▐ *** Service trace ended ***<br />
Figure 28. Sample Client daemon trace<br />
Message ID Explanation<br />
CCL1042 Start of trace message. The trace file is overwritten each time a<br />
trace is started. You can delete the file when required. Check<br />
the date and time stamp to ensure that you are reading the<br />
correct trace.<br />
CCL2048 Maximum trace data size is at the default size of 512 bytes.<br />
You can modify this size by specifying the size value in the<br />
start command for the client trace (see “Starting and stopping<br />
Client daemon tracing” on page 220).<br />
CCL3251 The client sends a CCIN transaction to the server to install its<br />
connection definition on the server.<br />
CCL3238 Reply to message CCL3238, includes the conversation ID for<br />
this conversation.<br />
CCL3113 The client sends a CCIN transaction to the server with Appl<br />
ID set to * to install its application. The Appl ID is specified in<br />
226 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
the configuration file as Client=*. This requests the server to<br />
dynamically generate an Appl ID that is unique within the<br />
<strong>CICS</strong> server system.<br />
CCL3114 This is the response to message CCL3114 with the<br />
dynamically generated Appl ID.<br />
CCL1043 End of trace message.<br />
Figure 29 shows trace information recorded when we tried to connect to a<br />
<strong>CICS</strong> server over TCP/IP using an invalid port number. The port number<br />
specified in the CTG.INI file was not defined in the services file of the server.<br />
Hence, the connection could not be established.<br />
16:16:41.562 [0000093c,000008ec] [1007] TRC:CCL1042 *** <strong>CICS</strong> Client for Windows v<strong>5.0</strong> Service Level 00 - service trace started ***<br />
16:16:41.572 [0000093c,000008ec] [2183] CCL:CCL2048 Maximum trace data size set to 512<br />
16:16:41.582 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
16:16:41.612 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is -1 seconds<br />
16:16:41.622 [0000093c,000008ec] [3207] CCL:CCL3429 Comms Open request (Server=<strong>CICS</strong>TCP, Driver=CCLIBMIP)<br />
16:16:41.622 [0000093c,000008ec] [4408] DRV:CCL4413 ▌CCL4413▐ TCP/IP (to <strong>CICS</strong>TCP) address=192.113.36.200, ▌port=1089▐, socket=3<br />
16:16:41.622 [0000093c,000008ec] [3210] CCL:CCL3236 Comms Open completed (Server=<strong>CICS</strong>TCP, LinkId=1, Rc=0)<br />
16:16:41.633 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 3660 seconds<br />
16:16:41.633 [0000093c,000008ec] [1004] TRC:CCL1043 ***Service trace ended ***<br />
Figure 29. Client daemon trace: using an invalid port number<br />
Problems with the Client daemon<br />
Message ID Explanation<br />
CCL4413 Shows the port number used for this connection request.<br />
You must check your definitions in the SIT on the server, the configuration file<br />
on the workstation, and the services file for the port number specified.<br />
You must provide a valid port number or use the default value.<br />
Diagnosing common problems: Client daemon<br />
This section provides information to help you solve some common problems<br />
with the Client daemon. The problems are discussed under the following<br />
headings:<br />
v “Starting clients and terminals” on page 228<br />
v “TCP/IP communication problems” on page 228<br />
v “APPC communication problems” on page 229.<br />
v “TCP62 communication problems” on page 230<br />
v “Traps” on page 230<br />
v “The Client daemon stops responding” on page 232<br />
This section lists problems for all supported operating systems, to provide for<br />
cases where client and server are on different operating systems.<br />
For information on error messages, refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong><br />
Messages.<br />
Chapter 14. Problem determination and problem solving 227
Diagnosing common problems: Client daemon<br />
Starting clients and terminals<br />
The following are solutions to problems that can occur when starting clients<br />
and terminals:<br />
A <strong>CICS</strong>TERM request has gone to the wrong server<br />
If you do not specify the -s=servername option on the <strong>CICS</strong>TERM command,<br />
the Client daemon sends a <strong>CICS</strong>TERM request to either of:<br />
v the default server<br />
v the first server listed in the configuration file<br />
even if it is not yet activated. The servername should be as specified in the<br />
configuration file.<br />
Problems loading protocol drivers<br />
The message ″Cannot load protocol driver″ in the <strong>CICS</strong>CLI.LOG file means that<br />
you are trying to use a protocol driver that does not exist. Check your<br />
CTG.INI file to make sure that the driver name is correct, and is supported in<br />
this release.<br />
The Client daemon can connect to the server, but <strong>CICS</strong>TERM cannot<br />
In other words, <strong>CICS</strong>CLI -s=servername connects successfully, but <strong>CICS</strong>TERM<br />
-s=servername does not. Check the following:<br />
v Is the CTIN transaction defined on the server?<br />
v Does <strong>CICS</strong>TERM-a successfully install a terminal that is not signon capable?<br />
<strong>CICS</strong>TERM attempts to install a signon capable terminal by default. If the<br />
-a option works, the server probably does not support signon capable<br />
terminals.<br />
<strong>CICS</strong> servers require APAR fixes to support terminal signon capability; see<br />
“Supported software” on page 22. Refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
README file for the latest details and check the PTFs for the <strong>CICS</strong> servers.<br />
See “APARs and fixes” on page 239 for general information about APARs.<br />
TCP/IP communication problems<br />
The following are solutions to problems that can occur when communicating<br />
over TCP/IP:<br />
A Client daemon running on Windows cannot load the TCP/IP protocol<br />
driver<br />
You have probably received message CCL3229E in a pop-up window and<br />
message CCL3247 in the <strong>CICS</strong>CLI.LOG error log file. These messages indicate<br />
228 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
you have probably specified the wrong device driver in the configuration file.<br />
For all TCP/IP communication, the Client daemon on Windows should use<br />
the CCLWNTIP driver. Any vendor offering a WINSOCK interface can use<br />
this TCP/IP driver.<br />
Message CCL4404 TCP/IP (to ’<strong>CICS</strong>TCP’) unable to resolve name: RC=2<br />
The <strong>CICS</strong> server, in this example <strong>CICS</strong>TCP, could not be resolved by the<br />
TCP/IP protocol driver. Ensure that your domain name server and router<br />
address information is correct, and that any names and IP addresses in the<br />
TCP/IP ETC\HOSTS file are correct.<br />
Use the TCP/IP ping or nslookup commands to see if TCP/IP can resolve the<br />
hostname.<br />
APPC communication problems<br />
The following are solutions to problems that can occur when communicating<br />
over APPC:<br />
CCIN not recognized, CTIN not recognized<br />
Diagnosing common problems: Client daemon<br />
The CCIN transaction installs your Client daemon definition on the <strong>CICS</strong><br />
server. The CTIN transaction installs your client terminal definition on the<br />
<strong>CICS</strong> server. These transactions must be available on the <strong>CICS</strong> server if it<br />
supports the EPI, because the EPI implies <strong>CICS</strong> 3270 terminal emulation and<br />
<strong>CICS</strong> 3270 printer emulation. For information on which <strong>CICS</strong> servers support<br />
EPI and hence <strong>CICS</strong> 3270 emulation, see Table 5 on page 27. You can ignore<br />
these messages if your <strong>CICS</strong> server does not support the EPI.<br />
A <strong>CICS</strong>TERM command for a mainframe <strong>CICS</strong> server failed<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRNT use <strong>CICS</strong> 3270 emulation. Some mainframe <strong>CICS</strong><br />
servers do not support <strong>CICS</strong> 3270 emulation. For information on which <strong>CICS</strong><br />
servers support <strong>CICS</strong> 3270 emulation, see Table 5 on page 27.<br />
Automatic transaction initiation against a Client daemon terminal<br />
does not work<br />
Different products provide different APPC implementations for handling<br />
inbound attaches. Therefore for the Client daemon using IBM eNetwork<br />
Communications Server, Microsoft SNA Server, and IBM eNetwork Personal<br />
Communications, you must predefine the CRSR attach program to relay the<br />
information to the Client daemon. This is necessary to enable the <strong>CICS</strong> server<br />
to perform automatic transaction initiation (ATI) against the Client daemon<br />
terminals. (As long as the <strong>CICS</strong> server supports <strong>CICS</strong> 3270 terminal<br />
emulation, see Table 5 on page 27.)<br />
Chapter 14. Problem determination and problem solving 229
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: Client daemon<br />
For the Client daemon therefore, you must define the inbound attach<br />
transaction CRSR as follows:<br />
A Client daemon running on Windows and using IBM eNetwork<br />
Communications Server<br />
Define CRSR to use program CCLCLNT.EXE. See “IBM<br />
eNetwork Communications Server” on page 46.<br />
A Client daemon running on Windows and using IBM eNetwork Personal<br />
Communications<br />
Define CRSR to use program CCLCLNT.EXE. See “IBM<br />
eNetwork Personal Communications” on page 48.<br />
SNA error log: The SNA error log can help your support organization to<br />
diagnose problems. The path to the file, if the product is installed to its<br />
default location, is as follows: c:\program files\Personal<br />
Communications\pcwmsg.mlg<br />
TCP62 communication problems<br />
CCL5820 TCP62: Attempt to open server ’server1’ which is a<br />
duplicate of ’server2’<br />
Multiple server definitions with identical combinations of Local LU, Partner<br />
LU, and Mode name are not permitted in CTG.INI in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>. This ensures that every connection that the <strong>CICS</strong> region<br />
and the network protocol see is represented by a unique server definition in<br />
the configuration file. Existing Client applications that use different server<br />
names to send requests to the same <strong>CICS</strong> region continue to work if a user<br />
exit is defined to redirect requests. A sample user exit that does this is<br />
provided; see \samples\samples.txt.<br />
Traps<br />
Dr. Watson<br />
On Windows systems, the Dr. Watson tool can supply useful information<br />
in the event of an operating system trap. It attempts to produce a stack of<br />
trace exceptions. Dr. Watson is the program error debugger supplied with<br />
Windows. Refer to the product documentation for full instructions on how<br />
to install and use it. What follows is an example of how to run Dr. Watson<br />
and use the information supplied.<br />
1. Run file %windir%\system32\drwtsn32.exe. This opens a window that<br />
allows you to configure Dr. Watson.<br />
v The log file path defaults to %windir%.<br />
v A crash dump is a binary system dump, and can be large. Clear<br />
the Create Crash Dump File checkbox if you do not want a binary<br />
system dump.<br />
230 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Diagnosing common problems: Client daemon<br />
2. Leave Dr. Watson running, and recreate the trap scenario.<br />
3. When a window appears saying that a trap has occurred, press<br />
cancel to debug the application.<br />
4. Click OK when prompted, to create the log file.<br />
5. You can now open the log file (drwtsn32.log) to determine which<br />
process trapped.<br />
6. Near the top of the log are entries that give the process id (pid) of<br />
the trapping process:<br />
*----> System Information Task List
|<br />
|<br />
|<br />
Diagnosing common problems: Client daemon<br />
10. The task list shows which tasks were running at the time the trap<br />
occurred, and shows which address of memory they were loaded<br />
into. You can cross-reference this with the fault address to work out<br />
which file the trap occurred in.<br />
The Client daemon stops responding<br />
This section discusses what to do if you think the Client daemon has stopped<br />
responding, for example because:<br />
v API, ECI and EPI calls do not complete, or<br />
v <strong>CICS</strong>TERM hangs<br />
Check that your <strong>CICS</strong> <strong>Transaction</strong> Server is working correctly, for example by<br />
looking at the <strong>CICS</strong> log. Insufficient storage on the <strong>CICS</strong> region may cause<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to hang.<br />
To test whether <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has stopped responding, issue<br />
<strong>CICS</strong>CLI -l from the command line. If the call hangs then <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> is not responding. See “If a process locks” on page 213, for<br />
information on what to do if the <strong>Gateway</strong> daemon is not responding.<br />
Try to reproduce the problem with tracing turned on. Take a client trace with<br />
as many components as possible active. As a minimum you need the API,<br />
DRV and CCL tracepoints; add TRN if possible. (Use trace wrapping if you<br />
do not want the trace file to get too large; see “Tracing” on page 209.) The<br />
summary trace shows whether the client or user application has stopped<br />
responding, and gives an indication as to whether the problem is in the client<br />
or server.<br />
If you can reproduce the problem, have details of how to reproduce it<br />
available for your support organization. If you cannot reproduce the problem,<br />
have available details of the circumstances that led up to the hang, for<br />
example:<br />
v Does it hang only when the system is under heavy load?<br />
v Does it hang only when there are many concurrent users?<br />
v Does it hang only under a particular configuration, or after a known<br />
sequence of events?<br />
<strong>CICS</strong> server problem determination<br />
The most important facilities for problem determination on <strong>CICS</strong> servers are:<br />
v Traces<br />
– auxiliary<br />
– internal<br />
v Dumps<br />
v <strong>CICS</strong> message logs<br />
v Statistics information<br />
232 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
v Monitoring information<br />
v Execution diagnostic facility (EDF)<br />
v <strong>CICS</strong>-supplied transactions, CEBR and CECI<br />
v Independent software vendor (ISV) tools<br />
<strong>CICS</strong> server problem determination<br />
Information about these facilities is given in the Problem Determination books<br />
for the individual products (see “<strong>CICS</strong> <strong>Transaction</strong> Server publications” on<br />
page 267). You may need to contact the server system administrator for more<br />
information, for example, about a <strong>CICS</strong> server error log.<br />
The following shows the error message prefixes for <strong>CICS</strong> products:<br />
CCL <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> Universal Client<br />
FAA <strong>CICS</strong> for OS/2<br />
DFH <strong>CICS</strong> on System/390 ® and z/OS<br />
ERZ <strong>Transaction</strong> Server for Windows NT <strong>Version</strong> 4.0, and TXSeries<br />
AEG <strong>CICS</strong> for OS/400.<br />
Communication problem determination<br />
Even a small telecommunications network is a very complex system in which<br />
all components depend on one another. If one component fails and presents<br />
incorrect information to the other components, the latter may fail even more<br />
severely than the former. Sometimes the failure may be considerably delayed,<br />
and the error indicator may be lost before the error is detected. Thus, it is<br />
sometimes very difficult to analyze a problem in the communication part of a<br />
system.<br />
The Client daemon generates various messages associated with the use of the<br />
supported communication protocols and the associated products. Refer to<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for a list of these messages and<br />
their explanations.<br />
The communication products themselves generate error messages. For details<br />
of these, and information on troubleshooting, you should refer to the<br />
documentation for the communication product. The following sections<br />
summarize useful commands and utilities for problem determination.<br />
TCP/IP-providing products: TCP/IP provides the following diagnostic tools:<br />
ARP Displays and modifies the IP-to-Ethernet or<br />
token ring physical address translation tables<br />
used by address resolution protocol (ARP).<br />
HOSTNAME Displays the host name of your workstation.<br />
IPCONFIG Displays all current TCP/IP network<br />
Chapter 14. Problem determination and problem solving 233
Communication problems<br />
configuration values. This is helpful if you<br />
have to find out if an IP interface is active.<br />
NETSTAT Displays protocol statistics and current<br />
TCP/IP network connections. This helps you<br />
obtain information about your own IP<br />
interfaces, for example, to list IP addresses<br />
and TCP/IP routing tables in use at your<br />
workstation.<br />
NSLOOKUP Displays information from Domain Name<br />
System (DNS) name servers.<br />
PING Verifies connections to a remote computer or<br />
computers.<br />
TRACERT Traces the TCP/IP path to a requested<br />
destination. It is useful for determining<br />
whether there is a problem with one of the<br />
intermediate nodes.<br />
For more information on these utilities, refer to the online help for TCP/IP.<br />
APPC-providing products: This section describes problem determination in<br />
products involved in APPC communication.<br />
VTAM Buffer Trace: You can use VTAM buffer tracing to record the flow of<br />
data between logical units in the <strong>CICS</strong> environment. The trace entries include<br />
the netname of the terminal (logical unit) to which they relate. For details on<br />
VTAM buffer tracing and other VTAM problem determination functions, see<br />
the appropriate book in the VTAM library.<br />
SNA Server: See the Microsoft SNA Server Administration Guide for information<br />
on diagnostic tools that you can use with SNA Server.<br />
The APING utility: In an APPC environment, you can use the APING utility<br />
to test a connection. APING exchanges data packets with a partner computer<br />
over APPC and times how long the data transfer takes. It can be used to get a<br />
first estimate of the session setup time between two computers and the<br />
throughput and turnaround time on that APPC session. You can use APING<br />
to determine whether a session can be set up between two computers and to<br />
display extensive error information if session allocation fails. APING consists<br />
of two transaction programs: APING, which runs on the client side, and<br />
APINGD, which runs on the server side.<br />
Checking client and host configuration: If the SNA product on the Client<br />
daemon machine, and the host are both correctly configured, you should be<br />
234 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
able to activate the connection between them. Follow the steps below to<br />
activate the connection; you do not need to start the client first.<br />
1. Start the node on the SNA product on the Client daemon machine.<br />
2. Use the CEMT transaction to acquire the connection. Type CEMT I CON. The<br />
screen will look similar to this:<br />
I CON<br />
STATUS: RESULTS - OVERTYPE TO MODIFY<br />
Con(SIMD) Net(PYKS88BA) Ins ▌Rel▐ Vta Appc<br />
Con(SYSB) Net(IYCKZCCV) Ins Rel Vta Appc<br />
SYSID=SYSA APPLID=IYCKZCCU<br />
RESPONSE: NORMAL TIME: 12.2<strong>5.0</strong>4 DATE: 03.01.01<br />
PF 1 HELP 3 END 5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 SF<br />
3. Overtype ▌Rel▐ with ACQ, to acquire the connection.<br />
Communication problems<br />
If you cannot acquire the connection, SNA is wrongly configured on the<br />
product or the host.<br />
IBM Communications Server for Windows NT and Windows 2000: IBM<br />
Communications Server writes a log file called pcwmsg.mlg, which can help to<br />
diagnose communications errors. Because it is a text file, you can view it in<br />
any text editor, or you can use the supplied Communications Server Log Viewer<br />
utility. The viewer includes online help.<br />
Use the supplied Getsense utility to understand error messages that contain<br />
sense codes.<br />
Your IBM support organization will need the log file if you have SNA errors<br />
that you cannot resolve. They may also ask you for a trace. To turn trace on,<br />
select the Communications Server Trace Facility. The trace facility has options to<br />
start and stop the trace, save it, and format it to a text file. IBM support will<br />
probably ask you to trace these components:<br />
Function Component Trace options<br />
APPN ® and APPC Nof API Verb trace up to 128 bytes<br />
APPC API Verb trace up to 128 bytes<br />
Connectivity (Your network type) Verb trace up to 128 bytes<br />
For more details, see your IBM Communications Server documentation.<br />
Chapter 14. Problem determination and problem solving 235
Program Support<br />
Program support<br />
If you need to contact your IBM support organization, first refer to the Service<br />
and Support card supplied with the product for details of the support<br />
available to you, or visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Support link.<br />
This section provides guidance on reporting problems, detailing the<br />
information you should collect to assist your support organization. It also<br />
explains how the problem is handled through to resolution and the provision<br />
of a fix.<br />
Reporting problems<br />
Before reporting your problem to the support organization try to ensure that<br />
the error is actually occurring within your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system,<br />
even if you are unsure whether the problem is due to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> itself.<br />
In practice, many errors reported to support organizations turn out to be user<br />
errors, or they cannot be reproduced, indicating just how difficult it can be to<br />
determine the precise cause of a problem. User errors are mainly caused by<br />
faults in application programs or by errors in setting up systems.<br />
The ability of the support organization to resolve your problem quickly<br />
depends on the quality of the information you provide to them. For this<br />
reason it is good practice to collect and organize problem data before making<br />
the initial contact.<br />
Summarize your problem and the documentation/information you collect on<br />
a problem reporting sheet. This sheet provides a valuable summary to the<br />
support organization, and a copy will be useful for your own records.<br />
Level-1 support<br />
If this is your first contact regarding this problem a unique incident number<br />
will be assigned. A Problem Management Record (PMR) is opened on the<br />
RETAIN ® database system, where all activity associated with your problem is<br />
recorded. The PMR remains “open” until it is solved.<br />
Make a note of the incident number on your copy of the problem reporting<br />
sheet. You will be expected to quote the incident number in all future<br />
correspondence relating to this problem.<br />
Your initial communication with the support organization is through a Level-1<br />
representative, who uses the keywords that you have provided to search the<br />
RETAIN database for problems with similar symptoms. If your problem is<br />
236 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Program Support<br />
found to be one already known to the support organization, and a fix has<br />
been devised for it, you will be advised of the availability of corrective service<br />
software that you can install to overcome the problem, as described in<br />
“Obtaining the fix” on page 240. If the RETAIN search is unsuccessful, the<br />
problem is passed on to a Level-2 representative who will contact you for<br />
more information about your problem, to start a more detailed investigation<br />
of the cause.<br />
Level-2 support<br />
Let the Level-2 representative know if any of the following events occurred<br />
before the problem appeared:<br />
1. Changes in level of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, compiler or associated<br />
licensed programs<br />
2. Corrective service software and fixes applied to workstation software<br />
3. Problem Tracking Fixes (PTFs) applied to other associated products<br />
4. Additional features used<br />
5. Application programs changed<br />
6. Unusual operator action.<br />
At this stage you may be asked to supply more details or documentation. If<br />
this happens, the PMR is updated to show any documentation you have<br />
submitted.<br />
Based on the information you supply, the investigation then carried out can<br />
determine whether the cause of your problem is new to the support<br />
organization, or is already known.<br />
If the problem is a valid new one, an APAR may be raised, to be dealt with<br />
by the <strong>CICS</strong> service team, as described in “APARs and fixes” on page 239. If,<br />
however, the problem is already known, and a fix has been developed, you<br />
can obtain it as described in “Obtaining the fix” on page 240.<br />
Documenting problems<br />
In a communication environment, where many clients may be connected to<br />
several servers, you must obtain information from both the client and the<br />
server sides.<br />
To facilitate problem determination, try to reduce your environment to only<br />
one client workstation and one server to narrow down the range of<br />
possibilities that may cause the error.<br />
Listed below are the types of information most likely to be needed by the<br />
support organization. The list is not exhaustive; it covers the most commonly<br />
requested information.<br />
Chapter 14. Problem determination and problem solving 237
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Program Support<br />
v The version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, including details of any<br />
service releases applied.<br />
v The utility or programming language that gives the problem, for example:<br />
– ECI, EPI, ESI<br />
– C, C++, Java<br />
For languages, include the version.<br />
v The network protocols being used.<br />
v The end-to-end configuration, and product stacks at each step of the way,<br />
for example, WebSphere Application Server async ECIRequest class over<br />
SSL to ctgstart on Solaris up using TCP62 to <strong>CICS</strong> <strong>Transaction</strong> Server 2.2.<br />
v The operating system on which the problem occurs. If the Client application<br />
and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are on different operating systems, provide<br />
details of both. Details of the <strong>CICS</strong> server are also useful.<br />
v A recreate scenario, if possible.<br />
v Details of any log messages at the time the problem occurred.<br />
v A short description of the problem in terms of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
calls, including why you think it is a problem with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. For example, a specific API call hangs and never returns, or an<br />
unexpected return code on a specific API call.<br />
Locating and compiling information<br />
The advice listed below will help you compile the information required. If<br />
you are in any doubt about how to gather any of the items listed above, wait<br />
until you can seek advice from your support organization.<br />
v Try to establish which program in your system seems to be the cause of the<br />
problem. As you are reading this book, it is likely that you already believe<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to be the problem source.<br />
You also need to provide the version and release number of the product, for<br />
example <strong>Version</strong> <strong>5.0</strong>, together with the number of any PTF or other fix<br />
applied, for example UNnnnnn (where nnnnn is a valid PTF number).<br />
v Obtain Windows operating system details by using the WINVER.EXE<br />
command at a command prompt.<br />
If you are using SNA Server, you can find its version number by entering<br />
the SNAVER.EXE command.<br />
v You should find details of your compiler level on the product media labels<br />
or the associated documentation. Alternatively, check the panel displayed<br />
on the screen at compile time.<br />
v Give the problem a severity level. Severity levels have the following<br />
meanings:<br />
– Severity level 1 indicates that you are unable to use a program, resulting<br />
in a critical condition that needs immediate attention.<br />
238 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Program Support<br />
– Severity level 2 indicates that you are able to use the program, but that<br />
operation is severely restricted.<br />
– Severity level 3 indicates that you are able to use the program, with<br />
limited functions, but the problem is not critical to your overall<br />
operation.<br />
– Severity level 4 indicates that you are able to use the program with the<br />
problem causing negligible hindrance.<br />
When deciding the severity of the problem, take care to categorize it<br />
correctly, as the procedures followed by the support organization depend<br />
on the severity level supplied.<br />
v Also, try to classify the error and give a brief description of the problem.<br />
Include keywords associated with the problem, such as ABEND, WAIT,<br />
LOOP, PERFORMANCE, INCORROUT, and MESSAGE, corresponding to<br />
the problem classification types used in the RETAIN database. Strings<br />
containing other keywords are also useful. These are not predefined, and<br />
might include such items as a message or message number, an abend code,<br />
any parameters known to be associated with the problem, or, for example,<br />
STARTUP, INITIALIZATION, or TRANSIENT DATA.<br />
v Finally, you should include your address, relevant contact names, and<br />
details of the other products at your installation.<br />
Keep a copy of the problem reporting sheet which summarizes all the<br />
information relevant to the problem, together with any available<br />
documentation such as dumps, traces and output from programs, translators,<br />
and compilers.<br />
Submitting the documentation<br />
If you are asked to provide documentation, it will help the support<br />
organization during their investigation if you adhere to the following rules<br />
when preparing it:<br />
v Provide as much information as possible in softcopy format.<br />
v Write any notes and documents in English.<br />
v If you are asked to supply any additional trace output, provide an<br />
unformatted binary version, rather than the viewable output from the<br />
formatter.<br />
v If you upload files to a mainframe system, do so in binary rather than<br />
ASCII format.<br />
APARs and fixes<br />
Once a reported problem is confirmed as being both new and valid, An<br />
authorized program analysis report (APAR) is raised from the Problem<br />
Management Record (PMR) and becomes a permanent record describing your<br />
Chapter 14. Problem determination and problem solving 239
Program Support<br />
error, and in time, its solution. An APAR is the means of reporting to the<br />
appropriate product service team any problems you find with an IBM<br />
program.<br />
The APAR process<br />
The first step in the APAR process is that a Level-2 representative from the<br />
support organization enters an APAR containing a description of your<br />
problem into the RETAIN system. If you have a means of getting round the<br />
problem, details of this are entered as well. Your name is also entered, so that<br />
your support organization knows who to contact if the service team need to<br />
ask anything further about the APAR documentation.<br />
At this stage, you are given an APAR number. This number is always<br />
associated with the APAR and its resolution and, if a code change is required,<br />
is associated with the fix as well.<br />
The service team may ask for additional backup documentation, normally via<br />
the Level-2 representative. The specific documentation required will vary from<br />
problem to problem, and depends on what information has already been<br />
supplied during the PMR stage.<br />
During the investigation, you can ask your support organization at any time<br />
about how your APAR is progressing, particularly if it is a problem of high<br />
severity.<br />
Obtaining the fix<br />
When the service team has found a fix for your problem, you may be asked to<br />
test it on your system. If so, you may be sent a Program Temporary Fix (PTF)<br />
in the form of individual replacement modules. This is normally done through<br />
the Level-2 organization and feedback from your testing will be requested.<br />
Each PTF may contain several APAR fixes. If an individual APAR fix within a<br />
PTF is found to be in error, it may still be advisable to apply the PTF, to<br />
obtain the other APAR fixes.<br />
In time, formal corrective service software is made available, which you can<br />
order through your support organization. Traditionally, corrective service<br />
software has been supplied on Corrective Service Diskettes (CSD) ordered by<br />
CSD number. It may now be supplied on CD-ROM or via the Internet.<br />
Fixes for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are available from the <strong>CICS</strong> Support web<br />
page at: www.ibm.com/software/ts/cics/support/details.<br />
240 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Chapter 15. Migration<br />
This chapter deals with issues that can arise when you move from an earlier<br />
version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, or a product related to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. Topics covered include:<br />
v “Migrating from <strong>CICS</strong> Client <strong>Version</strong> 2” on page 243<br />
v “Migrating from <strong>CICS</strong> Universal Client, or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
<strong>Version</strong> 3” on page 243<br />
v “Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java” on page 244<br />
v “Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong>” on page 245<br />
v “Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes ” on page 248<br />
v “EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>”<br />
on page 248<br />
See also “Upgrading” on page 30.<br />
The configuration conversion tool<br />
The configuration conversion tool (ctgconv) converts the configuration files of<br />
versions of the following to the current format:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> v3.0<br />
v <strong>CICS</strong> Universal Client v3.0<br />
v <strong>CICS</strong> Client <strong>Version</strong> 2<br />
v <strong>CICS</strong> <strong>Gateway</strong> for Java<br />
If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> installation upgrades your<br />
existing product, the configuration conversion tool runs automatically if it<br />
finds configuration files in the old format. If you have to uninstall the earlier<br />
product first, or your configuration files cannot be found during the upgrade,<br />
run ctgconv after installation.<br />
The conversion tool converts the following:<br />
<strong>Gateway</strong>.properties<br />
Properties file of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 and <strong>CICS</strong><br />
<strong>Gateway</strong> for Java.<br />
<strong>CICS</strong>CLI.INI<br />
Client initialization file of <strong>CICS</strong> Clients <strong>Version</strong> 2 and <strong>Version</strong> 3.0.<br />
© Copyright IBM Corp. 1996, 2002 241
Migration<br />
<strong>CICS</strong>X.INI<br />
Workload Manager configuration file of <strong>CICS</strong> Universal Clients for<br />
Windows <strong>Version</strong> 3.0.<br />
The conversion tool produces one output file called CTG.INI by default.<br />
Old files are renamed with the BAK extension.<br />
Using the conversion tool<br />
The parameters of ctgconv are:<br />
ctgconv −c=file [−g=file] [−l=file] [−o=file]<br />
For each parameter, file can be any of the following:<br />
v A filename and extension; the \bin directory is assumed.<br />
The extension must be INI, except for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> 3.0 and <strong>CICS</strong> <strong>Gateway</strong> for Java input files, which have the<br />
properties extension.<br />
v A full pathname.<br />
v A directory name (without a trailing \); the default filename is assumed.<br />
−c=file<br />
Specifies the Client initialization file to be converted. If file specifies a<br />
directory, a filename of <strong>CICS</strong>CLI.INI is assumed.<br />
If the parameter is not specified, the <strong>CICS</strong>CLI environment variable is<br />
used to locate the <strong>Gateway</strong> initialization file. If <strong>CICS</strong>CLI is not set, the file<br />
<strong>CICS</strong>CLI.INI, in the \bin subdirectory, is assumed.<br />
−g=file<br />
Specifies the <strong>Gateway</strong>.properties file to be converted. If you do not<br />
specify this parameter, no <strong>Gateway</strong> section is created in CTG.INI.<br />
−l=file<br />
Specifies the Workload Manager configuration file to be converted. If you<br />
specify a directory, the filename <strong>CICS</strong>X.INI is assumed. If you do not<br />
specify this parameter, the <strong>CICS</strong>X_CONFIG_URL environment variable is<br />
used to locate the file. If this environment variable is not set, the default<br />
file in the \bin subdirectory is assumed.<br />
If no Workload Manager configuration file exists, no Workload Manager<br />
section is created in CTG.INI.<br />
−o=file<br />
Specifies the pathname of the converted file. The default is CTG.INI, inthe<br />
\bin subdirectory.<br />
For help on using ctgconv, enter ctgconv −?<br />
242 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
During conversion, the input files are renamed so that the last three characters<br />
of the file extension become BAK. Any file with that name is overwritten, and<br />
any output file that exists before the conversion is renamed in the same way.<br />
A banner is inserted into the renamed files stating that they are obsolete.<br />
Redundant parameters are removed from the old configuration files, and<br />
other parameters are given new names in the converted file.<br />
Migrating from <strong>CICS</strong> Client <strong>Version</strong> 2<br />
You might have customized versions of the following configuration files:<br />
File Default Name<br />
Keyboard mapping file <strong>CICS</strong>KEY.INI<br />
Color mapping file <strong>CICS</strong>COL.INI<br />
Window settings <strong>CICS</strong>TERM.INI<br />
Follow these steps:<br />
1. Take a copy of any customized configuration files, including <strong>CICS</strong>CLI.INI<br />
2. Delete <strong>CICS</strong> Client <strong>Version</strong> 2.<br />
3. Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong><br />
4. Run the configuration conversion tool (ctgconv) to convert <strong>CICS</strong>CLI.INI to<br />
the new format; see “The configuration conversion tool” on page 241.<br />
Migrating from <strong>CICS</strong> Universal Client, or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, <strong>Version</strong> 3<br />
The following are not supported:<br />
v PL/I<br />
v REXX<br />
v <strong>CICS</strong>TELD<br />
v Windows ® 95, Windows 98, OS/2 ®<br />
v 16-bit applications<br />
v NetBIOS and DCE protocols<br />
v IBM VisualAge C++ for Windows<br />
v Novell Netware for SAA ®<br />
v The <strong>CICS</strong>CLI -f parameter<br />
Migration<br />
TCP62 multiple server definitions<br />
Multiple server definitions with identical combinations of Local LU, Partner<br />
LU, and Mode name are not permitted in CTG.INI in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>. This ensures that every connection that the <strong>CICS</strong> region<br />
and the network protocol see is represented by a unique server definition in<br />
Chapter 15. Migration 243
|<br />
|<br />
|<br />
|<br />
Migration<br />
the configuration file. Existing Client applications that use different server<br />
names to send requests to the same <strong>CICS</strong> region continue to work if a user<br />
exit is defined to redirect requests. A sample user exit that does this is<br />
provided; see \samples\samples.txt.<br />
You might have customized versions of the following configuration files:<br />
File Default Name<br />
Keyboard mapping file <strong>CICS</strong>KEY.INI<br />
Color mapping file <strong>CICS</strong>COL.INI<br />
Windows settings <strong>CICS</strong>TERM.INI<br />
When you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> your customized files<br />
are preserved, even though <strong>CICS</strong> Universal Client <strong>Version</strong> 3.0 is deleted.<br />
In <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> the configuration file (CTG.INI),<br />
replaces the Client initialization file (<strong>CICS</strong>CLI.INI).<br />
The new file also replaces the Workload Manager configuration file, and the<br />
<strong>Gateway</strong>.properties file.<br />
These files are automatically converted to the correct format when you install<br />
<strong>Version</strong> <strong>5.0</strong>, if the files are found on upgrade.<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java<br />
1. Take a copy of your <strong>Gateway</strong>.properties file.<br />
2. Delete the <strong>CICS</strong> <strong>Gateway</strong> for Java.<br />
3. Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>.<br />
4. Use the configuration conversion tool to convert your <strong>Gateway</strong>.properties<br />
file; see “The configuration conversion tool” on page 241.<br />
Change all import statements in your programs and recompile them. Change<br />
all occurrences of:<br />
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*<br />
import ibm.cics.jgate.epi.* to: import com.ibm.ctg.epi.*<br />
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*<br />
Modify any programs written for the <strong>CICS</strong> <strong>Gateway</strong> for Java prior to <strong>Version</strong><br />
2.0.1 that use the Session interface. This is because the parameter to the<br />
Session.handleReply method was changed to TerminalInterface instead of a<br />
Terminal object. Change and then recompile your programs.<br />
244 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user<br />
classes that implement these methods need to be changed. The TCP/IP<br />
address of the remote computer is now passed to the methods called to<br />
generate handshake data. An afterDecode method has also been added to<br />
both interfaces. See Programming in Java, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide, for more information.<br />
Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong><br />
This section describes how to migrate from using the <strong>CICS</strong> Internet <strong>Gateway</strong><br />
to using the Terminal Servlet.<br />
Read Chapter 13, “The Terminal Servlet program” on page 187 before you<br />
perform migration, to familiarize yourself with the concepts of the Terminal<br />
Servlet.<br />
The <strong>CICS</strong> Internet <strong>Gateway</strong> reads settings from a configuration file, which is<br />
called cigd.ini.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> default settings<br />
Migration<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> Terminal Servlet equivalent<br />
Cursor The Cursor key equivalent. There is no<br />
equivalent setting for the Terminal Servlet.<br />
Instead, you can use JavaScript to set the<br />
position of the cursor. To allow this, set the<br />
servlet property screen@cursoring to true.<br />
Info Filename for the information file for the server<br />
(for AIX and Windows NT). There is no<br />
equivalent setting for the Terminal Servlet.<br />
Error Filename for the error file for the server. There<br />
is no equivalent setting for the Terminal<br />
Servlet.<br />
Trace Filename for the trace file for the server. There<br />
is no equivalent setting for the Terminal<br />
Servlet. Servlets write logging information to<br />
the servlet log provided by the Web server.<br />
See your Web server documentation to find<br />
out where this file is. If trace is turned on it is<br />
written to the standard output. Depending on<br />
your Web server, this may be directed to a file.<br />
MaxUsers The maximum number of users. The<br />
equivalent servlet property is<br />
pool@maxTerminals.<br />
Chapter 15. Migration 245
Migration<br />
TimeOut<strong>CICS</strong> The “Wait for <strong>CICS</strong> ” timeout. The servlet<br />
property servlet@allocateTimeout limits the<br />
time that the servlet will wait for a terminal to<br />
be connected to <strong>CICS</strong>. There is no limit on the<br />
time the servlet will wait for <strong>CICS</strong> to respond<br />
in other situations.<br />
TimeOut<strong>Gateway</strong> The “Wait for <strong>Gateway</strong>” timeout. There is no<br />
equivalent setting for the Terminal Servlet.<br />
TimeOutInternet The “Wait for Internet” timeout. The servlet<br />
property pool@idleTimeout limits the time<br />
that the servlet will let a terminal be unused<br />
before it is disconnected.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> override settings<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> Terminal Servlet equivalent<br />
AutoExit Normally, the Terminal Servlet does not<br />
disconnect the terminal when a transaction<br />
ends. If this is the behavior you want, set the<br />
page mapping property page@idle to the URL<br />
/servlet/TerminalServlet?request=disconnect,<br />
replacing TerminalServlet with the name of an<br />
instance of the Terminal Servlet on your Web<br />
server.<br />
ExitAid The Exit key equivalent. The servlet uses<br />
Screen Handler beans to exit running<br />
transactions. You can generate and customize<br />
Screen Handler beans for specific <strong>CICS</strong><br />
screens, and you can create a default Screen<br />
Handler that knows how to exit a range of<br />
transactions. The supplied sample<br />
DefaultScreenHandler exits using the AID PF3.<br />
ExitPage The URL for the HTML exit page. Use the<br />
page mapping property page@disconnected to<br />
specify a page to be displayed when the<br />
terminal is disconnected.<br />
ImbedHTML Allows Imbedded HTML. The servlets default<br />
behavior is to write out the contents of <strong>CICS</strong><br />
screens as is, that is, text taken from the <strong>CICS</strong><br />
screen is assumed to be correct HTML. If the<br />
characters , or & are present on the <strong>CICS</strong><br />
screen, this may cause problems. To translate<br />
the characters , and & to < > and<br />
& respectively, set the request parameter<br />
246 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Migration<br />
translateText to true. No translation is<br />
performed when sending data to <strong>CICS</strong>.<br />
Header The filename for the HTML header. There is<br />
no equivalent setting for the Terminal Servlet.<br />
Trailer Filename for the HTML trailer. There is no<br />
equivalent setting for the Terminal Servlet.<br />
GraphicKeys Display the keys as GIFs. There is no<br />
equivalent setting for the Terminal Servlet.<br />
PAKeys Display the PA keys. There is no equivalent<br />
setting for the Terminal Servlet.<br />
PFKey24 Display extra row of PF keys. There is no<br />
equivalent setting for the Terminal Servlet.<br />
Output from the Terminal Servlet is inserted<br />
into a Web page that you provide. The sample<br />
file epissam1.shtml is provided as a starting<br />
point.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> actions<br />
The <strong>CICS</strong> Internet <strong>Gateway</strong> is invoked by an HTML form. To invoke the<br />
Terminal Servlet instead, change the action to /servlet/servlet where<br />
servlet is TerminalServlet or another name.<br />
Query the current gateway settings<br />
You can query the various servlet properties individually. See<br />
“Displayable properties” on page 205 for details.<br />
List the available <strong>CICS</strong> systems<br />
The servlet does not provide this function. Each Terminal Servlet<br />
instance can connect to only one <strong>CICS</strong> server. You should configure an<br />
instance of Terminal Servlet for each <strong>CICS</strong> server that you want to<br />
allow users to connect to.<br />
Start a transaction<br />
You must add a hidden element setting the name ″request″<br />
to the value ″send″, as in Table 10<br />
Table 10. Terminal Servlet equivalents of actions<br />
<strong>CICS</strong> Internet <strong>Gateway</strong><br />
element name<br />
Terminal Servlet equivalent<br />
SystemName None<br />
TranName transaction<br />
TranData transactionData<br />
AutoExit page@idle=/servlet/TerminalServlet?request=disconnect<br />
is equivalent to AutoExit=On<br />
Chapter 15. Migration 247
|<br />
|<br />
|<br />
|<br />
|<br />
Migration<br />
Table 10. Terminal Servlet equivalents of actions (continued)<br />
<strong>CICS</strong> Internet <strong>Gateway</strong><br />
element name<br />
Terminal Servlet equivalent<br />
ExitAID None<br />
ExitPage page@disconnected<br />
ImbedHTML translateText=true is equivalent to ImbedHTML=Off<br />
Anything else None<br />
See “Properties and parameters reference” on page 200 for more information.<br />
Administration functions<br />
You can query the number of terminals that are in use and turn trace on and<br />
off. However, these functions cannot be restricted to administrators.<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes <br />
<strong>CICS</strong> Clients <strong>Version</strong> 2 included the <strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes, also<br />
known as <strong>CICS</strong> Link for Lotus. This is not available in <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>.<br />
For inter-operation of <strong>CICS</strong> and Lotus Notes ® , IBM recommends that you use<br />
the MQSeries ® Enterprise Integrator, which offers these advantages over the<br />
<strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes:<br />
v A common API that you can use to integrate Lotus Notes with IMS or<br />
MQSeries as well as <strong>CICS</strong><br />
v Support for the EPI and ECI<br />
v Use it straight from a Web browser connected to Lotus Domino<br />
MQSeries Enterprise Integrator is included in MQSeries and <strong>CICS</strong><br />
Connections for Domino. For more information, visit the Web site at:<br />
www.lotus.com/<br />
and follow the Products link.<br />
EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
These beans, which previously were provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product, are now included with the set of sample programs:<br />
v EPIMonitor<br />
v EPIScreenButtons<br />
v EPIBasicScreenHandler<br />
248 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
Migration<br />
Include the archive \classes\ctgsamples.jar in the classpath<br />
of any programs that use these beans. The EPIBasicScreenHandler bean<br />
includes new functions, such as font and color selection, and an improved<br />
layout.<br />
Chapter 15. Migration 249
250 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Appendix A. Data conversion between the Client daemon<br />
and a <strong>CICS</strong> server<br />
The ECI and EPI allow non-<strong>CICS</strong> applications running in a client system to<br />
gain access to <strong>CICS</strong> facilities and data managed by a <strong>CICS</strong> server system.<br />
Character data may have to be converted as it is passed between client and<br />
server; for example data is encoded in ASCII on a client system and in<br />
EBCDIC on a <strong>CICS</strong>/390 server system. Data conversion is performed by the<br />
server system.<br />
The possible ASCII and EBCDIC encoding schemes are described in detail in<br />
SC09-2190, the Character Data Representation Architecture Reference and<br />
Registry (CRDA). In summary, each encoding scheme is identified by a Coded<br />
Character Set Identifier (CCSID) which defines a set of graphic characters and<br />
the Code Page Global Identifier (CPGID) which specifies the code points used<br />
to represent the graphic characters.<br />
The data managed by the server system may be accessed from several client<br />
systems each of which uses a different ASCII encoding scheme. To support<br />
such access, each client system must be able to supply a CCSID ’tag’ in order<br />
that the data is converted correctly.<br />
Data conversion on Windows<br />
The ASCII CCSID is determined dynamically. By default the GetOEMCP<br />
function is used to obtain the current OEM code page identifier, for example<br />
CCSID 850, for the system. If the Use OEM codepage configuration setting is<br />
specified, the GetACP function is used to obtain the current ANSI code page<br />
identifier, for example CCSID 1252, for the system.<br />
The identifier may not be unique. For example, there are differences between<br />
IBM CCSID 932 and Microsoft CCSID 932 - the Client daemon maps the<br />
Microsoft one to CCSID 943 which is the equivalent one defined in the CRDA<br />
Registry. The Microsoft CCSID 1252 may be the pre-euro or post-euro version<br />
- the post-euro is mapped to CCSID 5348.<br />
© Copyright IBM Corp. 1996, 2002 251
Data conversion<br />
Supported conversions<br />
The method used to perform data conversion depends on the server platform.<br />
The range of data conversions supported also depends on the platform. The<br />
following table has been extracted from Communicating from <strong>CICS</strong> on<br />
System/390, SC33-1697. ASCII and EBCDIC CCSIDs are assigned to geographic<br />
or linguistic groups.<br />
Data conversion is supported between ASCII and EBCDIC where both<br />
CCSIDs belong to the same group. The intent is that other <strong>CICS</strong> servers will<br />
provide equivalent support.<br />
Arabic:<br />
CCSID CPGID<br />
ASCII 00864 00864 PC data: Arabic<br />
01089 01089 ISO 8859-6: Arabic<br />
01256 01256 MS Windows: Arabic<br />
EBCDIC 00420 00420 Host: Arabic<br />
Baltic Rim:<br />
CCSID CPGID<br />
ASCII 00921 00921 PC data: Latvia, Lithuania<br />
01257 01257 MS Windows: Baltic Rim<br />
EBCDIC 01112 01112 Host: Latvia, Lithuania<br />
Cyrillic:<br />
CCSID CPGID<br />
ASCII 00866 00866 PC data: Cyrillic<br />
00915 00915 ISO 8859-5: Cyrillic<br />
01251 01251 MS Windows: Cyrillic<br />
EBCDIC 01025 01025 Host: Cyrillic multilingual<br />
Estonia:<br />
CCSID CPGID<br />
ASCII 00922 00922 PC data: Estonia<br />
01257 01257 MS Windows: Baltic Rim<br />
EBCDIC 01122 01122 Host: Estonia<br />
Greek:<br />
CCSID CPGID<br />
ASCII 00869 00869 PC data: Greece<br />
00813 00813 ISO 8859-7: Grek<br />
01253 01253 MS Windows: Greek<br />
EBCDIC 00875 00875 Host: Grek<br />
Hebrew:<br />
252 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
CCSID CPGID<br />
ASCII 00856 00856 PC data: Hebrew<br />
00916 00916 ISO 8859-8: Hebrew<br />
01255 01255 MS Windows: Hebrew<br />
EBCDIC 00424 00424 Host: Hebrew<br />
Latin-1:<br />
CCSID CPGID<br />
ASCII 00437 00437 PC data: USA, many other countries<br />
00819 00819 ISO 8859-1: Latin-1 countries<br />
00850 00850 PC data: Latin-1 countries<br />
01252 01252 MS Windows: Latin-1 countries<br />
EBCDIC 00037 00037 Host: USA, Canada, etc<br />
00273 00273 Host: Austria, Germany<br />
00277 00277 Host: Denmark, Norway<br />
00278 00278 Host: Finland, Sweden<br />
00280 00280 Host: Italy<br />
00284 00284 Host: Spain, Latin America (Spanish)<br />
00285 00285 Host: United Kingdom<br />
00297 00297 Host: France<br />
00500 00500 Host: International Latin-1<br />
00871 00871 Host: Iceland<br />
01047 01047 Host: Latin-1 Open Systems<br />
Latin-1 including euro support:<br />
CCSID CPGID<br />
ASCII 00858 00858 PC data: Latin-1 countries<br />
05348 01252 MS Windows: Latin-1 countries, version 2<br />
EBCDIC 01140 01140 Host: USA, Canada, etc<br />
01141 01141 Host: Austria, Germany<br />
01142 01142 Host: Denmark, Norway<br />
01143 01143 Host: Finland, Sweden<br />
01144 01144 Host: Italy<br />
01145 01145 Host: Spain, Latin America (Spanish)<br />
01146 01146 Host: United Kingdom<br />
01147 01147 Host: France<br />
01148 01148 Host: International Latin-1<br />
01149 01149 Host: Iceland<br />
Latin-2:<br />
CCSID CPGID<br />
ASCII 00852 00852 PC data: Latin-2 multilingual<br />
00912 00912 ISO 8859-2: Latin-2 multilingual<br />
01250 01250 MS windows: Latin-2<br />
EBCDIC 00870 00870 Host: Latin-2 multilingual<br />
Latin-5:<br />
CCSID CPGID<br />
ASCII 00857 00857 PC data: Latin-5 (Turkey)<br />
00920 00920 ISO 8859-9: Latin-5 (Turkey)<br />
01254 01254 MS Windows: Turkey<br />
EBCDIC 01026 01026 Host: Latin-5 (Turkey)<br />
Data conversion<br />
Appendix A. Data conversion between the Client daemon and a <strong>CICS</strong> server 253
Data conversion<br />
Latin-9:<br />
CCSID CPGID<br />
ASCII 00923 00923 ISO 8859-15: Latin-9<br />
EBCDIC 00924 00924 Host: Latin-9<br />
Japanese:<br />
CCSID CPGID<br />
ASCII 00932 00897 PC data: SBCS<br />
00301 PC data: DBCS<br />
00942 01041 PC data: extended SBCS<br />
00301 PC data: DBCS<br />
00943 00897 PC data: SBCS<br />
00941 PC data: DBCS for Open environment<br />
00954 00895 G0: JIS X201 Roman<br />
00952 G1: JIS X208-1990<br />
00896 G2: JIS X201 Katakana<br />
00953 G3: JIS X212<br />
EBCDIC 00930 00290 Host: Katakana, extended SBCS<br />
00300 Host: DBCS<br />
00931 00037 Host: Latin-1, SBCS<br />
00300 Host:DBCS<br />
00939 01027 Host: Latin-1, extended SBCS<br />
00300 Host: DBCS<br />
Korea:<br />
CCSID CPGID<br />
ASCII 00934 00891 PC data: SBCS<br />
00926 PC data: DBCS<br />
00944 01040 PC data: extended SBCS<br />
00926 PC data: DBCS<br />
00949 01088 PC data: SBCS, IBM KS code<br />
00951 PC data: DBCS, IBM KS code<br />
00970 00367 G0: ASCII<br />
00971 G1: KSC X5601-1989<br />
01363 01126 MS Windows: Korean SBCS<br />
01362 MS Windows: Korean DBCS<br />
EBCDIC 00933 00833 Host: extended SBCS<br />
00834 Host: DBCS<br />
Simplified Chinese:<br />
CCSID CPGID<br />
ASCII 00946 01042 PC data: extended SBCS<br />
00928 PC data: DBCS<br />
01381 01115 PC data: extended SBCS, IBM GB<br />
01380 PC data: DBCS, IBMGB<br />
01383 00367 G0: ASCII<br />
01382 G1: GB 2312-80 set<br />
01386 01114 PC data: SBCS, S-Chinese GBK,<br />
T-Chinese IBM BIG-5<br />
01385 PC data: DBCS, S-Chinese GBK<br />
EBCDIC 00935 00836 Host: extended SBCS<br />
00837 Host: DBCS<br />
254 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Traditional Chinese:<br />
CCSID CPGID<br />
ASCII 00938 00904 PC data: SBCS<br />
00927 PC data: DBCS<br />
00948 01043 PC data: extended SBCS<br />
00927 PC data: DBCS<br />
00950 01114 PC data: SBCS, IBM BIG-5<br />
00947 PC data: DBCS<br />
00964 00367 G0: ASCII<br />
00960 G1: CNS 11643 plane 1<br />
00961 G2: CNS 11643 plane 2<br />
EBCDIC 00937 00037 Host: Latin-1 SBCS<br />
00835 Host: DBCS<br />
Data conversion<br />
Appendix A. Data conversion between the Client daemon and a <strong>CICS</strong> server 255
Data conversion<br />
256 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Appendix B. Hardware and software<br />
This chapter lists hardware requirements and supported software for all<br />
operating systems on which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs.<br />
Hardware requirements<br />
This section discusses the disk space requirements on z/OS, and general<br />
hardware requirements on distributed platforms.<br />
Disk space requirements on z/OS<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is normally installed into a directory such as<br />
/usr/lpp/ctg, in USS (see also “Installation path” on page xii). In this case,<br />
during installation, the uncompressed tar file is present in the /usr/lpp<br />
directory. The HFS data set for this directory must be large enough to take the<br />
25MB (40 cylinders) that this file occupies. You can delete the files once<br />
installation is complete. Installation also requires 25MB (40 cylinders) in the<br />
/tmp directory.<br />
Once installed, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> occupies 27MB. You need enough<br />
disk space for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and any logging and tracing files.<br />
IBM recommends that you use a separate HFS data set with a primary<br />
allocation of 40 cylinders for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software. Increase this<br />
to 50 cylinders if the logging and trace files will be stored in the same HFS<br />
data set. Increase it further if many instances of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will run, or if much logging is required. Alternatively, you can use a separate<br />
HFS data set, with a primary allocation of 5 cylinders, for each instance of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
If you use the existing /usr/lpp HFS data set, ensure it has enough space to<br />
take the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software.<br />
Table 11. Hardware requirements on UNIX systems<br />
AIX LINUX SOLARIS HP-UX<br />
Processor v IBM RISC<br />
System/6000 ®®<br />
v IBM RS/6000 ®®<br />
Scalable<br />
POWERParallel<br />
System (SP2 ® G5, G6, MP3000 or<br />
above<br />
SPARC PA-RISC 1.1 or 2.0<br />
).<br />
© Copyright IBM Corp. 1996, 2002 257
Table 11. Hardware requirements on UNIX systems (continued)<br />
AIX LINUX SOLARIS HP-UX<br />
Terminals Any type of Any standard Any type of Any standard<br />
terminal or telnet or X based terminal or telnet or X based<br />
X/Terminal that terminal that can X/Terminal that terminal that can<br />
can attach to the access Linux. can attach to the access HP-UX.<br />
processor.<br />
processor.<br />
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB<br />
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB<br />
for temporary files for temporary files for temporary files for temporary files<br />
used during used during used during used during<br />
installation. installation. installation. installation.<br />
Table 12. Hardware requirements on Windows systems<br />
Processor Any processor capable of running the appropriate<br />
operating system and other prerequisite software.<br />
Network adapters To connect workstations to the LAN, you need a<br />
suitable adapter such as an ethernet adapter.<br />
Memory At least 64 MB.<br />
Disk space You need 30 MB of free disk space for your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (including documentation in US<br />
English only).<br />
Supported software<br />
The following products are supported.<br />
You need a further 30 MB for temporary files used<br />
during installation. At least 12 MB of this must be on<br />
your system partition.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v AIX V4.3.3 with Service Pack 25<br />
v AIX 5.1<br />
v HP-UX 11.0<br />
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)<br />
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)<br />
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)<br />
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
258 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)<br />
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)<br />
v OS/390 V2.10<br />
v z/OS V1.2<br />
v Windows XP Professional<br />
v Windows 2000 Professional with a minimum of Service Pack 1<br />
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a<br />
minimum of Service Pack 1<br />
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a<br />
v Windows NT Server V4.0 with a minimum of Service Pack 6a.<br />
Notes:<br />
– Windows NT 4 Terminal Server is not supported<br />
– The setting of multiple user interface languages, under Windows<br />
2000 MultiLanguage <strong>Version</strong>, is not supported.<br />
– If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> under load, and<br />
using remote protocols, it is strongly recommended that you use<br />
a server version, rather than a workstation version, of Windows.<br />
See “ConnectFailed exceptions when running under load” on<br />
page 216, for more information.<br />
Web browsers<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
v HotJava Browser V 1.1 (for Solaris)<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
Appendix B. Hardware and software 259
|<br />
|<br />
|<br />
|<br />
|<br />
Telnet clients<br />
If you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> over telnet, certain telnet clients can<br />
cause problems with the display. For example, your telnet session might<br />
truncate message lines over a certain length. This is usually a problem with<br />
the telnet client that you are using, or the terminal type that you are going in<br />
as. Currently there is no solution to this problem.<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v AIX: IBM Java SDK 1.3 (service release 6)<br />
v HP-UX: Java SDK 1.3.0.02<br />
v Solaris: Sun Java SDK SE 1.3.0_04.<br />
v z/OS: IBM Java SDK 1.3<br />
If using the IBM Persistent Reusable JVM, you are recommended to run at a<br />
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable<br />
functionality of this JVM.<br />
If using Java under DBCS code pages, especially IBM-939, install service<br />
refresh 14 or later.<br />
v Windows: IBM Java SDK 1.3 (service release 6)<br />
JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– AIX: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
– HP-UX: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Linux for S/390: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Solaris: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– z/OS with JRE 1.3.1: includes a version of JSSE that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> supports<br />
– Windows: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
260 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied.<br />
v <strong>CICS</strong> for MVS/ESA V4.1, with communication through SNA. (with APAR<br />
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for<br />
EPI emulation. APAR PN79262 is needed for DBCS support.<br />
v <strong>CICS</strong> for OS/400 V4.4<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for OS/2 V4.1 with CSD 3<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA 1.1.0 (with APAR PQ30170, for<br />
signon capable terminals, applied), or a minimum service level of 1.1.1<br />
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)<br />
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)<br />
v TXSeries V<strong>5.0</strong> (Windows, AIX)<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,<br />
AIX and Solaris.<br />
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.<br />
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF<br />
UQ99329 (Service Level W401030).<br />
SNA communications<br />
Customers wishing to use SNA communications should install one of the<br />
following products:<br />
Windows operating systems<br />
Any one of:<br />
v IBM eNetwork Communications Server V6.1, with a minimum of<br />
service level 1<br />
v IBM eNetwork Personal Communications V<strong>5.0</strong>, with a minimum of<br />
service level 2<br />
v IBM eNetwork Personal Communications V5.5<br />
Appendix B. Hardware and software 261
v Microsoft SNA Server V4.0 with a minimum of SP4<br />
AIX<br />
IBM eNetwork Communications Server V6.1, with a minimum of service<br />
level 1 (AIX).<br />
SNA is not supported on other UNIX operating systems.<br />
TCP/IP communications<br />
TCP/IP support is provided by the operating system.<br />
TCP62 communications<br />
TCP62 support is provided by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Compilers and application development tools<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following compilers and<br />
application development tools:<br />
AIX<br />
v IBM C for AIX V4.4<br />
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6<br />
v IBM VisualAge C++ Professional V4.0<br />
v IBM VisualAge C++ Professional V<strong>5.0</strong> (requires AIX version 4.2 or later)<br />
HP-UX<br />
v HP ANSI C B.11.01, with a minimum of service level 7<br />
v HP aC++ B.11.01, with a minimum of service level 6<br />
Linux for S/390<br />
v GNU compiler C runtime V2.95, with a minimum of service level 2<br />
v GNU compiler C++ runtime V2.95, with a minimum of service level 2<br />
Solaris<br />
Sun WorkShop C++ V<strong>5.0</strong><br />
Note: The C++ compiler must have all available service patches applied.<br />
Windows<br />
v IBM VisualAge COBOL V3.0<br />
v Microsoft Visual C++ V6.0<br />
v Microsoft Visual Basic V6.0<br />
v Microsoft Visual Basic Script (VBScript) V<strong>5.0</strong><br />
Note: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support use of the COM<br />
libraries with Microsoft <strong>Transaction</strong> Server (MTS), or the MTS<br />
component of COM+.<br />
262 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
Screen readers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with JAWS.<br />
Other tools<br />
These tools are available for viewing the PDF online documents:<br />
v Adobe Acrobat Reader V<strong>5.0</strong><br />
v GhostView V4.0 on Linux<br />
GPL licence and copyright issues on Linux<br />
This product uses the following libraries from the glibc package: libnsl.so,<br />
libm.so, libdl.so, ld.so, libc.so and libpthread.so. Refer to the glibc package on<br />
your machine for the various copyright statements and licensing terms for<br />
these libraries.<br />
This product also uses libncurses.so from the ncurses package. Again, refer to<br />
this package on your machine for the copyright statement and licensing terms<br />
applicable to this library.<br />
IMPORTANT: Your use of the libstdc++ or egcs-c++ packages is subject to the<br />
GNU GPL licence terms which could require you to provide source code in<br />
certain circumstances. Note that IBM will not supply source code, for example<br />
for the <strong>CICS</strong> <strong>Gateway</strong>s C++ libraries.<br />
Appendix B. Hardware and software 263
264 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 266<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks” on page 267 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 267 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 269 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 1996, 2002 265
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX for IBM eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
266 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Redbooks<br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT: Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA: Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400: Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 267
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
Microsoft ® Windows Family publications<br />
The following book provides introductory material about the Windows Family<br />
of operating systems:<br />
v Windows NT System Guide<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for Windows NT and Windows 2000:<br />
Communications Server for Windows: Quick Beginnings, GC31-8424<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
IBM eNetwork Personal Communications:<br />
IBM Personal Communications for Windows NT: Quick Beginnings,<br />
GC31-8679-02<br />
IBM Personal Communications: Administrator’s Reference, SC31-8840<br />
Microsoft products<br />
Microsoft SNA Server Installation Guide<br />
Microsoft SNA Server Administration Guide<br />
Microsoft SNA Server Reference<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
268 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
Other publications<br />
The product library and related literature 269
270 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
Installation<br />
iKeyMan<br />
Samples<br />
and follow the Library link.<br />
The following are known issues:<br />
v Screen readers do not read the progress bars that appear during the various<br />
phases of installation.<br />
v The installation program does not support system settings for font size and<br />
font colors.<br />
These shortcut keys activate options from the installation options screen:<br />
Alt+C Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Alt+J Install Java.<br />
See this Web site for information:<br />
www.tivoli.com<br />
The samples are not accessible.<br />
Configuration tool accessibility<br />
Components<br />
Each component in the configuration tool has a name and description for<br />
screen readers.<br />
© Copyright IBM Corp. 1996, 2002 271
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Keys<br />
You can use the following keys to operate the configuration tool:<br />
Alt, Space<br />
Press and release the Alt key, then press Space, to open the window<br />
menu. This allows you to move, size, maximize or minimize the window.<br />
Ctrl+letter<br />
Certain actions have shortcuts assigned to them. Hold down the Ctrl key<br />
and type the letter to do the action.<br />
Ctrl+letter Action<br />
C Copies the selected value.<br />
N Creates a new configuration.<br />
O Opens an existing configuration.<br />
P Pastes.<br />
S Saves the current configuration.<br />
U Cuts the selected value.<br />
V Pastes.<br />
W Creates a new server definition.<br />
X Cuts the selected value.<br />
Arrows (left and right)<br />
1. (Applies if the menus are active.) Move to a different menu.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the tree is active.) If a node contains subnodes, the left<br />
arrow collapses the node, the right arrow expands it. If a node cannot<br />
be expanded further, pressing the right arrow moves down to the next<br />
node. If a subnode is selected, pressing the left arrow moves to the<br />
parent node.<br />
Arrows (up and down)<br />
1. (Applies if the tree is active.) Move up and down through the tree.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the Authorized Hosts list box is active.) Move through the<br />
entries in the list. If only one entry is in the list, press the Home key<br />
to select it.<br />
Control+Page Up<br />
Scroll left.<br />
Control+Page Down<br />
Scroll right.<br />
272 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Control+Tab<br />
Use this (rather than Tab) on panels that contain a table to cycle between<br />
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to<br />
move backwards.<br />
Enter<br />
Activates a button in the Task Guide.<br />
Escape<br />
Closes the menu.<br />
F2 Select and change an editable number field in a table, for example the<br />
Bias value field on the Program definition for managing workload panel.<br />
F6 (Applies if the tree or the panel is active.) Toggles between the tree and<br />
the panel.<br />
F8 (Applies if the tree or the panel is active.) Allows you to gain control of<br />
the split between the tree and panel areas. After pressing F8, use the<br />
arrow keys to move the split:<br />
v Press the left arrow key to move the split left (decrease the width of the<br />
tree, increase the width of the panel).<br />
v Press the right arrow key to move the split right (increase the width of<br />
the tree, decrease the width of the panel).<br />
F10<br />
Opens the file menu.<br />
Home<br />
Selects the first entry in the Authorized Hosts list box.<br />
Page Up<br />
Scroll up.<br />
Page Down<br />
Scroll down.<br />
Shift+Tab<br />
If the cursor is on a field in the panel other than the first field, moves<br />
backwards through the fields. Otherwise, toggles between the tree and the<br />
panel.<br />
Space<br />
1. Activates a button.<br />
2. Selects a checkbox.<br />
3. Selects a node in the tree.<br />
Tab<br />
Cycles through the tree, fields in the panel, and the buttons.<br />
Accessibility 273
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Customizing colors and fonts<br />
Use the Settings option on the menu to change colors and fonts. Settings are<br />
not applied consistently on the Task Guide.<br />
To make them more noticeable, the names of items that contain errors are<br />
displayed in the original typeface, in red and underlined.<br />
Using help<br />
Screen readers read the entire page in the help window, rather than the area<br />
required by a user who has pressed F1. Also, the help window is not<br />
navigable by the keyboard. The solution is to open the help files, which are<br />
html files, in a browser outside the configuration tool. The help file index is<br />
cclhlp15.htm in directory:<br />
\bin\resource\<br />
where represents the directory containing the help files in these<br />
languages:<br />
Language <br />
English html<br />
German html_de<br />
Spanish html_es<br />
French html_fr<br />
Italian html_it<br />
Japanese html_ja<br />
Korean html_ko<br />
Turkish html_tr<br />
Simplified Chinese html_zh<br />
Task Guide<br />
Screenreaders cannot read the Task Guide; do not use the Task Guide if you<br />
use a screenreader. Use the menu in the configuration tool to add servers<br />
(Tools —> New server). Use the tree structure to enable protocols that the<br />
Java gateway will use.<br />
274 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans.<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 1996, 2002 275
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX, TXSeries<br />
for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390. A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA, <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
276 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 277
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
278 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 279
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
280 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed. The default keyboard mapping file for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is <strong>CICS</strong>KEY.INI.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.<br />
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
Glossary 281
Glossary<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
282 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
R<br />
RACF. Resource Access Control Facility. An IBM<br />
licensed program that provides access control by<br />
identifying users to the system; verifying users of<br />
the system; authorizing access to protected<br />
resources; logging detected, unauthorized<br />
attempts to enter the system; and logging<br />
detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.<br />
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
Glossary 283
Glossary<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
284 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for OS/2,<br />
<strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.<br />
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 285
Glossary<br />
286 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Index<br />
Special characters<br />
xii<br />
<strong>CICS</strong>CLI.BIN 219, 220, 222<br />
<strong>CICS</strong>CLI.LOG 74<br />
<strong>CICS</strong>CLI.TRC 219<br />
Numerics<br />
3270 data streams 167, 174<br />
A<br />
accessibility 271<br />
Acrobat 25, 263<br />
adapters 22, 258<br />
administration 149<br />
Adobe 25, 263<br />
advanced program-to-program communication<br />
(APPC) 26, 45<br />
Anynet domain name suffix configuration setting 82<br />
APAR (authorized program analysis report)<br />
authorization 239<br />
closing 240<br />
documentation needed 237<br />
process 240<br />
submitting 239<br />
API (Application Programming Interface) 3<br />
APPC (advanced program-to-program<br />
communication) 26, 45<br />
application development tools 25, 262<br />
Application Programming Interface (API) 3<br />
application servers 24, 261<br />
application tracing 210<br />
Applid configuration setting 71<br />
asymmetric keys 7<br />
ATI 229<br />
authentication 10<br />
Authorized Hosts configuration setting 69<br />
B<br />
beans, Java 14<br />
Biasing configuration setting 85<br />
binary trace formatter 222<br />
BMS Map Conversion Utility 194, 205<br />
books 265<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 265<br />
browsers 22, 259<br />
bthdinst 77<br />
C<br />
CA (certification authority) 8<br />
CCLCLNT.EXE 230<br />
CCLLOG.HLP 218<br />
cclmeci.dll 184<br />
cclmepi.dll 185<br />
CCLMSG.HLP 218<br />
CCLSNWTP.EXE 230<br />
certification authority (CA) 8<br />
cfwk.zip 215<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java 244<br />
<strong>CICS</strong> gateway for Lotus Notes; 248<br />
<strong>CICS</strong> resource adapters 90<br />
<strong>CICS</strong> server problem determination 232<br />
<strong>CICS</strong> server PTF requirements 25<br />
<strong>CICS</strong> servers 23, 261<br />
<strong>CICS</strong> servers, communicating with 41<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>CICS</strong> gateway for Lotus Notes; 248<br />
hardware requirements 22<br />
local 101<br />
migration 241<br />
problem determination 207<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with preset<br />
options 142<br />
starting <strong>Gateway</strong> with user-specified options 142<br />
startup options 142<br />
stopping 144<br />
Workload management 19<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>Start Menu shortcuts 144<br />
<strong>CICS</strong>CLI command 156<br />
<strong>CICS</strong>CLI environment variable 54, 242<br />
cicscli.log 218<br />
<strong>CICS</strong>COL environment variable 100<br />
cicseci.rar 90<br />
cicsepi.rar 90<br />
<strong>CICS</strong>FTRC utility 222<br />
<strong>CICS</strong>KEY environment variable 97<br />
<strong>CICS</strong>PRNT command 173<br />
<strong>CICS</strong>TERM command 167<br />
<strong>CICS</strong>TERM.INI 172<br />
CLASSPATH 53, 248<br />
CLASSPATH environment variable 124, 215, 216<br />
CLASSPATH setting 53<br />
client control 5<br />
Client daemon<br />
running as a Windows service 153<br />
trace analysis 225<br />
Client daemon tracing 220<br />
© Copyright IBM Corp. 1996, 2002 287
Client daemon, restarting 158<br />
Client daemon, starting 156, 157<br />
Client daemon, stopping 157<br />
client security 158<br />
client trace file 225<br />
Client trace file configuration setting 89<br />
client tracing 158<br />
client/server connections 27<br />
ClientSecurity 91, 93<br />
code pages 28<br />
Codepage identifier override configuration setting 74<br />
codepage problems 213<br />
color mapping file 99, 168<br />
commands<br />
<strong>CICS</strong>CLI 156<br />
<strong>CICS</strong>PRNT 173<br />
<strong>CICS</strong>TERM 167<br />
Common Client Interface (CCI) 16<br />
Common Object Request Broker (CORBA)<br />
standard 19<br />
Communicating with <strong>CICS</strong> servers 41<br />
communication<br />
problems 233<br />
communication protocols 24, 261<br />
APPC 26<br />
TCP/IP 26<br />
Communications Server 235<br />
compilers 25, 262<br />
configuration<br />
CLASSPATH 53<br />
configuration file 54<br />
configuration tool 54<br />
<strong>Gateway</strong>.properties file 54<br />
programming environment 53<br />
setting the time 53<br />
configuration conversion tool 241<br />
configuration file 54<br />
referencing 54<br />
renaming 96<br />
configuration file, referencing 165<br />
configuration settings<br />
Anynet domain name suffix 82<br />
Applid 71<br />
Authorized Hosts 69<br />
Biasing 85<br />
Client trace file 89<br />
Codepage identifier override 74<br />
Connection timeout 79<br />
Connection timeout (ms) 63<br />
Description 76<br />
Display TCP/IP hostnames 60<br />
Drop working connections 63<br />
Enable popups 75<br />
Enable protocol handler 62<br />
Enable reading input from console 60<br />
288 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
configuration settings (continued)<br />
Enable the Workload Manager 84<br />
Fully qualified CP name or template 82<br />
<strong>Gateway</strong> trace file 88<br />
<strong>Gateway</strong> trace wrap size 89<br />
Handler wakeup timeout (ms) 63<br />
Hostname or IP address 78<br />
Idle timeout (ms) 63<br />
Initial number of Connection Manager threads 59<br />
Initial number of Worker threads 59<br />
Initial transaction 77<br />
IP address mask for CP name (optional) 82<br />
IP address mask for LU name template<br />
(optional) 81<br />
Java clients obtaining generic ECI replies 60<br />
KeyRing or Keystore name 66<br />
KeyRing or Keystore password 66<br />
Local LU name 79<br />
Local LU name or template 80<br />
Log client connections and disconnections 61<br />
Log file 74<br />
Manage workload for this program 86<br />
Max dedicated connections 69<br />
Maximum buffer size 72<br />
Maximum Client wrap size 89<br />
Maximum logical SNA sessions 83<br />
Maximum number of Connection Manager<br />
threads 59<br />
Maximum number of Worker threads 59<br />
Maximum requests 72<br />
Maximum servers 72<br />
Maximum SNA RU size 83<br />
Mode name 79, 81<br />
Model terminal definition 77<br />
Named pipe name 84<br />
Partner LU name 79, 80<br />
Ping time frequency (ms) 63<br />
Port 62, 78<br />
Print command 73<br />
Print file 73<br />
Region timeout (s) 85<br />
Remote node inactivity poll interval 83<br />
Require clients to use security classes 64<br />
Round robin 84<br />
Send TCP/IP Keepalive packets 79<br />
Server name 76<br />
Server retry interval 74<br />
SNA pacing size 83<br />
SO_LINGER setting 64<br />
Terminal exit 72<br />
Timeout for in-progress requests to complete<br />
(ms) 61<br />
Trace 86<br />
Trace settings 219<br />
Use client authentication 65
configuration settings (continued)<br />
Use LU alias names 79<br />
Use OEM codepage 75<br />
Use upper case security 78<br />
Use Windows credentials for security 77<br />
Validate message qualifiers 61<br />
Validate Units of Work 60<br />
Worker thread available timeout (ms) 61<br />
configuration tool 54<br />
configuration tool help 274<br />
connecting to <strong>CICS</strong> servers 157, 161<br />
Connection timeout (ms) configuration setting 63<br />
Connection timeout configuration setting 79<br />
ConnectionURL 91, 92<br />
CORBA (Common Object Request Broker) standard 19<br />
Corrective Service Diskette (CSD) 240<br />
corrective service software 39<br />
CRSR transaction 45<br />
CSD (Corrective Service Diskette) 240<br />
CTG_JNI_TRACE 87, 211<br />
ctgcfg command 54<br />
ctgclient.jar 216<br />
ctgconv, conversion tool 242<br />
ctgikey 104, 115<br />
ctgjava 147<br />
ctgjava command 52<br />
ctgsamples.jar 248<br />
ctgserver.jar 216<br />
ctgservice utility 147<br />
ctgstart command 142<br />
customizing<br />
keyboard 97<br />
screen colors 99<br />
D<br />
Data conversion 50<br />
defining 3270 printer terminal emulator<br />
characteristics 174<br />
defining 3270 terminal emulator characteristics 168<br />
Description configuration setting 76<br />
development tools 25, 262<br />
DeviceType 94<br />
diagnosing common problems<br />
Client daemon 227<br />
codepage problems 213<br />
<strong>Gateway</strong> daemon 212<br />
if a process locks 213<br />
Java exceptions 216<br />
Java security exceptions 217<br />
java.lang.OutOfMemory exception 217<br />
running as a windows service 213<br />
SSL exceptions 214<br />
using Java debugging tools to debug user<br />
applications 218<br />
diagnostic tools<br />
APING 234<br />
digital certificates 8, 10<br />
externally signed 105, 115<br />
maintaining 104, 115<br />
self-signed 110, 120<br />
digital signatures 8<br />
disability 271<br />
disabling the display of messages 159<br />
disabling the display of pop-up messages 159<br />
disk space required 22, 258<br />
Display TCP/IP hostnames configuration setting 60<br />
displaying command syntax 160<br />
distinguished name (DN) 8<br />
DN (distinguished name) 8<br />
documentation 265<br />
documenting problems 237<br />
Drop working connections configuration setting 63<br />
dynamic name generation (TCP62) 82<br />
E<br />
ECI (External Call Interface) 1, 3, 4<br />
ECI resource adapter 91<br />
Enable popups configuration setting 75<br />
Enable protocol handler configuration setting 62<br />
Enable reading input from console configuration<br />
setting 60<br />
Enable the Workload Manager configuration<br />
setting 84<br />
enabling the display of pop-up messages 159<br />
Encoding 94<br />
encryption 7, 10<br />
eNetwork Communications Server 46<br />
Enterprise Information Systems (EIS) 15<br />
environment variables 96<br />
<strong>CICS</strong>CLI 54, 242<br />
<strong>CICS</strong>COL 100<br />
<strong>CICS</strong>KEY 97<br />
CLASSPATH 53, 124, 215<br />
CTG_JNI_TRACE 87, 211<br />
JAVA_HOME 104, 115<br />
PATH 36, 102<br />
EPI (External Presentation Interface) 1, 3, 4<br />
EPI resource adapter 92<br />
EPIBasicScreenHandler 248<br />
EPIMonitor 248<br />
EPIScreenButtons 248<br />
error log<br />
cicscli.log 218<br />
client error log 218<br />
server error log 233<br />
Error log<br />
IBM Communications Server 235<br />
ESI (External Security Interface) 1, 3, 4<br />
Euro support 74, 75<br />
Index 289
EXEC <strong>CICS</strong> RETURN TRANSID IMMEDIATE<br />
command 169, 175<br />
External Call Interface (ECI) 1, 3, 4<br />
External Presentation Interface (EPI) 1, 3, 4<br />
External Security Interface (ESI) 1, 3, 4<br />
externally-signed certificates 9<br />
F<br />
firewalls 14<br />
font selection on terminal emulators 172<br />
fonts<br />
selecting on terminal emulators 172<br />
free memory 72<br />
Fully qualified CP name or template configuration<br />
setting 82<br />
G<br />
<strong>Gateway</strong> daemon tracing 209<br />
<strong>Gateway</strong> trace file configuration setting 88<br />
<strong>Gateway</strong> trace wrap size 89<br />
<strong>Gateway</strong>.properties file 54<br />
generic ECI replies<br />
Configuration 60<br />
Getsense 235<br />
GhostView 25, 263<br />
glossary of terms and abbreviations 275<br />
H<br />
Handler wakeup timeout (ms) configuration<br />
setting 63<br />
hangs 213, 232<br />
hardware requirements 22<br />
help 274<br />
Hostname or IP address configuration setting 78<br />
HTTP (Hypertext Transfer Protocol) 2<br />
HTTP over SSL (HTTPS) 2<br />
HTTPS 12<br />
HTTPS (HTTP over SSL) 2<br />
Hypertext Transfer Protocol (HTTP) 2<br />
I<br />
IBM Communicatins Server 235<br />
Idle timeout (ms) configuration setting 63<br />
IIOP (Internet InterOrb Protocol) 19<br />
iKeyMan 104, 115<br />
distributing to client workstations 104<br />
inactivity poll interval 45<br />
Initial number of Connection Manager threads<br />
configuration setting 59<br />
Initial number of Worker threads configuration<br />
setting 59<br />
initial transaction 168, 174<br />
Initial transaction configuration setting 77<br />
initialization files<br />
cicscol.ini 99, 100<br />
cicskey.ini 97<br />
290 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
initialization files (continued)<br />
<strong>CICS</strong>TERM.INI 172, 243<br />
install_path xii<br />
installation<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 29<br />
complete installation 29<br />
custom installation 29<br />
maintaining <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 37<br />
path xii<br />
problems 30, 37<br />
repairing <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 37<br />
silent installation 39<br />
types of installation 29<br />
uninstalling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 37<br />
installation path xii<br />
InstallTimeout 94<br />
Internet InterOrb Protocol (IIOP) 19<br />
IP address mask for CP name (optional) configuration<br />
setting 82<br />
IP address mask for LU name template (optional)<br />
configuration setting 81<br />
J<br />
J2EE<br />
resource adapter files 90<br />
resource adapters 3<br />
Java<br />
applet 13<br />
application 13<br />
beans 14<br />
classes 3<br />
firewall 14<br />
Java language 12<br />
samples 248<br />
servlet 13<br />
Java debugging tools, using 218<br />
Java development kit 23, 260<br />
Java exceptions 213, 216<br />
Java Secure Socket Extension (JSSE) 23, 260<br />
Java security exceptions 217<br />
Java virtual machine (JVM) 52<br />
JAVA_HOME environment variable 104, 115<br />
java.lang.OutOfMemory exception 217<br />
JDK levels 23, 260<br />
JNI tracing 87, 149, 211<br />
JSSE 9, 11, 23, 114, 115, 260<br />
installation 114<br />
migration from SSLight 114<br />
JVM (Java virtual machine) 52<br />
K<br />
KeepAlive packets 45<br />
keyboard 272<br />
keyboard mapping file 97, 168<br />
KeyRing or Keystore name configuration setting 66
KeyRing or Keystore password configuration<br />
setting 66<br />
KeyRingClass 92, 94<br />
KeyRingPassword 92, 94<br />
KeyRings 9, 104<br />
keys specific to particular keyboards 99<br />
KeyStores 9, 115<br />
L<br />
license files 32<br />
listing connected servers 159<br />
local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 101<br />
local gateway connection 13<br />
Local LU name configuration setting 79<br />
Local LU name or template configuration setting 80<br />
Local Named Pipe protocol 26<br />
locks 213<br />
Log file configuration setting 74<br />
logical unit (LU) 45<br />
LogonLogoffClass 94<br />
LU6.2 26<br />
M<br />
Manage workload for this program configuration<br />
setting 86<br />
mapping files<br />
renaming 96<br />
Max dedicated connections configuration setting 69<br />
Maximum buffer size configuration setting 72<br />
Maximum Client wrap size configuration setting 89<br />
Maximum logical SNA sessions configuration<br />
setting 83<br />
Maximum number of Connection Manager threads<br />
configuration setting 59<br />
Maximum number of Worker threads configuration<br />
setting 59<br />
Maximum requests configuration setting 72<br />
Maximum servers configuration setting 72<br />
Maximum SNA RU size configuration setting 83<br />
memory leak 217<br />
memory requirements 72<br />
messages 208, 218<br />
messages, disabling the display of 159<br />
Microsoft SNA Server 49<br />
migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java 244<br />
migration<br />
<strong>CICS</strong> Client <strong>Version</strong> 2 243<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java 244<br />
<strong>CICS</strong> Universal Client <strong>Version</strong> 3.0 243<br />
configuration files 243<br />
migration issues 241<br />
mode definitions, APPC 45<br />
Mode name configuration setting 79, 81<br />
Model terminal definition configuration setting 77<br />
N<br />
Named pipe name configuration setting 84<br />
Named Pipes protocol 50<br />
network drives, problems with 36<br />
network gateway connection 13<br />
Network Provider Interface (NPI) 126<br />
network security<br />
authentication 10<br />
certification authority (CA) 8<br />
concepts 6<br />
ctgikey 104, 115<br />
digital certificates 8, 10<br />
externally signed 105, 115<br />
maintaining 104, 115<br />
self-signed 110, 120<br />
digital signatures 8<br />
distinguished name (DN) 8<br />
encryption 7, 10<br />
externally-signed certificates 9<br />
HTTPS 12, 124<br />
iKeyMan 104, 115<br />
distributing to client workstations 104<br />
JSSE 9, 11, 114, 115<br />
installation 114<br />
migration from SSLight 114<br />
KeyRings 9, 104<br />
keys 7<br />
KeyStores 9, 115<br />
migrating old self-signed certificates 114, 124<br />
Network Provider Interface (NPI) 126<br />
security exits 12<br />
self-signed certificates 9<br />
signer certificate 8<br />
SSL 10, 124<br />
SSL handshaking 10<br />
SSLight 11, 104<br />
System SSL 11<br />
trusted root key 8<br />
X.509 protocol 8, 10<br />
non-existent directories 36<br />
NPI (Network Provider Interface) 126<br />
O<br />
object request broker (ORB) 19<br />
online help, for end user messages, 218<br />
onlne help, for trace and log messages 218<br />
operating systems 22, 258<br />
operation<br />
starting the <strong>Gateway</strong> 141<br />
stopping the <strong>Gateway</strong> 144<br />
options<br />
<strong>CICS</strong>CLI command 160<br />
<strong>CICS</strong>PRNT command 176<br />
<strong>CICS</strong>TERM command 170<br />
ORB (object request broker) 19<br />
Index 291
P<br />
Partner LU name configuration setting 79, 80<br />
Password 91, 93<br />
password expiry management (PEM) 4, 130<br />
PATH environment variable 36<br />
PEM (password expiry management) 4, 130<br />
performance<br />
assessing 135<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration 136<br />
Java considerations 138<br />
monitoring 140<br />
other system factors 138<br />
tracing 139<br />
Ping time frequency (ms) configuration setting 63<br />
planning 21<br />
PMR (Problem Management Record) 236<br />
pop-up messages, disabling the display of 159<br />
pop-up messages, enabling the display of 159<br />
Port configuration setting 62, 78<br />
PortNumber 91, 93<br />
Print command configuration setting 73<br />
Print file configuration setting 73<br />
print file, processing 168, 174<br />
print terminal emulator, starting 174<br />
printer support 5<br />
printer terminal emulator characteristics, defining 174<br />
problem determination 207<br />
application tracing 210<br />
diagnosing common problems<br />
<strong>Gateway</strong> daemon 212<br />
<strong>Gateway</strong> daemon tracing 209<br />
JNI tracing 211<br />
messages 208, 218<br />
preliminary checks 207<br />
servlet tracing and logging in WebSphere 211<br />
tracing<br />
Client daemon 219<br />
<strong>Gateway</strong> daemon 209<br />
Problem Management Record (PMR) 236<br />
problem reporting<br />
documenting problems 237<br />
information needed 238<br />
support organization 236<br />
problems, communication 233<br />
process locks 213<br />
program support 236<br />
protocols<br />
HTML 16<br />
HTTP 2<br />
HTTPS 2<br />
SSL 2, 10<br />
TCP/IP 2<br />
PTF (Program Temporary Fix) 240<br />
public key encryption 7<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 265<br />
292 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration<br />
R<br />
railroad diagrams xii<br />
re-authentication support 92, 95<br />
README file 21<br />
ReadTimeout 94<br />
Region timeout (s) configuration setting 85<br />
Remote Method Invocation (RMI) 19<br />
Remote node inactivity poll interval 45<br />
Remote node inactivity poll interval configuration<br />
setting 83<br />
removing <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 37<br />
Require clients to use security classes configuration<br />
setting 64<br />
requirements, hardware 22<br />
resource adapter files 90<br />
resource adapters 90<br />
resource adapters, J2EE 3<br />
Restarting the Client daemon 158<br />
restrictions, using <strong>CICS</strong> servers 27<br />
RETAIN database 236<br />
RETAIN problem management system<br />
APARs 240<br />
Problem Management Record 236<br />
RMI (Remote Method Invocation) 19<br />
roaming user support 172<br />
Round robin configuration setting 84<br />
S<br />
samples text file 195<br />
samples, Java 248<br />
Samples.txt 195, 196<br />
screen readers 25, 263<br />
Secure Sockets Layer (SSL) 2, 10<br />
security 78<br />
External Security Interface (ESI) 4<br />
password expiry management (PEM) 4<br />
security exits 12<br />
self-signed certificates 9<br />
Send TCP/IP Keepalive packets configuration<br />
setting 79<br />
Sense codes 235<br />
Server name configuration setting 76<br />
Server retry interval configuration setting 74<br />
ServerName 91, 93<br />
servers<br />
application 24, 261<br />
<strong>CICS</strong> 23, 261<br />
web 24, 261<br />
servers, listing 159<br />
ServerSecurity 92, 93<br />
Service startup parameters 155<br />
services, Windows 146, 153<br />
services, Windows NT 146<br />
servlet tracing and logging in WebSphere 211<br />
servlets 13
shortcut keys 272<br />
signer certificate 8<br />
signon capable terminals 25<br />
SignonType 94<br />
silent installation 39<br />
SNA 24, 261<br />
checking configuration 234<br />
configuring 45<br />
SNA (Systems Network Architecture) 26<br />
SNA pacing size configuration setting 83<br />
SNA Server 49<br />
SO_LINGER setting configuration setting 64<br />
SSL (Secure Sockets Layer) 2, 10<br />
SSL exceptions 214<br />
SSL handshaking 10<br />
SSLight 11, 104<br />
Start Menu shortcuts, creating 36<br />
Start Menu shortcuts, for Client daemon<br />
commands 36<br />
starting a 3270 print terminal emulator 174<br />
starting a 3270 terminal emulator 168<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 141<br />
Starting the Client daemon 156, 157<br />
Starting the Client daemon service at Windows NT<br />
startup 155<br />
Startup options for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
service 146<br />
stopping a terminal emulator 169<br />
Stopping the Client daemon 157<br />
stopping the <strong>Gateway</strong> 144<br />
support organization<br />
program support 236<br />
sending documentation to 239<br />
symmetric keys 7<br />
syntax notation xii<br />
System SSL 11<br />
Systems Network Architecture (SNA) 26<br />
T<br />
TCP/IP (Transmission Control Protocol/Internet<br />
Protocol) 2, 24, 26, 41, 262<br />
TCP/IP communication problems 228<br />
TCP62 24, 262<br />
communication problems 230<br />
multiple server definitions 243<br />
port number 83<br />
TCP62 protocol 42<br />
TCP62 support 28<br />
TCPAdmin protocol settings 69<br />
Telnet 23, 260<br />
terminal emulation 4<br />
terminal emulator<br />
preferences 172<br />
terminal emulator characteristics, defining 168<br />
terminal emulator, starting 168<br />
terminal emulator, stopping 169<br />
Terminal exit configuration setting 72<br />
Terminal Servlet 4<br />
the system locks up 232<br />
thread limits 17<br />
timeout 94<br />
Timeout for in-progress requests to complete (ms)<br />
configuration setting 61<br />
tools<br />
application development 25, 262<br />
other 25, 263<br />
TPNName 91<br />
Trace configuration setting 86<br />
Trace settings, configuration tool 219<br />
TraceLevel 92, 95<br />
tracing 95<br />
Client daemon 219<br />
dynamic 149<br />
<strong>Gateway</strong> daemon 149, 209<br />
if the <strong>Gateway</strong> daemon is running as a Windows<br />
service 210<br />
JNI 149<br />
levels 95<br />
performance considerations 210<br />
query current trace settings 149<br />
tracing, JNI 211<br />
TranName 91<br />
transaction programs (TP), APPC 45<br />
transaction support 92, 95<br />
transmission control protocol/internet protocol<br />
(TCP/IP) 26<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP) 2, 26, 41<br />
traps 230<br />
troubleshooting<br />
hangs 232<br />
starting clients and terminals 228<br />
traps 230<br />
trusted root key 8<br />
U<br />
uninstall 37<br />
updating<br />
installed software 39<br />
Use client authentication configuration setting 65<br />
Use LU alias names configuration setting 79<br />
Use OEM codepage configuration setting 75<br />
Use upper case security configuration setting 78<br />
Use Windows credentials for security configuration<br />
setting 77<br />
Userid 91, 93<br />
V<br />
Validate message qualifiers 61<br />
Validate Units of Work 60<br />
Index 293
variables, environment 96<br />
VTAM<br />
buffer trace 234<br />
W<br />
web browsers 22, 259<br />
web servers 24, 261<br />
Web servers 15<br />
Windows NT service 146<br />
Windows secured environment 75<br />
Windows service 146, 153<br />
WINSOCK 229<br />
Worker thread available timeout (ms) configuration<br />
setting 61<br />
Workload management 19<br />
Workload Manager 56, 84<br />
biasing algorithm 183<br />
installation 185<br />
overview 179<br />
port 180<br />
programs 180<br />
regions 180<br />
round-robin algorithm 183<br />
server instance 180<br />
TCP/IP port 180<br />
workload management 180<br />
X<br />
X.509 protocol 8, 10<br />
XAResource 92<br />
294 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 1996, 2002 295
Trademarks<br />
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
AIX Anynet<br />
<strong>CICS</strong> eNetwork<br />
IBM MQSeries<br />
MVS MVS/ESA<br />
OS/390 OS/400<br />
RETAIN TXSeries<br />
VisualAge VSE/ESA<br />
VTAM WebSphere<br />
296 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Lotus Domino, Lotus Notes, and Domino Go Webserver are trademarks of<br />
Lotus Development Corporation.<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of<br />
Microsoft Corporation in the United States, other countries, or both.<br />
Java and all Java-based trademarks and logos are trademarks or registered<br />
trademarks of Sun Microsystems, Inc. in the United States, other countries, or<br />
both.<br />
UNIX is a registered trademark in the United States and other countries<br />
licensed exclusively through X/Open Company Limited.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
Notices 297
298 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 1996, 2002 299
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6190-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Windows Administration <strong>Version</strong> <strong>5.0</strong>
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
UNIX Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6139-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
UNIX Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6139-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 265.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of the <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong>, program number 5724-D12. It will also apply to<br />
all subsequent versions, releases, and modifications until otherwise indicated in new editions.<br />
Vertical lines at the left side of the page indicate material that is new to this edition.<br />
© Copyright International Business Machines Corporation 1996, 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
|<br />
Contents<br />
About this book . . . . . . . . . . vii<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . viii<br />
Installation path . . . . . . . . . . x<br />
Programming language specific . . . . . x<br />
Operating system specific . . . . . . . x<br />
Syntax notation . . . . . . . . . . x<br />
Summary of changes . . . . . . . . xiii<br />
Chapter 1. Overview . . . . . . . . . 1<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides . . 3<br />
A <strong>Gateway</strong> daemon. . . . . . . . . 3<br />
The <strong>Gateway</strong> classes . . . . . . . . 3<br />
J2EE resource adapters . . . . . . . . 3<br />
A Client daemon . . . . . . . . . . 3<br />
The external access interfaces (ECI, EPI, ESI) 3<br />
A Terminal Servlet . . . . . . . . . 4<br />
Additional functions . . . . . . . . . 4<br />
3270 terminal emulation (cicsterm) . . . . 4<br />
3270 printer support (cicsprnt) . . . . . 5<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: local control . . 5<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: remote control 6<br />
Network security. . . . . . . . . . . 6<br />
Encryption . . . . . . . . . . . . 7<br />
Digital signatures and digital certificates . . 8<br />
Obtaining a digital certificate. . . . . . 9<br />
KeyRings and KeyStores . . . . . . . 9<br />
Authentication using SSL . . . . . . 10<br />
HTTPS . . . . . . . . . . . . . 12<br />
Security exits. . . . . . . . . . . 12<br />
Java technology . . . . . . . . . . . 12<br />
The Java language . . . . . . . . . 12<br />
Java applets . . . . . . . . . . . 13<br />
Java servlets . . . . . . . . . . . 13<br />
Java applications . . . . . . . . . 13<br />
JavaBeans . . . . . . . . . . . 14<br />
Firewalls . . . . . . . . . . . . 14<br />
Web servers . . . . . . . . . . . 15<br />
The J2EE resource adapters . . . . . . . 15<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses<br />
<strong>CICS</strong> . . . . . . . . . . . . . . 16<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading<br />
model . . . . . . . . . . . . . . 17<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request<br />
brokers. . . . . . . . . . . . . . 19<br />
Chapter 2. Planning your installation . . . 21<br />
Hardware requirements . . . . . . . . 22<br />
Supported software . . . . . . . . . 23<br />
Operating systems . . . . . . . . . 23<br />
Web browsers . . . . . . . . . . 23<br />
Telnet clients . . . . . . . . . . . 23<br />
JDK levels. . . . . . . . . . . . 24<br />
JSSE. . . . . . . . . . . . . . 24<br />
<strong>CICS</strong> Servers. . . . . . . . . . . 24<br />
Web servers . . . . . . . . . . . 25<br />
Application servers . . . . . . . . 25<br />
SNA communications . . . . . . . . 25<br />
TCP/IP communications . . . . . . . 25<br />
TCP62 communications . . . . . . . 25<br />
Compilers and application development<br />
tools . . . . . . . . . . . . . 25<br />
Other tools . . . . . . . . . . . 26<br />
GPL licence and copyright issues on Linux 26<br />
<strong>CICS</strong> server PTF requirements . . . . . . 26<br />
Terminal Signon capability . . . . . . 26<br />
Timeout support . . . . . . . . . 26<br />
Communication between the <strong>Gateway</strong> and<br />
<strong>CICS</strong> servers . . . . . . . . . . . . 27<br />
Restrictions on <strong>CICS</strong> for OS/400 . . . . 28<br />
Why use a particular protocol?. . . . . 29<br />
DBCS Multibyte Characters . . . . . . . 29<br />
Chapter 3. Installation . . . . . . . . 31<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . 31<br />
National language support . . . . . . . 33<br />
Using an alternative code set on AIX. . . 33<br />
Using an alternative code set (other UNIX<br />
platforms). . . . . . . . . . . . 34<br />
Using X-Windows from a remote system . . 35<br />
Uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 35<br />
Chapter 4. Setting up communication with<br />
<strong>CICS</strong> servers . . . . . . . . . . . 37<br />
TCP/IP configuration . . . . . . . . . 37<br />
Verifying the TCP/IP installation . . . . 37<br />
Next steps . . . . . . . . . . . 38<br />
TCP62 configuration . . . . . . . . . 38<br />
© Copyright IBM Corp. 1996, 2002 iii
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
On z/OS . . . . . . . . . . . . 40<br />
On <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS . . 40<br />
On the workstation . . . . . . . . 41<br />
Firewall implications . . . . . . . . 41<br />
KeepAlive packets . . . . . . . . . 41<br />
Next steps . . . . . . . . . . . 42<br />
SNA configuration (AIX only) . . . . . . 42<br />
Configuring SNA for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for AIX . . . . . . . . . 42<br />
Data conversion. . . . . . . . . . . 44<br />
Configuring message queues . . . . . . 44<br />
Chapter 5. Configuration . . . . . . . 47<br />
Before you start. . . . . . . . . . . 48<br />
Gather information. . . . . . . . . 48<br />
Configure your programming environment 48<br />
Recommended Java options for the Solaris<br />
JVM. . . . . . . . . . . . . . 49<br />
Using the configuration tool . . . . . . 49<br />
Running the configuration tool on a<br />
different operating system . . . . . . 50<br />
The configuration tool interface . . . . 51<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings . . . . . . . . . . . . 53<br />
Configuring Client settings . . . . . . 66<br />
Configuring Server settings . . . . . . 70<br />
Trace settings . . . . . . . . . . 78<br />
Editing the configuration file . . . . . . 80<br />
J2EE setup and configuration . . . . . . 81<br />
Deploying <strong>CICS</strong> resource adapters . . . 81<br />
Tracing. . . . . . . . . . . . . 86<br />
Sample configuration and mapping files . . 87<br />
Keyboard mapping for cicsterm . . . . . 88<br />
Keyboard mapping file syntax . . . . . 88<br />
The keyboard mapping file . . . . . . 88<br />
Customizing the screen colors for cicsterm . . 90<br />
Color mapping syntax . . . . . . . 91<br />
The color mapping file . . . . . . . 91<br />
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support . . . . . . . . . . 92<br />
Chapter 6. Network Security . . . . . . 93<br />
Determining your use of SSLight or JSSE for<br />
the SSL and HTTPS protocols . . . . . . 94<br />
SSLight . . . . . . . . . . . . . 94<br />
Conflict with JSSE . . . . . . . . . 94<br />
Maintaining your digital certificates for<br />
SSLight . . . . . . . . . . . . 94<br />
Using externally signed certificates under<br />
SSLight . . . . . . . . . . . . 95<br />
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under<br />
SSLight . . . . . . . . . . . . 100<br />
Java Secure Socket Extension (JSSE) . . . . 104<br />
Migration from SSLight . . . . . . . 104<br />
Installation . . . . . . . . . . . 104<br />
Maintaining your digital certificates for<br />
JSSE . . . . . . . . . . . . . 105<br />
Using externally signed certificates under<br />
JSSE . . . . . . . . . . . . . 105<br />
Using self-signed certificates under JSSE 110<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
SSL and HTTPS . . . . . . . . . . 114<br />
SSL and HTTPS configuration settings 114<br />
Specifying a client KeyRing or KeyStore 115<br />
Using the SSL and HTTPS protocols . . 115<br />
Chapter 7. Client Security . . . . . . 117<br />
Overview . . . . . . . . . . . . 117<br />
Default connection settings. . . . . . . 118<br />
ECI security. . . . . . . . . . . . 118<br />
EPI terminal security. . . . . . . . . 118<br />
Password expiry management . . . . . 119<br />
Signon capable and signon incapable<br />
terminals. . . . . . . . . . . . . 120<br />
Mainframe <strong>CICS</strong> servers . . . . . . 121<br />
TXSeries and <strong>CICS</strong> OS/2 servers. . . . 123<br />
<strong>CICS</strong>/400 servers . . . . . . . . . 123<br />
Chapter 8. Performance . . . . . . . 125<br />
Assessing system performance . . . . . 125<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration . . 126<br />
Java considerations . . . . . . . . . 128<br />
Other system factors . . . . . . . . . 128<br />
Tracing . . . . . . . . . . . . . 129<br />
Performance monitoring tools. . . . . . 130<br />
Chapter 9. Operating the <strong>Gateway</strong> . . . 131<br />
Before you start . . . . . . . . . . 131<br />
Starting the <strong>Gateway</strong>. . . . . . . . . 132<br />
Starting the <strong>Gateway</strong> with preset options 132<br />
Starting the <strong>Gateway</strong> with user-specified<br />
options . . . . . . . . . . . . 132<br />
Stopping the <strong>Gateway</strong> . . . . . . . . 134<br />
Administering your system . . . . . . 135<br />
Setting the <strong>Gateway</strong> trace . . . . . . 135<br />
Setting the JNI trace . . . . . . . . 135<br />
Querying trace settings . . . . . . . 135<br />
Parameters . . . . . . . . . . . 136<br />
Chapter 10. Operating the Client daemon 139
The cicscli command. . . . . . . . . 139<br />
The cicscli command. . . . . . . . . 139<br />
Starting the Client daemon. . . . . . 140<br />
Starting connections with additional<br />
servers . . . . . . . . . . . . 140<br />
Stopping the Client daemon in a<br />
controlled manner . . . . . . . . 140<br />
Stopping the Client daemon immediately 141<br />
Restarting the Client daemon in a<br />
controlled manner . . . . . . . . 141<br />
Restarting the Client daemon<br />
immediately . . . . . . . . . . 141<br />
Starting client tracing . . . . . . . 142<br />
Specifying the trace components . . . . 142<br />
Stopping client tracing . . . . . . . 142<br />
Security considerations for trace and log<br />
files . . . . . . . . . . . . . 142<br />
Setting up security . . . . . . . . 143<br />
<strong>Version</strong> information . . . . . . . . 143<br />
Listing the connected servers . . . . . 144<br />
Disabling the display of messages . . . 144<br />
Enabling and disabling the display of<br />
console messages . . . . . . . . . 144<br />
Displaying the command parameters . . 145<br />
The cicscli command and applications 145<br />
cicscli command reference . . . . . . . 145<br />
Chapter 11. Terminal Emulation . . . . 151<br />
Summary of Terminal Emulation commands 151<br />
The cicsterm command . . . . . . . . 151<br />
Using cicsterm . . . . . . . . . . 152<br />
Stopping a terminal emulator . . . . . 153<br />
cicsterm and user exits . . . . . . . 153<br />
cicsterm and RETURN TRANSID<br />
IMMEDIATE . . . . . . . . . . 153<br />
Using X-Windows Clients . . . . . . 153<br />
Using cicsterm with an XTERM window 154<br />
cicsterm command reference . . . . . . 154<br />
The cicsprnt command . . . . . . . . 157<br />
Using cicsprnt . . . . . . . . . . 157<br />
cicsprnt and user exits . . . . . . . 158<br />
cicsprnt and RETURN TRANSID<br />
IMMEDIATE . . . . . . . . . . 158<br />
cicsprnt command reference . . . . . . 158<br />
Chapter 12. The Terminal Servlet program 163<br />
What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Terminal Servlet? . . . . . . . . . . 163<br />
Installing and configuring the Terminal<br />
Servlet . . . . . . . . . . . . . 165<br />
Configuring the Web server’s<br />
CLASSPATH and PATH settings . . . . 166<br />
Adding the Terminal Servlet to the Web<br />
server’s configuration . . . . . . . 166<br />
Configuring the servlet initialization<br />
parameters . . . . . . . . . . . 166<br />
Considering other configuration options 170<br />
Loading the Terminal Servlet . . . . . 171<br />
Using the Terminal Servlet. . . . . . . 171<br />
Connecting to <strong>CICS</strong> and starting a<br />
transaction . . . . . . . . . . . 171<br />
Invoking the Terminal Servlet . . . . . 171<br />
What happens next? . . . . . . . . 173<br />
Displaying screens and fields . . . . . 173<br />
Sending the screen back to <strong>CICS</strong>. . . . 175<br />
Setting the AID . . . . . . . . . 175<br />
Disconnecting . . . . . . . . . . 176<br />
Properties and parameters reference . . . 176<br />
Servlet configuration properties . . . . 177<br />
Page mapping properties . . . . . . 179<br />
Request parameters . . . . . . . . 180<br />
Displayable properties . . . . . . . 181<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web<br />
Interface . . . . . . . . . . . . . 182<br />
Chapter 13. Problem determination and<br />
problem solving. . . . . . . . . . 183<br />
Preliminary checks . . . . . . . . . 183<br />
What to do next . . . . . . . . . 184<br />
Problems with the <strong>Gateway</strong> daemon . . . 184<br />
Messages . . . . . . . . . . . 184<br />
Tracing . . . . . . . . . . . . 185<br />
Diagnosing common problems: <strong>Gateway</strong><br />
daemon . . . . . . . . . . . . 188<br />
Problems with the Client daemon . . . . 194<br />
Messages . . . . . . . . . . . 194<br />
Tracing . . . . . . . . . . . . 195<br />
Diagnosing common problems: Client<br />
daemon . . . . . . . . . . . . 203<br />
Program support . . . . . . . . . . 212<br />
Reporting problems . . . . . . . . 212<br />
Documenting problems . . . . . . . 213<br />
Locating and compiling information . . 214<br />
Submitting the documentation . . . . 215<br />
APARs and fixes . . . . . . . . . 215<br />
Chapter 14. Migration . . . . . . . . 217<br />
The configuration conversion tool . . . . 217<br />
Using the conversion tool . . . . . . 218<br />
Contents v
|<br />
|<br />
|<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> 4. . . . . . . . . . . . . 218<br />
Migrating from <strong>CICS</strong> Universal Client, or<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, <strong>Version</strong> 3 . . . 219<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java . . 219<br />
Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong><br />
on AIX . . . . . . . . . . . . . 220<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> default settings 220<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> override settings 221<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> actions 222<br />
Administration functions . . . . . . 223<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Lotus<br />
Notes . . . . . . . . . . . . . 223<br />
Configuring APPC for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for AIX . . . . . . . . . . 224<br />
EPI beans provided in earlier versions of the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . . . . . . 224<br />
Appendix A. Data conversion when using<br />
the Client daemon and a <strong>CICS</strong> server . . 225<br />
Supported conversions . . . . . . . . 225<br />
Appendix B. Hardware and software. . . 229<br />
Hardware requirements. . . . . . . . 229<br />
Supported software . . . . . . . . . 230<br />
Operating systems . . . . . . . . 230<br />
Web browsers . . . . . . . . . . 231<br />
Telnet clients . . . . . . . . . . 231<br />
JDK levels . . . . . . . . . . . 232<br />
JSSE . . . . . . . . . . . . . 232<br />
<strong>CICS</strong> Servers . . . . . . . . . . 232<br />
Web servers. . . . . . . . . . . 233<br />
Application servers . . . . . . . . 233<br />
SNA communications . . . . . . . 233<br />
TCP/IP communications . . . . . . 234<br />
TCP62 communications . . . . . . . 234<br />
Compilers and application development<br />
tools . . . . . . . . . . . . . 234<br />
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Screen readers . . . . . . . . . . 234<br />
Other tools . . . . . . . . . . . 235<br />
GPL licence and copyright issues on<br />
Linux . . . . . . . . . . . . . 235<br />
The product library and related literature 237<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 237<br />
Sample configuration documents. . . . . 238<br />
Redbooks . . . . . . . . . . . . 239<br />
Other Useful Books . . . . . . . . . 239<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 239<br />
APPC-related publications . . . . . . 240<br />
TCP62–related publications . . . . . 240<br />
Obtaining books from IBM. . . . . . . 240<br />
Accessibility . . . . . . . . . . . 241<br />
Documentation . . . . . . . . . . 241<br />
iKeyMan. . . . . . . . . . . . . 241<br />
Samples . . . . . . . . . . . . . 241<br />
Configuration tool accessibility . . . . . 241<br />
Components . . . . . . . . . . 241<br />
Keys . . . . . . . . . . . . . 241<br />
Customizing colors and fonts . . . . . 243<br />
Using help . . . . . . . . . . . 243<br />
Task Guide . . . . . . . . . . . 244<br />
Glossary . . . . . . . . . . . . 245<br />
Index . . . . . . . . . . . . . 257<br />
Notices . . . . . . . . . . . . . 265<br />
Trademarks . . . . . . . . . . . . 266<br />
Sending your comments to IBM . . . . 269
About this book<br />
This book describes the planning, installation, configuration, and operation, of<br />
the IBM ® <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> product.<br />
You should be familiar with the operating system on which your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> runs, and also with Internet terminology.<br />
Summary of changes Read this for information on functional changes made in this<br />
version of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Chapter 1, “Overview” Read this for an overview of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and<br />
the functions it provides.<br />
Chapter 2, “Planning<br />
your installation”<br />
Chapter 3,<br />
“Installation”<br />
Chapter 4, “Setting up<br />
communication with<br />
<strong>CICS</strong> servers”<br />
Chapter 5,<br />
“Configuration”<br />
Chapter 6, “Network<br />
Security”<br />
Chapter 7, “Client<br />
Security”<br />
Chapter 8,<br />
“Performance”<br />
Chapter 9, “Operating<br />
the <strong>Gateway</strong>”<br />
Chapter 10,<br />
“Operating the Client<br />
daemon”<br />
Chapter 12, “The<br />
Terminal Servlet<br />
program”<br />
Read this for information on planning your installation,<br />
including the hardware and software you need to run <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to install <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Read this for information on how to set up communication<br />
links between <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers.<br />
Read this for information on how to configure your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to set up <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> to use the network security protocols SSL and<br />
HTTPS.<br />
Read this for information on how to provide a userid and<br />
password when connecting to a <strong>CICS</strong> server.<br />
Read this for information on how to tune your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, and other system components, to<br />
achieve the best possible performance.<br />
Read this for information on how to operate the <strong>Gateway</strong><br />
daemon.<br />
Read this for information on how to operate the Client<br />
daemon of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to use the Terminal Servlet<br />
to access <strong>CICS</strong> 3270 applications using a Web browser.<br />
© Copyright IBM Corp. 1996, 2002 vii
Chapter 13, “Problem<br />
determination and<br />
problem solving”<br />
Chapter 14,<br />
“Migration”<br />
Appendix A, “Data<br />
conversion when<br />
using the Client<br />
daemon and a <strong>CICS</strong><br />
server”<br />
The product library<br />
and related literature<br />
Read this for information on problem determination and<br />
problem solving.<br />
Read this if you are currently using an earlier version of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or <strong>CICS</strong> Universal Client.<br />
Read this for information on the conversion of character data<br />
as it passes between the Client daemon of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> and a <strong>CICS</strong> server.<br />
Read this for information on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
product library and related literature, and the various forms<br />
in which it is available.<br />
Accessibility Read this for information on the accessibility features of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Notices Read this for important information on the availability of<br />
IBM products and service in different countries, and also on<br />
issues concerning patents, licenses, and trademarks.<br />
Sending your<br />
comments to IBM<br />
Read this for information on how to send your comments to<br />
IBM.<br />
Conventions and terminology used in this book<br />
A number of parts, both internal and external to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, are used when creating a business solution using the product.<br />
Figure 1 on page ix shows some of the possible scenarios you will encounter,<br />
and the terminology used in each case.<br />
viii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Distributed platforms running in remote mode<br />
Java client<br />
application<br />
z/OS running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Distributed platforms running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
Client<br />
daemon<br />
Distributed platforms running non-Java applications<br />
Client<br />
application<br />
Client<br />
daemon<br />
z/OS running in remote mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Client<br />
daemon<br />
<strong>CICS</strong><br />
server<br />
<strong>CICS</strong><br />
server<br />
Figure 1. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses, with their associated terminology<br />
<strong>CICS</strong><br />
server<br />
The following explains the terms used in Figure 1:<br />
<strong>Gateway</strong> daemon<br />
Used only in remote mode, the <strong>Gateway</strong> daemon listens on protocols<br />
defined in CTG.INI for gateway requests from remote Java client<br />
applications. It issues these requests to the Client daemon on<br />
distributed platforms, and directly to <strong>CICS</strong> over the EXCI on z/OS ® .<br />
The <strong>Gateway</strong> daemon runs the protocol listener threads, the worker<br />
threads and the connection manager threads. It uses the GATEWAY<br />
section of CTG.INI (and on z/OS the ctgenvvar script) for its<br />
configuration.<br />
Client daemon<br />
The Client daemon (process cclclnt) exists only on distributed<br />
platforms. It manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending and receiving the<br />
appropriate flows from the <strong>CICS</strong> server to satisfy the application<br />
requests. It uses the CLIENT section of CTG.INI for its configuration.<br />
About this book ix
<strong>Gateway</strong> classes<br />
The interface for Java Client applications to connect to the <strong>Gateway</strong><br />
daemon. The <strong>Gateway</strong> classes, which are supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, must be in the classpath for Java Client<br />
applications to run.<br />
Client application<br />
A user application, written in a supported programming language<br />
other than Java, that communicates directly with the Client daemon.<br />
Java Client application<br />
A Java application, servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Installation path<br />
The term is used in file paths to represent the directory where<br />
you installed the product. The default installation locations for each operating<br />
system are shown in Table 1:<br />
Table 1. Default <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> installation locations<br />
Operating System Default installation location<br />
Windows ®<br />
c:\Program Files\IBM\IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
AIX ®<br />
/usr/lpp/ctg<br />
Linux, HP-UX, Solaris /opt/ctg<br />
z/OS A ctg subdirectory of the directory from which the<br />
installation was run. For example, if the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> was installed by the command<br />
ctginstall in the /usr/lpp directory, the<br />
is /usr/lpp/ctg<br />
Programming language specific<br />
The term C refers to both the C and C++ programming languages.<br />
Operating system specific<br />
Unless otherwise specified, the term Windows refers to Windows NT ® ,<br />
Windows 2000, and Windows XP.<br />
The term Windows 2000 Terminal Server means a server with the Terminal<br />
Services feature installed.<br />
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.<br />
Syntax notation<br />
The syntax of commands is shown in a standard way. This syntax, commonly<br />
known as railroad syntax, is described in Table 2 on page xi. You interpret the<br />
syntax by following the arrows from left to right, and from top to bottom,<br />
x <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
along the main path line.<br />
Table 2. Command syntax conventions<br />
Symbol Meaning<br />
Required items appear on the main path line.<br />
►► AB ►◄<br />
►► A<br />
B<br />
C<br />
►►<br />
►►<br />
►►<br />
A B<br />
A<br />
B<br />
C<br />
A<br />
B<br />
C<br />
►► ▼ A<br />
►► ▼<br />
A<br />
B<br />
C<br />
B<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
Punctuation and uppercase<br />
characters<br />
Lowercase characters appearing<br />
like this<br />
If there is more than one required item to choose<br />
from, the items are stacked vertically. This is a set of<br />
alternatives—one of which you must specify.<br />
Optional items appear below the main path line.<br />
If there is more than one optional item to choose<br />
from, the items are stacked vertically below the<br />
main path line. This is a set of alternatives—one of<br />
which you may specify.<br />
If one item in a set of alternatives is the default, this<br />
item appears above the main path line and all other<br />
items are stacked vertically below the line.<br />
An arrow returning to the left above items on the<br />
main path line means that the items can be repeated.<br />
Such items may be either required or optional.<br />
An arrow returning to the left above a set of items<br />
means that more than one item can be selected or<br />
that a single item can be repeated.<br />
Note: For <strong>CICS</strong>, unless otherwise stated, this<br />
representation means only that more than one item<br />
can be selected.<br />
Code exactly as shown.<br />
Code your own text, as appropriate. For example,<br />
with FILE(name) you must specify FILE and ()<br />
unchanged, but are free to specify any valid text<br />
string for the name of your file.<br />
About this book xi
xii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Summary of changes<br />
The following functional changes have been made for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>:<br />
v The Binary Trace Formatter utility has been enhanced to format SNA and<br />
MPTN data structures within TCP62 data flows. See “Formatting the binary<br />
trace file” on page 197.<br />
v A systems administration function allows you to set options for <strong>Gateway</strong><br />
and JNI traces, to start and stop these traces, and to query trace settings;<br />
see “Administering your system” on page 135. Using the CTG_JNI_TRACE<br />
environment variable to enable JNI tracing is supported only for migration<br />
purposes.<br />
v The way that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes log messages has changed:<br />
– Each message entry begins with the current date in the format<br />
month/day/year.<br />
– <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes error and warning messages to<br />
standard error (stderr), and information messages to standard output<br />
(stdout); see “Messages” on page 184.<br />
– A new gateway configuration setting, Log client connections and<br />
disconnections, controls whether <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes a<br />
message each time that a client application program connects to, or<br />
disconnects from, the <strong>Gateway</strong> daemon. See “Log client connections and<br />
disconnections” on page 56.<br />
v Some beans that were previously provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product are now, instead, included with the set of sample<br />
programs. See “EPI beans provided in earlier versions of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>” on page 224 for details.<br />
v Java Secure Socket Extension (JSSE) is supported.<br />
This gives 128 bit encryption capability and is IBM’s recommended solution<br />
for SSL. For compatibility with previous versions of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, this version supports both JSSE and SSLight. However, support<br />
for SSLight might be removed in a future release.<br />
This edition replaces SC34-5933, SC34-5934, SC34-5936, SC34-5937, SC34-5941,<br />
SC34-5942, SC34-5943, and SC34-5944.<br />
Vertical lines at the left side of the page indicate material that is new to this<br />
edition.<br />
© Copyright IBM Corp. 1996, 2002 xiii
xiv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 1. Overview<br />
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides secure, easy access from Web<br />
browsers and network computers to <strong>CICS</strong> applications, using standard<br />
Internet protocols in a range of configurations. It is a robust and scalable<br />
complement to a Web server. You can implement it as an e-business connector<br />
for IBM WebSphere ® Application Server, which is a J2EE-compliant runtime<br />
environment for Java servlets. An API is provided that allows Java<br />
programmers to take advantage of features provided in J2EE-compliant<br />
runtime environments.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs on a wide variety of operating systems. On<br />
the Windows and UNIX ® operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
access many different types of <strong>CICS</strong> server. On z/OS <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> can access only <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS. See “Supported<br />
software” on page 23 for information on supported operating systems and<br />
<strong>CICS</strong> servers.<br />
On the Windows and UNIX operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
uses a Client daemon to route External Call Interface (ECI), External Presentation<br />
Interface (EPI), and External Security Interface (ESI) requests to a <strong>CICS</strong> server<br />
(see “The external access interfaces (ECI, EPI, ESI)” on page 3). On z/OS, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can route only ECI requests, and has no Client daemon.<br />
© Copyright IBM Corp. 1996, 2002 1
Overview<br />
Network<br />
computer<br />
Java-enabled<br />
browser<br />
Figure 2 shows how a web client can access <strong>CICS</strong> programs and data. Note<br />
that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is shown as installed on a Web server<br />
machine. This is necessary only if you are using the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> with Java applets or servlets.<br />
HTTP<br />
HTTPS<br />
SSL<br />
TCP<br />
HTTP<br />
Figure 2. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Server machine<br />
Web server<br />
<strong>CICS</strong><br />
<strong>Transaction</strong><br />
<strong>Gateway</strong><br />
Java application<br />
<strong>CICS</strong><br />
server<br />
Communication between <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the client application<br />
uses the following protocols:<br />
v Transmission control protocol/Internet protocol (TCP/IP) sockets<br />
v Hypertext Transfer Protocol (HTTP)<br />
v Secure Sockets Layer (SSL)<br />
v HTTP over SSL (HTTPS)<br />
TCP/IP sockets and SSL provide an efficient method of communication for<br />
intranet applications. Where firewalls exist, HTTP, and its secure alternative<br />
HTTPS, are effective communication protocols for internet applications. See<br />
“Network security” on page 6.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can manage many concurrent links to connected<br />
Web browsers. It can also control asynchronous conversations to multiple<br />
<strong>CICS</strong> servers. The multithreaded architecture of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
enables a single gateway to support multiple concurrently connected users.<br />
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
Local<br />
EPI<br />
ESI<br />
ECI
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
A <strong>Gateway</strong> daemon<br />
For security reasons, this is usually resident on a Web server workstation. It<br />
communicates with <strong>CICS</strong> applications running on <strong>CICS</strong> servers through ECI,<br />
EPI, or ESI.<br />
The <strong>Gateway</strong> classes<br />
This Java library includes classes that:<br />
v provide Application Programming Interfaces (APIs) for ECI, EPI, and ESI<br />
This allows communication between Java applications, or Java servlets, and<br />
the <strong>Gateway</strong> daemon.<br />
v allow client applications to communicate with transactions on a server and<br />
to handle 3270 data streams<br />
v allow your applications to use the SSL network security protocol<br />
J2EE resource adapters<br />
Use these to provide a J2EE-compliant interface to <strong>CICS</strong> for your applications.<br />
A Client daemon<br />
The Client daemon can support concurrent, ECI and EPI, calls to one or more<br />
<strong>CICS</strong> servers.<br />
The Client daemon can communicate with multiple <strong>CICS</strong> servers using a<br />
variety of protocols. See “Communication between the <strong>Gateway</strong> and <strong>CICS</strong><br />
servers” on page 27. Support for a protocol may be provided by one or more<br />
communication software products, so you can use the products best suited to<br />
your network environment. See “Supported software” on page 23.<br />
The way the client operates, and the servers and protocols used for<br />
communication, are defined in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization<br />
file. You can use the configuration tool to define these settings. See Chapter 5,<br />
“Configuration” on page 47.<br />
The external access interfaces (ECI, EPI, ESI)<br />
The external access interfaces allow non-<strong>CICS</strong> applications to access and<br />
update <strong>CICS</strong> resources by initiating <strong>CICS</strong> transactions, or by calling <strong>CICS</strong><br />
programs. When used in conjunction with the <strong>CICS</strong> communication facilities,<br />
they enable non-<strong>CICS</strong> programs to access and update resources on any <strong>CICS</strong><br />
system. This supports such activities as developing graphical user interface<br />
(GUI) front ends for <strong>CICS</strong> applications, and allows the integration of <strong>CICS</strong><br />
systems and non-<strong>CICS</strong> systems.<br />
These APIs are provided for both Java and non-Java programming languages.<br />
Chapter 1. Overview 3
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
External Call Interface (ECI)<br />
The ECI enables a non-<strong>CICS</strong> client application to call a <strong>CICS</strong> program<br />
synchronously, or asynchronously. It enables the design of new applications to<br />
be optimized for client/server operation, with the business logic on the server<br />
and the presentation logic on the client.<br />
External Presentation Interface (EPI)<br />
The EPI enables a non-<strong>CICS</strong> client application to act as a logical 3270 terminal<br />
and so control a <strong>CICS</strong> 3270 application. It enables modern technologies, such<br />
as graphical or multimedia interfaces, to be used with traditional <strong>CICS</strong> 3270<br />
applications.<br />
External Security Interface (ESI)<br />
ESI enables non-<strong>CICS</strong> client applications to invoke services provided by APPC<br />
password expiry management (PEM). This allows non-<strong>CICS</strong> applications to verify<br />
that a password matches that recorded by an external security manager (ESM)<br />
for a specified user ID. ESI also allows you to change passwords.<br />
For more information on the external access interfaces, see <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Reference.<br />
A Terminal Servlet<br />
This allows you to use a Web browser as an emulator for a 3270 <strong>CICS</strong><br />
application running on any <strong>CICS</strong> server. The Terminal Servlet can be used<br />
with a Web server, or servlet engine. The Terminal Servlet provides an<br />
alternative to using EPI. For information on supported Web servers, refer to<br />
“Supported software” on page 23.<br />
Additional functions<br />
3270 terminal emulation (cicsterm)<br />
<strong>CICS</strong> 3270 terminal emulation enables a <strong>Gateway</strong> system to function as a 3270<br />
display for <strong>CICS</strong> applications, without needing a separate 3270 emulator<br />
product. Multiple <strong>CICS</strong> 3270 emulation sessions can run to one or more <strong>CICS</strong><br />
servers.<br />
You can use mapping files to customize the client emulator’s screen color<br />
attributes and keyboard settings, for example, to comply with company<br />
standard keyboard layouts.<br />
<strong>CICS</strong> Client terminal definitions (with some exceptions, see Table 5 on<br />
page 28) are autoinstalled at most <strong>CICS</strong> server systems, and do not have to be<br />
predefined at the server.<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Additional functions<br />
3270 printer support (cicsprnt)<br />
<strong>CICS</strong> 3270 printer support allows you to define a printer terminal on a<br />
<strong>Gateway</strong> system. This enables <strong>CICS</strong> applications running on a server to send<br />
output to a printer attached to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You can send output to a physical printer or you can specify a command to<br />
process the data into a format more suitable for special-purpose printers.<br />
<strong>CICS</strong> 3270 printer support uses <strong>CICS</strong> 3270 terminal emulation functions. See<br />
Table 5 on page 28 for information on which <strong>CICS</strong> servers currently support<br />
<strong>CICS</strong> 3270 emulation and hence <strong>CICS</strong> 3270 client printer support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: local control<br />
Commands are provided to:<br />
v Control the <strong>Gateway</strong> daemon<br />
You can:<br />
– Specify the TCP/IP port on which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> listens.<br />
– Specify an initial number of ConnectionManager threads<br />
– Specify a maximum number of ConnectionManager threads<br />
– Specify an initial number of Worker threads<br />
– Specify a maximum number of Worker threads<br />
– Enable standard tracing<br />
– Disable the reading of input from the console<br />
– Specify the file to which trace output is written<br />
– Enable full debug tracing<br />
– Specify the maximum size of the trace output file<br />
– Specify the maximum size of any data blocks that are shown in the trace<br />
– Enable the display of symbolic TCP/IP hostnames in messages<br />
– Specify the offset from which displays of any data blocks start<br />
– Enable Java exception stack tracing<br />
– Pass an argument to the JVM<br />
v Control the Client daemon<br />
You can:<br />
– Start or stop the client daemon<br />
– Turn client trace on or off<br />
– Specify the client components to be traced<br />
– Set up security by specifying user IDs and passwords for a <strong>CICS</strong> server<br />
– List connected servers<br />
– Enable and disable the display of messages<br />
– Perform controlled restarts of the client daemon<br />
v Control terminal emulation<br />
You can:<br />
– Start and stop the terminal emulator<br />
– Specify the initial transaction<br />
Chapter 1. Overview 5
|<br />
|<br />
|<br />
|<br />
|<br />
Additional functions<br />
– Define the terminal characteristics<br />
– Specify the name of the keyboard and screen color mapping files<br />
– Define the command used to process print requests<br />
– Specify the name of a file used for appending print requests<br />
v Control client printer operation<br />
You can:<br />
– Start and stop the client printer emulator<br />
– Specify the initial transaction to be run against the client printer<br />
– Define the printer terminal characteristics<br />
– Define the command used to process print requests<br />
– Specify the name of a file used for appending print requests.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: remote control<br />
You can:<br />
v Set the trace for the <strong>Gateway</strong> daemon<br />
v Set JNI trace<br />
v Query trace options<br />
Network security<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides comprehensive support for secure<br />
communication, which is critical to successful Internet operation. The secure<br />
network protocols SSL and HTTPS allow your client applications to<br />
communicate securely with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Network security<br />
and its implementation on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is discussed in detail in<br />
Chapter 6, “Network Security” on page 93; the following sections summarize<br />
the functions provided by SSL and HTTPS.<br />
The characteristics of secure communication are:<br />
Confidentiality<br />
The content of messages remains private as they pass over the<br />
Internet, or your intranet.<br />
Data exchanged between the client and the server is encrypted. Only<br />
your client (your application or servlet) and your server (the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>) can make sense of the data.<br />
Integrity<br />
Messages are not altered during transmission.<br />
Integrity guarantees that the message you sent reaches the recipient<br />
intact. Encryption and digital signatures ensure integrity.<br />
Accountability<br />
The sender and the receiver both agree that the exchange took place.<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Network security<br />
Accountability settles any disputes over whether the message was<br />
sent and received. Digital signatures ensure accountability, so that you<br />
can identify who is responsible if something goes wrong.<br />
Authenticity<br />
You know who you are talking to and you can trust that person.<br />
Authenticity requires verification of identities, so that you can be sure<br />
that others are who they say they are. Digital signatures and digital<br />
certificates ensure authenticity.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s implementation of the SSL protocol<br />
provides server authentication. This means that when a client<br />
establishes a connection with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, it must<br />
authenticate the server’s details. You can also enable client<br />
authentication. This means that the server will authenticate the client’s<br />
details.<br />
Encryption<br />
Encryption ensures confidentiality in transmissions sent over the Internet. In<br />
its simplest form, encryption is the scrambling of a message so that it cannot<br />
be read until it is unscrambled later by the receiver. The sender uses an<br />
algorithmic pattern, or key, to encrypt the message, and the receiver uses a<br />
decryption key to unscramble the message.<br />
Two kinds of key can be used for encryption:<br />
1. Symmetric keys<br />
The sender and receiver use the same key to encrypt and decrypt the<br />
message. The risk with symmetric keys is that you need a safe<br />
transportation method to use when sending your key to the people with<br />
whom you want to communicate.<br />
2. Asymmetric keys<br />
These consists of a pair of keys: a public key and a private key. Unlike<br />
symmetric keys, these are different from each other. The private key holds<br />
more of the secret encryption pattern than the public key.<br />
A sender sends its public key to anyone it wants to communicate with<br />
securely. It retains the private key and protects it with a password. Only<br />
the sender can decrypt a received message encrypted with its public key,<br />
because only it has the private key.<br />
Asymmetric key encryption is also known as public key encryption.<br />
SSL uses both asymmetric and symmetric key encryption. It uses public key<br />
(asymmetric) encryption as a safe way of sharing a symmetric key between<br />
server and client. This symmetric key is then used to encrypt and decrypt all<br />
data transferred on the SSL connection. This encryption protects the data from<br />
Chapter 1. Overview 7
Network security<br />
other parties that try to eavesdrop and ensures that private information, such<br />
as credit card numbers, can be transferred securely. See “Authentication using<br />
SSL” on page 10.<br />
Digital signatures and digital certificates<br />
A digital signature is a unique, mathematically computed, signature that<br />
ensures accountability.<br />
A digital certificate allows unique identification of an entity; it is essentially an<br />
electronic ID card, issued by a trusted third party. Digital certificates form part<br />
of the ISO authentication framework, also known as the X.509 protocol. This<br />
framework provides for authentication across networks.<br />
A digital certificate serves two purposes: it establishes the owner’s identity,<br />
and it makes the owner’s public key available. A digital certificate is issued by<br />
a certification authority (CA), for example VeriSign, or Thawte. It is issued for<br />
only a limited time, and when its expiry date has passed, it must be replaced.<br />
A digital certificate consists of:<br />
v The public key of the person being certified<br />
v The name and address of the person being certified, also known as the<br />
Distinguished Name (DN)<br />
v The digital signature of the CA<br />
v The issue date<br />
v The expiry date<br />
The Distinguished Name is the name and address of a person or organization.<br />
You enter your Distinguished Name as part of requesting a certificate. The<br />
digitally-signed certificate includes not only your own Distinguished Name,<br />
but the Distinguished Name of the CA, which allows verification of the CA.<br />
To communicate securely, the receiver in a transmission must trust the CA<br />
that issued the certificate that the sender is using. This means that, when a<br />
sender signs a message, the receiver must have the corresponding CA’s signer<br />
certificate and public key designated as a trusted root key. For example, your<br />
Web browser has a default list of signer certificates for trusted CAs. If you<br />
want to trust certificates from another CA, you must receive a certificate from<br />
that CA and designate it as a trusted root key.<br />
If you send your digital certificate containing your public key to someone<br />
else, what keeps that person from misusing your digital certificate and posing<br />
as you? The answer is: your private key.<br />
A digital certificate alone is not proof of anyone’s identity. The digital<br />
certificate allows verification only of the owner’s identity, by providing the<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
Network security<br />
public key needed to check the owner’s digital signature. Therefore, the digital<br />
certificate owner must protect the private key that belongs with the public key<br />
in the digital certificate. If the private key were stolen, anyone could pose as<br />
the legitimate owner of the digital certificate.<br />
Obtaining a digital certificate<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows you to obtain digital certificates in two<br />
ways. You can buy externally-signed certificates from a CA, or you can<br />
establish yourself as a CA to allow you to issue self-signed X.509 certificates.<br />
Externally-signed certificates are more suitable for Internet use, while<br />
self-signed certificates might be suitable for internal use within an<br />
organization.<br />
Buying a certificate from a certification authority<br />
If you plan to conduct commercial business on the Internet, buy a server<br />
certificate from a CA such as VeriSign or Thawte.<br />
When you submit a certificate request to a CA, they require you to prove who<br />
you are before they issue you a certificate. The approval process is necessary<br />
to protect you, your organization, and the CA. The CA will digitally sign your<br />
certificate request and return the unique certificate to you by e-mail.<br />
Issuing certificates yourself<br />
If you act as a CA, you can sign your own or anyone else’s certificate request.<br />
This is a good choice if you need the certificates only within your own<br />
organization, and not for external Internet commerce. You may choose to<br />
allow access to only a carefully controlled group of key people within your<br />
intranet.<br />
Your key people should have browsers, such as Netscape Navigator, that can<br />
receive your self-signed CA certificate and designate it as a trusted root. They<br />
can then trust your communications and share information safely.<br />
See Chapter 6, “Network Security” on page 93 for more information on<br />
obtaining digital certificates.<br />
KeyRings and KeyStores<br />
Digital certificates, public keys, private keys, and trusted root keys are kept in<br />
special types of file which the security protocols can use:<br />
v SSLight, System SSL, and HTTPS use Java class files called KeyRings<br />
v Java Secure Socket Extension (JSSE) uses files called KeyStores<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses KeyRings and KeyStores to hold information<br />
about certificates and keys on both the SSL server and SSL clients. See<br />
“SSLight” on page 94, and “Java Secure Socket Extension (JSSE)” on page 104,<br />
for information on how to create these files. The SSL and HTTPS protocols<br />
Chapter 1. Overview 9
Network security<br />
require access to these files to establish secure connections. See “Configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS” on page 114 for information<br />
on how to provide this access.<br />
Authentication using SSL<br />
SSL allows the client to authenticate the identity of the server. This is called<br />
server authentication.<br />
SSL <strong>Version</strong> 3 also allows the server to authenticate a client. This is called<br />
client authentication, and is used if the server needs to check who a client is<br />
before responding. If SSL client authentication is enabled, the server requests<br />
the client’s certificate whenever the client makes an SSL connection. The<br />
server validates the DN information in the client request against the DN<br />
information in the client’s certificate before serving the document.<br />
SSL uses public key (asymmetric) encryption for a security “handshake” when<br />
establishing a TCP/IP connection between the client and the server. Figure 3<br />
on page 11 illustrates SSL handshaking with server authentication. During the<br />
handshake, the client receives the server’s digital (X.509) certificate. The client<br />
authenticates the server, using a list of known CAs. Also, if the client requests<br />
a document protected by SSL client authentication, the server requests the<br />
client’s certificate. The client then generates a random symmetric key and<br />
encrypts it using server’s public key. SSL then uses the symmetric key to<br />
encrypt and decrypt all of the information in both the client request and the<br />
server response, including:<br />
v The URL the client is requesting<br />
v The contents of any form being submitted<br />
v Authentication information, such as user names and passwords<br />
v All data sent between the client and the server<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Client Server<br />
Client issues secure session request<br />
(https.//someserver.org/somedata.html)<br />
Server sends X.509 certificate containing server’s public key<br />
Client authenticates certificate against list of known CA’s<br />
(If CA is unknown browser can give user option to accept certificate at user’s risk)<br />
Client generates random symmetric key and encrypts it using server’s public key<br />
Client and server now both know the symmetric key<br />
and encrypt end-user data using symmetric key for duration of session<br />
Figure 3. SSL handshaking with server authentication<br />
Network security<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports the following implementations of SSL:<br />
SSLight<br />
An implementation of SSL that is written in pure Java.<br />
This protocol is supported for compatibility with previous<br />
versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for<br />
SSLight might be removed in a future release.<br />
JSSE<br />
Another Java implementation, that provides support for 128<br />
bit encryption.<br />
IBM recommends that you use JSSE in preference to SSLight.<br />
See “Migration from SSLight” on page 104, for more<br />
information.<br />
System SSL<br />
Chapter 1. Overview 11
Network security<br />
This implementation, which is written in native code, is<br />
supported only for SSL servers on z/OS. It supports hardware<br />
encryption technology available to the z/OS operating system.<br />
HTTPS<br />
HTTPS is a protocol that combines SSL and HTTP, and is used for handling<br />
secure transactions. You specify https:// as an anchor in HTML documents<br />
that link to documents protected by SSL. A client user can also open a URL by<br />
specifying https:// to request an SSL-protected document.<br />
Because HTTPS and HTTP are different protocols, and usually use different<br />
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests<br />
at the same time. This allows you to provide information to all users using no<br />
security, and specific information only to browsers which make secure<br />
requests. This is how retail companies on the Internet allow users to look<br />
through the merchandise without security, but then fill out order forms and<br />
send their credit card numbers using security.<br />
Security exits<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides exits that enable the user to define<br />
security operations such as public key encryption. They may also be used for<br />
data compression. Some example source files are provided in this directory:<br />
/samples/java/com/ibm/ctg/samples/security<br />
Java technology<br />
You can also use the security exits to authenticate an X.509 client certificate<br />
when client authentication is enabled.<br />
For more information, refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide book.<br />
This section discusses the Java language, including the types of program that<br />
can be developed, and the security implications.<br />
The Java language<br />
Java is an interpreted object-oriented language, similar to C++. It can be used<br />
to build programs that are independent of operating systems in both source<br />
and object form. Its unique operational characteristics, which span Web<br />
browsers as well as Web servers, enable new and powerful functions in<br />
Internet applications.<br />
To achieve operating system independence, the Java language allows no<br />
operations that are dependent on specific operating system. Also, it excludes<br />
some C++ functions such as a preprocessor, operator overloading, multiple<br />
inheritances, and pointers. All Java programming is encapsulated within<br />
classes, and the Java Development Kit (JDK) includes special classes that are<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
critical to assuring operating system independence, including GUI functions,<br />
input/output functions, and network communications.<br />
The Java compiler produces an intermediate bytecode format that is machine<br />
independent. This, in turn, is processed at run time by a Java interpreter. The<br />
interpreter also inspects the bytecode at run time to ensure its validity and<br />
safety to the machine environment. Because of the isolation the Java<br />
interpreter provides, it is sometimes referred to as a Java Virtual Machine<br />
(JVM).<br />
The Java language can be used to construct Java servlets, Java applets, and Java<br />
applications.<br />
Java applets<br />
Java applets are supported for compatibility with previous versions of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be removed in a<br />
future release. It is recommended that you use Java applications, or Java<br />
servlets, when developing new solutions.<br />
Java servlets<br />
Java servlets are small Java applications that run on a Web server machine,<br />
unlike Java applets, which are downloaded to a Web browser.<br />
Java servlets have become popular as a replacement for CGI (Common<br />
<strong>Gateway</strong> Interface) programs. The advantage of Java servlets over CGI<br />
applications is that they can execute more quickly since they are invoked as<br />
threads in a daemon process, meaning that they are persistent in memory and<br />
can fulfill multiple requests.<br />
Note that servlets must ensure references to the gateway objects are<br />
thread-safe.<br />
Java technology<br />
Java applications<br />
A Java application is a program that executes locally on a computer. It has<br />
operating system dependent capabilities in addition to those of an applet. It<br />
can access local files, create and accept general network connections, and call<br />
native C or C++ functions in machine-specific libraries.<br />
Java applications can use the <strong>CICS</strong>-provided Java classes to perform<br />
transaction processing in <strong>CICS</strong> systems. They can use the Java<strong>Gateway</strong> class<br />
to establish two kinds of connection:<br />
v A network gateway connection is a connection across a network to a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
v A local gateway enables a Java application to communicate directly with a<br />
<strong>CICS</strong> <strong>Transaction</strong> Server, without the need for a network.<br />
Chapter 1. Overview 13
Java technology<br />
JavaBeans <br />
When the connection between the application and the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> has been established, an application can use the ECIRequest class,<br />
for example, to do transaction processing.<br />
The JavaBeans API, developed by Sun Microsystems, allows you to write<br />
component software in Java. Components are self-contained, reusable software<br />
units that you can build into servlets using visual application builder tools.<br />
Any JDK <strong>Version</strong> 1.1-compliant browser or tool supports JavaBeans.<br />
JavaBeans components are called beans. Most builder tools allow you to<br />
maintain beans in a palette or toolbox. You can select a particular bean from<br />
the toolbox, drop it onto a form, modify its appearance and behavior, and<br />
define how it interacts with other beans. You can build your selected bean<br />
and other beans into a servlet, or new bean, without actually writing any<br />
code. For more information on JavaBeans, see the Sun Web site<br />
(www.java.sun.com).<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides EPI Java bean samples based on<br />
high-level EPI interfaces. These beans allow you easily to create Java<br />
programs that access data from existing <strong>CICS</strong> 3270 applications, without any<br />
programming. Using a bean composer tool, you can quickly and easily create<br />
new Java front-ends that can connect to <strong>CICS</strong>, run transactions, display data<br />
from 3270 screens, and send user input back to the <strong>CICS</strong> server. For more<br />
information, see the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Firewalls<br />
A current design consideration in the use of Java applet communication is the<br />
impact of firewalls. This is the term given to a configuration of software that<br />
prevents unauthorized traffic between a trusted network and an untrusted<br />
network. Firewalls are put in place to protect company assets from outside<br />
intrusion, but they can also limit legitimate communications. Firewalls have<br />
two functions:<br />
1. To restrict access to a server by outside users - inbound restrictions<br />
2. To limit the ability of users inside a firewall to perform certain network<br />
functions outside their firewall - outbound restrictions.<br />
A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration is well suited to avoid problems in<br />
the first area since the <strong>Gateway</strong> processor can be placed outside the firewall<br />
and be connected through the firewall to the <strong>CICS</strong> server. Outbound firewalls<br />
that users may have to contend with can be a problem. A large company<br />
might use a firewall to limit the types of connections and protocols that can<br />
be used.<br />
The use of Java on an intranet (a local implementation of the Internet) works<br />
very well since firewalls are typically not a factor. If you are designing<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Java technology<br />
applications to run over the Internet (rather than an intranet), determine<br />
whether your potential users are behind firewalls. If so, consider alternative<br />
processing for those users, such as executing the Java code as a Java servlet<br />
on the Web server. Also consider using HTTP and HTTPS protocols supported<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Authentication using SSL” on page 10 and<br />
“HTTPS” on page 12.<br />
Web servers<br />
A Web server is a software program that responds to information requests<br />
generated by Web browsers. When a request from a browser is received, the<br />
Web server processes the request to determine the action to take:<br />
v Return the requested document.<br />
v Deny the request.<br />
v Pass the request through for further processing by an external application.<br />
The request might be, for example, to a database to perform a search<br />
request, or to a more dynamic form of information delivery such as Lotus ®<br />
Domino .<br />
Communication between a Web server and an external application is<br />
transparent; you need to know only the URL of the Web server to direct a<br />
request to it. Also, all Web servers can handle requests from many browsers<br />
concurrently.<br />
Specialized servers can also be configured to limit access to a restricted set of<br />
users, or to provide security for purchase of goods or services.<br />
Web servers exist for almost every operating system and are available from<br />
many suppliers. For information on the Web servers supported by <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, see “Supported software” on page 23.<br />
The J2EE resource adapters<br />
An API in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java programmers to take<br />
advantage of features provided in J2EE-compliant runtime environments (e.g.<br />
IBM WebSphere Application Server). The J2EE resource adapter defines a<br />
standard architecture for connecting the Java 2 Platform, Enterprise Edition<br />
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as <strong>CICS</strong>.<br />
The resource adapter architecture defines a set of scalable, secure, and<br />
transactional mechanisms that enable the integration of EISs with application<br />
servers and enterprise applications.<br />
A proprietary application server, such as IBM WebSphere, can be extended to<br />
support the resource adapter architecture, and is then assured of a seamless<br />
Chapter 1. Overview 15
Introduction<br />
connectivity to multiple EISs. Similarly, a vendor provides a standard resource<br />
adapter that can connect any application server that supports the resource<br />
adapter architecture to an EIS.<br />
The resource adapter architecture defines a Common Client Interface (CCI) for<br />
EIS access. The CCI defines a client API for interacting with heterogeneous<br />
EISs. The resource adapter architecture enables a vendor such as IBM to<br />
provide a standard resource adapter to allow access to its product. This<br />
resource adapter connects to an application server and provides connectivity<br />
between the EIS, the application server, and the enterprise application.<br />
The Programming using J2EE chapter in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide describes the J2EE resource adapters. The chapter includes information<br />
on the J2EE samples which are provided.<br />
The samples.txt file, in the \samples subdirectory, provides<br />
additional information on the J2EE sample programs.<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses <strong>CICS</strong><br />
This section describes how <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java servlets to<br />
access <strong>CICS</strong> programs and data.<br />
1. The Web server loads and initializes the servlet. This could be when the<br />
Web server starts, or when the first request is made to the servlet by the<br />
Web browser or network computer.<br />
2. The servlet creates a Java<strong>Gateway</strong> object to connect to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. This establishes communication between the<br />
browser and the long running <strong>Gateway</strong> daemon process using Java’s<br />
sockets protocol.<br />
3. When a HTTP request from the Web browser or network computer<br />
invokes the servlet, the Web server calls its Service method with details<br />
of the request.<br />
4. The servlet creates an ECIRequest, EPIRequest, orESIRequest object,<br />
that contains ECI, EPI, or ESI calls, and sends it to the <strong>Gateway</strong> daemon<br />
using the Java<strong>Gateway</strong>.flow method.<br />
5. The <strong>Gateway</strong> daemon receives, and unpacks the request. The Client<br />
daemon makes corresponding ECI, EPI, or ESI calls to the <strong>CICS</strong> server.<br />
6. The <strong>CICS</strong> server processes the calls, including verification of the userid<br />
and password if required, and passes control and user data to the <strong>CICS</strong><br />
application program.<br />
7. When the <strong>CICS</strong> application program has finished processing, it returns<br />
control and data to <strong>CICS</strong>.<br />
8. The <strong>CICS</strong> server returns control and data to the Client daemon.<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
9. The <strong>Gateway</strong> daemon packs these results and returns them to the Java<br />
servlet.<br />
10. When the servlet receives the results, it generates a HTTP response to<br />
return to the Web browser.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a multithreaded model for handling<br />
network connections, and for assigning threads for requests from, and replies<br />
to, Java clients. The threading model uses the following objects:<br />
ConnectionManagers<br />
A ConnectionManager manages all the connections from a particular Java<br />
client. When it receives a request, it allocates a Worker thread from a pool of<br />
available Worker threads to execute the request.<br />
Workers<br />
A Worker is the object that actually executes a request from a Java client<br />
application. Each Worker object has its own thread, which is activated when<br />
there is some work to do. When a worker thread has finished processing it<br />
returns to the pool of available worker threads.<br />
You can set both the initial and maximum sizes of the resource pools for these<br />
objects; see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings” on page 53 for<br />
information on setting configuration parameters. You can also specify these<br />
limits when you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Starting the<br />
<strong>Gateway</strong> with user-specified options” on page 132.<br />
Table 3 shows thread limits that should be considered when setting the<br />
number of Connection Manager and Worker threads on the various operating<br />
systems:<br />
Table 3. Thread limits on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating systems<br />
Operating<br />
system<br />
System-wide limit of<br />
the maximum number<br />
of threads<br />
z/OS This may be restricted<br />
by the total number of<br />
MVS ® Task Control<br />
Blocks (one is created<br />
per UNIX System<br />
Services thread)<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses <strong>CICS</strong><br />
Process limit of the number of threads<br />
Governed by the UNIX System Services<br />
parameters: MAXTHREADS and<br />
MAXTHREADTASKS<br />
Windows No limit Limited by the amount of virtual memory<br />
available for the process (by default a<br />
thread has 1M of stack meaning that 2028<br />
threads can be created per process)<br />
Chapter 1. Overview 17
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
Table 3. Thread limits on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating systems (continued)<br />
Operating<br />
system<br />
System-wide limit of<br />
the maximum number<br />
of threads<br />
AIX 262 143 32 768<br />
HP-UX No limit (30 000 kernel<br />
threads)<br />
Linux Equal to the maximum<br />
number of processes<br />
Solaris No limit No limit<br />
Process limit of the number of threads<br />
30 000 (refer to Configurable Kernel<br />
Parameters in the SAM utility)<br />
1024 (refer to your LinuxThreads<br />
documentation for more information)<br />
For more information on the way Java allocates memory for threads, refer to<br />
“Performance issues” in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
book.<br />
The threading model is illustrated in the following figures:<br />
Figure 4. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for TCP/IP and SSL. These protocols have a persistent socket.<br />
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request brokers<br />
Figure 5. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for HTTP/HTTPS. These protocols do not have a persistent<br />
socket.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and object request brokers<br />
Some Web servers contain an object request broker (ORB) that conforms to the<br />
Object Management Group’s (OMG) Common Object Request Broker<br />
(CORBA) standard. If you have such a Web server, you can develop servlet<br />
objects that can be invoked from a remote browser using the CORBA Internet<br />
InterORB Protocol (IIOP). IIOP is transmitted to the browser using HTTP.<br />
Chapter 1. Overview 19
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 2. Planning your installation<br />
This chapter helps you to plan the installation of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> by listing the hardware and software that you need. For information<br />
about hardware and software requirements on all supported operating<br />
systems, see Appendix B, “Hardware and software” on page 229. The <strong>CICS</strong><br />
servers to which <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can connect are also listed.<br />
The Chapter consists of the following topics:<br />
“Hardware requirements” on page 22 Read this for information about the<br />
hardware you need to run your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (processor type,<br />
memory, disk space).<br />
“Supported software” on page 23 Read this for information about the<br />
software products that are supported for<br />
use with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“<strong>CICS</strong> server PTF requirements” on<br />
page 26<br />
“Communication between the <strong>Gateway</strong><br />
and <strong>CICS</strong> servers” on page 27<br />
Read this for information about APARs<br />
and PTFs (service updates) for <strong>CICS</strong><br />
servers.<br />
Read this for information about the<br />
communications protocols you can use to<br />
connect to your <strong>CICS</strong> servers.<br />
“DBCS Multibyte Characters” on page 29 Read this for information about support<br />
for multibyte characters.<br />
If you are using an earlier version of the product, or a <strong>CICS</strong> Universal Client,<br />
see Chapter 14, “Migration” on page 217 for a discussion of migration issues.<br />
See the product readme file for any late changes to hardware and software<br />
requirements.<br />
If you are installing from CD, the readme file is in the root directory:<br />
Operating system README file<br />
AIX README.AIX<br />
HP-UX README.HPUX<br />
Linux README.LNX<br />
Solaris README.SOL<br />
© Copyright IBM Corp. 1996, 2002 21
Planning<br />
Hardware requirements<br />
If you have downloaded the product, the packaged file that you downloaded<br />
contains the product code and the readme file for your operating system.<br />
When you install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the file is copied into your<br />
installation directory as readme.txt.<br />
Table 4. Hardware requirements on UNIX systems<br />
AIX LINUX SOLARIS HP-UX<br />
Processor v IBM RISC<br />
System/6000 ®®<br />
v IBM RS/6000 ®®<br />
Scalable<br />
POWERParallel<br />
System (SP2 ® G5, G6, MP3000 or<br />
above<br />
SPARC PA-RISC 1.1 or 2.0<br />
).<br />
Terminals Any type of<br />
terminal or<br />
X/Terminal that<br />
can attach to the<br />
processor.<br />
Any standard<br />
telnet or X based<br />
terminal that can<br />
access Linux.<br />
Any type of<br />
terminal or<br />
X/Terminal that<br />
can attach to the<br />
processor.<br />
Any standard<br />
telnet or X based<br />
terminal that can<br />
access HP-UX.<br />
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB<br />
Disk space 30MB,plus30MB<br />
for temporary files<br />
used during<br />
installation.<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
30MB,plus30MB<br />
for temporary files<br />
used during<br />
installation.<br />
30MB,plus30MB<br />
for temporary files<br />
used during<br />
installation.<br />
30MB,plus30MB<br />
for temporary files<br />
used during<br />
installation.
Supported software<br />
The following products are supported.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v AIX V4.3.3 with Service Pack 25<br />
v AIX 5.1<br />
v HP-UX 11.0<br />
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)<br />
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)<br />
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)<br />
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)<br />
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)<br />
Web browsers<br />
Supported software<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft ® Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
v HotJava Browser V 1.1 (for Solaris)<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
Telnet clients<br />
If you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> over telnet, certain telnet clients can<br />
cause problems with the display. For example, your telnet session might<br />
truncate message lines over a certain length. This is usually a problem with<br />
the telnet client that you are using, or the terminal type that you are going in<br />
as. Currently there is no solution to this problem.<br />
Chapter 2. Planning your installation 23
Supported software<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v AIX: IBM Java SDK 1.3 (service release 6)<br />
v HP-UX: Java SDK 1.3.0.02<br />
v Solaris: Sun Java SDK SE 1.3.0_04.<br />
JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– AIX: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
– HP-UX: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Linux for S/390: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Solaris: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied.<br />
v <strong>CICS</strong> for MVS/ESA V4.1, with communication through SNA. (with APAR<br />
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for<br />
EPI emulation. APAR PN79262 is needed for DBCS support.<br />
v <strong>CICS</strong> for OS/400 ® V4.4<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for OS/2 ® V4.1 with CSD 3<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA 1.1.0 (with APAR PQ30170, for<br />
signon capable terminals, applied), or a minimum service level of 1.1.1<br />
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)<br />
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
v TXSeries V<strong>5.0</strong> (Windows, AIX)<br />
Supported software<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,<br />
AIX and Solaris.<br />
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.<br />
SNA communications<br />
Customers wishing to use SNA communications should install one of the<br />
following products:<br />
AIX<br />
IBM eNetwork Communications Server V6.1, with a minimum of service<br />
level 1 (AIX).<br />
SNA is not supported on other UNIX operating systems.<br />
TCP/IP communications<br />
TCP/IP support is provided by the operating system.<br />
TCP62 communications<br />
TCP62 support is provided by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Compilers and application development tools<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following compilers and<br />
application development tools:<br />
AIX<br />
v IBM C for AIX V4.4<br />
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6<br />
v IBM VisualAge ® C++ Professional V4.0<br />
v IBM VisualAge C++ Professional V<strong>5.0</strong> (requires AIX version 4.2 or later)<br />
HP-UX<br />
v HP ANSI C B.11.01, with a minimum of service level 7<br />
v HP aC++ B.11.01, with a minimum of service level 6<br />
Linux for S/390<br />
v GNU compiler C runtime V2.95, with a minimum of service level 2<br />
v GNU compiler C++ runtime V2.95, with a minimum of service level 2<br />
Solaris<br />
Sun WorkShop C++ V<strong>5.0</strong><br />
Chapter 2. Planning your installation 25
|<br />
|<br />
|<br />
Supported software<br />
Note: The C++ compiler must have all available service patches applied.<br />
Other tools<br />
These tools are available for viewing the PDF online documents:<br />
v Adobe Acrobat Reader V<strong>5.0</strong><br />
v GhostView V4.0 on Linux<br />
GPL licence and copyright issues on Linux<br />
This product uses the following libraries from the glibc package: libnsl.so,<br />
libm.so, libdl.so, ld.so, libc.so and libpthread.so. Refer to the glibc package on<br />
your machine for the various copyright statements and licensing terms for<br />
these libraries.<br />
This product also uses libncurses.so from the ncurses package. Again, refer to<br />
this package on your machine for the copyright statement and licensing terms<br />
applicable to this library.<br />
IMPORTANT: Your use of the libstdc++ or egcs-c++ packages is subject to the<br />
GNU GPL licence terms which could require you to provide source code in<br />
certain circumstances. Note that IBM will not supply source code, for example<br />
for the <strong>CICS</strong> <strong>Gateway</strong>s C++ libraries.<br />
<strong>CICS</strong> server PTF requirements<br />
See the README file for the latest details on APARs and PTFs applicable to<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Terminal Signon capability<br />
<strong>CICS</strong> Servers require APAR fixes to support the terminal signon capability<br />
function available in this release; see “Supported software” on page 23 for<br />
details of the APAR relating to your <strong>CICS</strong> server. If the server does not have<br />
the required APAR applied and the ’-a’ option is not specified on <strong>CICS</strong>TERM,<br />
the installed terminal will give unpredictable results.<br />
Timeout support<br />
To provide complete support for timeouts, if you are using any TXSeries or<br />
<strong>Transaction</strong> Server on UNIX and Windows operating systems, it must include<br />
the appropriate PTF level; see “Supported software” on page 23 for details.<br />
If the server does not have the required APAR applied and the ’-a’ option is<br />
not specified on <strong>CICS</strong>TERM, this happens:<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> displays the message: CCL7053E Errors<br />
found while communicating with server<br />
v CCL3105 Inbound <strong>CICS</strong> datastream error (CTIN, 4, 0) is written to<br />
<strong>CICS</strong>CLI.LOG<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v On the server, the message: ERZ042004E/0112: An invalid request was<br />
received from client is written to CSMT.out<br />
v console.msg includes this: ERZ014016E/0036: <strong>Transaction</strong> CTIN Abend A42B<br />
Communication between the <strong>Gateway</strong> and <strong>CICS</strong> servers<br />
Supported software<br />
You can use these protocols to communicate with <strong>CICS</strong> servers:<br />
TCP/IP Transmission Control Protocol/Internet Protocol (TCP/IP) is a<br />
widely used, robust, suite of protocols, particularly important<br />
in connecting heterogeneous networks.<br />
SNA (AIX operating system only)<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses Advanced<br />
program-to-program communication (APPC) to provide SNA<br />
LU 6.2 communication. APPC is an implementation of the<br />
SNA LU 6.2 protocol that provides device-independent<br />
application-to-application communication over LU 6.2<br />
sessions.<br />
TCP62 TCP62 is a communications mechanism that allows<br />
connections from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to a <strong>Transaction</strong><br />
Server for z/OS region over an IP network. It uses IBM’s<br />
Multiprotocol Transport Networking (MPTN) protocol<br />
switching technology to send LU6.2 Systems Network<br />
Architecture (SNA) flows over an IP network.<br />
The protocols that you can use for the various client/server connections are<br />
shown in Table 5 on page 28. This table lists the protocols that you can use to<br />
connect your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to your <strong>CICS</strong> server. It also shows<br />
whether ECI, EPI emulation, and Autoinstall are supported for your<br />
combination of <strong>CICS</strong> server and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating system.<br />
Chapter 2. Planning your installation 27
Communication protocols<br />
Table 5. Protocols and functions supported. If a protocol or feature is supported by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> only on certain operating systems, the operating systems are listed. Otherwise, *<br />
means supported on Windows and all UNIX operating systems; V means not supported.<br />
SERVER TCP/IP SNA TCP62 ECI<br />
<strong>CICS</strong> for MVS/ESA<br />
V4.1<br />
<strong>CICS</strong> for OS/400<br />
V4.4<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for OS/2 V4.1<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS V1.2<br />
and V1.3<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA<br />
V1.1.0 and V1.1.1<br />
V<br />
*<br />
*<br />
V<br />
V<br />
<strong>CICS</strong>/VSE V2.3 V<br />
TXSeries V4.2<br />
(HP-UX)<br />
TXSeries V4.3 (AIX,<br />
Solaris, Windows )<br />
*<br />
*<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
AIX<br />
Windows<br />
* *<br />
EPI<br />
Emulation<br />
See note<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
ESI<br />
*<br />
* * * *<br />
V * * V<br />
* *<br />
V *<br />
V *<br />
Windows<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
AIX<br />
HP-UX<br />
Solaris<br />
AIX<br />
HP-UX<br />
Solaris<br />
Windows<br />
V * * V<br />
V * * V<br />
Note: EPI always incorporates <strong>CICS</strong> 3270 terminal emulation and <strong>CICS</strong> 3270<br />
client printer support.<br />
All servers support autoinstall. This means that you do not need to predefine<br />
the client to the <strong>CICS</strong> server; control table definitions are automatically<br />
created for the client at the <strong>CICS</strong> server. For <strong>CICS</strong>/VSE, autoinstall is possible<br />
via LU 6.2 single session only. This restriction does not affect <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA.<br />
Restrictions on <strong>CICS</strong> for OS/400<br />
The following restrictions apply:<br />
v DBCS languages are not supported.<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
*<br />
V<br />
V
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Communication protocols<br />
v Signon capable terminals are not supported.<br />
v You cannot start the CEDA transaction from a client terminal.<br />
v You cannot use PF1 to get <strong>CICS</strong> online help from a client terminal.<br />
Why use a particular protocol?<br />
As shown in table 5 some protocols can be used only for certain types of<br />
client/server connection.<br />
If you need to connect different types of networks, for example, Token Ring<br />
and Ethernet networks, consider using TCP/IP.<br />
TCP62 allows access to <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS over a TCP/IP<br />
network. Partner LU62 applications can communicate without complex SNA<br />
configuration definitions on the client, and without any changes to the LU62<br />
applications on the client or server. If you require easy client access to <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS over your TCP/IP network, use the TCP62<br />
support. For information on configuring TCP62, see “TCP62 configuration” on<br />
page 38.<br />
DBCS Multibyte Characters<br />
Some characters in certain codesets are represented with 3 or more bytes. The<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for the UNIX operating systems does not support<br />
multibyte characters that are longer than 2 bytes. If you try to display such<br />
characters on a <strong>CICS</strong> terminal, you will get unpredictable results.<br />
If you are running on an AIX or Solaris-unique locale, you might experience<br />
problems when connecting to certain <strong>CICS</strong> servers. The table below lists the<br />
relevant client/server combinations.<br />
<strong>CICS</strong> Client Codepage <strong>CICS</strong> Server operating<br />
system<br />
<strong>CICS</strong> Server Codepage<br />
ja_JP (33722) OS/2 932<br />
ja_JP (33722) Windows NT 932<br />
ja_JP (33722) AIX 932<br />
ko_KR (970) OS/2 949<br />
ko_KR (970) Windows 949<br />
zh_TW (964) OS/2 950<br />
zh_TW (964) AIX 950<br />
zh_CN (1383) OS/2 1381<br />
zh_CN (1383) Windows NT 1381<br />
Chapter 2. Planning your installation 29
Communication protocols<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 3. Installation<br />
This chapter describes how to install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It consists<br />
of the following:<br />
“Installing the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>”<br />
Read this for detailed instructions on how<br />
to install your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“National language support” on page 33 Read this for information on:<br />
v Changing the language in which the<br />
<strong>Gateway</strong> displays user messages<br />
v Using alternative code sets<br />
“Using X-Windows from a remote Read this for information on how to<br />
system” on page 35<br />
access z/OS applications from a remote<br />
system.<br />
“Uninstalling the <strong>CICS</strong> <strong>Transaction</strong> Read this if you wish to uninstall the<br />
<strong>Gateway</strong>” on page 35<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Installing the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
To install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
1. Log in as root.<br />
2. Stop any Client daemon that is running (issue the cicscli -i command).<br />
AIX<br />
3. Run the slibclean command to remove any unused libraries.<br />
End of AIX<br />
4. The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is distributed as a compressed tar or rpm<br />
file containing an executable script file. When run, the script file creates<br />
the library files, commands, messages and customization (.INI) files. Find<br />
the file on the distribution medium. Figure 6 on page 32 lists the filenames.<br />
© Copyright IBM Corp. 1996, 2002 31
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
Operating system File name<br />
AIX ctg-500x.tar.Z<br />
HP-UX ctg-500h.tar.Z<br />
Linux ctg-<strong>5.0</strong>.0-1.s390.rpm<br />
Solaris ctg-500s.tar.Z<br />
Figure 6. Installation files<br />
5. Copy the tar file to a working directory on your hard disk.<br />
6. Proceed as follows:<br />
AIX, HP-UX and Solaris<br />
Uncompress the file and extract the files:<br />
uncompress <br />
tar -xf <br />
where is the filename in Figure 6 for your<br />
operating system, and is the same name without<br />
the .Z.<br />
This creates a script file called ctginstall in the current directory.<br />
Linux<br />
Issue the following command:<br />
rpm -Uvh ctg-<strong>5.0</strong>.0-1.s390.rpm<br />
This creates a command ctginstall.<br />
7. Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> by entering:<br />
ctginstall<br />
8. Read and accept the license agreement to continue the installation. If the<br />
agreement does not display properly, restart the installation using the<br />
command ctginstall 40. This sets your screen width to 40 characters<br />
during installation.<br />
To view the license agreement after installation, issue the command<br />
ctgbrowse. If the agreement does not display properly, issue the command<br />
ctgbrowse 40.<br />
9. On all operating systems except AIX, refer to “Configuring message<br />
queues” on page 44 for advice on configuring your system to allow large<br />
client data flows.<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
National language support<br />
You can select the language in which user messages are displayed by the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> by entering the command:<br />
ctgmsgs XX <br />
where XX is the two character message language. To obtain a list of available<br />
languages, enter the command without parameters. Figure 7 shows the<br />
output:<br />
<strong>CICS</strong> Client for AIX - User messages<br />
-----------------------------------<br />
Language Locale Code Set<br />
--------------------- --------- -----------us<br />
US English en_US ISO8859-1<br />
EN_US UTF-8<br />
fr French fr_FR ISO8859-<br />
FR_FR UTF-8<br />
de German de_DE ISO8859-1<br />
DE_DE UTF-8<br />
it Italian it_IT ISO8859-1<br />
IT_IT UTF-8<br />
es Spanish es_ES ISO8859-1<br />
ES_ES UTF-8<br />
tr Turkish tr_TR ISO8859-9<br />
TR_TR UTF-8<br />
jp Japanese Ja_JP IBM-943<br />
ja_JP IBM-eucJP<br />
JA_JP UTF-8<br />
kr Korean ko_KR IBM-eucKR<br />
KO_KR UTF-8<br />
cn Simplified Chinese zh_CN IBM-1386<br />
zh_CN IBM-eucCN<br />
ZH_CN UTF-8<br />
Syntax: ctgmsgs <br />
Figure 7. Output from the ctgmsgs command (AIX system)<br />
National language support<br />
This also shows the locale and code set associated with the language.<br />
Using an alternative code set on AIX<br />
On AIX issue the command smitty iconv to use an alternate code set.<br />
This provides the Convert Flat File screen, on which you can enter<br />
parameters:<br />
Chapter 3. Installation 33
National language support<br />
Convert Flat File<br />
Type or select values in entry fields.<br />
Press Enter AFTER making all desired changes.<br />
[Entry Fields]<br />
* CURRENT FILE / DIRECTORY name []<br />
* CURRENT CODE set [] +<br />
* NEW FILE / DIRECTORY name []<br />
* NEW CODE set [] +<br />
F1=Help F2=Refresh F3=Cancel F4=List<br />
Esc+5=Reset F6=Command F7=Edit F8=Image<br />
F9=Shell F10=Exit Enter=Do<br />
Fill in this screen as follows:<br />
CURRENT FILE / DIRECTORY name<br />
Enter /CCLMSG.TXT<br />
CURRENT CODE set<br />
Enter the code set for the language you selected with ctgmsgs.<br />
NEW FILE / DIRECTORY name<br />
Enter the name of the new file.<br />
NEW CODE set<br />
Enter the alternative code set. You can view a list of the alternative<br />
code sets using the smitty lang command, which is used to set the<br />
language environment. For example, the code set IBM-850 is an<br />
alternative for the US English code set ISO8859-1.<br />
When you have done the conversion, overwrite the CCLMSG.TXT file with<br />
the new file.<br />
Using an alternative code set (other UNIX platforms)<br />
To use an alternate code set, use the iconv routine for the flat file<br />
/CCLMSG.TXT. For example, to convert<br />
/CCLMSG.TXT from code set ISO8859-1 to code set ISO-850<br />
enter:<br />
iconv -f ISO8859-1 -t ISO-850 /CCLMSG.TXT > CCLMSG.NEW<br />
When you have done this conversion, you can overwrite the CCLMSG.TXT<br />
file with the new file:<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
mv CCLMSG.NEW /CCLMSG.TXT<br />
Using X-Windows from a remote system<br />
When using X-Windows from a remote system, for example, to access the<br />
configuration tool and iKeyman, you must set up the DISPLAY environment<br />
variable to allow the application to display its windows on that system.<br />
On the display system (that is the one that will display the windows), enter<br />
the command:<br />
xhost +appl<br />
where appl is the network name of the system being used to run the<br />
application.<br />
On the application system, before you run the application, enter the<br />
command:<br />
DISPLAY=disp:0.0<br />
followed by<br />
export DISPLAY<br />
where disp is the host name or IP address of the system where the windows<br />
will be displayed (followed by a colon and the display id—normally 0.0). The<br />
application windows are then displayed on the disp system.<br />
Uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
To uninstall the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> issue the command:<br />
ctguninst<br />
National language support<br />
On Linux, the command rpm -e ctg-<strong>5.0</strong>.0-1 also uninstalls the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Chapter 3. Installation 35
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 4. Setting up communication with <strong>CICS</strong> servers<br />
After you have installed the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and set up your <strong>CICS</strong><br />
servers for communication, your next step is to set up the communication<br />
links between the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and your <strong>CICS</strong> servers. This<br />
chapter consists of the following:<br />
“TCP/IP configuration” Read this if you will use TCP/IP.<br />
“TCP62 configuration” on page 38 Read this if you will use TCP62.<br />
“Data conversion” on page 44 Read this for information on how data<br />
may be converted as it passes between<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a<br />
<strong>CICS</strong> server.<br />
“Configuring message queues” on page 44 Read this if you are running HP-UX,<br />
LINUX or Solaris, for information on<br />
configuring your system for large data<br />
flows.<br />
A number of sample configuration documents provide step-by-step guidance<br />
on configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers for different<br />
scenarios. If one of the documents covers your desired configuration, simply<br />
follow the instructions in it. See “Sample configuration documents” on<br />
page 238.<br />
After you have set up your communications links, continue at Chapter 5,<br />
“Configuration” on page 47. This tells you how to make the required entries<br />
in the configuration file.<br />
TCP/IP configuration<br />
The TCP/IP stack on your local machine should already be correctly<br />
configured. Contact your system administrator if there are problems.<br />
Verifying the TCP/IP installation<br />
To verify that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can communicate with <strong>CICS</strong><br />
servers, use the TCP/IP PING command to check the route to the <strong>CICS</strong><br />
server:<br />
ping [machine address | name]<br />
To start PING, enter a command like the following:<br />
ping 192.113.36.200<br />
© Copyright IBM Corp. 1996, 2002 37
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
TCP/IP configuration<br />
where 192.113.36.200 is the IP the address of your <strong>CICS</strong> server. If you are<br />
using a Domain Name Server (DNS), you can specify the symbolic hostname<br />
rather than the IP address of the server.<br />
To stop the PING command, press the Ctrl+C keys simultaneously.<br />
If TCP/IP is configured correctly, you see messages as shown in the following<br />
figure:<br />
ping 192.113.36.200 56 3<br />
PING 192.113.36.200: 56 data bytes<br />
64 bytes from 192.113.36.200: icmp_seq=0 ttl=255 time=3 ms<br />
64 bytes from 192.113.36.200: icmp_seq=1 ttl=255 time=3 ms<br />
64 bytes from 192.113.36.200: icmp_seq=2 ttl=255 time=3 ms<br />
----192.113.36.200 PING Statistics----<br />
3 packets transmitted, 3 packets received, 0% packet loss<br />
round-trip min/avg/max = 3/3/3 ms<br />
#<br />
Figure 8. Example messages returned by ping command<br />
If the statistics message shows a value other than 0% packet loss, it is possible<br />
that TCP/IP is not correctly configured:<br />
v Check for TCP/IP definition errors.<br />
v Check the physical connection to the network.<br />
The PING command differs slightly, depending on your operating system. For<br />
more information, refer to the documentation supplied with your operating<br />
system. This example is from an AIX machine.<br />
Refer to “TCP/IP settings” on page 72 for information on TCP/IP settings.<br />
Next steps<br />
1. Use the configuration tool to create a server definition; see “The<br />
configuration tool interface” on page 51.<br />
2. Configure the server definition (see “TCP/IP settings” on page 72):<br />
Specify TCP/IP as the protocol.<br />
Enter the hostname or IP address of your <strong>CICS</strong> server.<br />
TCP62 configuration<br />
The TCP62 support for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows communication with<br />
<strong>CICS</strong> for MVS/ESA <strong>Version</strong> 4.1 and later over a TCP/IP network.<br />
On <strong>CICS</strong> for MVS/ESA <strong>Version</strong> 4.1 and <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS,<br />
you can use autoinstall to define SNA client connections. The advantage of<br />
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
autoinstall is that it allows you to use the same client configuration settings<br />
for all workstations without having to define multiple entries in VTAM ® and<br />
<strong>CICS</strong>. Autoinstall allows the Client Local LU name and CP name to be created<br />
from a template and IP address of the client machine.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> TCP62 communication supports only<br />
parallel-session SNA connections, not single-session connections. This has<br />
implications for your <strong>CICS</strong> VTAM configuration, as explained in “On z/OS”<br />
on page 40.<br />
TCP62 links to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support data synchronization<br />
levels (sync levels) 0 and 1.<br />
Enabling <strong>CICS</strong> on z/OS to communicate with a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
using TCP62 requires actions on z/OS, <strong>CICS</strong>, and the client workstation. This<br />
section outlines the steps you need to take. For more details, see “Sample<br />
configuration documents” on page 238, and “Redbooks” on page 239. You also<br />
need to make entries in the configuration file; see Chapter 5, “Configuration”<br />
on page 47.<br />
Table 6 shows the entries that you need to make. The values in the Example<br />
column are taken from the sample configuration documents.<br />
Table 6. Matching definitions for TCP62 on z/OS, <strong>CICS</strong>, and configuration file.<br />
z/OS <strong>CICS</strong> configuration tool Client workstation Example<br />
IP address - - 2.12.14.227<br />
DNSUFX - AnyNet ® domain<br />
name suffix<br />
hursley.ibm.com<br />
NETID - Partner LU name. The<br />
Partner LU name is<br />
NETID.APPL.<br />
ABC3XYZ4<br />
APPL Applid Partner LU name IYCKCTU1<br />
LOGMODE Modename Mode name LU62PS<br />
IP address mask for<br />
LU name template<br />
(optional)<br />
TCP/IP subnet mask FFFFFE00<br />
Fully qualified CP<br />
name or template<br />
Local LU name or<br />
template<br />
TCP62 configuration<br />
ABC3XYZ4.PQRS1234<br />
CCLI****<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 39
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
TCP62 configuration<br />
On z/OS<br />
1. Define the TCP/IP address and hostname for the z/OS system in the MVS<br />
TCP/IP PROFILE.TCPIP and TCPIP.DATA data sets.<br />
2. Install a TCP major node, which defines the AnyNet interface between<br />
TCP/IP and VTAM. The important parameters are:<br />
DNSUFX<br />
The domain name suffix, for example hursley.ibm.com. You will enter<br />
this later in the AnyNet domain name suffix field in the configuration<br />
tool.<br />
TCPIPJOB<br />
The TCP/IP job name refers to the TCP/IP stack that VTAM AnyNet<br />
will use if multiple stacks are in use.<br />
For more information about how to install a major node, see the Guide to<br />
SNA over TCP/IP book, SC31-6527.<br />
3. To allocate cross-domain resource definitions (CDRSC) dynamically,<br />
specify DYNLU=YES as a startup option for VTAM. If you set this<br />
parameter, you do not have to define multiple static CDRSCs within<br />
VTAM. The CDRSC names are dynamically generated from the CP name<br />
and IP address mask for CP name client configuration settings, along with<br />
the IP address of the client machine.<br />
4. Specify the NETID for VTAM in your VTAM start procedure.<br />
5. Create the VTAM APPL definition. Because TCP62 supports only LU6.2<br />
parallel sessions, specify PARSESS=YES.<br />
6. Configure a VTAM LOGMODE.<br />
The MPTN (multiprotocol transport networking) function supplied with the<br />
OS/390 or z/OS Communications Server, to provide the SNA over TCP/IP<br />
capability (using AnyNet), is required to complement TCP62 in the client.<br />
On <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
On <strong>CICS</strong>:<br />
1. Set the following SIT parameters:<br />
ISC=YES<br />
APPLID=IYCKCTU1<br />
AIEXIT=DFHZATDY<br />
where IYCKCTU1 is the VTAM APPL that you defined earlier.<br />
2. Install these groups:<br />
v DFHISC<br />
v DFHCLNT<br />
3. Define an SNA connection to the client workstation. (You can define the<br />
connection statically, or autoinstall it.)<br />
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v On the MODENAME option of the SESSIONS definition, specify the<br />
same modename as your VTAM LOGMODE. You will also use this<br />
value in Mode name field of the configuration file.<br />
v On the MAXIMUM option of the SESSIONS definition, the first number<br />
refers to the Maximum logical SNA sessions field on the configuration<br />
tool; see “Maximum logical SNA sessions” on page 76. The default is 8;<br />
increase this if necessary. Specify the second value as 1, that is, that<br />
<strong>CICS</strong> is to have one contention winner. For example, MAXIMUM(8,1)<br />
means that the modeset is to support eight sessions, and that <strong>CICS</strong> has<br />
one contention winner.<br />
On the workstation<br />
If the domain name suffix is SNA.IBM.COM and the fully qualified partner LU<br />
name is NETID.LUA, TCP/IP must be able to resolve LUA.NETID.SNA.IBM.COM to<br />
the IP address of the server. Use one of the following methods to do this:<br />
v Supply the name and IP address to a TCP/IP domain name server<br />
v Place the name and IP addresses in the hosts file (/etc/hosts) on the<br />
workstation<br />
Verify that TCP/IP is working correctly. In particular make sure the name<br />
formed from .. can<br />
be used to reach the server. For details on verifying TCP/IP see “Verifying the<br />
TCP/IP installation” on page 37.<br />
Firewall implications<br />
You might experience problems when configuring a TCP62 connection<br />
through a firewall.<br />
For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to function correctly your firewall needs to<br />
be configured to permit UDP packets on the TCP62 port, which by default is<br />
set to 397; see “TCP62 port” on page 76.<br />
KeepAlive packets<br />
When using <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, with the TCP62 protocol, KeepAlive<br />
packets can be sent to the <strong>CICS</strong> server to check its availability.<br />
KeepAlive packets are enabled by default.<br />
TCP62 configuration<br />
You can enable or disable the sending of KeepAlive packets using the Remote<br />
node inactivity poll interval setting in the configuration tool; see “Remote node<br />
inactivity poll interval” on page 76.<br />
Changing this inactivity poll value alters how frequently <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> sends KeepAlive packets. A higher interval value will result in less<br />
network traffic but <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will take longer to detect that a<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 41
|<br />
|<br />
|<br />
|<br />
TCP62 configuration<br />
connection has been lost. With a lower value the opposite is true, lost<br />
connections are detected and there ish a greater amount of network traffic.<br />
Next steps<br />
1. Use the configuration tool to create a server definition using the TCP62<br />
protocol; see “The configuration tool interface” on page 51.<br />
2. Configure the server definition (see “TCP62 settings” on page 73).<br />
SNA configuration (AIX only)<br />
To set up communication over SNA, define the following in your SNA<br />
communications product:<br />
v The local node characteristics that are common to all SNA users at the<br />
workstation<br />
v A local logical unit (LU) for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v A partner logical unit (PLU) for each <strong>CICS</strong> server with which the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> will communicate<br />
v One or more modes to specify sets of session properties that are used in<br />
binding SNA sessions<br />
v A transaction program (TP) for the CRSR transaction. You need this if:<br />
– The <strong>CICS</strong> servers support terminal emulation, and<br />
– You require automatic transaction initiation (ATI) against the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> terminals.<br />
Note: The terms used to describe these definitions vary with the product used<br />
to provide SNA support. The terms used above are the ones used by<br />
IBM eNetwork Communications Server.<br />
SNA links to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support data synchronization<br />
levels (sync levels) 0 and 1.<br />
Configuring SNA for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX<br />
To run the SNA transport, install and configure a SNA Server, such as IBM<br />
Communications Server for AIX <strong>Version</strong> 6.0.1.0. You need to make entries on<br />
VTAM, <strong>CICS</strong>, Communications Server for AIX, and the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. Table 7 shows the entries that you need to make.<br />
Table 7. Matching definitions for SNA<br />
VTAM <strong>CICS</strong><br />
<strong>Transaction</strong><br />
Server<br />
IBM<br />
Communications<br />
Server for AIX<br />
NETID — First part of fully<br />
qualified LU name<br />
in Partner LU<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
CTG.INI Example<br />
— ABC3XYZ4
Table 7. Matching definitions for SNA (continued)<br />
VTAM <strong>CICS</strong><br />
<strong>Transaction</strong><br />
Server<br />
IBM<br />
Communications<br />
Server for AIX<br />
PU — Control Point alias<br />
in Node Definition<br />
LU Netname LU Name/LU<br />
alias in<br />
independent LU<br />
Type 6.2<br />
XID — Last five digits of<br />
Node identifier in<br />
Node Definition<br />
Token Ring<br />
destination<br />
address<br />
— Adjacent node<br />
MAC address in<br />
Link Station<br />
APPL APPLID Second part of<br />
fully qualified LU<br />
name in Partner<br />
LU<br />
Configuring SNA<br />
CTG.INI Example<br />
— IYAMR021<br />
Local LU name IYAMT210<br />
— 05d316fc<br />
— 400045121088<br />
— IYCQST34<br />
LogMode Modename Name in Mode Mode name LU62PS<br />
— — — Partner LU name IYCQST34<br />
Notes:<br />
1. The NETID is the VTAM SNA network name. It is defined for your VTAM<br />
network in the VTAM start options.<br />
2. The PU is the name of the AIX physical unit (PU). It is named in the<br />
VTAM switched major node.<br />
3. The LU is the independent LU6.2 used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
It must also be defined to VTAM in a switched Major Node.<br />
4. The XID (or node ID) is configured in the VTAM switched major node<br />
using IDBLK and IDNUM. It is used in the XID exchange to activate the<br />
link station.<br />
5. The token ring destination address is the MAC address of the<br />
communications adapter used by the VTAM front end processor. This<br />
might by a Communications Controller such as the 3172,or a 2216 router,<br />
or an OSA adapter.<br />
6. The APPL is is the <strong>CICS</strong> APPLID and also the VTAM APPL. It is defined<br />
in the VTAM application major node used by the <strong>CICS</strong> region.<br />
7. The LogMode is the mode group used to control LU6.2 session properties.<br />
It must be defined in a VTAM logon mode table, which must be named on<br />
the VTAM APPL definition.<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 43
Configuring SNA<br />
Data conversion<br />
8. The Host system control point name is the CP for the PU of the VTAM<br />
front end processor.<br />
More information on connecting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS is in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere<br />
Connector for <strong>CICS</strong>. See also “Sample configuration documents” on page 238,<br />
for step-by-step guidance on configuration for specific scenarios.<br />
To enable ATI against client terminals, define the transaction program CRSR<br />
on the SNA Server. Follow the instructions in the SNA Administration Guide.<br />
To define the transaction program using the X-Windows utility:<br />
1. Start the SNA administration application, xsnaadmin.<br />
2. Select Services—>APPC—> <strong>Transaction</strong> Programs.<br />
3. Select TP invocation and the Add button.<br />
4. Enter CRSR as the Application TP.<br />
5. Indicate Parameters are for invocation on any LU Queue incoming<br />
allocates and enter the path to the executable as: /usr/sbin/cclclnt<br />
6. Set Arguments to CRSR<br />
7. Set Userid to root and Group to system.<br />
8. Close the TP definition window.<br />
The ECI and EPI allow non-<strong>CICS</strong> applications running in a client system to<br />
access <strong>CICS</strong> facilities and data managed by a <strong>CICS</strong> server system. Character<br />
data may have to be converted as it is passed between client and server; for<br />
example data is encoded in ASCII on a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system and<br />
in EBCDIC on a <strong>CICS</strong>/390 server system. Data conversion is performed by the<br />
server system. For more information on this see Appendix A, “Data<br />
conversion when using the Client daemon and a <strong>CICS</strong> server” on page 225.<br />
Configuring message queues<br />
In UNIX systems, the Client daemon communicates internally using message<br />
queues. In systems other than AIX, the default configuration settings for these<br />
queues are too small to allow for large client data flows (such as 3270 maps or<br />
user COMMAREAs). Some symptoms of this problem are:<br />
v An ECI program gives return code -3 (ECI_ERR_NO_<strong>CICS</strong>)<br />
v A cicsterm locks when a large map is sent to it<br />
v Messages like the following are displayed:<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
CCL9116 Unable to send message to queue ’NNNN’<br />
CCL9117 This may be because you have not changed your system to allow large<br />
IPC queues<br />
CCL9118 Consult the <strong>CICS</strong> client troubleshooting documentation for further<br />
information on how to do this<br />
IBM recommends that you change the configuration settings of the message<br />
queues to allow for large client data flows. The way that you do this depends<br />
on your UNIX system:<br />
v “Message queues on HP-UX”<br />
v “Message queues on LINUX” on page 46<br />
v “Message queues on Solaris” on page 46<br />
HP-UX<br />
IBM recommends the following settings:<br />
msgssz 32 Message Segment Size<br />
msgmnb 65535 Max Number of Bytes on Message Queue<br />
msgmax 65535 Message Max Size (bytes)<br />
msgseg 16384 Number of Segments Available for Messages<br />
Configuring SNA<br />
Set these values by using the SAM utility:<br />
1. Type sam at the command prompt.<br />
2. Select Kernel Configuration —> Configurable Parameters.<br />
This displays a list of kernel parameters that you can change.<br />
3. Select a parameter, either by clicking on it with the mouse or by moving<br />
the cursor to it and pressing the enter key.<br />
4. Select Actions —> Modify configurable parameter.<br />
5. Enter the new value for the parameter in the Formula/Value field, and<br />
then select OK.<br />
If the value you entered is not valid, SAM displays a window explaining<br />
the error.<br />
6. When you have made all of the required changes, select Actions —><br />
Process New Kernel.<br />
SAM displays a window asking for confirmation; select Yes.<br />
SAM then compiles the kernel and displays a window asking if you want to<br />
replace the old kernel before restarting the system. You must restart the<br />
system for the changes to take effect.<br />
Chapter 4. Setting up communication with <strong>CICS</strong> servers 45
Configuring SNA<br />
Linux<br />
IBM recommends the following settings:<br />
#define MSGMAX 40960 /* max size of message (bytes) */<br />
#define MSGMNB 163840 /* default max size of a message queue */<br />
#define MSGQNUM 20480 /* max messages in flight / queue */<br />
Set these values by changing the entries in the<br />
/usr/src/linux/include/linux/msg.h file. Refer to your Linux kernel source<br />
documentation for information on how to change the file and rebuild your<br />
kernel image.<br />
End of Linux<br />
Solaris<br />
IBM recommends the following settings:<br />
set msgsys:msginfo_msgmax = 65535 Maximum size of System V message.<br />
set msgsys:msginfo_msgmnb = 65535 Maximum number of bytes that can be on any<br />
one message queue.<br />
set msgsys:msginfo_msgssz = 32 Specifies size of chunks system uses to<br />
manage space for message buffers.<br />
Obsolete since the Solaris 8 release.<br />
set msgsys:msginfo_msgseg = 16384 Number of msginfo_msgssz segments the system<br />
uses as a pool for available message memory.<br />
Total memory available for messages is<br />
msginfo_msgseg * msginfo_msgssz.<br />
Obsolete since the Solaris 8 release.<br />
set semsys:seminfo_semmni = 4096 Maximum number of semaphore identifiers.<br />
set msgsys:msginfo_msgtql = 10000 The maximum number of queue entries that<br />
can be in the system at the same time.<br />
A low value can adversely affect<br />
system performance, or cause the<br />
client to freeze. IBM recommends that<br />
you set this value to the maximum (10000),<br />
or at least double the maximum number of<br />
concurrent requests. Stress load your<br />
system, and then use the ipcs -qa command<br />
to determine the setting.<br />
Set these values by changing the entries in the /etc/system file. See “Solaris<br />
system notes” on page 209 for information on changing this file.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
End of Solaris
Chapter 5. Configuration<br />
This chapter describes how to configure your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It<br />
consists of the following:<br />
“Before you start” on page 48 Read this for information on what to do<br />
before configuring the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
“Using the configuration tool” on page 49 Read this for general information on<br />
configuring the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, including:<br />
v How to change the default location of<br />
your configuration details<br />
v Using the Task Guide to define basic<br />
details about your <strong>CICS</strong> server and the<br />
protocols you will use<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings” on page 53<br />
“Configuring Client settings” on page 66<br />
“Configuring Server settings” on page 70<br />
Read this if you want to allow non-<strong>CICS</strong><br />
applications written in Java to<br />
communicate with <strong>CICS</strong> servers.<br />
Read these sections if you want to set up<br />
communication with <strong>CICS</strong> servers.<br />
“Editing the configuration file” on page 80 Read this if you prefer to edit the<br />
configuration file direct, rather than use<br />
the configuration tool.<br />
“Keyboard mapping for cicsterm” on<br />
page 88<br />
“Customizing the screen colors for<br />
cicsterm” on page 90<br />
“Preparing to use local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support” on page 92<br />
Read these sections if you intend to use<br />
cicsterm.<br />
Read this for information on setting up<br />
your Java environment correctly.<br />
A number of sample configuration documents provide step-by-step guidance<br />
on configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> servers for different<br />
scenarios. If one of the documents covers your desired configuration, simply<br />
follow the instructions in it. See “Sample configuration documents” on<br />
page 238.<br />
See also:<br />
v IBM Redbooks (see “Redbooks” on page 239)<br />
v Chapter 4, “Setting up communication with <strong>CICS</strong> servers” on page 37<br />
© Copyright IBM Corp. 1996, 2002 47
Configuration<br />
Before you start<br />
This section covers some of the things you need to do before running the<br />
configuration tool. In particular, make sure that communication links with<br />
your <strong>CICS</strong> servers are correctly set up; see Chapter 4, “Setting up<br />
communication with <strong>CICS</strong> servers” on page 37.<br />
Note: You must restart the Client daemon and the <strong>Gateway</strong> daemon for any<br />
changes to the configuration file to take effect.<br />
Gather information<br />
Have the following information available:<br />
v The protocol you will use to connect to the <strong>CICS</strong> server (TCP/IP, TCP62,<br />
SNAon AIX only)<br />
v The hostname or IP address of the server<br />
v The port number at the server to which the Client daemon should connect<br />
v The protocols you will use with the <strong>Gateway</strong> (TCP, SSL, HTTP and HTTPS)<br />
See Table 6 on page 39, and Table 7 on page 42, for information on matching<br />
definitions for TCP62 and SNA.<br />
Configure your programming environment<br />
The Java Virtual Machine (JVM) uses the CLASSPATH environment variable<br />
to find classes, and zip or jar archives containing classes. To allow the JVM to<br />
access class files, you must specify the full path of directories containing class<br />
files or archives.<br />
To compile and run Java applications for use with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, add the full path of the following to the CLASSPATH environment<br />
variable:<br />
v ctgclient.jar<br />
v ctgserver.jar (if you are using a local gateway)<br />
v cfwk.zip (if you are using SSLight security)<br />
These archives are in the /classes subdirectory.<br />
Set the CLASSPATH<br />
Use a shell command like the following to set the CLASSPATH environment<br />
variable:<br />
export CLASSPATH=.:/usr/local/classes:/classes/ctgclient.jar:${CLASSPATH}<br />
Figure 9. Shell command for AIX:<br />
48 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
export CLASSPATH=.:/opt/classes:/classes/ctgclient.jar:${CLASSPATH}<br />
Figure 10. Shell command for Linux, Solaris or HP-UX :<br />
This shell command makes the classes in the current directory, and in<br />
directory /usr/local/classes on AIX, or directory /opt/classes on Linux,<br />
Solaris, and HP-UX, accessible by the JVM. It also makes the ctgclient.jar<br />
archive accessible by the JVM.<br />
You can place the shell command in the .profile file in your home directory<br />
so that the CLASSPATH environment variable is automatically set when you log<br />
on to your system.<br />
Use the following shell command to display the value of the CLASSPATH<br />
environment variable:<br />
echo $CLASSPATH<br />
Recommended Java options for the Solaris JVM<br />
For <strong>Gateway</strong> applications running under Java 1.3.0, you are recommended to<br />
use the -XX:+UseLWPSynchronization Java option.<br />
Also ensure that /usr/lib/lwp appears before /usr/lib in the<br />
LD_LIBRARY_PATH variable.<br />
If you do not set these options, calls to the Java<strong>Gateway</strong>.open() method might<br />
hang when using the TCP/IP protocol. See your Solaris documentation for<br />
more details.<br />
Using the configuration tool<br />
Use the configuration tool to configure the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
To use the configuration tool remotely, export the display using the<br />
commands described in “Using X-Windows from a remote system” on<br />
page 35.<br />
Configuration<br />
To start the configuration tool, enter the ctgcfg command.<br />
Task Guide<br />
The first time you run the configuration tool, you are asked if you want to<br />
use the Task Guide to define basic information about your system. The<br />
Task Guide allows you to enter details of your <strong>CICS</strong> servers, and enable<br />
the TCP and HTTP protocols for the Java gateway. You can change any of<br />
the settings you enter here later, through the configuration tool. You can<br />
bypass the Task Guide, and go straight to the configuration tool, by<br />
Chapter 5. Configuration 49
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
clicking No when asked if you want to use the Task Guide. You are<br />
recommended to use the Task Guide unless you use a screenreader; see<br />
“Accessibility” on page 241.<br />
For help in completing any of the screens on the Task Guide, refer to the<br />
online help, or the relevant section in “The configuration tool interface” on<br />
page 51.<br />
The configuration file<br />
Configuration details are stored by default in the CTG.INI file in the<br />
/bin subdirectory. IBM recommends that you use the<br />
configuration tool to update this file.<br />
You can specify a different path to the configuration file by setting the<br />
<strong>CICS</strong>CLI environment variable. (The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> log<br />
indicates the location of CTG.INI.) The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will not<br />
run if a configuration file is not found.<br />
The Task Guide also launches if it fails to find CTG.INI in the<br />
/bin subdirectory. If you specified a different location for<br />
the configuration file through the <strong>CICS</strong>CLI environment variable, and<br />
wish to edit an existing configuration file, click No when asked if you<br />
want to use the Task Guide. Once the configuration tool has launched,<br />
open your configuration file.<br />
Running the configuration tool on a different operating system<br />
You can use the configuration tool on any of the other <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> operating systems to generate a configuration file for your operating<br />
system. See Appendix B, “Hardware and software” on page 229 for other<br />
supported operating systems.<br />
1. Install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the workstation on which you want<br />
to run the configuration tool.<br />
2. To edit an existing configuration, copy CTG.INI to the /bin<br />
subdirectory on the workstation, using FTP in ASCII mode.<br />
3. Issue the following command:<br />
Operating system Command<br />
AIX ctgcfg -PLAT AIX<br />
HP-UX ctgcfg -PLAT HPUX<br />
Linux ctgcfg -PLAT L390<br />
Solaris ctgcfg -PLAT SOL<br />
Windows ctgcfg -PLAT WIN<br />
This makes the configuration tool run as if it is on your operating system.<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
4. Make the required entries and click Save. This creates or updates the<br />
CTG.INI file.<br />
5. Use FTP in ASCII mode to transfer the file to your system.<br />
The configuration tool interface<br />
The screen has four input areas (described separately below):<br />
1. Menu bar<br />
2. Toolbar<br />
3. Tree structure<br />
4. Settings panel<br />
A fifth area, the status bar, shows which configuration file and operating<br />
system you are using. The status bar is display only.<br />
Figure 11. The configuration tool<br />
Configuration<br />
Note: Screen captures later in this chapter are taken from the Windows<br />
version of the configuration tool. On your platform, the configuration<br />
tool may look slightly different.<br />
Tree structure<br />
The tree structure (see Figure 11) allows you to navigate through all of the<br />
settings in your configuration. The types of root node are as follows:<br />
Chapter 5. Configuration 51
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Java <strong>Gateway</strong> Contains a subnode for each protocol that the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can use (TCP, SSL, HTTP, HTTPS and<br />
TCPAdmin).<br />
Client Contains a subnode for each of your server definitions.<br />
Menu bar<br />
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.<br />
The File pulldown has the following options:<br />
New Creates a new configuration.<br />
Open Opens an existing configuration.<br />
Save Saves the current configuration. If a new configuration has<br />
been created, the file name is CTG.INI (in the<br />
/bin subdirectory).<br />
Save As Allows you to override the default path and name of the<br />
configuration file.<br />
Exit Exits the configuration tool. If you have made any alterations<br />
you are asked whether you want to save the configuration.<br />
The Edit pulldown has Cut, Copy and Paste options, which perform the<br />
standard text functions.<br />
The Tools pulldown has the following options:<br />
Trace Settings Displays the Trace Settings dialog.<br />
Task Guide Starts the Task Guide for creating new server definitions.<br />
New Server Defines a new server named A_Server, that uses the TCP<br />
protocol. Recommended for users of screenreaders and expert<br />
users; otherwise use the Task Guide option.<br />
Delete Server Deletes a server node from the tree structure.<br />
The Settings pulldown has these options:<br />
Color Changes the background color on panels and fields. If you<br />
change the color, all fields (except check boxes and radio<br />
buttons) take on the same background color as the main<br />
panel.<br />
Font Changes the typeface, size, style and color of text.<br />
Any changes that you make to color and font settings are lost when you close<br />
the configuration tool.<br />
52 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
Configuration<br />
The Help pulldown has the following options:<br />
Context Help Displays online help information according to the current<br />
screen context, for example, for a particular configuration<br />
setting.<br />
Contents Displays the contents list for online help.<br />
Keys Help Displays information on keyboard alternatives, and other<br />
information to help users with a disability to use the software.<br />
See also “Accessibility” on page 241.<br />
Index Displays a subject index for online help.<br />
About Displays the version number and other information about the<br />
configuration tool.<br />
Toolbar<br />
The toolbar provides some of the functionality available from the menu bar in<br />
a set of icons. These icons have hover help, so that when you place the cursor<br />
over them, a text box describing the option appears.<br />
Settings panels<br />
When you select nodes in the tree structure, the relevant settings panel is<br />
displayed. The settings in these panels correspond to parameters in the<br />
CTG.INI file.<br />
On each settings panel there is an Undo Changes button that allows you to<br />
undo changes you have made.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings<br />
To display the <strong>Gateway</strong> Settings panel, select the <strong>Gateway</strong> node in the tree<br />
structure. The settings map to the parameters in the <strong>Gateway</strong> section of the<br />
CTG.INI file.<br />
Using the configuration tool, you can provide preset values for any parameter<br />
that can be specified using a <strong>Gateway</strong> command line option.<br />
If a parameter defined using the configuration tool is specified via the<br />
associated command line option when the <strong>Gateway</strong> is started, the command<br />
line setting takes precedence.<br />
General <strong>Gateway</strong> settings<br />
See Figure 11 on page 51 for the screen layout. The general <strong>Gateway</strong> settings<br />
are:<br />
Initial number of Connection Manager threads: Enter the initial number of<br />
ConnectionManager threads. The default is 1.<br />
Chapter 5. Configuration 53
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Set this to the normal number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients.<br />
You can override this setting with the ctgstart -initconnect command.<br />
Maximum number of Connection Manager threads: Enter the maximum<br />
number of ConnectionManager threads. The default is 100.<br />
This limits the maximum number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients. Set this to the maximum number of Java<strong>Gateway</strong><br />
objects that could be open at any one time from all the remotely-connected<br />
Java clients.<br />
You can override this setting with the ctgstart -maxconnect command.<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
ConnectionManager threads.<br />
For information on threading limits, see Table 3 on page 17.<br />
Initial number of Worker threads: Enter the initial number of Worker<br />
threads. The default is 1.<br />
Set this to the normal number of concurrent requests expected to be processed<br />
concurrently by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> daemon.<br />
You can override this setting with the ctgstart -initworker command.<br />
Maximum number of Worker threads: Enter the maximum number of<br />
Worker threads. The default is 100.<br />
This limits the maximum number of parallel ECI, ESI and EPI requests that<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can process. Set it to:<br />
v Less than or equal to maxconnect (for single Java<strong>Gateway</strong> programs)<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
Worker threads.<br />
You can override this setting with the ctgstart -maxworker command.<br />
For information on threading limits, see Table 3 on page 17.<br />
Enable reading input from console: Select this check box to enable the<br />
reading of input from the console.<br />
Reading of input from the console is enabled by default.<br />
54 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
You can override this setting with the ctgstart -noinput command.<br />
Display TCP/IP hostnames: Select this check box to enable the display of<br />
TCP/IP hostnames in messages.<br />
This option allows you to choose how TCP/IP addresses are displayed in<br />
messages. By default, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> displays TCP/IP addresses<br />
in messages in numeric form. If you enable this option, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> uses the Domain Name System (DNS) to convert numeric TCP/IP<br />
addresses to symbolic TCP/IP hostnames in messages. This makes the<br />
messages easier to read.<br />
Note: Selecting this option might cause severe performance reduction on<br />
some systems.<br />
Let Java clients obtain generic ECI replies: Select this check box if you wish<br />
Java clients to be able to obtain generic ECI replies from the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Generic replies are those obtained using the Call_Type: ECI_GET_REPLY or<br />
ECI_GET_REPLY_WAIT. Specific replies are those obtained using the<br />
Call_Type: ECI_GET_SPECIFIC_REPLY or ECI_GET_SPECIFIC_REPLY_WAIT.<br />
This setting does not apply to local <strong>Gateway</strong>s.<br />
Validate Units of Work: Select this check box if you want the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to validate logical units of work (LUWs). This ensures<br />
that a LUW ID can be used only on the Java<strong>Gateway</strong> connection to which it<br />
was allocated. If you clear this check box, you disable validation:<br />
v LUWs can be accessed by any connection to the same remote <strong>Gateway</strong>.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> cannot clean up used LUWs when a<br />
connection is closed or breaks.<br />
The default is that LUW validation is enabled.<br />
Configuration<br />
Validate message qualifiers: Select this check box if you want the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to validate message qualifiers. This ensures that a<br />
message qualifier ID can be used only on the Java<strong>Gateway</strong> connection to<br />
which it was allocated. A message qualifier that has been assigned on an<br />
asynchronous call cannot be used by any connection using the same remote<br />
<strong>Gateway</strong> until the reply has been received.<br />
If you clear this check box, you disable validation:<br />
v ECI asynchronous calls tagged with a message qualifier on one connection<br />
can have a call of the GET_SPECIFIC_REPLY type made from another<br />
connection to the same remote gateway.<br />
Chapter 5. Configuration 55
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
v The same message qualifier can be used on an asynchronous call even if a<br />
reply with that message qualifier is still outstanding in the remote <strong>Gateway</strong>.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> cannot clean up used message qualifiers<br />
when a connection is closed or breaks. In some circumstances logical units<br />
of work (LUWs) will also not be cleaned up: because the <strong>Gateway</strong> cannot<br />
clean up the message qualifier, it cannot determine if the LUW is still<br />
active.<br />
The default is that message qualifier validation is enabled.<br />
Log client connections and disconnections: Select this check box if you want<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to write a message to the log each time that a<br />
client application program connects to, or disconnects from, the <strong>Gateway</strong><br />
daemon. The default is for these messages not to be written.<br />
Timeout for in-progress requests to complete (ms): Enter a value in<br />
milliseconds.<br />
When a Java-client program disconnects from the <strong>Gateway</strong>, the <strong>Gateway</strong> may<br />
still be processing requests on behalf of that program. If work is still in<br />
progress, the ConnectionManager that was managing requests on behalf of<br />
that Java-client waits for the requests to complete for up to the timeout<br />
period. If there are still requests in progress after the timeout has expired, the<br />
ConnectionManager continues its processing and marks itself as available for<br />
use by a new connection. The default timeout is 10 000 milliseconds, but you<br />
may enter a value to override the default.<br />
If this value is set to zero, the ConnectionManager does not wait for<br />
in-progress requests to complete.<br />
Worker thread available timeout (ms): Enter a value in milliseconds.<br />
When a ConnectionManager accepts a request, it must allocate a Worker<br />
thread to execute that request. If a Worker does not become available within<br />
the timeout period, an error message is sent rejecting that request and the<br />
request is not executed. The default timeout is set to 10 000 milliseconds, but<br />
you can enter a value to override that default.<br />
If you set this value to zero, the request is rejected unless a Worker is<br />
immediately available.<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Figure 12. TCP settings<br />
TCP protocol settings<br />
Select the TCP subnode to display the settings for TCP:<br />
Enable protocol handler: Select this check box to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for use with this protocol.<br />
Port: Enter the TCP/IP port number.<br />
The default port for TCP/IP is 2006.<br />
You can override this setting with the ctgstart -port command.<br />
Handler wakeup timeout (ms): Enter a value in milliseconds.<br />
Configuration<br />
This setting controls how frequently the protocol handler wakes from<br />
accepting inbound connections. When it wakes, it checks to see whether the<br />
Chapter 5. Configuration 57
Configuration<br />
<strong>Gateway</strong> is being stopped, and so this value affects the time taken for the<br />
<strong>Gateway</strong> to shutdown cleanly. If you set this value to zero then the handler<br />
only wakes when a new connection is accepted, and so the <strong>Gateway</strong> will not<br />
shutdown cleanly until that time.<br />
Connection timeout (ms): Enter a value in milliseconds.<br />
When a new connection has been accepted, this value specifies how long the<br />
protocol handler waits for a ConnectionManager thread to become available.<br />
If a ConnectionManager thread does not become available within this time,<br />
then the connection is refused. If this value is set to zero, a connection is<br />
refused if a ConnectionManager is not immediately available.<br />
Idle timeout (ms): Enter a value in milliseconds.<br />
This setting specifies how long a connection is allowed to remain dormant.<br />
The idle timeout period is counted from when a request was last flowed<br />
down the connection. When the idle timeout has expired, the connection is<br />
disconnected, though if work is still in progress on behalf of the connection, it<br />
may be left connected. If this value is not set, or is set to zero, then idle<br />
connections will not be disconnected.<br />
Cleanup processing will only result after a timeout if the server has support<br />
for this function installed.<br />
Ping time frequency (ms): Enter a value in milliseconds.<br />
This value specifies how often a PING message is sent by the <strong>Gateway</strong> to an<br />
attached client to check that client is still active. If a PONG response has not<br />
been received by the time the next PING message is due to be sent, then the<br />
connection is disconnected. Again, if work is still in progress on behalf of the<br />
connection it may (depending on the drop working connections value setting)<br />
be left connected. If this value is not set, or is set to zero, then PING messages<br />
are not sent.<br />
Drop working connections: Select this check box to specify that a connection<br />
can be disconnected, due to an idle timeout or a PING/PONG failure even if<br />
work is still in progress on behalf of this connection.<br />
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this<br />
handler. The SO_LINGER setting specifies a delay value in seconds for closing<br />
a socket. If this value is not entered, or set to zero, then SO_LINGER is<br />
disabled for any sockets used by this protocol handler.<br />
If SO_LINGER is enabled, and data transmission has not finished, a Close call<br />
blocks the calling program until the data is transmitted or until the connection<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
times out. If SO_LINGER is disabled, a Close call returns without blocking the<br />
caller and TCP/IP still tries to send the data. Normally this transfer is<br />
successful, but it cannot be guaranteed, because TCP/IP repeats the Send<br />
request for only a specified period of time.<br />
Require clients to use security classes: Select this check box if you wish<br />
your <strong>Gateway</strong> to accept only connections that use security classes.<br />
When a Java-client program connects to the <strong>Gateway</strong>, it can specify a pair of<br />
security classes for use on the connection. However, by default a <strong>Gateway</strong><br />
also accepts connections from programs that do not specify this pair of<br />
security classes.<br />
For more information on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security exits, see<br />
“Security exits” on page 12.<br />
Configuration<br />
Chapter 5. Configuration 59
Configuration<br />
Figure 13. SSL settings<br />
SSL protocol settings<br />
Select the SSL subnode to display the settings for SSL. The settings are the<br />
same as for TCP except that the default port is 8050, and SSL also has the<br />
following settings:<br />
Use client authentication: Select this check box to enable client<br />
authentication for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The default is that client<br />
authentication is disabled.<br />
When client authentication is enabled, any connection attempted to either the<br />
ssl: or https: handler requires the client to present its own Client Certificate<br />
(also known as a Digital ID).<br />
For information on how to obtain Client Certificates for the clients, see<br />
“Configuring your SSL clients” on page 98.<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Configuration<br />
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,<br />
or the server KeyStore name for JSSE.<br />
For a KeyStore, give either the full path name, or the relative path name of<br />
the file. Use either a forward slash (/) character, or double back slash (\\)<br />
characters, as a separator in the path name on all operating systems. For<br />
example:<br />
/mykeys/jsse/keystore.jks<br />
\\mykeys\\jsse\\keystore.jks<br />
The server KeyRing or KeyStore consists of a valid x.509 certificate that<br />
identifies this server to connecting clients. This KeyRing or KeyStore is<br />
generated using the SSL tools supplied with this product.<br />
For more information about SSL and its associated KeyRings or KeyStores, see<br />
Chapter 6, “Network Security” on page 93.<br />
KeyRing or Keystore password: Enter the password that you specified for<br />
the server KeyRing or KeyStore.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the password to the configuration file in a<br />
form that prevents a casual observer from easily reading it.<br />
Chapter 5. Configuration 61
Configuration<br />
Figure 14. HTTP settings<br />
HTTP protocol settings<br />
Select the HTTP subnode to display the settings for HTTP. The settings are<br />
the same as for TCP.<br />
The default port for HTTP is 8080.<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Figure 15. HTTPS settings<br />
HTTPS protocol settings<br />
Configuration<br />
Select the HTTPS subnode to display the settings for HTTPS. The settings are<br />
the same as for HTTP except that HTTPS also has Use client authentication,<br />
KeyRing or Keystore name, and KeyRing or Keystore password settings. See<br />
“SSL protocol settings” on page 60 for details.<br />
The default port for HTTPS is 443. However, on some operating systems,<br />
processes require special privileges to access port numbers between 1 and<br />
1024. If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> without these required<br />
privileges, change the port number to a value greater than 1024.<br />
Chapter 5. Configuration 63
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Figure 16. TCPAdmin settings<br />
TCPAdmin protocol settings<br />
Select the TCPAdmin subnode to display the settings for administration. The<br />
settings are the same as for TCP except for the following:<br />
v The default port is 2810<br />
v There is no Require clients to use security classes field.<br />
v TCPAdmin also has the following settings:<br />
Max dedicated connections: Enter a value specifying the maximum number<br />
of simultaneous dedicated client connections that can be made to the <strong>Gateway</strong><br />
administration handler.<br />
Authorized Hosts: Enter a host name or IP address in the entry field. Click<br />
Add to add the host to the Authorized Hosts list, below the entry field. Click<br />
Remove to remove all selected hosts from the Authorized Hosts list.<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
If there are entries in the Authorized Hosts list, only those hosts are allowed<br />
to access the administration protocol handler. Be aware: If the list is empty, all<br />
hosts are allowed access.<br />
The default entry is 127.0.0.1, which represents the host on which the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is installed. IP address 127.0.0.1 and the host name<br />
localhost are considered to be different from the real IP address or host name<br />
of the system.<br />
For information about administering your system, see “Administering your<br />
system” on page 135.<br />
Chapter 5. Configuration 65
Configuration<br />
Configuring Client settings<br />
Figure 17. Client settings<br />
Select the Client node to display the Client Settings panel. The settings map<br />
to the parameters in the Client section of the CTG.INI file.<br />
Default Server<br />
Select the default server from the drop-down list.<br />
Applid<br />
Enter up to 8 characters, or leave this field with the default value of *.<br />
This value specifies the applid of the <strong>CICS</strong> Universal Client workstation in the<br />
form in which it will be autoinstalled as a system at the <strong>CICS</strong> server. The<br />
name must be unique within the <strong>CICS</strong> server system. The value of *<br />
automatically generates a name that is guaranteed to be unique.<br />
66 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Note: If the client is to be autoinstalled to more than one <strong>CICS</strong> server, and if<br />
you enter a specific name for the applid, that name must be unique<br />
with respect to all servers it is connected to. If the name is not unique,<br />
then attempts to connect to a server may be rejected because another<br />
client has already been installed using the same name. If a name of * is<br />
used, the client may be known by a different unique name at each<br />
server.<br />
If the client is to communicate with a given server via SNA (AIX operating<br />
system only), this applid may be overridden at the time the client is installed<br />
at the server by the Local LU name for the client.<br />
Maximum buffer size<br />
Enter a number of kilobytes, in the range 4 through 32. The default is 32 KB.<br />
This value specifies the size of the transmission buffers in which application<br />
or terminal data will flow. The value should be large enough to cater for the<br />
largest possible COMMAREA or terminal input/output area (TIOA) to be<br />
used. The value does not include an overhead of 512 bytes needed by the<br />
clients for some protocols.<br />
Leave this setting at the default unless the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running on a machine that is short of memory.<br />
Terminal exit<br />
Enter a character string of between 1 and 4 characters. The default is EXIT.<br />
The string, when entered at a terminal emulator at any time and place where<br />
a transaction name can be entered, causes the terminal emulator to terminate.<br />
The string must not contain any blank characters.<br />
The string is case-sensitive. If a terminal emulator has uppercase translation in<br />
its <strong>CICS</strong> terminal definition, enter this string in uppercase.<br />
Maximum servers<br />
Enter a value in the range 1 through 256. The default is 10.<br />
This value specifies the maximum number of servers that can be accessed<br />
concurrently from the client.<br />
Maximum requests<br />
Enter a value in the range 1 through 10 000. The default is 256.<br />
Configuration<br />
This value specifies the maximum number of concurrent items that may be<br />
executing on the Client daemon, where an item is one of:<br />
v a terminal emulator<br />
Chapter 5. Configuration 67
Configuration<br />
v an EPI terminal<br />
v an ECI unit of work<br />
v an ESI unit of work<br />
It is used to detect runaway conditions where an application could, in error,<br />
submit an excessive number of requests to a server. The actual limit may be<br />
less than this setting if other operating system limits (for example, memory<br />
constraint or communication sessions), come into effect.<br />
Print command<br />
Enter a character string, from 1 to 256 characters long.<br />
The specified string is a command specific to the operating system under<br />
which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running. When a request to print is<br />
received, the Client daemon generates a temporary print file with a unique<br />
name.<br />
The parameter string is appended with the temporary file name, and the<br />
resultant command executed. This allows, for example, print requests to be<br />
copied to a file, directed to a local printer, formatted for inclusion into<br />
documentation, and so on.<br />
It is the responsibility of the Print Command to delete the temporary print file<br />
after it has finished processing it.<br />
Use a shell script with the print command (for example, lpr) followed by the<br />
command to delete (rm).<br />
See also the Print file description for more information.<br />
Print file<br />
Enter a character string, 1 to 256 characters long.<br />
This option applies only if you make no entry in the Print Command setting.<br />
The specified string identifies a file to which output from print requests<br />
received at the Client daemon is directed. Each print request is appended to<br />
the end of the current file.<br />
Note: This setting acts only as a default. The terminal and print emulators<br />
provide options to override this value.<br />
Codepage identifier override<br />
Enter a value indicating a Coded Character Set Identifier (CCSID) to override<br />
your local codepage identifier.<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Use this setting if your platform has been updated for Euro support, and the<br />
<strong>CICS</strong> Server has Euro support. For example, for Latin-1 countries, use a<br />
CCSID value of 858 to indicate that the codepage 850 includes Euro support.<br />
For codepage 1252, specify a CCSID value of 5348.<br />
Notes:<br />
1. Regardless of the value in the Codepage identifier override setting,<br />
cicsterm always displays characters based on the local codepage of the<br />
workstation.<br />
2. If you use the CCSID to change the codepage identifier, data that is<br />
already stored on the server may be modified when retrieved by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, if it includes characters for which the code points<br />
produce different characters.<br />
3. On AIX: On AIX 4.3.2 and above, support for Ja_JP locale uses<br />
CCSID=943. If the <strong>CICS</strong> Server does not support this CCSID, enter a<br />
Codepage identifier override of 932, or add the statement ’CCSID=932’ to<br />
the Client Section of the initialization file CTG.INI.<br />
For more information on CCSIDs and data conversion, refer to Appendix A,<br />
“Data conversion when using the Client daemon and a <strong>CICS</strong> server” on<br />
page 225.<br />
Server retry interval<br />
Enter a number of seconds. This is the time in seconds between attempts by<br />
the Client daemon to reconnect to a server. The default is 60 seconds.<br />
When the Client daemon becomes aware that a server to which it was<br />
connected is no longer active, it attempts to reconnect to the server 1 second<br />
after it becomes inactive. If it fails it keeps trying, at the interval specified<br />
here.<br />
Log file<br />
Enter the name of the log file to be used for problem diagnosis.<br />
Configuration<br />
If not specified, the log filename defaults to <strong>CICS</strong>CLI.LOG in the /var/cicscli<br />
subdirectory.<br />
Chapter 5. Configuration 69
Configuration<br />
Configuring Server settings<br />
Figure 18. Server settings<br />
Select a server in the tree structure to display the Server Settings panel. The<br />
settings map to the parameters in a Server section of the CTG.INI file.<br />
Server name<br />
Enter a name of between 1 and 8 characters. This provides a<br />
communications-protocol-independent name for the server, local to the Client<br />
daemon.<br />
Requests to access the server from ECI, EPI, ESI, or terminal emulators<br />
reference the server through this name.<br />
Description<br />
Enter a description for the server of between 1 and 60 characters. This<br />
description is optional.<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The description is returned to applications running on the Client daemon by<br />
the <strong>CICS</strong>_EpiListSystems and <strong>CICS</strong>_EciListSystems functions.<br />
Initial transaction<br />
Enter a transaction identifier of between 1 and 128 characters.<br />
This string is case-sensitive and identifies the initial transaction (and any<br />
parameters) to be run when the terminal emulator connects to the server. If<br />
you do not enter anything, no initial transaction is run. The first four<br />
characters, or the characters up to the first blank in the string are taken as the<br />
transaction. The remaining data is passed to the transaction on its invocation.<br />
Model terminal definition<br />
Enter a string of between 1 and 16 characters.<br />
The string is case-sensitive and specifies the name of a model terminal<br />
definition at the server, identifying the characteristics of terminals to be<br />
autoinstalled from the client. If the model cannot be located at the server, or<br />
you do not enter anything, a default terminal definition is used. This default<br />
is server-specific.<br />
The interpretation of the Model terminal definition setting is server-specific.<br />
For example,for a TXSeries for AIX server, the value is 1 to 16 characters, and<br />
is the DevType for a <strong>CICS</strong> terminal definition entry to be used as the model.<br />
Use upper case security<br />
Select this check box to specify that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> converts to<br />
uppercase any userid or password from an ECI application or from a user<br />
prompt.<br />
With this setting selected, you can enter userids and passwords in either<br />
uppercase or lowercase. This setting is disabled by default.<br />
Network protocol<br />
Select from the drop-down list the protocol to be used for the server<br />
connection:<br />
v TCP/IP<br />
v SNA (AIX operating system only)<br />
v TCP62<br />
Configuration<br />
Protocol settings displayed on the panel change according to the protocol you<br />
select.<br />
Chapter 5. Configuration 71
Configuration<br />
TCP/IP settings<br />
Hostname or IP address: Enter the character or numeric TCP/IP identifier<br />
for the host on which the <strong>CICS</strong> server is running. For example,<br />
cicssrv2.company.com (hostname) or 192.113.36.200 (IP Address).<br />
Hostnames are mapped to IP addresses either by the name server or in the<br />
hosts system file. It is better to use a hostname in case the IP address<br />
changes.<br />
The hosts system file is in the /etc directory.<br />
Port: Enter a numeric value in the range 0 through 65 535 defining the port<br />
number at the server to which the Client daemon should connect. The default<br />
value is 0.<br />
A value of 0 indicates that the services system file should be used to locate<br />
the port number for the <strong>CICS</strong> service using the TCP protocol.<br />
The services system file is in the /etc directory.<br />
If no entry can be located in the services system file, a value of 1435 is<br />
assumed. This is the port assigned to the Client daemon in the TCP/IP<br />
architecture.<br />
Connection timeout: Enter a value in the range 0 through 3600, specifying<br />
the maximum time in seconds that establishing a connection is allowed to<br />
take; the default value of 0 means that no limit is set by the Client daemon.<br />
A timeout occurs if connection establishment takes longer than the specified<br />
time. The TCP/IP socket is closed and the return code passed back to the<br />
client application is either ECI_ERR_NO_<strong>CICS</strong> or <strong>CICS</strong>_EPI_ERR_FAILED.<br />
Cleanup processing happens after a timeout only if the server has support for<br />
this function installed.<br />
Send TCP/IP Keepalive packets: Select this check box if you want TCP/IP<br />
to periodically send KeepAlive packets to the server to check the connection.<br />
SNA settings<br />
Note: SNA is only available on the AIX operating system<br />
Use LU alias names: Select this check box to use LU alias names.<br />
LU names are always aliases on AIX, so this setting is ignored.<br />
72 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
Partner LU name: Enter the LU Name of the server as it is known to the<br />
APPC configuration at the Client daemon.<br />
This must be an eight-character alias name.<br />
Local LU name: Enter the name of a local LU to be used when connecting to<br />
the server. The same LU can be used for all server connections.<br />
This must be an eight-character alias name.<br />
Mode name: Enter between 1 and 8 characters specifying the mode name to<br />
be used when connecting to the server.<br />
Enter * if you want the mode name to be filled with spaces.<br />
TCP62 settings<br />
hosts file: When configuring a TCP62 <strong>CICS</strong> server, you must also update the<br />
local hosts file. The path to the file is:<br />
/etc/hosts<br />
Configuration<br />
The file maps IP addresses to host names. Keep each entry on a<br />
separate line. Entries are in this form:<br />
192.113.36.200 <strong>CICS</strong>A.NYEBO.myplace.ibm.com<br />
Each element of the entry is explained below:<br />
192.113.36.200<br />
The IP address of the <strong>CICS</strong> system. It must start in column<br />
one, and be separated from the rest of the entry by at least one<br />
space.<br />
<strong>CICS</strong>A.NYEBO<br />
The Partner LU name, in reverse order. In the example above,<br />
NYEBO.<strong>CICS</strong>A is the Partner LU name, as entered in the<br />
Configuration tool.<br />
myplace.ibm.com<br />
The Anynet domain name suffix.<br />
Multiple server definitions with identical combinations of Local LU, Partner<br />
LU, and Mode name are not permitted in CTG.INI in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>. This ensures that every connection that the <strong>CICS</strong> region<br />
and the network protocol see is represented by a unique server definition in<br />
Chapter 5. Configuration 73
|<br />
|<br />
|<br />
|<br />
Configuration<br />
the configuration file. Existing Client applications that use different server<br />
names to send requests to the same <strong>CICS</strong> region continue to work if a user<br />
exit is defined to redirect requests. A sample user exit that does this is<br />
provided; see /samples/samples.txt.<br />
Partner LU name: Enter the LU Name of the server as it is known to the<br />
SNA configuration at the client. This must be a qualified 17-character name,<br />
for example, ABC3XYZ4.PQRS1234.<br />
Local LU name or template: Enter a real LU name or a template for the<br />
name of a local LU to be used when connecting to the <strong>CICS</strong> server.<br />
If you enter a template, you must fill in the IP address mask for LU name<br />
template (optional) field.<br />
A template contains replacement characters, that is, asterisks (*), and is used<br />
to generate an LU name dynamically. For example, a template of CTS8BC**<br />
indicates that a name must be dynamically generated to replace the two<br />
asterisks. An algorithm based on the template, IP address mask, and the<br />
workstation IP address, is used to create a unique Local LU name of, for<br />
example, CTS8BC38.<br />
To use a template you must configure your <strong>CICS</strong> server to install connections<br />
dynamically.<br />
With dynamic name generation for the Local LU name, you can use the same<br />
configuration on all <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machines because different<br />
Local LU names are generated on the basis of the IP address of the client<br />
machine. Therefore, you do not have to define multiple LUs within VTAM.<br />
If several hundred clients are to use dynamic LU name generation to connect<br />
to the <strong>CICS</strong> server, you should have more template replacement characters in<br />
your Local LU name, for example, CTS8****. In fact, <strong>CICS</strong> <strong>Transaction</strong> Server<br />
for z/OS uses the last four characters of the LU name as the connection name,<br />
so these characters must be unique.<br />
IP address mask for LU name template (optional): Enter an IP address mask<br />
in big-endian, that is, most significant byte first order. This must be a<br />
hexadecimal number, for example, FFFFFF80.<br />
This address mask is used in dynamic LU name generation. See the<br />
description of Local LU name or template for more information.<br />
This parameter is ignored if Local LU name is not a template. The default is<br />
00000000.<br />
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Mode name: Enter between 1 and 8 characters specifying the mode name to<br />
be used when connecting to the server.<br />
Enter * if you want the mode name to default to TCP62.<br />
Use the Maximum logical SNA sessions, Maximum SNA RU size, and SNA<br />
pacing size settings to define the mode values specified for the Mode name<br />
on your <strong>CICS</strong> server.<br />
Common TCP62 settings<br />
Configuration<br />
Fully qualified CP name or template: Enter a fully-qualified CP name, or a<br />
template for the fully-qualified CP name, of the node to be started.<br />
If you enter a template, you must fill in the IP address mask for CP name<br />
(optional) field.<br />
A template contains replacement characters, that is, asterisks (*), and is used<br />
to generate a CP name dynamically. For example, a template of<br />
USIBMJKA.CP62**** indicates that a name must be dynamically generated to<br />
replace the four asterisks. An algorithm based on the template, IP address<br />
mask and the workstation IP address, is used to create a unique CP name of,<br />
for example, USIBMJKA.CP62AH38.<br />
With dynamic name generation for the CP name, you can use the same<br />
configuration on all <strong>CICS</strong> Client machines because different CP names are<br />
generated on the basis of the IP address of the client machine. Therefore, you<br />
do not have to define multiple CPs to VTAM.<br />
If several hundred clients are to use dynamic CP name generation, you should<br />
have more template replacement characters in your template, for example,<br />
USIBMJKA.CP******.<br />
The net ID part (the first part) of the template must not contain any template<br />
replacement characters.<br />
IP address mask for CP name (optional): Enter an IP address mask in<br />
big-endian, that is, most significant byte first order. This must be a<br />
hexadecimal number, for example, FFFF8080.<br />
This address mask is used in dynamic CP name generation. See the<br />
description of Fully qualified CP name or template for more information.<br />
This parameter is ignored if Fully qualified CP name or template is not a<br />
template. The default is 00000000.<br />
Chapter 5. Configuration 75
Configuration<br />
Anynet domain name suffix: Enter the AnyNet ® domain name suffix. This<br />
parameter is used with the partner (Partner LU name) to determine the IP<br />
address of the host associated with that LU.<br />
For example, if the domain name suffix is sna.ibm.com and the partner LU<br />
name is NETID.LUA a gethostbyname call is issued for hostname<br />
LUA.NETID.sna.ibm.com to obtain the IP address of the node that has the LU<br />
name NETID.LUA.<br />
See “TCP62 settings” on page 73, for information on how IP addresses map to<br />
host names.<br />
TCP62 port: Enter a number between 0 and 65535 to set the port number on<br />
the server to which the Client daemon connects.<br />
The default value is 0. This means that the Client daemon uses port 397, the<br />
default port for the TCP/IP service MPTN.<br />
On UNIX operating systems, only a root user can access ports in the range 1<br />
to 1023. This means that if <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is started by a user who<br />
has not logged in as root, it cannot use the default port for TCP62. To use<br />
TCP62 from a user other than root, set TCP62 port to a value outside the<br />
range 1 to 1023. You must also set the TCP62 port number on the <strong>CICS</strong> server<br />
to the same value.<br />
You must configure your <strong>CICS</strong> server with the same port number.<br />
Remote node inactivity poll interval: Enter a number of seconds between 0<br />
and 65535. The default value is 60 seconds. A value of 0 turns off polling.<br />
This configuration setting controls the time that the Client daemon waits<br />
before polling inactive connections.<br />
The Client daemon polls inactive connections by sending MPTN keepalive<br />
datagrams by User Datagram Protocol (UDP) to the <strong>CICS</strong> server. If the Client<br />
daemon receives no response after it has sent several datagrams, it closes the<br />
connection with <strong>CICS</strong>. For more information on MPTN keepalives, see an<br />
Anynet publication such as Anynet: Guide to SNA over TCPIP, SC31-8578-00.<br />
Advanced TCP62 settings<br />
Maximum logical SNA sessions: Enter a value in the range 1 through 255.<br />
The default value is 8.<br />
This parameter defines the maximum number of logical SNA sessions<br />
allowed. The number of concurrent transactions that can exist for a client is<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
estricted by the number of client contention winners available on the session.<br />
For example, if the maximum number of sessions is 8, and the server has 1<br />
contention winner, the client is left with 7 contention winners. This allows 7<br />
concurrent transactions.<br />
Maximum SNA RU size: Enter a value in the range 256 through 4096. You<br />
are recommended to use the default value of 1024.<br />
This parameter specifies the maximum size of the request or response units<br />
sent over sessions.<br />
SNA pacing size: Enter a value in the range 0 through 63. You are<br />
recommended to use the default value of 8.<br />
Configuration<br />
This parameter specifies how many request units can be sent before receiving<br />
a pacing response.<br />
Chapter 5. Configuration 77
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
Trace settings<br />
To configure the trace settings, select the Trace Settings option from the Tools<br />
menu.<br />
Trace Settings<br />
Select check boxes to specify the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and Client<br />
daemon components that will be traced when tracing is turned on.<br />
Trace everything<br />
All components.<br />
Client API level 1<br />
The client API layer (level 1).<br />
Client API level 2<br />
The client API layer (level 1 and 2).<br />
<strong>CICS</strong>CLI command line<br />
The cicscli command interface.<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRINT<br />
cicsterm and cicsprnt emulators.<br />
CPP classes<br />
The C++ class libraries.<br />
Client daemon<br />
The Client daemon.<br />
Transport layer<br />
Interprocess communication.<br />
<strong>Gateway</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
JNI Trace<br />
You cannot enable JNI trace through the configuration tool. Use one of<br />
the following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
where filename is the name of the file to which trace output is to be<br />
sent.<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin<br />
protocol handler (see “TCPAdmin protocol settings” on page 64). See<br />
“Administering your system” on page 135 for details of how to enable<br />
JNI trace dynamically.<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v For Java Client applications running in local mode, use Java to launch<br />
your application and set the system property gateway.T.setJNITFile, as<br />
shown in the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
Protocol drivers level 1<br />
Protocol drivers (for example, TCP). This traces data sent and received<br />
and provides supplementary information about failures.<br />
Protocol drivers level 2<br />
This traces internal flows through the protocol drivers and interactions<br />
with other software components. It is currently only supported by the<br />
CCLTCP62 protocol driver.<br />
You can also use the M option with the cicscli command to specify trace<br />
components (excluding the <strong>Gateway</strong> daemon). This overrides any settings in<br />
the configuration file. For more information about the cicscli command, see<br />
“The cicscli command” on page 139.<br />
If you turn on tracing without specifying the components in either the cicscli<br />
command or in CTG.INI, a default set of components is traced:<br />
v Protocol drivers<br />
v The Client daemon<br />
v Client API level 1<br />
Selecting any of the check boxes in the configuration tool overrides the default<br />
set of components.<br />
<strong>Gateway</strong> trace file<br />
Enter the pathname of a trace file to which trace messages will be written, if<br />
tracing is enabled. If no path is specified, the trace is written as follows:<br />
/bin/CTG.TRC<br />
You can also specify a trace file using the tfile option on the ctgstart<br />
command.<br />
Configuration<br />
The trace file is overwritten (not appended to) each time the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> starts.<br />
Chapter 5. Configuration 79
Configuration<br />
Performance: Turning on the <strong>Gateway</strong> trace has a significant impact on<br />
performance. It is not recommended that <strong>Gateway</strong> trace is<br />
enabled in a production environment.<br />
<strong>Gateway</strong> trace wrap size<br />
Enter a value in the range 0 through 1 000 000 kilobytes.<br />
This value specifies the size in kilobytes to which the gateway trace file will<br />
grow. Subsequent trace entries will continue to be written from the beginning<br />
of the file. The default value of 0 disables wrapping.<br />
Client trace file<br />
Enter the pathname of a trace file to which trace messages will be written, if<br />
tracing is enabled.<br />
You do not have to enter an extension for the filename, as a file of type .BIN<br />
is always generated (or .WRP if the trace file wraps).<br />
If no path is specified, the trace is written as follows:<br />
/var/cicscli/<strong>CICS</strong>CLI.BIN<br />
To minimise any performance impact, the trace file is written out in binary<br />
format. To read it, convert the file to ASCII using the cicsftrc command.<br />
For more information about tracing, see “Tracing” on page 185.<br />
Maximum Client wrap size<br />
Enter a value in the range 0 through 65 535 KB.<br />
This value specifies how large the trace file will grow on disk before<br />
wrapping. The default value of 0 disables wrapping.<br />
Editing the configuration file<br />
Although it is recommended that you use the configuration tool you can edit<br />
the configuration file direct.<br />
The configuration file has the following sections:<br />
1. GATEWAY<br />
2. CLIENT<br />
3. SERVER<br />
4. DRIVER<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
For information on the properties in each section, refer to the descriptions of<br />
the corresponding settings in the configuration tool.<br />
The DRIVER section has no corresponding section in the configuration tool.<br />
The configuration tool automatically selects the correct protocol drivers.<br />
Each section has the format:<br />
SECTION sectioname [=value]<br />
# Comment describing the section<br />
property1=value<br />
property2=value<br />
...<br />
propertyN=value<br />
ENDSECTION<br />
Note: If you use the # character to denote a comment, either:<br />
v place it at the start of a line; or<br />
v precede it by a space or tab character<br />
because some valid names (for example modename) can start with the<br />
# character.<br />
J2EE setup and configuration<br />
Configuration<br />
This topic discusses the administration of <strong>CICS</strong> resource adapters. Two<br />
resource adapters are supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The<br />
/deployable directory contains an adapter for ECI (cicseci.rar),<br />
and one for EPI (cicsepi.rar).<br />
Any value set by the setExecuteTimeout method of the ECIInteractionSpec<br />
class is ignored; neither connector supports timeout. An alternative is to set<br />
the TIMEOUT parameter in the external <strong>CICS</strong> interface options table,<br />
DFHXCOPT. See the <strong>CICS</strong> External Interfaces Guide for more information.<br />
Deploying <strong>CICS</strong> resource adapters<br />
Before you can use a J2EE resource adapter in a server runtime environment<br />
you must supply parameters for its internal ManagedConnectionFactory class.<br />
In a managed environment you set these parameters when you deploy the<br />
resource adapter to your server. For instructions on how to do this consult<br />
your server’s documentation.<br />
<strong>CICS</strong> resource adapters are provided in standard resource adapter modules<br />
ready for deployment into a J2EE server environment. They can be packaged<br />
in J2EE applications along with other components such as Enterprise Beans,<br />
and used to create larger, more complex systems.<br />
Chapter 5. Configuration 81
Deployment parameters for the ECI resource adapter<br />
Deployment parameters for the ECI resource adapter<br />
This section describes the available deployment parameters for the ECI<br />
resource adapter, and their effect on the final deployed resource adapter. The<br />
tools used to configure these parameters are server-specific. Not all<br />
parameters are required; the default value is shown where appropriate.<br />
ConnectionURL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with which the resource<br />
adapter will communicate. The URL takes the form<br />
protocol://address. These protocols are available:<br />
v tcp<br />
v http<br />
v ssl<br />
v local<br />
So, for example, you might specify a URL of tcp://ctg.business.com.<br />
For the local protocol simply specify local:.<br />
PortNumber<br />
The port to connect to where the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running. This parameter is not relevant if you are using the local<br />
protocol.<br />
ServerName<br />
The name of the <strong>CICS</strong> server to connect to for all interactions through<br />
this resource adapter. This is the name as defined in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file. To use multiple servers within<br />
an environment you must deploy several resource adapters, each with<br />
a different ServerName attribute set.<br />
TranName<br />
The name of the <strong>CICS</strong> <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run.<br />
TPNName<br />
The name of the <strong>CICS</strong> TPN <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run. Note that TPNName<br />
takes precedence if both TranName and TPNName are specified.<br />
UserName<br />
The <strong>CICS</strong> userid to be used if no other security credentials are<br />
available. See the J2EE section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide for more information.<br />
Password<br />
The password for the <strong>CICS</strong> userid defined above.<br />
ClientSecurity<br />
The fully qualified name of the ClientSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Deployment parameters for the ECI resource adapter<br />
then no ClientSecurity class is used. For more information on what<br />
ClientSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
ServerSecurity<br />
The fully qualified name of the ServerSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ServerSecurity class is used. For more information on what<br />
ServerSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
KeyRingClass<br />
The fully qualified name of the SSL keyring class to use. This only<br />
applies when using the SSL protocol.<br />
KeyRingPassword<br />
The password for the class defined in KeyRingClass. Because it is<br />
linked to KeyRingClass, it is also optional, and applies only to the SSL<br />
protocol.<br />
TraceLevel<br />
The level of trace to be output by the resource adapter. For more<br />
details on trace levels and tracing see “Tracing” on page 86.<br />
As well as these user-definable properties, the ECI resource adapter has a set<br />
of predefined attributes that each deployed resource adapter will inherit.<br />
These properties are defined in the J2EE/CA specification and are as follows:<br />
<strong>Transaction</strong> Support<br />
The ECI resource adapter is defined as Local<strong>Transaction</strong>. If your<br />
server supports LastResourceOptimization, the resource adapter can<br />
participate in a global transaction, provided it is the only<br />
Local<strong>Transaction</strong> resource that has been enlisted.<br />
Re-Authentication Support<br />
The ECI resource adapter supports re-authentication. This is the<br />
ability to change the security credentials when a connection is<br />
requested from the server and an already existing one is allocated<br />
without having to disconnect and reconnect to the EIS. This improves<br />
performance.<br />
Deployment parameters for the EPI resource adapter<br />
The EPI resource adapter has the following deployment parameters. The tools<br />
used to configure these parameters are server-specific. Not all of these<br />
parameters are required; the default value is shown where appropriate.<br />
ConnectionURL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with which the resource<br />
Chapter 5. Configuration 83
Deployment parameters for the EPI resource adapter<br />
adapter will communicate. The URL takes the form<br />
protocol://address. These protocols are available:<br />
v tcp<br />
v http<br />
v ssl<br />
v local<br />
So, for example, you might specify a URL of tcp://ctg.business.com.<br />
For the local protocol simply specify local:.<br />
PortNumber<br />
The port to connect to where the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running. This parameter is not relevant if you are using the local<br />
protocol.<br />
ServerName<br />
The name of the <strong>CICS</strong> server to connect to for all interactions through<br />
this resource adapter. This is the name as defined in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file. To use multiple servers within<br />
an environment you must deploy several resource adapters, each with<br />
a different ServerName attribute set.<br />
UserName<br />
The <strong>CICS</strong> userid to be used if no other security credentials are<br />
available. See the J2EE section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide for more information.<br />
A LogonLogoff class is required if<br />
v The requested terminal is signon capable, or<br />
v The <strong>CICS</strong> Server does not support signon capable terminals (for<br />
example, <strong>CICS</strong> for OS/2)<br />
Password<br />
The password for the <strong>CICS</strong> userid defined above.<br />
ClientSecurity<br />
The fully qualified name of the ClientSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ClientSecurity class is used. For more information on what<br />
ClientSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
ServerSecurity<br />
The fully qualified name of the ServerSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ServerSecurity class is used. For more information on what<br />
ServerSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Deployment parameters for the EPI resource adapter<br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
KeyRingClass<br />
The fully qualified name of the SSL keyring class to use. This only<br />
applies when using the SSL protocol.<br />
KeyRingPassword<br />
The password for the class defined in KeyRingClass. Because it is<br />
linked to KeyRingClass, it is also optional, and applies only to the SSL<br />
protocol.<br />
SignonType<br />
The EPI resource adapter allows you to define whether the terminals<br />
on <strong>CICS</strong> that are used by the resource adapter are signon capable or<br />
incapable. Acceptable values are:<br />
v 0 — Signon capable terminal (default)<br />
v 1 — Signon incapable terminal<br />
Encoding<br />
The Java Encoding to use when creating 3270 datastreams. The<br />
encoding will be converted to the appropriate CCSid. See the<br />
appendix in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
manual for a list of supported encodings. Ensure that your <strong>CICS</strong><br />
Server supports the CCSid from the given encoding.<br />
LogonLogoffClass<br />
The fully qualified name of the Java Class that provides the logic to<br />
Logon to a <strong>CICS</strong> Server using signon transactions. This property is<br />
mandatory for signon capable terminals and for <strong>CICS</strong> servers that do<br />
not support signon capability (such as <strong>CICS</strong> for OS/2).<br />
DeviceType<br />
The Terminal Model type, as defined in <strong>CICS</strong>, to be used by this<br />
resource adapter.<br />
ReadTimeout<br />
The maximum time a <strong>CICS</strong> server waits for a response from a user or<br />
J2EE component when taking part in a conversational transaction.<br />
Acceptable values for this parameter are:<br />
0 No timeout.<br />
1– 3600 Time in seconds.<br />
InstallTimeout<br />
The timeout value for terminal installation on <strong>CICS</strong>. The acceptable<br />
values for this parameter are as follows:<br />
0 No timeout.<br />
Chapter 5. Configuration 85
Deployment parameters for the EPI resource adapter<br />
1– 3600 Time in seconds.<br />
TraceLevel<br />
The level of trace to be output by the resource adapter. For more<br />
details on trace levels and tracing see “Tracing”.<br />
As well as these user-definable properties, the EPI resource adapter has a set<br />
of predefined attributes that each deployed resource adapter will inherit.<br />
These properties are defined in the J2EE/CA specification and are as follows:<br />
<strong>Transaction</strong> Support<br />
The EPI resource adapter is nontransactional. It can be used within<br />
transactional contexts, but does not react to commit or rollback<br />
requests.<br />
Re-Authentication Support<br />
The EPI resource adapter supports re-authentication. This is the ability<br />
to change the security credentials when a connection is requested<br />
from the server and an already existing one is allocated, without<br />
having to disconnect and reconnect to the EIS. This improves<br />
performance. A LogonLogoff class is required if the terminal requested<br />
is SignonCapable, or if the <strong>CICS</strong> Server does not support signon<br />
capable terminals (such as <strong>CICS</strong> for OS/2).<br />
Tracing<br />
To help you in problem determination with any J2EE resource adapter<br />
applications that use the <strong>CICS</strong> resource adapters, a detailed tracing function is<br />
provided in both the ECI and EPI resource adapters. The <strong>CICS</strong> resource<br />
adapters support four levels of trace:<br />
0 No trace messages<br />
1 Exception tracing only (default level)<br />
2 Exception and method entry/exit trace messages<br />
3 Exception, method entry/exit and debug trace messages<br />
To provide more control over tracing, these system properties are available:<br />
com.ibm.connector2.cics.tracelevel<br />
This allows you to override the deployed trace level for the resource<br />
adapters without having to redeploy or deploy another <strong>CICS</strong> resource<br />
adapter.<br />
com.ibm.connector2.cics.dumpoffset<br />
The offset into a byte array that a hex dump will start at.<br />
com.ibm.connector2.cics.dumplength<br />
The maximum length of data displayed in a hex dump.<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
com.ibm.connector2.cics.outputerr<br />
Declaring this directive sends trace output to standard error, if no<br />
other trace location has been specified either by the J2EE server, or by<br />
the application developer working in a nonmanaged environment. In<br />
other circumstances the provided logwriter takes precedence.<br />
Control of where trace is output is handled by the ConnectionManager being<br />
used by your environment. In a managed environment an option should be<br />
provided to allow you to set the path of the file that will be used for storing<br />
trace. Depending on how your environment allocates ConnectionManagers to<br />
resource adapters this file may contain messages from other resource adapters<br />
using the same ConnectionManager.<br />
When you deploy the <strong>CICS</strong> resource adapters into your environment, security<br />
restrictions are set up to allow access to the local file system for the purpose<br />
of writing trace files. The permissions used restrict access to this path:<br />
${user.home}${file.separator}IBM${file.separator}CTG${file.separator}-<br />
This might map to:<br />
/home/ctguser/IBM/CTG/-<br />
Therefore, when setting the name and path of the trace file in your J2EE<br />
environment, use a location below this directory structure to store your trace.<br />
Otherwise the resource adapters will not have security permissions to write to<br />
the file.<br />
Sample configuration and mapping files<br />
The following files are supplied in the /bin subdirectory:<br />
CTGSAMP.INI A sample configuration file. (The default<br />
configuration file name is CTG.INI.)<br />
<strong>CICS</strong>KEY.INI The keyboard mapping file. (A sample file<br />
<strong>CICS</strong>KEYSAMP.INI is also provided.)<br />
<strong>CICS</strong>COL.INI The color mapping file. (A sample file<br />
<strong>CICS</strong>COLSAMP.INI is also provided.)<br />
It is recommended that you create your own customized versions of these<br />
files with different names, because installation of service updates may<br />
overwrite the files and cause any customization to be lost.<br />
Tracing<br />
Reference your customized files through the following environment variables:<br />
File Environment variable<br />
configuration file <strong>CICS</strong>CLI<br />
Chapter 5. Configuration 87
Sample configuration and mapping files<br />
keyboard mapping file <strong>CICS</strong>KEY<br />
color mapping file <strong>CICS</strong>COL<br />
Keyboard mapping for cicsterm<br />
The keyboard mapping for terminal emulator operation is defined in a<br />
keyboard mapping file. A sample key mapping file is supplied with your<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>; see “Sample configuration and mapping files” on<br />
page 87 for details. It is recommended that you create your own customized<br />
mapping file.<br />
The keyboard mapping file can be specified by:<br />
v The -k option of the cicsterm command, which identifies a keyboard<br />
mapping file with a particular terminal (see page “Keyboard mapping for<br />
cicsterm”).<br />
v The <strong>CICS</strong>KEY environment variable. For example:<br />
export <strong>CICS</strong>KEY=/var/cicscli/MYKEYS.INI<br />
If you do not specify otherwise, a filename of <strong>CICS</strong>KEY.INI in the<br />
/bin subdirectory is assumed.<br />
You can change the keyboard mapping file at any time, although changes do<br />
not take effect until the next time the terminal emulator is started.<br />
Keyboard mapping file syntax<br />
This section describes the syntax of the keyboard mapping file. A statement<br />
must be provided for each key that is needed, because there are no default<br />
assignments (except for the alphabetic and numeric keys). There is no case<br />
sensitivity. Each binding must be on a separate line, and of the following<br />
form:<br />
Keyboard mapping file syntax<br />
►► BIND 3270function<br />
modifier+<br />
key<br />
; comment<br />
#<br />
For example, to map the 3270 function EraseEof to the Ctrl+Delete keys<br />
pressed together the binding is as follows:<br />
bind EraseEof Ctrl+Delete ;erase to end of field<br />
The keyboard mapping file<br />
In the mapping file, 3270function can be any one of the following:<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
►◄
ackspace pa1 pf1 pf13<br />
backtab pa2 pf2 pf14<br />
clear pa3 pf3 pf15<br />
cursordown pf4 pf16<br />
cursorleft printscreen pf5 pf17<br />
cursorright reset pf6 pf18<br />
cursorselect tab pf7 pf19<br />
cursorup pf8 pf20<br />
delete ignore pf9 pf21<br />
enter pf10 pf22<br />
eraseeof pf11 pf23<br />
eraseinput pf12 pf24<br />
home<br />
insert<br />
newline<br />
The value of ignore is provided to permit unwanted control keys on the<br />
keyboard to be ignored. (Unexpected glyphs are not generated.)<br />
The Modifier can be either:<br />
Ctrl<br />
Shift<br />
The Key can be any one of the keys shown in Table 8, (but some combinations<br />
of modifier+key are not supported — see “Key combinations” on page 90):<br />
Table 8. Keys that you can map<br />
Group Keys<br />
Escape key Escape<br />
Function keys f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12<br />
Numeric keys 0 1 2 3 4 5 6 7 8 9<br />
Alphabetic keys a b c d e f g h i j k l m<br />
n o p q r s t u v w x y z<br />
Tab key Tab<br />
Movement keys newline backspace<br />
insert home pageup<br />
delete end pagedown<br />
up left down right<br />
Keypad keys keypad/ keypad* keypadkeypad7<br />
keypad8 keypad9<br />
keypad4 keypad5 keypad6 keypad+<br />
keypad1 keypad2 keypad3<br />
keypad0 keypad. keypadenter<br />
Keyboard mapping for cicsterm<br />
Chapter 5. Configuration 89
Keyboard mapping for cicsterm<br />
Note: For the Client daemon, the Ctrl/Act, Print Screen, Scroll Lock and<br />
Pause keys are not available. The 3270 function Clear is assigned to the<br />
Esc key by default.<br />
Key combinations<br />
The following combinations of modifier and key can be mapped:<br />
No modifier All keys available for mapping.<br />
Ctrl modifier Only function keys, movement keys,<br />
alphabetic keys, tab key, and keypad keys can<br />
be mapped.<br />
Shift modifier Only function keys, numeric keys, tab key,<br />
and alphabetic keys can be mapped.<br />
Customizing the screen colors for cicsterm<br />
Screen colors and attributes are defined in a color mapping file. A sample is<br />
provided for you to tailor; see “Sample configuration and mapping files” on<br />
page 87 for details. It is recommended that you create your own customized<br />
mapping file.<br />
The color mapping file can be identified by either of these methods:<br />
v The -c option of the cicsterm command, which identifies a color mapping<br />
file with a particular server (see page “Customizing the screen colors for<br />
cicsterm”).<br />
v The <strong>CICS</strong>COL environment variable: For example:<br />
export <strong>CICS</strong>COL=/var/cicscli/MYCOLS.INI<br />
If you do not specify otherwise, a filename of <strong>CICS</strong>COL.INI in the<br />
/bin subdirectory is assumed.<br />
A color mapping file provides alternative representations in hardware<br />
environments where it is not possible exactly to replicate 3270 screen<br />
attributes, for example, blinking or underscore. The color mapping file<br />
therefore defines how 3270 screen attributes are emulated on the client<br />
hardware.<br />
The color mapping file is optional. However, for most hardware environments<br />
a mapping file is required if blinking or underscore support is required by the<br />
emulator.<br />
Notes:<br />
1. If the color mapping file specifies a mapping for an attribute, this mapping<br />
is used even if the hardware upon which the client is running actually<br />
supports the screen attribute.<br />
90 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
2. If an application requests a 3270 field to be displayed with, for example,<br />
underscore, and no emulation setting has been specified, and the hardware<br />
cannot display underscore, then the field is displayed without any<br />
highlighting at all.<br />
You can change the color mapping file at any time, although changes do not<br />
take effect until the next time the terminal emulator is started.<br />
Color mapping syntax<br />
The syntax of the color mapping file is as follows. Each binding must be on a<br />
separate line, in this form:<br />
Color mapping file syntax<br />
►► BIND 3270attrib fg_color<br />
/bg_color ; comment<br />
#<br />
The file is not case-sensitive.<br />
The color mapping file<br />
In the color mapping file, 3270attrib can be any one of the following:<br />
normal_protected intensified_protected<br />
normal_unprotected intensified_unprotected<br />
default blinking_default underscored_default<br />
blue blinking_blue underscored_blue<br />
green blinking_green underscored_green<br />
cyan blinking_cyan underscored_cyan<br />
red blinking_red underscored_red<br />
magenta blinking_magenta underscored_magenta<br />
white blinking_white underscored_white<br />
yellow blinking_yellow underscored_yellow<br />
default_highlight<br />
operator_information_area<br />
Each of fg_color and bg_color (foreground color and background color) can be<br />
any one of the following:<br />
black light_gray<br />
blue light_blue<br />
brown yellow<br />
cyan light_cyan<br />
green light_green<br />
magenta light_magenta<br />
red light_red<br />
gray white<br />
Customizing the screen colors for cicsterm<br />
If bg_color is omitted, a default value of black is taken.<br />
►◄<br />
Chapter 5. Configuration 91
|<br />
|<br />
|<br />
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
Preparing to use local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
Before you can run an application that uses the local <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> support, ensure that you have correctly configured your<br />
environment. The following are required:<br />
1. A correctly configured Java environment<br />
AIX:<br />
Use a shell command like the following to add the /bin<br />
subdirectory to your LIBPATH:<br />
export LIBPATH=/bin:${LIBPATH}<br />
Other UNIX operating systems:<br />
A Java application that uses the local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> support<br />
is a normal Java program, and so is executed with the standard JDK Java<br />
executable. Your environment must be correctly set so that the Java<br />
binaries, libraries, and classes can be found. Refer to the JDK<br />
documentation for the correct environment settings.<br />
2. The correct settings to allow the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> binaries to<br />
be found<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> .class files need to be available. Set your<br />
CLASSPATH environment variable to include the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>’s ctgserver.jar and ctgclient.jar archives. Also, the relevant<br />
binaries must be available.<br />
On Linux and Solaris, set your LD_LIBRARY_PATH environment variable to<br />
include the /bin subdirectory so that your application can<br />
find libCTGJNI.so.<br />
On HP-UX set your SHLIB_PATH environment variable to include the<br />
/bin subdirectory so that your application can find<br />
libCTGJNI.so.<br />
On AIX, set your PATH environment variable to include the<br />
/bin subdirectory, so that the cicsjava script can be called<br />
easily.<br />
To run the application: use the JDK java command with suitable options.<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 6. Network Security<br />
This chapter describes how to set up <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to use the<br />
network security protocols SSL and HTTPS. This chapter consists of the<br />
following:<br />
“Determining your use of SSLight or JSSE<br />
for the SSL and HTTPS protocols” on<br />
page 94<br />
“Maintaining your digital certificates for<br />
SSLight” on page 94<br />
“Using externally signed certificates<br />
under SSLight” on page 95<br />
“Using self-signed certificates under<br />
SSLight” on page 100<br />
Read this for information on how <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> determines whether<br />
you are using SSLight or JSSE.<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
SSLight.<br />
“Migration from SSLight” on page 104 Read this for information on migrating<br />
from SSLight to JSSE.<br />
“Installation” on page 104 Read this for information on installing<br />
JSSE.<br />
“Maintaining your digital certificates for<br />
JSSE” on page 105<br />
“Using externally signed certificates<br />
under JSSE” on page 105<br />
“Using self-signed certificates under JSSE”<br />
on page 110<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for SSL and HTTPS” on page 114<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
JSSE.<br />
Read this for information on how to<br />
configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
use the secure protocols.<br />
© Copyright IBM Corp. 1996, 2002 93
|<br />
|<br />
Security<br />
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols<br />
SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> determines whether you wish to use SSLight or<br />
JSSE as follows:<br />
v If you pass a KeyRing class to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using SSLight.<br />
v If you pass a KeyStore file to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using JSSE.<br />
Conflict with JSSE<br />
SSLight might not function correctly if JSSE is installed on your system. If<br />
JSSE is installed, rename file gskikm.jar, intheJRE/EXT directory.<br />
Maintaining your digital certificates for SSLight<br />
iKeyMan<br />
Use the ctgikey command to invoke iKeyMan for certificate management.<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 95.<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 100.<br />
v Add certificates to your KeyRing files.<br />
v Change your KeyRing password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyRing.<br />
Distributing iKeyMan to client workstations<br />
Although you perform most of the KeyRing management on the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> machine, you might need to distribute the iKeyMan tool<br />
to clients connecting to your SSL server. The client machines must have the<br />
minimum level of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Java support; see “Supported<br />
software” on page 23. They might also require a script or command file to<br />
invoke the iKeyMan Java startup class.<br />
The following is an example of a command that you can use to invoke<br />
iKeyMan with the JDK or the JRE:<br />
94 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Maintaining your digital certificates for SSLight<br />
java -classpath<br />
"/cfwk.zip;/gsk5cls.jar;"<br />
-Dkeyman.javaOnly=true com.ibm.gsk.ikeyman.Ikeyman<br />
Where is the directory where ikeyman is installed.<br />
These examples assume that the client workstation has the following files in<br />
the ikeyman directory:<br />
v cfwk.zip<br />
v cfwk.sec<br />
v gsk5cls.jar<br />
v ikminit.properties<br />
All of these files are in the /classes subdirectory.<br />
Using iKeyman in DBCS environments<br />
If you have trouble running iKeyman in your locale, you can use this<br />
command to run it in English:<br />
java -classpath "/classes/cfwk.zip:<br />
/classes/gsk5cls.jar:"<br />
-Dkeyman.javaOnly=true<br />
-Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman<br />
Using externally signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyRing class<br />
2. Creating a certificate request<br />
3. Obtaining a digital certificate<br />
4. Receiving the digital certificate into the KeyRing<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyRings, or, in the case of HTTPS connections, the repository in<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyRing<br />
Chapter 6. Network Security 95
Using externally signed certificates under SSLight<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 98.<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Using externally signed certificates under SSLight<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site and request a Test<br />
Server Certificate:<br />
a. Point your Web browser at: www.verisign.com and navigate to their<br />
request Test Server Certificate application pages.<br />
b. Open the certificate request file you created earlier, using an ASCII text<br />
editor.<br />
Figure 19 on page 98 shows an example of a certificate request.<br />
c. During the Test Server Certificate request process you will be asked to<br />
submit your CSR — Copy and paste the contents of the file into the<br />
text box in the Web page.<br />
d. Verify the contents of your certificate request and provide the personal<br />
details when requested.<br />
If you are requesting a full VeriSign Server ID, rather than a test<br />
version, these details are used to authenticate your application.<br />
e. VeriSign processes your enrollment and sends an e-mail to the address<br />
specified in your personal details.<br />
This e-mail contains your Test Server Certificate, and instructions on<br />
how to:<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
Chapter 6. Network Security 97
Using externally signed certificates under SSLight<br />
-----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u<br />
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC<br />
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP<br />
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF<br />
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx<br />
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH<br />
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq<br />
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh<br />
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW<br />
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY<br />
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ<br />
-----END NEW CERTIFICATE REQUEST-----<br />
Figure 19. Example certificate request<br />
4. Receive the Server Certificate into the server KeyRing<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyRing.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyRing MyServerKeyRing.class is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyRing class, or in the case of HTTPS, the browser certificate<br />
repository, must contain the signer certificate of the Server Certificate. In our<br />
example, the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following sections describes how to obtain a VeriSign Digital ID.<br />
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Using externally signed certificates under SSLight<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyRing class<br />
using the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyRing class.<br />
3. Import the Client Certificate into the client KeyRing<br />
To import the #PKCS12 file containing the Client Certificate:<br />
Chapter 6. Network Security 99
Using externally signed certificates under SSLight<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Your client KeyRing MyClientKeyRing.class is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyRing classes<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyRing<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
Using self-signed certificates under SSLight<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 98.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyRing class:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
Chapter 6. Network Security 101
Using self-signed certificates under SSLight<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Import the server’s signer certificate<br />
a. In iKeyMan select Add<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Using self-signed certificates under SSLight<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyRing need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyRing.class file with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support<br />
server authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyRing class also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
Chapter 6. Network Security 103
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under SSLight<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Migrating old self-signed certificates(Solaris and AIX operating systems<br />
only)<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyRing class files, created with <strong>Version</strong> 3.0,<br />
using the iKeyMan tool.<br />
Restricting access to the server KeyRing<br />
The contents of the server KeyRing are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyRing class files have appropriate security access<br />
permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Java Secure Socket Extension (JSSE)<br />
Migration from SSLight<br />
To avoid possible conflicts between the different versions of iKeyMan used in<br />
SSLight and JSSE, IBM strongly recommends that you perform all migration<br />
actions before you install JSSE.<br />
To migrate from SSLight to JSSE:<br />
v Create new KeyStores and use these instead of existing KeyRing classes<br />
v Change existing security exits that implement the SSLightServerSecurity<br />
interface to implement the JSSEServerSecurity interface<br />
Installation<br />
See “Supported software” on page 23 for details of environments in which<br />
JSSE is supported.<br />
If you do not have a supported level of JSSE on your system, you need to<br />
install the version supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. JSSE support is<br />
included in two zip files supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
product:<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v ibm-jsse.zip<br />
v ibm-jce.zip<br />
Copy the zip files to the jre subdirectory of your Java installation directory<br />
on your system, and extract the archived files into this directory.<br />
The Java root directory is the directory which has jre as a subdirectory.<br />
On HP-UX and Solaris, you might need to update the<br />
lib/security/java.security file. In this file, locate the lines which begin<br />
security.provider and add a line like the following if it does not already<br />
exist:<br />
security.provider.=com.ibm.crypto.provider.IBMJCE<br />
where is the next number in sequence following any existing entries.<br />
Maintaining your digital certificates for JSSE<br />
iKeyMan<br />
Use the following command to start the iKeyMan program:<br />
java com.ibm.ikeyman.Ikeyman<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 95.<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 100.<br />
v Add certificates to your KeyStore files.<br />
v Change your KeyStore password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyStore.<br />
Using externally signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyStore<br />
2. Creating a certificate request<br />
Installing JSSE<br />
Chapter 6. Network Security 105
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
3. Obtaining a digital certificate<br />
4. Receiving the digital certificate into the KeyStore<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyStores, or, in the case of HTTPS connections, the repository in<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyStore<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 108.<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site (www.verisign.com)<br />
and request a Test Server Certificate. You will be asked to paste in the<br />
contents of the certificate request file you created earlier (Figure 19 on<br />
page 98 shows an example of a certificate request) and agree to their<br />
licensing conditions. VeriSign will then send you a confirmation e-mail.<br />
This e-mail contains your Test Server Certificate, and instructions on how<br />
to:<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
Chapter 6. Network Security 107
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
4. Receive the Server Certificate into the server KeyStore<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyStore.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyStore MyServerKeyStore.jks is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyStore, or in the case of HTTPS, the browser certificate repository,<br />
must contain the signer certificate of the Server Certificate. In our example,<br />
the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following instructions describe how to obtain a VeriSign Digital ID.<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyStore using<br />
the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyStore.<br />
3. Import the Client Certificate into the client KeyStore<br />
To import the #PKCS12 file containing the Client Certificate:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Chapter 6. Network Security 109
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
Your client KeyStore MyClientKeyStore.jks is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyStores<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyStore<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
Using self-signed certificates under JSSE<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 108.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyStore:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
Chapter 6. Network Security 111
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Import the server’s signer certificate<br />
a. In iKeyMan select Add<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyStore need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyStore.jks file with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support server<br />
authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyStore also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Chapter 6. Network Security 113
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
Migrating old self-signed certificates(Solaris and AIX operating systems<br />
only)<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyStore files, created with <strong>Version</strong> 3.0, using the<br />
iKeyMan tool.<br />
Restricting access to the server KeyStore<br />
The contents of the server KeyStore are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyStore files have appropriate security access permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
To use the SSL and HTTPS protocols, enable them using the configuration<br />
tool; see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings” on page 53. You<br />
can specify that either or both of the protocols is used. When you enable the<br />
protocols, by default, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> listens for SSL requests on<br />
port 8050, and for HTTPS requests on port 443.<br />
SSL and HTTPS configuration settings<br />
The following configuration settings are specific to the SSL and HTTPS<br />
protocols:<br />
KeyRing or KeyStore name Specifies the name of the server KeyRing or<br />
KeyStore.<br />
For a KeyRing, you must also add the<br />
classname to the CLASSPATH environment<br />
variable.<br />
KeyRing or KeyStore password<br />
Specifies the password used to read the<br />
encrypted server KeyRing or KeyStore.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the<br />
password to the configuration file in a form<br />
that prevents a casual observer from easily<br />
reading it.<br />
Use client authentication Enables client authentication. The default is<br />
that only server authentication is enabled.<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides two default KeyRing class files,<br />
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS<br />
connections under SSLight. Both KeyRings have been encrypted using the<br />
password default. Use them only in testing environments.<br />
Specifying a client KeyRing or KeyStore<br />
Your choice of secure protocol determines whether or not you need a<br />
KeyRing, or KeyStore, for both server and client:<br />
HTTPS<br />
Specify a KeyRing or KeyStore only in the server.<br />
SSL<br />
The SSL protocol requires you to specify KeyRings, or KeyStores for both the<br />
server and the client.<br />
For more information see SSL Java<strong>Gateway</strong>, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide.<br />
Using the SSL and HTTPS protocols<br />
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP<br />
protocols. To make a connection to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, your client<br />
application flows a request using the appropriate URL. For example, for SSL<br />
use a URL like:<br />
ssl://trans<strong>Gateway</strong>Machine:8050<br />
Similarly, for HTTPS:<br />
https://trans<strong>Gateway</strong>Machine:443<br />
For more information on the design and implementation of client-side<br />
programs, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> programming interface HTML pages.<br />
Chapter 6. Network Security 115
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 7. Client Security<br />
Overview<br />
This chapter describes how to provide a userid and password when<br />
connecting to a <strong>CICS</strong> server. It consists of the following:<br />
“Overview” Read this for an overview of <strong>CICS</strong><br />
client/server security.<br />
“Default connection settings” on page 118 Read this for information on setting<br />
default values for userid and password.<br />
“ECI security” on page 118 Read this for information on providing a<br />
userid and password on an ECI request.<br />
“EPI terminal security” on page 118 Read this for information on providing a<br />
userid and password on an EPI request.<br />
“Signon capable and signon incapable<br />
terminals” on page 120<br />
Read this for information on signon<br />
capable and signon incapable terminals.<br />
<strong>CICS</strong> servers may require the Client daemon to supply a userid and password<br />
before they permit the following:<br />
v A client connection<br />
v Terminals to be installed<br />
v <strong>Transaction</strong>s to be run<br />
This depends on the server and protocol security settings. The userid and<br />
password are sent to the server in the FMH header of the transaction attach<br />
request for each conversation. A userid and password are also required when<br />
a signon transaction is invoked on a signon capable terminal. In this instance,<br />
the userid and password are flowed to the server as part of the 3270<br />
datastream.<br />
Because the Client daemon has no security manager, it does not support<br />
userid authentication. It is recommended that you configure your <strong>CICS</strong> server<br />
client connections so that incoming attach requests must specify a userid and<br />
password. For mainframe servers, specify AttachSec = Verify in the <strong>CICS</strong><br />
connection definition. AttachSec = Identify, which indicates that userid, but<br />
not password, are required, is not supported for client connections.<br />
Note: Userids and passwords must not contain DBCS characters.<br />
© Copyright IBM Corp. 1996, 2002 117
Client Security<br />
Default connection settings<br />
ECI security<br />
The Client daemon maintains a default userid and password for each server<br />
connection, which may be set by any of the following methods:<br />
v <strong>CICS</strong>CLI security commands:<br />
cicscli /c=servername /u=userid /p=password<br />
The servername parameter can also be specified with the /s option.<br />
v From C use the ESI function <strong>CICS</strong>_SetDefaultSecurity. This call is not<br />
available from the Java APIs.<br />
v From C++, use the makeSecurityDefault method of the CclConn or<br />
CclTerminal class.<br />
These default values are used when required on all subsequent transaction<br />
requests for that server, provided that no values have been passed on the ECI<br />
request itself, or have been set for the specific EPI terminal against which the<br />
transaction will run.<br />
Note: If the Client daemon is running in an environment where it survives<br />
user logoff, the default userid and password values entered by the<br />
currently logged on user are retained even when that user logs off, and<br />
are subsequently reused as required.<br />
An application may provide a userid and password on an ECI request and<br />
these values will override any default values set for the server connection as<br />
follows.<br />
v C programs:<br />
Set eci_userid and eci_password or eci_userid2 and eci_password2 in the<br />
ECI parameter block.<br />
v C++ programs:<br />
Set the userid and password parameters when constructing a server<br />
connection object - CclConn.<br />
v Java client programs:<br />
Set the userid and password parameters when constructing an ECIRequest<br />
object.<br />
EPI terminal security<br />
The Client daemon also maintains a userid and password per installed<br />
terminal. These values will override any default values set for the server<br />
connection. They can be set by one of the following methods:<br />
v C programs:<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Client Security<br />
Set UserId and Password in the <strong>CICS</strong>_EpiAttributes_t structure on a<br />
<strong>CICS</strong>_EpiAddExTerminal call. Or, use the EPI function<br />
<strong>CICS</strong>_EpiSetSecurity. This call would typically be used to change the<br />
terminal security settings if, for example, the user’s password had expired.<br />
v C++ programs:<br />
Set the userid and password parameters when constructing a CclTerminal<br />
class object. Or, use the alterSecurity method of the CclTerminal class.<br />
v Java client programs:<br />
– EPI Request Classes<br />
Set the userid and password parameters when constructing an<br />
EPIRequest object via the addTerminal or addTerminalAsync method.<br />
Or, use the alterSecurity method of the EPIRequest class.<br />
– EPI Support Classes<br />
Create a Terminal object using the default Constructor, then use<br />
setUserid and setPassword to set security, or create a Terminal object<br />
using the extended Constructor.<br />
– EPI Beans<br />
Set the Userid and Password properties on the extended terminal<br />
properties panel or programmatically by creating an EPI Terminal bean,<br />
get the terminal object it holds using getTerminal() and then use<br />
setUserid and setPassword.<br />
v Terminal Servlet<br />
Set pool@userid and pool@password. These settings apply to all terminals<br />
in the pool.<br />
Terminal security cannot be set when using the <strong>CICS</strong> CCF Connectors.<br />
Terminal security would normally only be required if using signon incapable<br />
terminals.<br />
Password expiry management<br />
For <strong>CICS</strong> clients the management of expired passwords can be handled by the<br />
ESI functions <strong>CICS</strong>_ChangePassword and <strong>CICS</strong>_VerifyPassword.<br />
The ESI functions can be used only with <strong>CICS</strong> servers that support password<br />
expiry management (PEM). See “Supported software” on page 23, for<br />
information on supported servers. Refer to the documentation for your <strong>CICS</strong><br />
server for information on PEM support.<br />
To use PEM, the Client daemon must be connected to the <strong>CICS</strong> server over<br />
SNA or TCP62. An ESM, such as resource access control facility (RACF ® ), must<br />
also be available to the <strong>CICS</strong> server. ESI calls can be included within your ECI<br />
Chapter 7. Client Security 119
Client Security<br />
or EPI application. Only <strong>CICS</strong> servers returned by the <strong>CICS</strong>_EciListSystems<br />
and <strong>CICS</strong>_EpiListSystems functions are acceptable.<br />
Signon capable and signon incapable terminals<br />
Signon capable terminals allow signon transactions, either <strong>CICS</strong>-supplied<br />
(CESN) or user-written, to be run, whereas signon incapable terminals do not<br />
allow these transactions to be run.<br />
If a terminal resource is installed as signon capable, the application or user is<br />
responsible for starting a signon transaction; the userid and password once<br />
entered are embedded in the 3270 data.<br />
v <strong>Transaction</strong>s started before the signon transaction will execute with the<br />
authorities granted to the default userid defined for the server. A check is<br />
also done against the userid associated with the connection to see whether<br />
the Client daemon itself has authority to access the resource.<br />
v <strong>Transaction</strong>s started after the signon transaction will execute with the<br />
authorities granted to the authenticated userid. For transactions attempting<br />
to access resources, security checking is done against the signed-on user’s<br />
userid and the userid associated with the connection. If a server supports<br />
signon timeout and a client terminal is left idle so that the timeout expires,<br />
the user is signed off without notification and the next transaction will run<br />
against the default userid.<br />
If the terminal resource is installed as signon incapable, the userid and<br />
password are authenticated for each transaction started for the terminal<br />
resource.<br />
Prior to <strong>Version</strong> 3.1.0 of Clients and <strong>Gateway</strong>s, whether a terminal was signon<br />
capable or not was dependant upon the server implementation. Client<br />
terminals installed on distributed <strong>CICS</strong> servers were signon capable and<br />
terminals installed on mainframe <strong>CICS</strong> and <strong>CICS</strong>/400 servers were signon<br />
incapable.<br />
In <strong>Version</strong> 3.1.0, extended EPI function was introduced to allow the signon<br />
capability of a terminal to be specified by one of the following methods.<br />
v C programs:<br />
Use <strong>CICS</strong>_EpiAddExTerminal and set the SignonCapability parameter in<br />
the <strong>CICS</strong>_EpiAttributes_t structure.<br />
v C++ programs:<br />
Set the signon capability parameter when constructing a CclTerminal class<br />
object.<br />
v Java client programs:<br />
– EPI Request Classes<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Set the signon capability parameter when constructing an EPIRequest<br />
object via the addTerminal or addTerminalAsync method.<br />
– EPI Support Classes<br />
Create a Terminal object using the default Constructor, then use<br />
setSignonCapability, or create a Terminal object using the extended<br />
Constructor. If a terminal is in disconnected state (ie has been<br />
disconnected, or never connected) calling setSignonCapability allows you<br />
to change the signon capability for the terminal and changes the terminal<br />
type to extended. When you connect, you connect an extended terminal<br />
with that signon capability. If you setSignonCapability while a terminal<br />
is connected then it get’s saved away, it does not alter the connected<br />
setting.<br />
– EPI Beans<br />
Set the SignonCapability property on the extended terminal properties<br />
panel, or programmatically by creating an EPI Terminal bean, get the<br />
terminal object it holds using getTerminal() and then use<br />
setSignonCapability.<br />
v Terminal Servlet<br />
Assign the appropriate Signon capability string to the Servlet Property<br />
pool@signonCapability. These settings apply to all terminals in the pool.<br />
The signon capability of the installed terminal is returned in the terminal<br />
attributes. This will be set to SIGNON_UNKNOWN if the server does not<br />
return a signon capability parameter in the terminal install (CTIN) response.<br />
The signon capability of a terminal cannot be specified when using the <strong>CICS</strong><br />
CCF Connectors. If you are using this interface, the EPI functionality available<br />
is unchanged from <strong>Version</strong> 3.0.x, that is, you cannot specify a userid and<br />
password per terminal, or specify the signon capability.<br />
To use any of the extended EPI functionality, you must ensure that you have<br />
applied the relevant server APAR; see “<strong>CICS</strong> server PTF requirements” on<br />
page 26.<br />
Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Programming Guide for further information.<br />
Mainframe <strong>CICS</strong> servers<br />
These servers support both signon capable and incapable terminals, provided<br />
that they are at the prerequisite maintenance level; see “<strong>CICS</strong> server PTF<br />
requirements” on page 26. A terminal install request that does not specify any<br />
signon capability, for example from <strong>CICS</strong>_EpiAddTerminal, will result in a<br />
signon incapable terminal being installed.<br />
For signon capable terminals:<br />
Client Security<br />
Chapter 7. Client Security 121
Client Security<br />
v Use the <strong>CICS</strong>_EpiAddExTerminal call specifying a SignonCapability of<br />
<strong>CICS</strong>_EPI_SIGNON_CAPABLE.<br />
v You do not need to set the userid and password fields on the<br />
<strong>CICS</strong>_EpiAddExTerminal call or use <strong>CICS</strong>_EpiSetSecurity, provided that<br />
you specify UseDfltUser = Yes in the <strong>CICS</strong> connection definition on the<br />
server.<br />
v A userid and password entered through a signon transaction are flowed to<br />
the server as part of the 3270 datastream and they will therefore appear in a<br />
client trace.<br />
It is recommended that you specify UseDfltUser = Yes in the <strong>CICS</strong><br />
CONNECTION definition, or ensure that the system administrator sets a<br />
default connection userid and password for the client. Otherwise, the add<br />
terminal request may fail with an EPI_ERR_SECURITY return code.<br />
v Before the user has signed on, transactions will run under the default<br />
userid for the <strong>CICS</strong> server. After signon, transactions will run under the<br />
signed-on userid.<br />
For signon incapable terminals without terminal security:<br />
v Use the <strong>CICS</strong>_EpiAddTerminal call<br />
v A connection userid and password will be required regardless of the setting<br />
of the UseDfltUser in the <strong>CICS</strong> connection definition on the server.<br />
v <strong>Transaction</strong>s will run under the userid specified in the corresponding FMH<br />
attach request.<br />
For signon incapable terminals with terminal security:<br />
v Use the EpiAddExTerminal call specifying a SignonCapability of<br />
<strong>CICS</strong>_EPI_SIGNON_INCAPABLE.<br />
v Set the userid and password fields on the <strong>CICS</strong>_EpiAddExTerminal call.<br />
v Specify UseDfltUser = No in the <strong>CICS</strong> connection definition on the server<br />
to enforce security.<br />
v Use <strong>CICS</strong>_EpiSetSecurity in conjunction with <strong>CICS</strong>_VerifyPassword and<br />
<strong>CICS</strong>_ChangePassword to change the security settings for an existing<br />
terminal.<br />
v The userid and password are flowed to the server in the FMH of the attach<br />
request and will not appear in a client trace.<br />
v <strong>Transaction</strong>s will run under the userid specified in the corresponding FMH<br />
attach request.<br />
If you wish to use one of the APIs that does not support the new EPI<br />
functionality, then you can use CRTE through a middle tier system to get<br />
signon capable terminal-like functionality.<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Client Security<br />
TXSeries and <strong>CICS</strong> OS/2 servers<br />
These servers do not support the signon capability parameter in a terminal<br />
install (CTIN) request but will tolerate it if the required APAR is applied; see<br />
“<strong>CICS</strong> server PTF requirements” on page 26. A terminal install request will<br />
always result in a signon capable terminal being installed, regardless of the<br />
signon capability requested.<br />
<strong>CICS</strong>/400 servers<br />
These servers do not support the signon capability parameter in a terminal<br />
install (CTIN) request . A terminal install request will result in a signon<br />
incapable terminal being installed, regardless of the signon capability<br />
requested.<br />
Chapter 7. Client Security 123
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 8. Performance<br />
This chapter helps you to:<br />
v understand the factors that affect <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> performance<br />
v achieve the best performance from your system<br />
“Assessing system performance” Read this for an overview of the things to<br />
consider when assessing the performance<br />
of your system.<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
configuration” on page 126<br />
Read this for information on <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
parameters which affect performance.<br />
“Java considerations” on page 128 Read this for information on Java factors<br />
which affect performance.<br />
“Other system factors” on page 128 Read this for information on other system<br />
factors which affect performance.<br />
“Tracing” on page 129 Read this for information on using tracing<br />
to measure performance.<br />
“Performance monitoring tools” on<br />
page 130<br />
Read this for information on performance<br />
monitoring tools.<br />
Assessing system performance<br />
To assess the overall performance of your system you need to understand<br />
how all system components, including <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, affect<br />
performance. These system components might include:<br />
v browser<br />
v routers and firewalls<br />
v WebServer or Web Application Server<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v <strong>CICS</strong> server<br />
The information you collect to assess performance should include:<br />
v processor loading<br />
v data transfer rates<br />
v response times<br />
Response times are particularly useful indicators. They help you to<br />
understand which system components most affect performance.<br />
© Copyright IBM Corp. 1996, 2002 125
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
IBM has chosen default values for configuration and tuning to give a<br />
compromise between:<br />
v limiting the system resources used by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> after it<br />
has started<br />
v giving <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> the flexibility to handle increases in<br />
workload<br />
The following factors affect performance; you might need to alter the default<br />
configuration to suit your system environment:<br />
Connection Manager threads<br />
If the value specified for Initial number of Connection Manager<br />
threads is too high, your system will waste resources managing the<br />
threads that are not needed.<br />
The design of your applications determines the number of Connection<br />
Manager threads you need. Incoming connections to <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> could be from a servlet, with each copy of the servlet issuing<br />
its own ECI requests, but sharing a single Connection Manager<br />
thread. Alternatively, the application could create a pool of<br />
connections, and ECI requests could be issued onto any connection<br />
from the pool.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new Connection Manager thread,<br />
and TCP/IP connection, each time a Java client side application<br />
creates a new Java<strong>Gateway</strong> object. This means that system<br />
performance is better if your applications issue many ECI requests<br />
using the same Java<strong>Gateway</strong> object, and from within the same thread,<br />
than if they create a new Java<strong>Gateway</strong> object for each request.<br />
Flowing multiple requests through the same Java<strong>Gateway</strong> object also<br />
reduces the system resources required to create, and to destroy,<br />
Java<strong>Gateway</strong> objects.<br />
If the number of threads needed by applications exceeds the value<br />
specified for Maximum number of Connection Manager threads,<br />
each new request that requires a Connection Manager thread must<br />
wait until a thread becomes available. If the waiting time exceeds the<br />
value specified in the Connection timeout parameter, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> refuses the connection.<br />
Worker threads<br />
Worker threads handle outbound connections between <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> and your <strong>CICS</strong> server. The design of your<br />
applications, and the workload that you need to support, affects the<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
number of Worker threads you need: the longer your <strong>CICS</strong><br />
transactions remain in process, the more Worker threads you need to<br />
maintain a given transaction rate.<br />
v If the value specified for Initial number of Worker threads is too<br />
high, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to manage threads<br />
that it does not need<br />
v If the value is too low, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to<br />
search for available Worker threads.<br />
When using ECI to call the same <strong>CICS</strong> program, you can estimate the<br />
number of Worker threads you need to support a given workload by<br />
multiplying the following values:<br />
v number of transactions per second passing through <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong><br />
v average transaction response time through <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> in seconds<br />
Communication protocols<br />
Your choice of protocol depends on the nature of your client<br />
applications. However, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does considerably<br />
more processing to handle the HTTP and HTTPS protocols than it<br />
does to handle the TCP and SSL protocols. In addition, when using<br />
HTTP or HTTPS, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new TCP/IP<br />
connection with each client request. For better performance, use TCP<br />
or SSL in preference to HTTP or HTTPS where possible.<br />
Display TCP/IP hostnames<br />
Selecting this option might cause severe performance reduction on<br />
some systems. See “Display TCP/IP hostnames” on page 55.<br />
Timeout values<br />
It is unlikely that you can improve performance by changing the<br />
default timeout values. However, you may need to change them for<br />
particular applications. Refer to “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> settings” on page 53 for more information on these and all<br />
other configuration parameters.<br />
Connection logging<br />
The gateway configuration setting, Log client connections and<br />
disconnections, controls whether or not <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
writes a message each time that a client application program connects<br />
to, or disconnects from, the <strong>Gateway</strong> daemon. The default is for these<br />
messages not to be written. Selecting this setting can significantly<br />
reduce performance, especially in a system where client application<br />
programs connect and disconnect frequently. See “Log client<br />
connections and disconnections” on page 56.<br />
Chapter 8. Performance 127
Java considerations<br />
Java considerations<br />
Other system factors<br />
Maximum Java heap size<br />
If your system requires large numbers of Connection Manager threads<br />
you might need to increase the heap size to improve performance; see<br />
also “java.lang.OutOfMemory exception” on page 193. How you set<br />
the heap size depends on your JVM. Refer to the documentation for<br />
your JVM for more information.<br />
Just-In-Time (JIT) compiler<br />
Use the java -version command to find whether or not the JIT is<br />
enabled; it is enabled by default in JDK 1.3.1. Performance<br />
immediately after a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has started might be<br />
relatively slow because of JIT overheads. The JIT threshold is 2000 on<br />
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to<br />
run 2000 times before it is ’JITed‘. Refer to your JVM documentation<br />
for information on JIT techniques.<br />
Java<strong>Gateway</strong> objects<br />
Performance is better if you flow multiple requests using the same<br />
Java<strong>Gateway</strong> object than if you create a new Java<strong>Gateway</strong> object with<br />
each request. Each time you create, and destroy, a new Java<strong>Gateway</strong><br />
object you use additional system resources for:<br />
v creation and destruction of the object itself<br />
v creation and destruction of any associated sockets<br />
v garbage collection<br />
ECI COMMAREA size<br />
The size of the ECI COMMAREA has a large effect on performance. If<br />
you make the COMMAREA larger, you need more system resources<br />
to process it, and your response times are longer. Refer to <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for information on how to<br />
specify COMMAREA parameters in ECI requests.<br />
The setCommareaOutboundLength method, which is part of the<br />
EciRequest object, is particularly important to performance. The<br />
amount of data that an application sends in the COMMAREA flow to<br />
<strong>CICS</strong> may be small , and the amount of data expected from <strong>CICS</strong> in<br />
return may be unknown. To improve performance significantly, and<br />
reduce network loading:<br />
v Use the setCommareaOutboundLength method to ensure that you<br />
send only the required data in the outbound flow to <strong>CICS</strong>, and not<br />
the full Commarea_Length.<br />
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Tracing<br />
Other system factors<br />
<strong>CICS</strong> removes any null data from the COMMAREA in the return<br />
flow, and the Client daemon automatically pads out the nulls and<br />
returns the full COMMAREA to the application.<br />
v Use the getInboundDataLength method to show the amount of<br />
non-null data returned.<br />
v Do not use the deprecated setCommareaInboundLength method<br />
because it prevents automatic commarea null stripping.<br />
<strong>CICS</strong> server transactions<br />
The design of your <strong>CICS</strong> server transactions affects the performance of<br />
your system. The response time through <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
might increase if your transactions:<br />
v need to wait for shared resources, for example data sets or<br />
applications, to become available<br />
v make remote links to other <strong>CICS</strong> systems<br />
v are unnecessarily complex<br />
Refer to the Performance and Tuning documentation for your <strong>CICS</strong><br />
server system for information on how to get the best performance.<br />
Synchronous or asynchronous ECI calls<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has to do less processing to handle a<br />
synchronous ECI call than to handle an equivalent asynchronous call.<br />
Also, synchronous ECI calls create fewer network flows than<br />
asynchronous calls. This means that synchronous ECI calls give better<br />
performance than asynchronous calls.<br />
Extended logical units of work<br />
Take care when extending a logical unit of work across multiple<br />
program link calls that may span a long time period (for example,<br />
user thinking time). The logical unit of work holds various locks, and<br />
other <strong>CICS</strong> resources, on the server. This may cause delays to other<br />
users who are waiting for the same locks and resources.<br />
Also, each logical unit of work occupies one <strong>CICS</strong> non-facility task for<br />
the duration of its execution. This means that you must define enough<br />
free tasks in the <strong>CICS</strong> server to service the maximum expected<br />
number of concurrent calls.<br />
Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more<br />
information.<br />
IBM does not recommend the use of the full <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace<br />
to monitor performance in a production environment. This is because the<br />
trace itself significantly decreases performance.<br />
Chapter 8. Performance 129
Tracing<br />
Where possible, try to measure response times, without using tracing, through<br />
the different parts of your system, to find where delays are happening. For<br />
example, you could measure response times at the client application, and also<br />
through <strong>CICS</strong> and WebSphere.<br />
Performance monitoring tools<br />
The following performance monitoring tools are available on the AIX<br />
operating system. Similar tools are available on other UNIX operating system:<br />
vmstat<br />
Gives statistics about virtual memory, disks, traps, and processor<br />
activity. Use it to determine system loading.<br />
iostat Gives processor statistics and I/O statistics for tty, disks, and<br />
CD-ROM drives.<br />
sar (system activity report)<br />
Collects, reports, or saves system activity information.<br />
netstat<br />
Shows network status.<br />
IBM Performance Toolbox<br />
Provides some useful performance tools that are integrated into a<br />
graphical user interface. <strong>Version</strong>s available for the Solaris and HP-UX<br />
operating systems.<br />
Refer also to the performance and tuning documentation for WebSphere, SNA,<br />
TCP/IP, <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, and TXSeries.<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 9. Operating the <strong>Gateway</strong><br />
This chapter describes how to operate the <strong>Gateway</strong> daemon of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It consists of the following:<br />
“Before you start” Read this for information on the<br />
privileges that a user needs to operate<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Starting the <strong>Gateway</strong>” on page 132 Read this for information on starting<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Stopping the <strong>Gateway</strong>” on page 134 Read this for information on stopping<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Administering your system” on page 135 Read this for information on setting the<br />
<strong>Gateway</strong> and JNI traces, and querying<br />
trace settings.<br />
Before you start<br />
To operate <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you must log in either as root, or as a<br />
user with the following privileges:<br />
v network access through TCP/IP<br />
v read access to file /var/cicscli/shared<br />
v read/write access to directory /var/cicscli<br />
v read access to file CTG.INI<br />
v read access to the directory in which you installed <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
See also:<br />
v “Security considerations for trace and log files” on page 142, for information<br />
on user access to trace files<br />
v “TCP62 port” on page 76, for information on using TCP62 if you do not log<br />
in as root<br />
© Copyright IBM Corp. 1996, 2002 131
|<br />
Starting the <strong>Gateway</strong><br />
You start the <strong>Gateway</strong> at the operating system command prompt of the<br />
computer on which you have installed it.<br />
First, set your working directory to the /bin subdirectory.<br />
You can start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> in two ways:<br />
v “Starting the <strong>Gateway</strong> with preset options”<br />
v “Starting the <strong>Gateway</strong> with user-specified options”.<br />
Starting the <strong>Gateway</strong> with preset options<br />
To start the <strong>Gateway</strong> with predefined options: Type ctgstart at the command<br />
prompt and press Enter.<br />
When you start the <strong>Gateway</strong> like this the values you configured using the<br />
configuration tool are used. (see “Using the configuration tool” on<br />
page 49).The gateway will not start without a valid INI file.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used for TCP/IP:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345<br />
Starting the <strong>Gateway</strong> with user-specified options<br />
The user-definable options on the start command are:<br />
-port=port_number<br />
-initconnect=number<br />
-maxconnect=number<br />
-initworker=number<br />
-maxworker=number<br />
-trace<br />
-noinput<br />
-tfile=pathname<br />
-x<br />
-tfilesize=number<br />
-truncationsize=number<br />
-dnsnames<br />
-dumpoffset=number<br />
-stack<br />
-jargument to pass to the JVM<br />
where:<br />
-port<br />
Specifies the TCP/IP port number which the gateway will listen on.<br />
-initconnect<br />
Specifies an initial number of ConnectionManager threads.<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
-maxconnect<br />
Specifies a maximum number of ConnectionManager threads. If you set<br />
this value to -1, no limits are applied to the number of<br />
ConnectionManager threads.<br />
-initworker<br />
Specifies an initial number of Worker threads.<br />
-maxworker<br />
Specifies a maximum number of Worker threads. If you set this value to<br />
-1, no limits are applied to the number of ConnectionManager threads.<br />
-trace<br />
Enables standard tracing (see “Tracing” on page 185). By default, the trace<br />
output shows only the first 128 bytes of any data blocks (for example the<br />
COMMAREA, or network flows). Other useful information, including the<br />
value of the CLASSPATH variable, and the codepage, is shown at the top of<br />
the trace output.<br />
If you used the configuration tool to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
the default destination for the trace output is file CTG.TRC in the<br />
/bin subdirectory. Otherwise, trace output is written to<br />
stderr.<br />
-noinput<br />
Disables the reading of input from the console.<br />
-tfile=pathname<br />
If tracing is enabled, trace output is written to the file specified in<br />
pathname. This overrides the default destination for trace output (see the<br />
-trace option).<br />
-x Enables full debug tracing (see “Tracing” on page 185). By default, the<br />
trace output shows the whole of any data blocks (for example the<br />
COMMAREA, or network flows). It also displays more information about<br />
the internal <strong>Gateway</strong> processing than the standard trace. See the -trace<br />
and -tfile options for information on the destination for trace output.<br />
Debug tracing significantly decreases performance.<br />
-tfilesize=number<br />
Specifies the maximum size, in kilobytes, of the trace output file.<br />
-truncationsize=number<br />
The value number specifies the maximum size of any data blocks that are<br />
shown in the trace. You can use this option with either the -trace or -x<br />
options to override the default size. Any positive integer is valid. If you<br />
specify a value of 0, then no data blocks are shown in the trace.<br />
Chapter 9. Operating the <strong>Gateway</strong> 133
|<br />
|<br />
|<br />
-dnsnames<br />
Enables the display of symbolic TCP/IP hostnames in messages. See<br />
“Display TCP/IP hostnames” on page 55 for more information.<br />
-dumpoffset=number<br />
The value number specifies the offset from which displays of any data<br />
blocks start. If the offset is greater than the total length of data to be<br />
displayed, an offset of 0 is used.<br />
-stack<br />
Enables Java exception stack tracing (see “Tracing” on page 185). Java<br />
exceptions are traced, including those which are expected during normal<br />
operation of the <strong>Gateway</strong>. No other trace output is created. See the -trace<br />
and -tfile options for information on the destination for trace output.<br />
-j Pass an argument to the JVM. For example, -j-D= sets a<br />
JVM system property. See the JVM command line interpreter help for<br />
guidance in using this switch.<br />
To override the startup defaults type ctgstart at the command prompt,<br />
followed by the start-up options you require, and press Enter. Options<br />
specified on the command line override those specified using the configuration<br />
tool.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used for TCP/IP:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345<br />
To get help on the startup options, enter:<br />
ctgstart -?<br />
Stopping the <strong>Gateway</strong><br />
To stop the <strong>Gateway</strong>:<br />
v If you did not start the <strong>Gateway</strong> with the -noinput option, you can stop it<br />
by typing the correct character and pressing the Enter key in the <strong>Gateway</strong><br />
console session. The allowable characters may be localized for your country;<br />
the default characters allowed are the Q or - characters.<br />
You can determine which characters will stop the <strong>Gateway</strong> by simply<br />
pressing the Enter key in the <strong>Gateway</strong> console session. A message like the<br />
following is displayed:<br />
CCL6508I: Type Q or - to stop the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v If you used the -noinput option, you must stop the <strong>Gateway</strong> process using<br />
some other method, for example:<br />
– Use the kill command<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on<br />
page 64), you can perform the following administrative functions without<br />
having to restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
v Set the <strong>Gateway</strong> trace<br />
v Set JNI trace<br />
v Query the current trace settings<br />
You execute the Java archive ctgadmin.jar from a command prompt to set<br />
trace or to query trace settings. You can administer the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> remotely from a workstation that has this JAR file and the supported<br />
level of Java; you do not need to install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the<br />
workstation. See “TCPAdmin protocol settings” on page 64 for details of how<br />
to define which hosts have permission to administer your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
The following sections describe the commands. Parameters are not case<br />
sensitive; those in brackets are optional.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier than version <strong>5.0</strong>.<br />
Earlier versions cause the administration program to lock. If this<br />
happens, terminate the process, for example by pressing Ctrl+C.<br />
Setting the <strong>Gateway</strong> trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]<br />
[-tfilesize=number] [-tlevel=number]<br />
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]<br />
See “Parameters” on page 136 for an explanation of parameters.<br />
Setting the JNI trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address<br />
-a=setjnitrace -tfile=path [-tlevel=number]<br />
See “Parameters” on page 136 for an explanation of parameters.<br />
Querying trace settings<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address -a=qtrace<br />
Administering your system<br />
See “Parameters” on page 136 for an explanation of parameters.<br />
Chapter 9. Operating the <strong>Gateway</strong> 135
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
Parameters<br />
ctg Mandatory. Specifies the <strong>Gateway</strong> which is to be<br />
administered. You can specify either a hostname, for example<br />
tcp://myserver:2810, or an IP address, for example<br />
tcp://127.0.0.1:2810. In these examples, 2810 is the port you<br />
specified for TCPAdmin; see “TCPAdmin protocol settings” on<br />
page 64.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier<br />
than version <strong>5.0</strong>. Earlier versions cause the<br />
administration program to lock. If this happens,<br />
terminate the process, for example by pressing<br />
Ctrl+C.<br />
a Mandatory. Defines the action to take. Permitted values are:<br />
v setgwtrace to control <strong>Gateway</strong> tracing<br />
v setjnitrace to control JNI tracing<br />
v qtrace to determine what trace settings are active<br />
tfile Specifies the output file for <strong>Gateway</strong> or JNI tracing, for<br />
example ./tracefile.trc. Do not specify the same file for<br />
<strong>Gateway</strong> and JNI trace output.<br />
<strong>Gateway</strong> tracing<br />
If you do not specify a value for this tag, trace output is<br />
sent to the console.<br />
JNI tracing<br />
You must specify a value for this tag. If you do not, an<br />
error is displayed.<br />
tlevel Specifies the trace level. Permitted values are:<br />
<strong>Gateway</strong> tracing:<br />
0 Off. No trace information is output.<br />
1 Exception tracing. Only exceptions are traced.<br />
Equivalent to ctgstart -stack; see “Starting the<br />
<strong>Gateway</strong> with user-specified options” on page 132.<br />
2 Trace exceptions, and entry and exit of methods.<br />
3 Trace exceptions, some internals, and entry and<br />
exit of methods (equivalent to ctgstart -trace).<br />
4 Full debug tracing (all trace points, equivalent to<br />
ctgstart -x).<br />
JNI tracing:<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
0 Off. No trace information is output.<br />
1 On.<br />
tfilesize Specifies the maximum size, in kilobytes, of the trace output<br />
file, for example 50000.<br />
dumpoffset Specifies the offset from which displays of any data blocks<br />
start, for example 512. If the offset is greater than the total<br />
length of data to be displayed, an offset of 0 is used. You<br />
cannot use this together with the fulldatadump parameter.<br />
truncationsize Specifies the byte at which to stop the hex dump, for example<br />
2000. It defines the end point, not the number of bytes to<br />
display. So if on a dump of size 40 you set the dumpoffset to<br />
11, and the truncationsize to 25, you will see 15 bytes (from<br />
11 to 25).<br />
You cannot use this together with the fulldatadump parameter.<br />
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in<br />
truncationsize.<br />
Chapter 9. Operating the <strong>Gateway</strong> 137
Administering your system<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 10. Operating the Client daemon<br />
This chapter describes how to operate the Client daemon. It consists of the<br />
following:<br />
“The cicscli command” Read this for an introduction to the Client<br />
daemon command.<br />
“The cicscli command” Read this for information on using the<br />
cicscli command to control the Client<br />
daemon.<br />
“cicscli command reference” on page 145 Read this for a detailed reference to the<br />
cicscli command.<br />
The cicscli command<br />
The cicscli command is used to start and stop the Client daemon, check the<br />
availability of servers, and set other options..<br />
The Client daemon starts automatically when you invoke any of the client<br />
functions, such as EPI, ECI, or 3270 terminal emulation. You do not need to<br />
use the cicscli command to start the Client daemon explicitly.<br />
You must explicitly terminate any server connections initiated by ECI calls. To<br />
do this, use the cicscli -x=servername or cicscli -i=servername command. See<br />
“cicscli command reference” on page 145.<br />
The cicscli command<br />
The following table shows the functions that you can perform with the cicscli<br />
command, and the parameters associated with each function:<br />
Function Parameters<br />
Start the Client daemon, and start communication with <strong>CICS</strong><br />
servers<br />
-s<br />
Stop the Client daemon -i and -x<br />
Restart the Client daemon -j and -y<br />
Start client tracing -d<br />
Stop client tracing -o<br />
Specify the client components to be traced -m<br />
© Copyright IBM Corp. 1996, 2002 139
The cicscli command<br />
Function Parameters<br />
Set up security -c, -u, and -p<br />
List connected <strong>CICS</strong> servers -l<br />
Enable the display of console messages -e<br />
Disable the display of console messages -n<br />
Wait for confirmation before completion -w<br />
Display information about the version and build level of the Client<br />
daemon<br />
-v<br />
The following sections provide examples of using the cicscli command. Full<br />
details of the command syntax are in “cicscli command reference” on<br />
page 145.<br />
Note: With the cicscli command, you can enter parameters preceded either by<br />
the dash (-) or by the forward slash (/) character.<br />
Starting the Client daemon<br />
To start the Client daemon, enter:<br />
cicscli -s<br />
To start the Client daemon and start communication with a <strong>CICS</strong> server, enter:<br />
cicscli -s=servername<br />
where servername is the name of a <strong>CICS</strong> server.<br />
Starting connections with additional servers<br />
To start a connection to a <strong>CICS</strong> server when the Client daemon is already<br />
running, enter:<br />
cicscli -s=servername<br />
where servername is the name of a <strong>CICS</strong> server.<br />
Note: If you change and reinstall the the <strong>CICS</strong> connection definition, you<br />
must stop and restart the connection.<br />
Stopping the Client daemon in a controlled manner<br />
To stop the Client daemon for all connected servers, after all outstanding units<br />
of work have completed, enter:<br />
cicscli -x<br />
To terminate the session with a particular server, enter:<br />
cicscli -x=servername<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
where servername is the name of a <strong>CICS</strong> server. This stops only the session<br />
with the named server; it does not stop the Client daemon or connections to<br />
other servers.<br />
Stopping the Client daemon immediately<br />
To stop the Client daemon for all connected servers, without completing<br />
outstanding units of work, enter:<br />
cicscli -i<br />
To terminate the session with a particular server, enter:<br />
cicscli -i=servername<br />
where servername is the name of a <strong>CICS</strong> server. This stops only the session<br />
with the named server; it does not stop the Client daemon or connections to<br />
other servers.<br />
Note:<br />
If the Client daemon does not stop completely, this may be because the<br />
Client daemon process, cclclnt, remains active. To stop this process,<br />
enter the command<br />
kill -2 pid<br />
where pid is the numeric process id of cclclnt.<br />
The cicscli command<br />
Do not use the kill -9 command as this stops a process without<br />
allowing its resources to be released; those resources remain active until<br />
you restart the system.<br />
Restarting the Client daemon in a controlled manner<br />
To stop the Client daemon for all connected servers, after all outstanding units<br />
of work have completed, and then start it again, enter:<br />
cicscli -y<br />
cicscli -y is equivalent to cicscli -x followed by cicscli -s. This does not<br />
re-establish server connections.<br />
Restarting the Client daemon immediately<br />
To stop the Client daemon for all connected servers, without completing<br />
outstanding units of work, and then start it again, enter:<br />
cicscli -j<br />
cicscli -j is equivalent to cicscli -i followed by cicscli -s. This does not<br />
re-establish server connections.<br />
Chapter 10. Operating the Client daemon 141
The cicscli command<br />
Starting client tracing<br />
To start tracing the Client daemon, enter:<br />
cicscli -d<br />
To trace the Client daemon from the startup sequence, enter the -s and -d<br />
parameters together.<br />
The Client daemon writes trace entries to the <strong>CICS</strong>CLI.BIN file in the<br />
/var/cicscli subdirectory. New trace entries overwrite any existing entries in<br />
the trace file. If required, make a backup copy of the old trace file before you<br />
start tracing.<br />
Use the cicsftrc utility to format the trace file.<br />
Specifying the trace components<br />
To specify which client components to trace, enter, for example:<br />
cicscli -m=TRN,API.2<br />
For information on which components you can trace, see “cicscli command<br />
reference” on page 145.<br />
Stopping client tracing<br />
To stop tracing the Client daemon, enter:<br />
cicscli -o<br />
Security considerations for trace and log files<br />
The Client daemon restricts access to the client trace and log files. By default,<br />
these are normal files, not links, called <strong>CICS</strong>CLI.BIN, and <strong>CICS</strong>CLI.LOG, inthe<br />
/var/cicscli subdirectory. You can specify names for these files using the<br />
configuration tool.<br />
The trace file<br />
The file permissions on <strong>CICS</strong>CLI.BIN allow only the owner, and group to write<br />
to the file, and only the owner to read it. However, if a user has write access<br />
to the /var/cicscli subdirectory, they can delete <strong>CICS</strong>CLI.BIN regardless of<br />
the file permissions.<br />
If you do not want unauthorized users to have access to the <strong>CICS</strong>CLI.BIN file,<br />
do not give them write access to the /var/cicscli subdirectory. For example,<br />
a command such as:<br />
chmod 755 /var/cicscli<br />
allows users to see files in /var/cicscli subdirectory but not to create, delete,<br />
or move them.<br />
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The Client daemon prevents you from starting tracing if an unauthorized user<br />
has deleted and recreated <strong>CICS</strong>CLI.BIN.<br />
The log file<br />
The file permissions on <strong>CICS</strong>CLI.LOG allow only the owner (root) and group to<br />
read and write the file.<br />
To improve security further:<br />
v Set the permissions on the /var/cicscli subdirectory to restrict general<br />
access<br />
chmod 0711 /var/cicscli<br />
This means users cannot even see which files are in this directory.<br />
v Allow ECI and EPI programs, and terminals, to start the Client daemon, but<br />
allow only the root user to perform all other client administration:<br />
chmod 0700 /var/cicscli<br />
Setting up security<br />
You can use the following commands after first starting the Client daemon.<br />
To set a userid to use when accessing server servername, enter:<br />
cicscli -c=servername -u=userid<br />
where userid is the userid and servername is the servername. (You are<br />
prompted for the password.)<br />
To set a password to use when accessing server servername, enter:<br />
cicscli -c=servername -p=password<br />
where password is the password and servername is the name of the server.<br />
You can enter the -u and -p parameters together.<br />
The cicscli command<br />
You can also specify the security parameters when you start the Client<br />
daemon:<br />
cicscli -s=servername -u=userid -p=password<br />
<strong>Version</strong> information<br />
To display information about the version and build level of your Client<br />
daemon, enter the command<br />
cicscli -v<br />
The Client daemon displays information similar to Figure 20 on page 144:<br />
Chapter 10. Operating the Client daemon 143
The cicscli command<br />
CCL8001I <strong>CICS</strong>CLI - <strong>CICS</strong> Client Control Program<br />
CCL0002I (C) Copyright IBM Corporation 1994, 2002. All rights reserved.<br />
CCL8029I <strong>CICS</strong> Client for Windows <strong>Version</strong> <strong>5.0</strong> Service Level 00<br />
CCL8074I Build Level ’c000-20020510a’<br />
CCL8025I The <strong>CICS</strong> Client has not been started<br />
CCL8023I <strong>CICS</strong>CLI performed no action<br />
Figure 20. <strong>Version</strong> and build level information for the Client daemon<br />
Listing the connected servers<br />
To list all the servers being used by the Client daemon, and their status, enter:<br />
cicscli -l<br />
The cicscli control program displays information similar to Figure 21:<br />
CCL8001I <strong>CICS</strong>CLI - <strong>CICS</strong> Client Control Program<br />
CCL0002I (C) Copyright IBM Corporation 1994,2002. All rights reserved.<br />
CCL8041I The <strong>CICS</strong> client is using the following servers:<br />
CCL8042I Server ’<strong>CICS</strong>AIX’ (using ’TCP/IP’ to ’<strong>CICS</strong>AIX’) is available<br />
Figure 21. Example list of <strong>CICS</strong> servers<br />
Disabling the display of messages<br />
To disable the display of all messages output with the command, enter, for<br />
example:<br />
cicscli -s -q<br />
Enabling and disabling the display of console messages<br />
By default, the Client daemon sends error messages to the system console,<br />
/dev/console, and also to the log file <strong>CICS</strong>CLI.LOG in the /var/cicscli<br />
subdirectory.<br />
On AIX, you can redirect these messages to another target device or file by<br />
using the swcons command.<br />
To disable the display of console messages, enter:<br />
cicscli -n<br />
To enable the display of console messages again, enter:<br />
cicscli -e<br />
You can specify the -n parameter together with the -s parameter.<br />
The display of console messages is enabled by default.<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Displaying the command parameters<br />
To display the parameters of the cicscli command, enter:<br />
cicscli -?<br />
The cicscli command and applications<br />
You can call cicscli from within applications, if this is supported by the<br />
programming language. You can therefore enter cicscli at the command line,<br />
then run an application to call cicscli with additional parameters.<br />
cicscli command reference<br />
All client control commands have options identified by a leading dash (-).<br />
Instead of dash signs you can use a forward slash (/) for all parameters.<br />
However for the ? parameter you must use a dash sign. All options of the<br />
form -x=variable may contain spaces in the variable part, if it is enclosed in<br />
double quotes. Double quotes within variables must be entered as \″ , that is<br />
with a backslash preceding the double quote.<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page viii.<br />
cicscli Command Syntax<br />
►► cicscli -s<br />
-s=servername -d -m -n<br />
-d=nnn -m=components<br />
-o<br />
-d<br />
-d=nnn<br />
-m<br />
-m=components<br />
-x<br />
-x=servername<br />
-i<br />
-i=servername<br />
-l<br />
-j<br />
-y<br />
-c=servername<br />
-u=userid -p=password<br />
-u -p<br />
-e<br />
-n<br />
-v<br />
-?<br />
The cicscli command<br />
The options are:<br />
-c=servername Identifies the name of the server to which security information<br />
in the form of a userid and password is to be associated.<br />
-q<br />
-w<br />
Chapter 10. Operating the Client daemon 145<br />
►◄
The cicscli command<br />
Some <strong>CICS</strong> servers require the user to provide security<br />
information to the server before interacting with the server.<br />
The Client daemon prompts the user at the workstation for a<br />
userid and password, unless these have already been<br />
provided via cicscli (see the descriptions of the -u and -p<br />
options).<br />
-d=[nnn] Starts debug tracing for the Client daemon. If tracing is<br />
required while the Client daemon is starting up, this option<br />
may be specified along with the -s option.<br />
nnn is the maximum size of data areas to be traced in bytes.<br />
The range is 1 through 32 767 bytes, and the default value is<br />
512 bytes.<br />
The Client daemon writes trace entries to the <strong>CICS</strong>CLI.BIN file<br />
in the /var/cicscli subdirectory. New trace entries overwrite<br />
any existing entries in the trace file. If required, make a<br />
backup copy of the old trace file before you start tracing.<br />
Use the cicsftrc utility to format the trace file. The resulting<br />
file, <strong>CICS</strong>CLI.TRC, is an ASCII file that you can read with a text<br />
editor. For more information see “Formatting the binary trace<br />
file” on page 197.<br />
-e Enables the display of Client daemon error and security<br />
messages on the console.<br />
-i Stops the Client daemon immediately. The options<br />
-i=servername and -i operate as for -x=servername and -x<br />
respectively but the Client daemon does not wait for<br />
outstanding units of work to complete. Stopping the Client<br />
daemon in this way may result in a loss of data at connected<br />
servers.<br />
-j Stops the Client daemon immediately and then restarts it.<br />
A restart involves shutting down the Client daemon, waiting<br />
for it to shut down, and then starting it again. cicscli -j is<br />
equivalent to cicscli -i followed by cicscli -s. Server<br />
connections are not re-established when the Client daemon is<br />
restarted.<br />
Using -y is the preferred way of restarting the Client daemon.<br />
-l Causes a list of all connected servers to be displayed. For each<br />
server, the netname of the server as it is known to the Client<br />
daemon is also displayed, as well as the state of the<br />
connection to the server and the connection protocol.<br />
146 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The cicscli command<br />
-m=[components]<br />
Specifies a comma-separated list of identifiers for components<br />
that will be traced when tracing starts. You can specify any of<br />
the following components:<br />
ALL All components<br />
API.1 The client API layer (level 1). This gives basic<br />
API tracing.<br />
API.2 The client API layer (level 1 and 2). This gives<br />
level 1 plus additional parameter tracing.<br />
API Synonymous with API.1<br />
CCL The Client daemon<br />
CPP The C++ class libraries<br />
CLI The cicscli command interface<br />
DEF The default components, that is the API, CCL,<br />
and DRV.1 components<br />
DRV Synonymous with DRV.1<br />
DRV.1 Protocol driver tracing level 1. This traces data<br />
sent and received and provides supplementary<br />
information about failures.<br />
DRV.2 Protocol driver tracing level 2. This traces<br />
internal flows through the protocol drivers<br />
and interactions with other software<br />
components. It is currently supported only by<br />
the CCLTCP62 protocol driver.<br />
EMU cicsterm and cicsprnt emulators<br />
TRN Interprocess communication<br />
For guidance on when to use the tracing options, see<br />
“Choosing which components to trace” on page 196.<br />
The -m parameter does not start tracing in the Client daemon;<br />
it simply specifies the components to trace. You cannot use -m<br />
while the Client daemon is not running, so you must specify<br />
the -s parameter before you use -m.<br />
If you specify -m with no parameters, a list of the possible<br />
component identifiers is displayed, with an ’x’ beside each<br />
component that it is currently enabled for tracing.<br />
Chapter 10. Operating the Client daemon 147
The cicscli command<br />
You can also specify settings for trace components using the<br />
configuration tool (see “Trace settings” on page 78 in the<br />
Configuration chapter for details). Any component tracing<br />
specified using cicscli overrides that specified using the<br />
configuration tool. If component tracing is not specified either<br />
by the cicscli command or by using the configuration tool, a<br />
default set of components is traced, namely: DRV.1, CCL, and<br />
API. Any component tracing specified using the configuration<br />
tool overrides the default set of components.<br />
For the API and DRV components, you can specify the level<br />
of information to trace. For example components API or API.1<br />
specify that basic API-related information is traced before and<br />
after ECI and EPI calls. Component API.2 specifies that<br />
additional API trace entries are produced in addition to those<br />
of level 1.<br />
Note that the cicscli -d=nnn command is used to set the<br />
maximum size of the data areas to be traced. The trace data<br />
may be truncated if you set nnn lower than the size of data<br />
expected.<br />
-n Disables the display of Client daemon error and security<br />
messages on the console<br />
Any messages that would have been logged are still logged.<br />
-o Stops tracing if it is already active.<br />
-p=password Sets the current password to be used when accessing the<br />
server specified by the -c parameter. This password is used if<br />
the server requires a password (and userid) before running<br />
transactions on the client’s behalf.<br />
For ECI applications, any userid and password specified in<br />
the ECI parameter block overrides values set via the cicscli<br />
command.<br />
Specifying -p or -p= (that is, no password is specified) resets<br />
the associated password to a null value.<br />
-q Disables the display of all messages output with the cicscli<br />
command.<br />
-s Starts the Client daemon. No attempt is made to initiate<br />
communication with a server unless -s=servername is specified.<br />
In this case, the Client daemon also connects to the server<br />
using information specified in the configuration file. The<br />
servername must exist in the configuration file.<br />
148 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The cicscli command<br />
-u=userid Sets the current userid to be used when accessing the server<br />
specified by the -c parameter. This userid is used if the server<br />
requires a userid (and password) before running transactions<br />
for the Client daemon.<br />
If you do not provide the -p parameter, you are prompted for<br />
the password.<br />
For ECI applications, any userid and password specified in<br />
the ECI parameter block overrides values set via the cicscli<br />
command.<br />
Specifying -u or -u= (that is, no userid is specified) resets the<br />
associated userid to a null value.<br />
-v Displays information about the version and build level of the<br />
Client daemon.<br />
-x Stops the Client daemon in a controlled manner. If<br />
-x=servername is specified, then when all outstanding units of<br />
work on the specified server have completed, the connection<br />
to the server is terminated. If other server connections are<br />
active, these remain unchanged.<br />
If -x is specified without a servername, the Client daemon<br />
waits for all outstanding units of work to complete, terminates<br />
all connections to servers, and ends the control process. Using<br />
-x or -x=servername is the preferred way of stopping the Client<br />
daemon.<br />
-y Restarts the Client daemon in a controlled manner.<br />
A restart involves shutting down the Client daemon, waiting<br />
for it to shut down, and then starting it up again. cicscli -y is<br />
equivalent to cicscli -x followed by cicscli -s. Server<br />
connections are not re-established when the Client daemon is<br />
restarted.<br />
Using -y is the preferred way of restarting the Client daemon.<br />
-? Causes the command syntax to be displayed.<br />
Note: The -f parameter is no longer supported. See “Using the configuration<br />
tool” on page 49 for information on how to specify a configuration file.<br />
Chapter 10. Operating the Client daemon 149
The cicscli command<br />
150 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 11. Terminal Emulation<br />
This chapter describes how to use the cicsterm and cicsprnt programs. It<br />
consists of the following:<br />
“Summary of Terminal Emulation<br />
commands”<br />
“cicsterm command reference” on<br />
page 154<br />
Read this for a summary of the<br />
commands explained in this chapter.<br />
Read this for a detailed reference to the<br />
cicsterm command.<br />
“The cicsprnt command” on page 157 Read this for information on using the<br />
cicsprnt command to control 3270 printer<br />
terminal emulation.<br />
“cicsprnt command reference” on<br />
page 158<br />
Summary of Terminal Emulation commands<br />
Read this for a detailed reference to the<br />
cicsprnt command.<br />
cicsterm<br />
This command starts a terminal emulation session with particular<br />
options.<br />
cicsprnt<br />
This command starts a printer terminal session with particular<br />
options.<br />
The cicsterm command<br />
The cicsterm command controls 3270 terminal emulation. You can start<br />
emulator sessions, specify terminal emulator characteristics, and the names of<br />
the keyboard mapping and color mapping files.<br />
You can have multiple terminal emulation sessions running simultaneously.<br />
The Client daemon does not support 3270 field outlining for the cicsterm<br />
command on UNIX operating systems.<br />
Note: Some uses of servers and protocols require a model terminal definition<br />
for the emulator that explicitly specifies that the Client daemon wants<br />
to display DBCS.<br />
© Copyright IBM Corp. 1996, 2002 151
The cicsterm command<br />
Using cicsterm<br />
The following table shows the functions that you can perform with the<br />
cicsterm command, and the parameters associated with each function:<br />
Function Parameters<br />
Start a 3270 terminal emulator -s and -r<br />
Specify the initial transaction -t<br />
Specify the name of the keyboard mapping file -k<br />
Specify the name of the color mapping file -c<br />
Define the 3270 terminal emulator characteristics -n and -m<br />
Specify a terminal emulator that is signon incapable -a<br />
Determine the print file processing -p<br />
Specify a file to which print files are appended -f<br />
cicsterm command once with all the parameters you require.<br />
The following is an example of a cicsterm command:<br />
cicsterm -s=<strong>CICS</strong>OS2 -t=CESN -k=mykeys.ini -c=mycols.ini<br />
-n=cicsv123 -f=clprint.txt -q<br />
In this example:<br />
-s=<strong>CICS</strong>OS2 Specifies that a 3270 terminal emulator is started for the server<br />
<strong>CICS</strong>OS2.<br />
-t=CESN Specifies that the initial transaction is CESN.<br />
-k=mykeys.ini Specifies that the keyboard mapping file is named as<br />
mykeys.ini.<br />
-c=mycols.ini Specifies that the color mapping file is named as mycols.ini.<br />
-n=cicsv123 Specifies that the 3270 terminal emulator characteristics are<br />
defined by the terminal definition cicsv123.<br />
-f=clprint.txt Specifies that the print file will be appended to the file<br />
clprint.txt.<br />
-q Specifies that the display of messages output by the command<br />
is disabled.<br />
All parameters of cicsterm are optional. That is, you can enter the cicsterm<br />
command without any parameters, and defaults are taken from the<br />
configuration file. Full details of the parameters are given in “cicsterm<br />
command reference” on page 154.<br />
152 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Stopping a terminal emulator<br />
To stop a terminal emulator, enter, from an empty terminal screen, the string<br />
specified by the Terminal exit configuration setting, and press Enter. The<br />
default string is EXIT<br />
cicsterm and user exits<br />
You can use cicsterm to drive EPI user exits.<br />
The cicsterm command<br />
The EPI user exits, and how cicsterm can use them, are described in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
cicsterm and RETURN TRANSID IMMEDIATE<br />
When an application running from a cicsterm session issues either of the<br />
commands:<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)<br />
the transaction named in the TRANSID option starts straight away without<br />
any user input. When the INPUTMESSAGE option is specified, the contents of<br />
the data-area are passed to the new transaction, and the screen is not updated<br />
with the data-area contents.<br />
Issuing these EXEC <strong>CICS</strong> commands from cicsterm does not result in the<br />
StartTranExit or ReplyExit user exits being driven. See <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide for more information.<br />
Using X-Windows Clients<br />
There are some known problems with certain X-Windows clients (such as<br />
Exceed). These include corruption of the text on the title bar of the window<br />
that you are trying to display, This might happen, for example, with the<br />
Configuration Tool. In some cases the title bar might be missing. The<br />
problems relate to the X-Windows client used and not to the Client daemon.<br />
There are two ways to solve this problem:<br />
1. Start a window manager before launching the Configuration Tool.<br />
The window manager HWM, is shipped with Exceed.<br />
2. Alter your settings in Exceed’s Xconfig as follows:<br />
a. Launch Xconfig<br />
b. Select ’screen definition’<br />
c. Alter the ’Window Manger’ to ’native’<br />
d. Make sure ’Use Native WM for Embedded Clients’ is checked<br />
If you use this second way you cannot run any other window manager.<br />
Chapter 11. Terminal Emulation 153
The cicsterm command<br />
Using cicsterm with an XTERM window<br />
When cicsterm runs in an XTERM window it may not recognise all function<br />
keys. This is because of the terminal type.<br />
There are two ways to solve this problem::<br />
1. Run cicsterm in a non XTERM window<br />
2. Set the TERM environment variable for the session to a different terminal<br />
type, such as vt100 (by default, this environment variable is often set to<br />
xtterm).<br />
cicsterm command reference<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page viii.<br />
You can enter parameters preceded by the dash (-) or by the forward slash (/)<br />
character. However for the ? parameter you must use a dash.<br />
cicsterm Command Syntax<br />
►► cicsterm<br />
►<br />
►<br />
-s = servername -t=initialtransid<br />
-s -t<br />
-r=servername<br />
-r<br />
-k=keyfile -c=colorfile -m=modelname -a<br />
-c -m<br />
-n=netname -p=printcmd -q -?<br />
-f=printfile -w<br />
The options are:<br />
-a Specifies that the terminal emulator is not signon capable. By default,<br />
cicsterm creates terminal emulators that are signon capable.<br />
For more information on signon capability, see <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide.<br />
-c=colorfile<br />
Identifies the name of a color mapping file to be used with the<br />
emulator; see “Customizing the screen colors for cicsterm” on page 90<br />
for more details. If you omit this parameter, the environment variable<br />
<strong>CICS</strong>COL is assumed to identify the color mapping file. If <strong>CICS</strong>COL is<br />
not defined, a filename of <strong>CICS</strong>COL.INI in the /bin<br />
subdirectory is assumed.<br />
154 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
►<br />
►<br />
►◄
The cicsterm command<br />
If the parameter is specified as -c=, that is, the color mapping filename<br />
is omitted, the emulator runs without any color definitions.<br />
-f=printfile<br />
Specifies the name of a file to which the output of print requests is<br />
appended. If the name of the file contains embedded blanks, it must<br />
be surrounded by double quotes (“). Any double quotes within the<br />
name of the file must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is provided, the Print command<br />
or Print file configuration settings define the command, file, or<br />
default action to take with print requests.<br />
-k=keyfile<br />
Identifies the name of a keyboard mapping file to be used with the<br />
emulator; see “Keyboard mapping for cicsterm” on page 88 for more<br />
details. If this parameter is omitted, the environment variable<br />
<strong>CICS</strong>KEY is assumed to identify the key mapping file. If <strong>CICS</strong>KEY is<br />
not defined, a filename of <strong>CICS</strong>KEY.INI in the /bin<br />
subdirectory is assumed.<br />
-m=modelname<br />
Specifies the name of a Model terminal definition, as known at the<br />
server to which the emulator is to connect, to be used to define the<br />
terminal characteristics. If neither this parameter nor -n=netname is<br />
specified, any Model terminal definition value from the configuration<br />
file is used. If no Model terminal definition value has been specified<br />
in the configuration file, the server’s default terminal definition is<br />
assumed.<br />
If the parameter is specified as -m= (that is, the modelname is<br />
omitted), any Model terminal definition value specified in the<br />
configuration file is ignored, and the server’s default terminal<br />
definition is assumed.<br />
This option is case sensitive.<br />
-n=netname<br />
Specifies the name of a particular terminal definition at the server that<br />
this emulator is to be installed as. The precise interpretation of<br />
netname varies between servers. For example, on <strong>CICS</strong> for OS/2 it<br />
references a termid defined in the <strong>CICS</strong> tables, but on TXSeries for<br />
AIX it is a netname.<br />
This option is case sensitive.<br />
-p=printcmd<br />
Specifies an operating system command used to process the<br />
temporary print file generated when print requests are received by the<br />
terminal emulator. If the command contains embedded blanks, then<br />
Chapter 11. Terminal Emulation 155
The cicsterm command<br />
the command must be enclosed by double quotes (“). Any double<br />
quotes within the command must be entered as backslash double<br />
quote (\“).<br />
If neither of the -f or -p parameters is specified, the Print command or<br />
Print file setting in the configuration file defines the command, file, or<br />
default action to take with print requests.<br />
The temporary print file is post-processed by appending the filename<br />
to the command, and executing the resultant command. Thus print<br />
output may simply be copied to a local printer, copied into a<br />
permanent file, processed further for inclusion into a document, and<br />
so on. If the temporary file is to be processed by a print command,<br />
the command is responsible for deleting the temporary file.<br />
-q Disables the display of all messages output by the command.<br />
-s=servername or -r=servername<br />
Specifies the name of the server that the terminal emulator is to be<br />
connected to. This servername must correspond to an entry in the<br />
configuration file. You can specify -s, or -r, but not both.<br />
If neither parameter is specified, the first server entry in the<br />
configuration file is used.<br />
If the parameter is specified as -s or -r (that is, no servername is<br />
provided) then, if the configuration file identifies more than one<br />
potential server to which the Client daemon can connect, the user is<br />
prompted to select from a list of available servers. These prompts are<br />
generated even if the -q parameter is specified.<br />
If there is only one potential server identified in the configuration file,<br />
that server is used and the user is not prompted.<br />
-t=initialtransid<br />
Identifies the initial transaction to be invoked for this terminal. If this<br />
option is omitted, any initial transaction specified in the configuration<br />
file is run. The string may be up to 128 characters long, specifying<br />
both a transaction name, and parameters to be passed to the<br />
transaction. The transaction name is the first four characters or the<br />
characters up to the first blank in the string. The rest of the string is<br />
the parameter data.<br />
If the parameter is specified as -t= (that is, the initialtransid is<br />
omitted), any initial transaction specified in the configuration file is<br />
ignored.<br />
This option is case sensitive.<br />
156 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
Note: Be careful that transactions that you specify either here or in<br />
the configuration file do not require terminal input to complete.
-? Causes the parameter syntax to be listed; any other options specified<br />
are ignored.<br />
The cicsprnt command<br />
The cicsprnt command controls 3270 printer terminal emulation.<br />
An application running on a server can direct output to a printer in one of<br />
two ways:<br />
1. An application running from a terminal can initiate printing by sending a<br />
map or data with the PRINT indicator set<br />
2. A user can start a 3270 Print Terminal Emulator, at a client, using the<br />
cicsprnt command. A 3270 Print Terminal Emulator must be started for a<br />
netname or model terminal definition predefined in the server’s terminal<br />
tables. Output is directed to such a device by starting a transaction against<br />
the printer device.<br />
Note: At client workstations you can use the PrintScreen key, as defined by<br />
the keyboard mapping file. However, any lines that contain only null<br />
characters are not printed. For a ‘blank’ line to be printed, it must<br />
contain at least one space character.<br />
Using cicsprnt<br />
The following table shows the functions that you can perform with the<br />
cicsprnt command, and the parameters associated with each function:<br />
Function Parameters<br />
Start a 3270 print terminal emulator -s and -r<br />
Specify the initial transaction -t<br />
Define the 3270 printer terminal emulator characteristics -n and -m<br />
Determine the print file processing -p<br />
Specify a file to which print files are appended -f<br />
Wait for confirmation before completing -q<br />
Inhibit all ouput messages -q<br />
Issue one print job per transaction -j<br />
You issue the cicsprnt command once with all the parameters you require.<br />
The following is an example of a cicsprnt command:<br />
cicsprnt -s=<strong>CICS</strong>OS2 -n=P123 -t=XPRT -f=clprint.txt -q<br />
In this example:<br />
The cicsterm command<br />
Chapter 11. Terminal Emulation 157
The cicsprnt command<br />
-s=<strong>CICS</strong>OS2 Specifies that a 3270 print terminal emulator is started for the<br />
server <strong>CICS</strong>OS2.<br />
-n=P123 Specifies that the 3270 print terminal emulator characteristics<br />
are defined by the terminal definition P123 (in the terminal<br />
control table for <strong>CICS</strong> for OS/2 in this case.)<br />
-t=XPRT Specifies that the initial transaction is XPRT.<br />
-f=clprint.txt Specifies that the print file to which print requests are<br />
appended is clprint.txt.<br />
-q Specifies that the display of messages output by the command<br />
is disabled.<br />
All parameters of cicsprnt are optional, except that you must specify either<br />
-n=netname or -m=modelname. That is, you can enter the cicsprnt command<br />
with just the -n or the -m parameter, or both, and defaults for other<br />
parameters are taken from the configuration file. Full details of the parameters<br />
are given in “cicsprnt command reference”.<br />
If the system upon which the Client daemon is running supports DBCS, it is<br />
assumed that the printer attached to the processor also supports DBCS.<br />
Conversely, if the system does not support DBCS, the Client daemon will not<br />
send DBCS data to the printer.<br />
cicsprnt and user exits<br />
You can use cicsprnt to drive EPI user exits.<br />
The EPI user exits, and how cicsprnt can use them, are described in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
cicsprnt and RETURN TRANSID IMMEDIATE<br />
Unlike cicsterm, cicsprnt does not support the commands:<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE<br />
EXEC <strong>CICS</strong> RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)<br />
For more information, refer to “cicsterm and RETURN TRANSID<br />
IMMEDIATE” on page 153.<br />
cicsprnt command reference<br />
For an explanation of syntax diagrams, see “Conventions and terminology<br />
used in this book” on page viii.<br />
You can enter parameters preceded by the dash (-) or by the forward slash (/)<br />
character. However for the ? parameter you must use a dash.<br />
158 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
cicsprnt Command Syntax<br />
►► cicsprnt<br />
-s=servername -t=initialtransid -j<br />
-s -t<br />
-r=servername<br />
-r<br />
► -m=modelname<br />
-n=netname -p=printcmd -q -?<br />
-f=printfile -w<br />
The options are:<br />
-f=printfile<br />
Specifies the name of a file to which the output of print requests is<br />
appended. If the name of the file contains embedded blanks, it must<br />
be surrounded by double quotes (“). Any double quotes within the<br />
name of the file must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is provided, the Print command<br />
or Print file setting in the configuration file defines the command, file,<br />
or default action to take with print requests.<br />
-j Specifies that cicsprnt should concatenate all EXEC <strong>CICS</strong> SEND<br />
PRINT commands issued on a server transaction into a single print<br />
job. This print job is issued when the transaction terminates.<br />
Otherwise cicsprnt will generate a separate print job for every EXEC<br />
<strong>CICS</strong> SEND PRINT command issued for a server transaction.<br />
-m=modelname<br />
Specifies the name of a model terminal definition, as known at the<br />
server to which the 3270 Print Terminal emulator is to connect, to be<br />
used to define the terminal characteristics. If this parameter is not<br />
specified, any Model terminal definition value from the configuration<br />
file is used. If no Model terminal definition value has been specified<br />
in the configuration file, the server’s default terminal definition is<br />
assumed.<br />
You must specify either the -m or the -n option, or both.<br />
This option is case-sensitive<br />
-n=netname<br />
Specifies the name of a particular terminal definition at the server that<br />
this 3270 Print Terminal emulator is to be installed as. The precise<br />
interpretation of netname varies between servers. For example, on<br />
TXSeries for AIX it is a netname.<br />
You must specify either the -m or the -n option, or both.<br />
-j<br />
The cicsprnt command<br />
►<br />
►◄<br />
Chapter 11. Terminal Emulation 159
The cicsprnt command<br />
This option is case-sensitive.<br />
-p=printcmd<br />
Specifies a command used to process the temporary print file<br />
generated when print requests are received by the terminal emulator.<br />
If the command contains embedded blanks, then the command must<br />
be surrounded by double quotes (“). Any double quotes within the<br />
command must be entered as backslash double quote (\“).<br />
If neither of the -f or -p parameters is specified, the Print command or<br />
Print file setting in the configuration file defines the command, file, or<br />
default action to take with print requests.<br />
The temporary print file is post-processed by appending the filename<br />
to the command, and executing the resultant command. Thus print<br />
output may simply be copied to a local printer, copied into a<br />
permanent file, processed further for inclusion into a document, and<br />
so on. If the temporary file is to be processed by a print command,<br />
the command is responsible for deleting the temporary file.<br />
-q Disables the display of all messages output by the command.<br />
-s=servername or -r=servername<br />
Specifies the name of the server that the printer is to be connected to.<br />
This servername must correspond to an entry in the configuration file.<br />
You can specify -s, or -r, but not both.<br />
If neither parameter is specified, the first server entry in the<br />
configuration file is used.<br />
If the parameter is specified as -s or -r (that is, no servername is<br />
provided) then, if the configuration file identifies more than one<br />
potential server to which the Client daemon can connect, the user is<br />
prompted to select from a list of available servers. These prompts are<br />
generated even if the -q parameter is specified.<br />
If there is only one potential server identified in the configuration file<br />
that server is used and the user is not prompted.<br />
-t=initialtransid<br />
Identifies the initial transaction to be invoked for this printer. If this<br />
option is omitted, any initial transaction specified in the configuration<br />
file is run. The string may be up to 128 characters long, specifying<br />
both a transaction name, and parameters to be passed to the<br />
transaction. The transaction name is the first four characters or the<br />
characters up to the first blank in the string. The rest of the string is<br />
the parameter data.<br />
If the parameter is specified as -t= (that is, the initialtransid is<br />
omitted), any initial transaction specified in the configuration file is<br />
ignored.<br />
160 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The cicsprnt command<br />
Note: Be careful that transactions that you specify either here or in<br />
the configuration file do not require terminal input to complete.<br />
This option is case-sensitive.<br />
-? Causes the parameter syntax to be listed; any other options specified<br />
are ignored.<br />
Chapter 11. Terminal Emulation 161
The cicsprnt command<br />
162 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 12. The Terminal Servlet program<br />
This chapter describes how to use the Terminal Servlet to access <strong>CICS</strong> 3270<br />
applications using a Web browser.<br />
v “What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet?” tells you what a<br />
servlet is, and in particular what the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal<br />
Servlet does.<br />
v “Installing and configuring the Terminal Servlet” on page 165 discusses how<br />
you install and configure the Terminal Servlet.<br />
v “Using the Terminal Servlet” on page 171 describes what you can do with<br />
the Terminal Servlet, and how to invoke it from your Web pages.<br />
v “Properties and parameters reference” on page 176 provides a complete<br />
reference to the servlet properties you can specify for the Terminal Servlet.<br />
v “Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong> on AIX” on page 220 describes<br />
what you need to do to migrate from AIX running the <strong>CICS</strong> Internet<br />
<strong>Gateway</strong> to using the Terminal Servlet.<br />
v “<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web Interface” on page 182 describes<br />
how HTML templates generated for use by the <strong>CICS</strong> Web Interface can be<br />
used by the Terminal Servlet.<br />
It is advisable to read through all of this chapter before configuring and using<br />
the Terminal Servlet.<br />
What is the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet?<br />
Servlets are Java programs that run on a Web server machine, inside a<br />
Java-enabled Web server or servlet engine, for example, WebSphere<br />
Application Server (see Figure 22 on page 165). Java servlets have become<br />
popular as alternatives to Common <strong>Gateway</strong> Interface (CGI) programs—the<br />
Terminal Servlet is a replacement for the <strong>CICS</strong> Internet <strong>Gateway</strong> shipped with<br />
IBM <strong>CICS</strong> Clients <strong>Version</strong> 2, which was a CGI program.<br />
A servlet can be loaded automatically when the Web server is started, or<br />
loaded when the first client request for the services of the servlet is made.<br />
Unlike CGI programs, servlets are persistent, that is, once they are loaded<br />
they stay running, waiting for additional client requests.<br />
Being Java programs, servlets are portable across operating systems. And,<br />
because the servlet interface is a standard, they can be used with different<br />
Web servers on different platforms.<br />
© Copyright IBM Corp. 1996, 2002 163
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
The Terminal Servlet allows you to access <strong>CICS</strong> 3270 applications using a Web<br />
browser. You create Web pages that invoke the Terminal Servlet to start a<br />
<strong>CICS</strong> transaction, display screen information sent from a <strong>CICS</strong> server, and<br />
send screens back to <strong>CICS</strong>.<br />
The Terminal Servlet can:<br />
v Behave like a simple terminal emulator.<br />
The <strong>CICS</strong> screen is displayed in the browser as part of an HTML form.<br />
When you press one of the buttons in the form, the form is submitted and<br />
data is sent to <strong>CICS</strong>.<br />
v Substitute data from a <strong>CICS</strong> screen into HTML template files.<br />
An HTML template file is used to determine how <strong>CICS</strong> data appears in the<br />
browser. The Terminal Servlet replaces variables in the HTML template file<br />
with <strong>CICS</strong> screen information, and the resulting output is sent to the<br />
browser. For more information, see “Using variable substitution” on<br />
page 174.<br />
v Using server-side includes, incorporate variable information in a Web<br />
page, or drive a terminal emulator without user interaction.<br />
Server-side includes are statements in an HTML file (.shtml) that are<br />
processed by the Web server before the Web page is returned to the<br />
browser. For example, you can use a server-side include to invoke the<br />
Terminal Servlet to display the value of fields in a <strong>CICS</strong> screen. For more<br />
information, see “Invoking the servlet with a server-side include” on<br />
page 173.<br />
v Map <strong>CICS</strong> screens to Web pages.<br />
Using the page mapping properties of the Terminal Servlet, you can<br />
associate particular Web pages with particular <strong>CICS</strong> screens. For example,<br />
you can specify the Web page to be displayed when the terminal is idle,<br />
and no transaction is running. For more information, see “Page mapping<br />
properties” on page 179.<br />
Like EPI programming, the Terminal Servlet allows you to create new front<br />
ends to existing <strong>CICS</strong> transactions. However, it also allows you to exploit the<br />
power, flexibility, and platform-independence of Java programming.<br />
Note: The Terminal Servlet does not support DBCS fields in 3270 data<br />
streams.<br />
164 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Workstation<br />
Java-enabled browser<br />
HTTP<br />
<strong>Gateway</strong> server<br />
Web server / servlet engine<br />
Servlet<br />
<strong>Gateway</strong> daemon<br />
Client daemon<br />
TCP62<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for OS/390<br />
<strong>CICS</strong> server<br />
Installing and configuring the Terminal Servlet<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Figure 22. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> using Terminal Servlet invoked by URL<br />
This section discusses how to install the Terminal Servlet on the Web server<br />
machine, and set the initialization parameters of the Terminal Servlet.<br />
The procedure for installing and configuring the Terminal Servlet will vary<br />
according to the Web server. However, you will need to do at least the<br />
following:<br />
v Configure the Web server’s CLASSPATH and PATH settings<br />
v Add the Terminal Servlet to the Web server’s configuration<br />
v Configure the servlet initialization parameters<br />
v Consider other configuration options, such as security, logging, and<br />
whether the Web server can process server-side includes.<br />
Chapter 12. The Terminal Servlet program 165
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Examples of installing and configuring the Terminal Servlet on a particular<br />
Web server are available in the sample configuration documents. See “Sample<br />
configuration documents” on page 238. The principles described should also<br />
apply to other Web servers.<br />
Refer to the documentation for your Web server for information on installing<br />
and configuring servlets.<br />
Configuring the Web server’s CLASSPATH and PATH settings<br />
You must ensure that the two <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> jar files,<br />
ctgclient.jar and ctgserver.jar, are in the Web server’s classpath.<br />
If you do not make the correct classpath settings, you may get a message to<br />
the effect that you cannot update the servlet, and that the class<br />
com.ibm.ctg.servlet.TerminalServlet cannot be loaded.<br />
You must also ensure that the /bin subdirectory is in the Web<br />
server’s path.<br />
Adding the Terminal Servlet to the Web server’s configuration<br />
To add the Terminal Servlet to the Web server’s configuration, you must<br />
provide a Servlet Name and associate this servlet instance with the Terminal<br />
Servlet class, which is com.ibm.ctg.servlet.TerminalServlet.<br />
You can configure more than one instance of the Terminal Servlet. Each of<br />
them would have a different Servlet Name, but would refer to the same<br />
Servlet Class. In fact, you must create a different Terminal Servlet instance for<br />
each <strong>CICS</strong> server that you want to connect to. Each instance of the Terminal<br />
Servlet may use different initialization parameters, and this can be useful<br />
when configuring for different <strong>CICS</strong> servers.<br />
Configuring the servlet initialization parameters<br />
After adding the Terminal Servlet to the Web server’s configuration, you must<br />
set up the initialization parameters for the Terminal Servlet.<br />
The following sections give some insight into how the Terminal Servlet works,<br />
which will help you in setting appropriate servlet initialization parameters.<br />
The Terminal Servlet now supports signon capable terminals. For information<br />
on the full set of initialization parameters available, including those to provide<br />
this type of terminal, refer to “Properties and parameters reference” on<br />
page 176.<br />
166 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
As a starting point consider setting some of the following parameters:<br />
Table 9. Servlet initialization parameters<br />
Parameter name Notes<br />
servlet@propertyFile The servlet can load configuration information from a<br />
properties file. A sample servlet.properties file is<br />
supplied, in the<br />
/samples/terminalservlet subdirectory.<br />
To use a properties file, set this parameter to the full<br />
path name of the properties file you want the Terminal<br />
Servlet to load. If you specify a properties file then you<br />
may want to use this file for all other servlet<br />
parameters. In this case, servlet@propertyFile is the<br />
only parameter that you need to set.<br />
servlet@extendedLogging The servlet writes logging information, for example,<br />
error messages, to the standard servlet log. Set this<br />
property to true to write more information to the log<br />
file. You may find this helpful when first configuring<br />
the servlet, but it should be turned off once the servlet<br />
is set up correctly.<br />
pool@maxTerminals Set this property to the maximum allowable number of<br />
connections to the <strong>CICS</strong> server. You should ensure that<br />
the <strong>CICS</strong> server has sufficient free tasks to handle this<br />
number of concurrent connections. You should also<br />
ensure that the <strong>CICS</strong> Client Maximum requests<br />
configuration setting is at least as large as this property.<br />
pool@serverName Each instance of the Terminal Servlet can connect to<br />
only one <strong>CICS</strong> server. This gives you more control of<br />
resource usage and security. Set this property to the<br />
name of the required <strong>CICS</strong> server, as defined by the<br />
appropriate Server name setting in your configuration.<br />
If this property is not set, the default <strong>CICS</strong> server is<br />
used.<br />
pool@gatewayUrl Set this property if you want the servlet to connect over<br />
the network to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Apart from the name of the property file, all the servlet properties can either<br />
be loaded from a properties file or set as servlet initialization parameters.<br />
Initialization parameters override properties file entries.<br />
The servlet property names are not case sensitive.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
Terminal pooling<br />
The Terminal Servlet uses a pool of terminals, and the servlet configuration<br />
properties allow you to control the behavior of the terminal pool. The default<br />
Chapter 12. The Terminal Servlet program 167
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
behavior is that a new terminal is connected to <strong>CICS</strong> whenever a user requires<br />
one, up to the pool@maxTerminals limit. When the user has finished with the<br />
terminal, it is disconnected.<br />
If the pool@minTerminals property is set, this number of terminals is<br />
connected to <strong>CICS</strong> when the servlet starts, and up to that number may be<br />
connected to <strong>CICS</strong> but not in use at any time. This allows new users to be<br />
allocated a terminal immediately, without waiting for a connection.<br />
Setting the pool@reusingTerminals property allows terminals to be reused,<br />
that is, when a user session ends, the terminal may be allocated to a new user<br />
instead of being disconnected. This property has no effect if<br />
pool@minTerminals is 0. Any transaction running on the terminal is ended<br />
and the screen is cleared, before it is reused. However, if a user has signed on<br />
to <strong>CICS</strong> (using CESN for example), the terminal will still be signed on when it<br />
is reused. For this reason, do not set this property unless you are sure it is<br />
suitable for your environment.<br />
The pool@idleTimeout property allows terminals that have been allocated to<br />
a user to be released if they have not been used for the specified timeout<br />
period. This property defaults to 0, that is, no timeout.<br />
Using a display request with the values: pool@connectedTerminals,<br />
pool@freeTerminals, and pool@terminalsInUse, you can query the number of<br />
terminals that are connected, free, or in use for a particular instance of the<br />
Terminal Servlet.<br />
Page mappings<br />
Page mappings tell the Terminal Servlet what Web page to display for a<br />
particular <strong>CICS</strong> screen or terminal state.<br />
The servlet’s choice of which page to display is based on the current page<br />
mapping settings, the current screen handler class, and the state of the<br />
terminal.<br />
The Terminal Servlet first looks at the page mapping properties to see if there<br />
is a specific page set for the current state of the session, as follows:<br />
Session State Page Mapping Property<br />
an error has occurred page@error<br />
the terminal is idle - no transaction is<br />
running<br />
page@idle<br />
the terminal has been disconnected page@disconnected<br />
there is a screen handler for the current Page mapping for the class name of the<br />
screen<br />
screen handler<br />
168 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
If no specific page is found, the page identified by the page mapping property<br />
page@default is used. If this is not set, an error message is displayed instead.<br />
The value of a page mapping property can be set in two ways:<br />
1. A URL, for example:<br />
http://webserver/index.html<br />
2. A template file to be loaded for variable substitution. This must start with<br />
″file://″, for example:<br />
file://d:/pages/template.html<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
If you set the servlet@templateDir property, template filenames can be<br />
specified relative to the template directory.<br />
Example settings for page mapping properties are as follows:<br />
page@error=http://server/errors.html<br />
page@idle=http://server/idle.html<br />
page@disconnected=/ctglab/html/servlet/epissam.html<br />
page@default=file://epissam1.html<br />
To set a page mapping for a particular screen, you must create a Screen<br />
Handler bean that can recognize that screen. Then, you must set the<br />
pool@handlerPath property to ensure that the Screen Handler bean is loaded<br />
by the Terminal Servlet. If, for example, you have created a Screen Handler<br />
bean called MAP1ScreenHandler in a package called testmaps, then the page<br />
mapping property for that screen handler is:<br />
page@testmaps.MAP1ScreenHandler.<br />
The name of the class is case sensitive. As for the standard page mappings,<br />
you set the property to the name of the Web page to display, for example:<br />
page@testmaps.MAP1ScreenHandler=http://server/test.html<br />
A page mapping can also be set in a request parameter to the Terminal<br />
Servlet, in which case it applies only to that request and overrides any page<br />
mappings associated with the instance of the servlet being used. You can<br />
query the current setting of a page mapping with an appropriate request (see<br />
“Displayable properties” on page 181).<br />
Screen Handler beans and terminal disconnection<br />
For a terminal to be disconnected successfully, it must exit from running<br />
transactions. The Terminal Servlet’s default behavior for achieving this is to<br />
send the AID (Attention identifier) PF3 key to <strong>CICS</strong>. However, if you will be<br />
running transactions for which this will not work, you should create one or<br />
more Screen Handler beans that know how to exit the relevant screens.<br />
Chapter 12. The Terminal Servlet program 169
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
You can generate Screen Handler beans automatically from BMS maps using<br />
the BMS Map Conversion Utility (BMSMapConvert) supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, or you can write your own classes. For information<br />
about Screen handlers and how to create them, see the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide book.<br />
To load screen handlers into the servlet, set the pool@handlerPath property.<br />
The handler path can include .jar files, .zip files and directories, although<br />
sub-directories will not be searched. For example, in the servlet properties file<br />
you might add:<br />
pool@handlerPath=d:/handlers/handlers.jar;d:/handlers/test<br />
to load screen handler classes from a .jar file and from a directory. See the<br />
sample properties file for more information on setting this property.<br />
You can also specify a default screen handler (using the property<br />
pool@defaultHandler), which is used to exit from a screen if no other screen<br />
handler recognizes it. The sample default screen handler is<br />
com.ibm.ctg.epi.DefaultScreenHandler, which sends the AID PF3 to <strong>CICS</strong>.<br />
Any screen handler bean that can be loaded from the classpath or from the<br />
handler path can be used as the default screen handler.<br />
The servlet will not keep trying to exit a running transaction indefinitely. The<br />
property pool@exitRetryLimit controls how many attempts it makes to exit<br />
the transaction. The default value of this property is 10, but you should<br />
ensure it is large enough for your environment. If the servlet finds there is<br />
still a transaction running on the terminal after this many attempts to exit, the<br />
terminal is assumed to be ‘dead’ and it will not be disconnected or allocated<br />
to a user. The only way to discard dead terminals is to unload the servlet,<br />
stop and restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and load the servlet again.<br />
If you have configured the servlet properly and provided Screen handler<br />
beans, you should not have any dead terminals.<br />
Considering other configuration options<br />
Other configuration options that you should consider are:<br />
v Security<br />
You may need to control access to the Terminal Servlet.<br />
v Logging<br />
The Terminal Servlet writes log information to the standard servlet log. You<br />
can set logging on or off.<br />
v Session tracking<br />
You should configure the Terminal Servlet to use session tracking.<br />
v Server-side includes<br />
170 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
You may wish to configure your Web server to process server-side includes.<br />
Loading the Terminal Servlet<br />
After you have configured the Terminal Servlet and saved the settings, you<br />
must load it. You can choose whether to load it immediately, or each time<br />
your Web server starts up.<br />
Using the Terminal Servlet<br />
If you have not configured the Terminal Servlet properly, error messages are<br />
displayed when the Web server attempts to load the Terminal Servlet. For<br />
more information refer to the Terminal Servlet section in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: <strong>Gateway</strong> Messages book.<br />
This section describes how to use the Terminal Servlet. It describes the<br />
different ways in which the Terminal Servlet can be invoked, and also how to<br />
develop the Web pages that use the Terminal Servlet.<br />
Sample files are provided in the /samples/terminalservlet<br />
subdirectory. File samples.txt describes the samples.<br />
Connecting to <strong>CICS</strong> and starting a transaction<br />
An instance of the Terminal Servlet can only connect to one <strong>CICS</strong> server. For<br />
each <strong>CICS</strong> server that you want to allow access to, you will have created an<br />
instance of the servlet. You might also have created instances of the servlet<br />
that have different initialization parameters.<br />
To start a transaction on the <strong>CICS</strong> server, you must invoke the Terminal<br />
Servlet with a suitable request.<br />
Invoking the Terminal Servlet<br />
There are three ways to invoke the Terminal Servlet:<br />
v by URL<br />
v with an HTML form<br />
v with a server-side include.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet<br />
In each case, you need to know the name of the servlet instance that you<br />
want to use, and you pass the servlet one or more request parameters that tell<br />
it what action to take. The parameter names and values are the same in all<br />
cases, but the way you specify them is different.<br />
To start a transaction on the <strong>CICS</strong> server, the parameters you must provide<br />
are:<br />
Chapter 12. The Terminal Servlet program 171
Using the Terminal Servlet<br />
Parameter Name Parameter Value<br />
request send<br />
transaction the transaction ID of the transaction you want started.<br />
Note however that ATI transactions cannot be started for the<br />
Terminal Servlet.<br />
The servlet will allocate a terminal to the user, if it is required.<br />
The full set of request parameters are listed in “Request parameters” on<br />
page 180.<br />
Invoking the servlet by URL<br />
To invoke a servlet instance called TerminalServlet, link to the URL:<br />
http://your_webserver/servlet/TerminalServlet<br />
where your_webserver is the hostname of your Web server and /servlet/ is the<br />
location of your servlet engine (or the context for the servlet).<br />
You can encode request parameters in the URL in the form of a query string,<br />
for example:<br />
http://your_webserver/servlet/TerminalServlet?request=send&transaction=CECI<br />
You should use this method of invoking the servlet when you do not need the<br />
user to enter any information.<br />
Invoking the servlet with an HTML form<br />
With this method, you create an HTML form in a Web page. For example:<br />
<br />
(Tags to place text entry areas, buttons, and other prompts go here)<br />
<br />
is a form that would invoke the servlet called TerminalServlet. The METHOD<br />
can be GET or POST. The various elements of the form have names and<br />
values, and these are sent to the servlet when the form is submitted. If you<br />
know you want to set a particular request parameter, add it as a hidden item<br />
in the form, for example: . Hidden inputs are always sent to the servlet. In general, the<br />
name of a form element is the name of a request parameter, and its value is<br />
the value of the request parameter.<br />
This is the only way to send user-entered information to the servlet.<br />
The supplied sample, epissam3.html, illustrates the HTML form method; see<br />
the samples.txt file on the product CD.<br />
172 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Invoking the servlet with a server-side include<br />
A server-side include is processed by the Web server before the Web page is<br />
sent to the user. The servlet is invoked, and any output it generates is<br />
included in the Web page in place of the server-side include tags. The user<br />
only sees the servlet output in the Web page.<br />
In the HTML source, a WebSphere server-side include of the servlet looks like<br />
this:<br />
<br />
<br />
<br />
<br />
<br />
A server-side include can be used to add variable information to a Web page,<br />
or to drive a terminal to perform some action whenever a Web page is<br />
displayed, without any user involvement.<br />
You can add as many server-side includes to a Web page as you wish, but<br />
note:<br />
v Server-side includes in one page may be processed in parallel. You can<br />
therefore not be sure in which order they are performed, although usually<br />
this is the order in which they occur in the source.<br />
v The servlet stores session information that allows it to access the terminal<br />
allocated to a user. If the user session is invoked by a server-side include,<br />
subsequent server-side includes in the same page will not be able to access<br />
the session information. Once the page has been sent to the user, the<br />
session is established, and a page with multiple server-side includes will<br />
work correctly.<br />
The supplied sample<br />
/samples/terminalservlet/epissam2.shtml illustrates the<br />
server-side include method.<br />
What happens next?<br />
When the servlet has been invoked from a form or by linking to a URL, some<br />
output must be sent back to the browser. To decide what should be displayed<br />
to the user, the servlet uses the page mapping properties that you have set up,<br />
see “Page mappings” on page 168.<br />
Displaying screens and fields<br />
There are two ways to include <strong>CICS</strong> screen information in a Web page:<br />
v server-side includes<br />
v variable substitution.<br />
You can mix the two approaches if you want to.<br />
Using the Terminal Servlet<br />
Chapter 12. The Terminal Servlet program 173
Using the Terminal Servlet<br />
Using server-side includes<br />
Your Web server must be configured to process server-side includes. You<br />
create SHTML pages that contain server-side includes that invoke the servlet.<br />
The output from the servlet is inserted into the page in place of the<br />
server-side include.<br />
For example, to display the screen, as part of an HTML form, using<br />
WebSphere:<br />
<br />
<br />
<br />
or to display the contents of the 22nd field on the screen, using WebSphere:<br />
<br />
<br />
<br />
Using variable substitution<br />
You create HTML template files that the servlet will load. The servlet replaces<br />
variables in the file with <strong>CICS</strong> screen information, and the resulting output is<br />
sent to the browser. You use page mapping properties to tell the servlet what<br />
template file to load (see “Page mappings” on page 168).<br />
For example, a template file for the CESN signon screen might look like:<br />
<br />
<br />
<strong>CICS</strong> Signon<br />
<br />
<br />
<strong>CICS</strong> Signon<br />
<br />
<br />
<br />
Userid: <br />
Password: <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
where the variables are &USERID; and &PASSWORD;. You can identify fields<br />
by number - to use names for fields, as in this example, you must have a<br />
Screen Handler bean which can recognize the screen and set fields by name.<br />
Page mapping property values can be the names of HTML template files or<br />
any URL. So that the servlet knows that a page mapping property identifies<br />
174 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
an HTML template, you should set it to the value file://template_filename, for<br />
example: file://d:/html/templates/test.html.<br />
What can be displayed?<br />
Any piece of information that can be displayed by a server-side include can<br />
also be used for variable substitution, and vice-versa. The variable name used<br />
in a template is the same as the value of the display parameter in the<br />
server-side include.<br />
Generally, you can display:<br />
v The screen, as part of an HTML form<br />
v A field - identified by number, or by name, if you have a Screen Handler<br />
bean for it<br />
v Servlet configuration settings<br />
v The number of terminals that are currently connected, in use, and free.<br />
The full set of properties that can be displayed is listed in “Properties and<br />
parameters reference” on page 176.<br />
Sending the screen back to <strong>CICS</strong><br />
To send the screen back to <strong>CICS</strong> you must invoke the servlet with the request<br />
parameter set to ″send″. You do not need to provide a transaction parameter -<br />
it is ignored if a transaction is already running. To update the screen with<br />
new information before sending it back to <strong>CICS</strong>, you specify further request<br />
parameters that identify the fields (by name or number) and what they should<br />
be set to.<br />
For example, the following WebSphere server-side include:<br />
<br />
<br />
<br />
<br />
<br />
<br />
sets the fields named USERID and PASSWORD to the values given, and then<br />
send the screen to <strong>CICS</strong>. In an HTML form, you might use the form element<br />
. When the user<br />
submits the form, the request parameter USERID is set to the value that they<br />
entered.<br />
Setting the AID<br />
The default AID is Enter.<br />
Using the Terminal Servlet<br />
To set the AID from an HTML form, include a Submit button, specified like<br />
this:<br />
Chapter 12. The Terminal Servlet program 175
Using the Terminal Servlet<br />
.<br />
If the user presses the button, the servlet is sent the request parameter<br />
″DFH_PF3″ with the value ″Exit″ (which the servlet ignores). The AID is set to<br />
PF3. In a,WebSphere server-side include, you could set the AID like this:<br />
<br />
<br />
<br />
<br />
<br />
The full set of request parameters is listed in see “Properties and parameters<br />
reference”.<br />
Disconnecting<br />
When the servlet has allocated a terminal to a user, it is retained until:<br />
v The servlet is invoked with the parameter ″request″ set to ″disconnect″<br />
v The user’s session on the Web server expires<br />
v If the pool@idleTimeout property has been set, the terminal is<br />
automatically disconnected if it is not accessed for the specified period of<br />
time.<br />
v The <strong>CICS</strong> Client is stopped<br />
v The connection to the <strong>CICS</strong> server is lost - or the server goes down<br />
v The servlet is unloaded by the Web server.<br />
You should try to explicitly release terminals when they are no longer<br />
required.<br />
Note that when a user has established a session with the servlet and been<br />
allocated a terminal, any instance of the servlet to which the user has access<br />
can continue the session. The same terminal is used until the user disconnects<br />
or the session is ended for some other reason. The page mappings and other<br />
properties used for any particular request are those set for the instance of the<br />
servlet that is processing the request.<br />
Properties that can be set as request parameters, for example, page mappings,<br />
override the settings for the servlet, but usually only apply to the current<br />
request, and do not affect requests by other users or subsequent requests by<br />
the same user.<br />
Properties and parameters reference<br />
This section describes the Terminal Servlet properties<br />
176 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Properties and parameters reference<br />
Servlet configuration properties<br />
In general, these properties can be specified either in a properties file or as<br />
servlet initialization parameters when you configure the Web server. The<br />
names are not case sensitive. Values given as servlet initialization parameters<br />
override settings loaded from a properties file. Apart from the servlet@debug<br />
and servlet@extendedLogging properties, these settings cannot be changed<br />
while the servlet is running. However, using the request parameter display,<br />
you can query the current settings of a property, see “Displayable properties”<br />
on page 181.<br />
servlet@debug<br />
If set to true, turns tracing on for all instances of the servlet. You can<br />
turn tracing on or off while the servlet is running, and output is<br />
directed to standard output. Note that turning tracing on seriously<br />
impacts performance!<br />
servlet@extendedLogging<br />
If set to true, turns extended logging on. Output is directed to the<br />
servlet log.<br />
servlet@propertyFile<br />
The full path name of a properties file to load. This property can only<br />
usefully be set as a servlet initialization parameter.<br />
servlet@templateDir<br />
The name of a directory from which HTML template files can be<br />
loaded. Setting this property prevents users from viewing files that<br />
are not in the template directory or its subdirectories. If you do not set<br />
this property, the servlet can load any file on the Web server that it<br />
has access to.<br />
pool@defaultHandler<br />
The screen handler to use to exit screens when no specific handler is<br />
found. If you set this to be one of the Screen Handlers loaded from<br />
the Screen Handler path, make sure that the handler path is set before<br />
the default handler.<br />
pool@deviceType<br />
The terminal model definition to use. If this property is not set, the<br />
default is used.<br />
pool@encoding<br />
Allows you to specify the Java Encoding to be used. Refer to<br />
″Appendix A. Java encodings″ in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference book for further details on this.<br />
pool@exitRetryLimit<br />
The number of times that the servlet will try to exit a running<br />
transaction during terminal disconnection. This prevents the servlet<br />
looping, if a screen cannot be exited.<br />
Chapter 12. The Terminal Servlet program 177
Properties and parameters reference<br />
pool@gatewayUrl<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> that the servlet should<br />
connect to. The default is to use a local <strong>Gateway</strong>, that is local://.<br />
pool@handlerPath<br />
The path from which Screen Handler beans are loaded. You can<br />
include directories, .jar files, and .zip files, but subdirectories are not<br />
searched.<br />
pool@idleTimeout<br />
The maximum time in seconds to allow a terminal to be left idle<br />
before it is automatically disconnected. The default value is 0,<br />
meaning no timeout.<br />
pool@installTimeout<br />
The maximum time in seconds to allow a terminal to install before<br />
failing. The valid range is 0 to 3600. The default value is 0, meaning<br />
no timeout<br />
pool@maxTerminals<br />
The maximum number of terminals that can be connected to <strong>CICS</strong><br />
concurrently. The default value is 5.<br />
pool@minTerminals<br />
The number of terminals that should be kept connected to <strong>CICS</strong> when<br />
not in use. The default value is 0.<br />
pool@password<br />
Specifies the password to be associated with a signon incapable<br />
terminal at the time of creation.<br />
pool@readTimeout<br />
The maximum time in seconds to allow for conversational<br />
transactions before timing out.. Valid range is 0 to 3600. A value of 0<br />
meaning no timeout.<br />
pool@reusingTerminals<br />
If set to true, released terminals are kept connected for the next user.<br />
The default behavior is to disconnect terminals when a user session<br />
ends. You must also set pool@minTerminals for this property to have<br />
any effect.<br />
pool@serverName<br />
The name of the <strong>CICS</strong> server to connect to. If this property is not set,<br />
the default <strong>CICS</strong> server, as defined in your configuration is used.<br />
pool@signonCapability<br />
Specifies signon capability for extended terminals. Valid entries are<br />
EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE.<br />
178 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Properties and parameters reference<br />
pool@pool@userid<br />
Specifies the userid to be associated with a signon incapable terminal<br />
at the time of creation.<br />
screen@coloring<br />
If set to true, colored fields are displayed in the color indicated in the<br />
3270 datastream.<br />
Due to the limitations of HTML, unprotected fields cannot be colored<br />
and always appear as black text on a white background.<br />
If the property is not specified. the Terminal Servlet displays the<br />
screen with black text on a white background.<br />
screen@cursoring<br />
If set to true, JavaScript sets the screen cursor position. The default<br />
setting is false.<br />
screen@NeutralColor<br />
Specifies the HTML color to which the screen handler will translate<br />
the neutral 3270 color.<br />
screen@stripBlanks<br />
If set to true, the Web Browser formats the field text.<br />
screen@stripEmptyRows<br />
If set to true, the screen handler removes screen rows that do not<br />
contain data.<br />
screen@TrimFields<br />
If set to true, the screen handler removes excess white space from the<br />
start and end of any input fields.<br />
Page mapping properties<br />
Page mappings associate Web pages with particular screens or terminal states.<br />
Page mappings can be specified in a properties file, or as servlet initialization<br />
parameters, when you configure the Web server. However, using the request<br />
parameter display, you can query the current settings of a page mapping, see<br />
“Displayable properties” on page 181.<br />
Standard page mapping properties Value<br />
page@disconnected The page to show when the terminal is<br />
disconnected.<br />
page@error The page to show when an error occurs<br />
page@idle The page to show when the terminal is<br />
idle, that is, no transaction is running<br />
page@default The page if no other page is specified.<br />
page@screen The page to show for this screen.<br />
Chapter 12. The Terminal Servlet program 179
Properties and parameters reference<br />
Request parameters<br />
These parameters are set only when a request is made. You can also specify<br />
any other property that can be set on a request, for example:<br />
servlet@extendedLogging.<br />
Parameter name Parameter value<br />
request Set to ″send″ to send a screen to <strong>CICS</strong> or ″disconnect″ to<br />
end a session<br />
If required, a new terminal session is started.<br />
display The name of a property that can be displayed, see<br />
“Displayable properties” on page 181.<br />
translateText Set to ″true″ to translate the characters and & to<br />
< > and & respectively. This is used when<br />
text is displayed.<br />
transaction The transaction ID of a transaction to be started. This is<br />
only used if the request is ″send″ and the terminal state<br />
is idle.<br />
ATI transactions cannot be started for the Terminal<br />
Servlet.<br />
transactionData Additional parameters to pass to a transaction. This is<br />
only used if the request is ″send″ and the terminal state<br />
is idle, and a transaction was specified.<br />
DFH_CURSOR The field where the screen cursor should be placed, as a<br />
field index (a number), or the name of the field, if a<br />
screen handler bean is available for the current screen.<br />
DFH_ENTER,<br />
DFH_CLEAR, DFH_PA1 -<br />
3, DFH_PF1 - 24<br />
This parameter name must be in upper case.<br />
The value is ignored.<br />
Use one of these parameters to specify the AID key to<br />
be sent to <strong>CICS</strong>. This must be in upper case.<br />
A field index The text to be set in the field.<br />
Use to set the contents of a field when you know the<br />
field index.<br />
usingSession Set to false if no terminal session is required.<br />
180 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
If this parameter is set, any terminal used for this<br />
request is discarded after use.
Parameter name Parameter value<br />
matchOnIdle Set to false by default.<br />
Properties and parameters reference<br />
Normally the servlet only attempts to find a<br />
ScreenHandler for the current screen when the terminal<br />
state is ‘client’, that is, a conversational or<br />
pseudo-conversational transaction is expecting a<br />
response. Setting this property to true causes the servlet<br />
to check the current ScreenHandler every time the<br />
screen changes regardless of the state. You may want to<br />
do this if you have transactions that use BMS maps, but<br />
which are not conversational or pseudo-conversational.<br />
If you have a large number of ScreenHandlers, the<br />
servlet may run more slowly when this property is set<br />
to true. For this reason, the default value is false.<br />
In addition, if a Screen Handler bean is available for the current screen, you<br />
can set any properties on that bean by specifying them in the request. For<br />
beans generated by BMSMapConvert, the field names defined in the BMS<br />
map are properties that can be set to the required text in the field.<br />
Displayable properties<br />
The following table shows the values that can be specified for the ″display″<br />
request parameter or used for variable substitution, see “Using variable<br />
substitution” on page 174.<br />
Display values Displays<br />
none Nothing. Use to suppress output from a<br />
server-side include.<br />
screen The screen - as part of an HTML form.<br />
errorMessage If an error has occurred, the error<br />
message.<br />
errorCause If an error has occurred, further<br />
information about the error.<br />
DFH_CURSOR The name of the field where the cursor is,<br />
if it can be determined, otherwise the<br />
field index.<br />
a field index The field text<br />
a screen handler property name The value of the property if it can be<br />
determined.<br />
any of the servlet configuration properties The value of the property for the current<br />
listed above<br />
servlet instance.<br />
Chapter 12. The Terminal Servlet program 181
Properties and parameters reference<br />
Display values Displays<br />
any page mapping property The value of the property for the current<br />
servlet instance.<br />
any request parameter, except for<br />
″request″ and ″display″<br />
The value of the property for the current<br />
request.<br />
pool@connectedTerminals The current number of connected<br />
terminals, for this servlet instance.<br />
pool@freeTerminals The current number of connected<br />
terminals that are not in use, for this<br />
servlet instance.<br />
pool@terminalsInUse The current number of terminals allocated<br />
to users, for this servlet instance.<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS Web Interface<br />
The <strong>CICS</strong> Web Interface, included in <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
<strong>Version</strong> 1.2 and above, is a collection of transactions and programs supporting<br />
direct access to <strong>CICS</strong> transaction processing services from Web browsers.<br />
If you have generated HTML templates for use by the <strong>CICS</strong> Web Interface,<br />
they can also be used as HTML templates by the Terminal Servlet. You will<br />
have to make some changes to invoke the servlet instead of the <strong>CICS</strong> Web<br />
Interface, but the format is basically the same.<br />
To use the template file:<br />
1. Copy the template file to a directory on the Web server.<br />
2. Edit it to change the action to /servlet/TerminalServlet and add<br />
a hidden element with name ″request″ and the value ″send″.<br />
3. Generate a Map class and Screen Handler bean for the BMS map that the<br />
HTML template refers to.<br />
4. Compile the generated Java source files.<br />
5. Copy the compiled class files to a suitable directory on the Web server.<br />
6. Set the servlet property pool@handlerPath so that it will load the new<br />
classes.<br />
7. Set a page mapping property to associate the new Screen Handler bean<br />
with the HTML template file.<br />
182 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 13. Problem determination and problem solving<br />
Preliminary checks<br />
Most problems in a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system are caused by one of<br />
the following:<br />
v User errors<br />
v Programming errors<br />
v Configuration errors.<br />
Before investigating a problem, check whether there is an obvious cause:<br />
v Has the system run successfully before now?<br />
v Have you made any changes to the configuration of the system or added<br />
new features or programs?<br />
v Is your CLASSPATH environment variable set correctly?<br />
See “Configure your programming environment” on page 48 for<br />
information on setting CLASSPATH.<br />
The CLASSPATH is displayed at the top of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace output. See “Starting the <strong>Gateway</strong> with user-specified options” on<br />
page 132 for information on starting the <strong>Gateway</strong> daemon with tracing<br />
enabled.<br />
v Is the environment configured correctly?<br />
Refer to the documents listed under “Sample configuration documents” on<br />
page 238.<br />
v Can the Client daemon connect to the <strong>CICS</strong> server?<br />
Use the command:<br />
cicscli -s=servername<br />
followed by the command:<br />
cicscli -l<br />
If the connection is good, this command returns the name of the server you<br />
specified in servername.<br />
v Are there any messages explaining the failure?<br />
See “Messages” on page 184.<br />
v Are there any Java exceptions?<br />
See “Java exceptions” on page 192.<br />
v Does the problem occur only at certain times?<br />
© Copyright IBM Corp. 1996, 2002 183
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problem determination<br />
This might be because the system is heavily loaded at those times; See<br />
“java.lang.OutOfMemory exception” on page 193 for more information.<br />
v Can you re-create the failure?<br />
What to do next<br />
If you think the problem is with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see<br />
“Diagnosing common problems: <strong>Gateway</strong> daemon” on page 188, or<br />
“Diagnosing common problems: Client daemon” on page 203 as appropriate.<br />
Here you will find information on diagnosing common configuration and<br />
other errors, as well as advice on the documentation you need to collect in<br />
specific situations.<br />
See “Program support” on page 212 for information on how to contact IBM.<br />
See “Documenting problems” on page 213 for the information that you will be<br />
asked to provide.<br />
If you think the problem is in another product, follow the problem<br />
determination procedures provided with that product. For <strong>CICS</strong> servers, see<br />
the <strong>CICS</strong> Problem Determination Guide.<br />
Problems with the <strong>Gateway</strong> daemon<br />
Messages<br />
The <strong>Gateway</strong> daemon writes log messages to standard output (stdout) orto<br />
standard error (stderr). If <strong>Gateway</strong> daemon tracing is enabled, it also writes<br />
log messages to the trace output file.<br />
Messages have the format:<br />
CCLnnnnt: <br />
where nnnn is a number, and t is one of:<br />
I for information messages, written to standard output<br />
E for error messages, written to standard error<br />
W for warning messages, written to standard error<br />
To redirect all <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> messages to standard error,<br />
regardless of their type, you can use a command like the following:<br />
ctgstart 1>&<br />
Refer to the documentation for your operating system for more information<br />
on redirecting output.<br />
See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for an explanation of all <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> messages.<br />
184 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Tracing<br />
There are three main levels of <strong>Gateway</strong> daemon and application tracing:<br />
Stack tracing Trace entries are written only when a Java<br />
exception occurs. They can help to determine<br />
the source of the exception. Use this when it is<br />
important to maintain performance. See<br />
Figure 23.<br />
Standard tracing Java exceptions and the main <strong>Gateway</strong><br />
daemon functions and events are traced. By<br />
default, the <strong>Gateway</strong> daemon displays only<br />
the first 128 bytes of any data blocks (for<br />
example the COMMAREA, or network flows)<br />
in the trace.<br />
Debug tracing Java exceptions and the main <strong>Gateway</strong><br />
daemon functions and events are traced in<br />
greater detail than with stack or standard<br />
tracing. By default, the <strong>Gateway</strong> daemon fully<br />
outputs any data blocks in the trace. Use this<br />
only when performance is not important or if<br />
standard tracing did not give enough<br />
information to solve the problem.<br />
10:38:12:262: main:S-C: java.io.IOException<br />
10:38:12:263: main:S-C: at com.ibm.gskssl.SSLSocketImpl.socketCreate(Native Method)<br />
10:38:12:264: main:S-C: at com.ibm.gskssl.SSLSocketImpl.create(SSLSocketImpl.java:133)<br />
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:109)<br />
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:73)<br />
10:38:12:266: main:S-C: at com.ibm.ctg.server.GskSslHandler.initialize(GskSslHandler.java:487)<br />
10:38:12:266: main:S-C: at com.ibm.ctg.server.JGate.main(JGate.java:941)<br />
Figure 23. Sample Java stack trace.<br />
<strong>Gateway</strong> daemon tracing<br />
You can start tracing in the <strong>Gateway</strong> daemon process, or in the user<br />
application that makes calls to the <strong>Gateway</strong> daemon (see“Application tracing”<br />
on page 186 for more information). The following explains how to start<br />
tracing in the <strong>Gateway</strong> daemon process.<br />
Use options on the ctgstart command to enable and control tracing in the<br />
<strong>Gateway</strong> daemon. For example, to enable the standard trace, use this<br />
command when starting the <strong>Gateway</strong> daemon:<br />
ctgstart -trace<br />
To enable the debug trace, use this command:<br />
Problems with the <strong>Gateway</strong> daemon<br />
Chapter 13. Problem determination and problem solving 185
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problems with the <strong>Gateway</strong> daemon<br />
ctgstart -x<br />
If you used the configuration tool to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the<br />
default destination for trace output is the CTG.TRC file in the<br />
/bin subdirectory. Otherwise, trace output is written to stderr.<br />
You can override the default destination for trace output by using the ctgstart<br />
-tfile option. For example, the command:<br />
ctgstart -x -tfile pathname<br />
starts the <strong>Gateway</strong> daemon with debug tracing enabled and writes the trace<br />
output to the file specified by pathname.<br />
Performance considerations: Tracing, especially debug tracing, decreases<br />
performance. The following changes were made in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
version 4.0 to reduce the effect of tracing on performance:<br />
v Trace output is not written to stderr if you used the -tfile option to specify<br />
a trace output file.<br />
v Only the first line of any data block in the trace output is time-stamped.<br />
v The -truncationsize and -dumpoffset options allow you to limit the size of<br />
any data blocks that are written in the trace.<br />
v The -tfilesize option allows you to limit the size of the trace output file.<br />
For more information on starting the <strong>Gateway</strong> daemon with trace options, see<br />
“Starting the <strong>Gateway</strong>” on page 132.<br />
For more information on performance considerations, see Chapter 8,<br />
“Performance” on page 125.<br />
Application tracing<br />
You can enable tracing in the application in two ways. Either use a Java<br />
directive when you start the JVM, or add calls to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> tracing API. Use the -D option on the java command to specify Java<br />
directives. The tracing API comprises several static methods in the T class of<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See ″Tracing in Java client programs″ in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide book for further information.<br />
JNI tracing<br />
You cannot enable JNI trace through the configuration tool. Use one of the<br />
following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
where filename is the name of the file to which trace output is to be sent.<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin protocol<br />
186 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problems with the <strong>Gateway</strong> daemon<br />
handler (see “TCPAdmin protocol settings” on page 64). See “Administering<br />
your system” on page 135 for details of how to enable JNI trace<br />
dynamically.<br />
v For Java Client applications running in local mode, use Java to launch your<br />
application and set the system property gateway.T.setJNITFile, as shown in<br />
the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
J2EE Tracing<br />
Refer to “Tracing” on page 86 for information on using the tracing function<br />
provided with the ECI and EPI resource adapters.<br />
Servlet tracing and logging in WebSphere<br />
IBM WebSphere Application Server provides the Advanced Administrative<br />
Console to simplify the tasks associated with managing applications.<br />
To enable servlet tracing in WebSphere do the following:<br />
1. Configure WebSphere to send standard output and standard error to a file<br />
of your choice:<br />
In the Administrative Console, select the application server in which you<br />
want to enable tracing. Under the General tab there are text-entry boxes<br />
labelled Standard output and Standard error. You can type filenames in<br />
these boxes to override the default destinations.<br />
2. Enable tracing in the application:<br />
v For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal Servlet, use the<br />
servlet@debug property to enable tracing.<br />
For more information see “Properties and parameters reference” on<br />
page 176.<br />
v For user-written applications, use Java directives to enable tracing. You<br />
can type these in the Command line arguments box in the<br />
Administrative Console. Use the same format for Java directives as in a<br />
java command line call. For example, to enable full debug tracing, type<br />
-Dgateway.T=on as the first command line argument.<br />
See ″Tracing in Java client programs″ in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide book for further information on Java directives for<br />
tracing.<br />
Chapter 13. Problem determination and problem solving 187
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Problems with the <strong>Gateway</strong> daemon<br />
3. Click on the Apply button, to update the WebSphere settings, and run the<br />
servlet.<br />
When a servlet runs, WebSphere writes logging information to the same<br />
destination as standard output. This information includes start times, stop<br />
times, and any error messages. For the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Terminal<br />
Servlet, use the servlet@extendedLogging property to enable extended<br />
logging. If you enabled extended logging, the Terminal Servlet writes to the<br />
log every time it receives a request. This can provide useful information for<br />
diagnosing problems but it reduces performance.<br />
You can enable both tracing, and extended logging, while the Terminal Servlet<br />
is running. For more information on Terminal Servlet properties see<br />
“Properties and parameters reference” on page 176.<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
Problems running the configuration tool<br />
Task Guide loses focus<br />
Under some JVMs on the Windows and UNIX operating systems, you<br />
might have problems when entering the name for a new server in the<br />
Task Guide. If the text box loses focus after each key press, click the Next<br />
button to move onto the next panel and then click the Back button to<br />
return. You should now be able to input text normally. This is a JVM<br />
problem.<br />
Task Guide restrictions under UTF8 and IBM-eucJP locales<br />
The Task Guide does not run correctly under the UTF8 and IBM-eucJP<br />
locales on the AIX, HP-UX and Solaris operating systems. Table 10 shows<br />
the combination of platforms, locales and JREs affected:<br />
Table 10.<br />
Platform Locale JRE Notes<br />
AIX UTF8<br />
IBM-eucJP<br />
IBM 1.3 —<br />
HP-UX UTF8 HP-UX See the HP-UX JRE<br />
release notes on<br />
supported locales.<br />
Solaris UTF8 1.3 —<br />
Chinese, Japanese or Korean characters do not display correctly<br />
To display Chinese, Japanese or Korean characters correctly on the<br />
Windows operating system, set the system locale to Chinese, Japanese or<br />
188 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
Korean. If characters still do not display correctly, install the relevant<br />
world type font package. You can download world type font packages<br />
from the following site:<br />
http://www.ibm.com/developerworks/java/jdk/linux130/<br />
The <strong>Gateway</strong> daemon fails to find Turkish configuration settings<br />
When you run the configuration tool under a Turkish locale for the first<br />
time, by default the configuration settings are saved in file CTG.INI.ini.<br />
Rename the file to CTG.INI to allow the <strong>Gateway</strong> daemon to find the<br />
settings automatically. You only have to do this once, when the<br />
configuration tool is first run.<br />
The configuration tool fails to launch under Turkish and the Solaris 1.3.0<br />
JVM<br />
This is a known problem with the Solaris 1.3.0 JVM and has been raised<br />
under SunBugs 4380798 and 4346718. A workaround is detailed under<br />
SunBug 4380798 in the Sun Java Bug Database; to access this, go to<br />
http://java.sun.com/, follow the link to Online Support and search the<br />
Bug Database for 4380798.<br />
Problems running the configuration tool in Turkish under the HP-UX JREs<br />
Running the tool under HP-UX JRE 1.3 results in messages saying that<br />
fonts are not found. Despite this, Turkish characters display correctly.<br />
Codepage problems<br />
A <strong>Gateway</strong> daemon trace shows the codepage in which the JVM is running. It<br />
is displayed in the System Properties section at the top of the trace. Refer to<br />
Appendix A, “Data conversion when using the Client daemon and a <strong>CICS</strong><br />
server” on page 225 for information on finding the codepage that the Client<br />
has sent to the server.<br />
If a process locks<br />
To determine where the lock is happening, enable tracing in the application,<br />
in the <strong>Gateway</strong> daemon, and in the Client daemon. See “Tracing” on page 185<br />
for information on tracing the <strong>Gateway</strong> daemon and the application. See<br />
“Tracing” on page 195 for information on tracing the Client daemon, and<br />
“Diagnosing common problems: Client daemon” on page 203 for information<br />
on how to determine whether the lock is in the Client daemon or the server. If<br />
the lock is in the <strong>Gateway</strong> daemon, contact your IBM support organization<br />
and provide them with the <strong>Gateway</strong> daemon trace.<br />
See “The Client daemon stops responding” on page 206, for information on<br />
what to do if the Client daemon is not responding.<br />
AIX: On some Java Virtual Machine (JVM)s you can force Java to write a<br />
stack dump showing the states of the current threads. For example, on IBM<br />
Java SDK 1.3 you can send a SIGQUIT (-3) signal to a Java process to make it<br />
Chapter 13. Problem determination and problem solving 189
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
write a stack dump to stderr. This shows the states of the current threads. Do<br />
not do this on a working production system but only on a system which is<br />
completely locked.<br />
Linux: The Linux threading model uses a separate process for each thread.<br />
When a terminal-based application is sent a terminal interrupt signal, for<br />
example when a user types CTRL+C, each process receives this signal. This<br />
means that each thread tries to stop at the same time. Sometimes the Linux<br />
threading model cannot handle this, and one or more threads, or processes,<br />
hangs.<br />
To remove them, issue the command<br />
kill -9 <br />
where is the ID of the process that has hung.<br />
<strong>Gateway</strong> daemon running on in-use Solaris 8 ports<br />
On Solaris 8 it is possible to open a handler on an IP port that is being used<br />
by another system server process, such as FTP or Telnet. This is a known<br />
problem with Solaris 8 and Java; see Sunbug ID 4511442.<br />
SSL problems<br />
In general: Enable stack tracing in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. This will<br />
show you what was happening when the exception occurred. It will also give<br />
you information about the configuration, such as the value of the<br />
CLASSPATH variable. If this does not give you enough information to<br />
diagnose the problem, obtain a standard trace and contact your IBM support<br />
organization.<br />
SSLight:<br />
When starting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: The following message is issued<br />
when starting the <strong>Gateway</strong>:<br />
CCL6525W: Unable to start handler for the ssl: protocol.<br />
[java.lang.ClassNotFoundException:<br />
server KeyRing class name]<br />
This message shows that the <strong>Gateway</strong> could not load the server KeyRing<br />
class. Start the <strong>Gateway</strong> with stack tracing enabled. Check that the<br />
CLASSPATH variable, which is displayed at the top of the trace output,<br />
includes an entry for the directory that contains the class. Also check that the<br />
CLASSPATH includes an entry for file cfwk.zip. If the <strong>Gateway</strong> cannot find<br />
this file, it cannot load the KeyRing files.<br />
You specify the name of the server KeyRing class in the KeyRing classname<br />
field in the SSL protocol settings panel in the configuration tool. Do not<br />
190 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
include the directory or file extension when you specify the KeyRing class<br />
name. The CLASSPATH should include an entry for the directory that<br />
contains the KeyRing class.<br />
In a user application: The API call<br />
SslJava<strong>Gateway</strong>.setKeyRing("ClientKeyRingName", "thePassword"); fails with<br />
the following error in a user application:<br />
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing<br />
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This<br />
file is supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
JSSE:<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore name to<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, but the class does not load, or cannot be found,<br />
the <strong>Gateway</strong> daemon assumes that you are using JSSE and not SSLight.<br />
iKeyMan locks with ″class not found″ exception: A message like the following is<br />
received by the application:<br />
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException<br />
This happens if the IBM Java Cryptography Extension (JCE) package is not<br />
installed. Ensure that you have installed the JCE supplied with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> in the ibm-jce.zip file. See “Installation” on page 104.<br />
Application receives an ″access denied″ exception: A message like the following is<br />
received by the application:<br />
java.io.IOException: CCL6651E: Unable to connect to the <strong>Gateway</strong>.<br />
[address = killerb2b, port = 8050]<br />
[java.security.AccessControlException: access denied<br />
(java.io.FilePermission \jssekeys\testclient.jks read)]<br />
This happens if your application does not have permission to read from the<br />
file system containing the keystore. See Using ECI, EPI, and ESI with a Java 2<br />
Security Manager, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, for more<br />
information.<br />
KeyStore name not recognized: Java interprets the back slash (\) character as a<br />
parameter delimitter. If you used the back slash character as a directory<br />
separator when entering the path name of the KeyStore file during<br />
configuration, Java cannot recognize the name. Use either a forward slash (/)<br />
character, or double back slash (\\) characters, as a separator in the path<br />
name on all operating systems. For example:<br />
/mykeys/jsse/keystore.jks<br />
\\mykeys\\jsse\\keystore.jks<br />
Chapter 13. Problem determination and problem solving 191
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
Java exceptions<br />
If the application or the <strong>Gateway</strong> daemon does not handle an exception, then<br />
the Java Virtual Machine (JVM) will write a Java stack dump. The destination<br />
for the dump output depends on your JVM implementation; check your Java<br />
documentation for more information.<br />
Disable the Just-In-Time (JIT) compiler to increase the information written to<br />
the Java stack dump. This information might include the line of Java source<br />
code where the exception happened. How you disable the JIT compiler<br />
depends on your JVM implementation; check your Java documentation for<br />
more information.<br />
Figure 24 shows a sample Java stack dump taken with the JIT compiler<br />
disabled.<br />
Exception in thread "main" java.lang.OutOfMemoryError<br />
at java.lang.Thread.start(Native Method)<br />
at com.ibm.ctg.server.ThreadManager.createObject(ThreadManager.java:345)<br />
at com.ibm.ctg.server.ThreadManager.(ThreadManager.java:131)<br />
at com.ibm.ctg.server.ManagedResources.(ManagedResources.java:106)<br />
at com.ibm.ctg.server.JGate.main(JGate.java:895)<br />
Figure 24. Sample Java stack dump<br />
If the <strong>Gateway</strong> daemon handles an exception, a Java stack dump is written<br />
only if tracing is enabled. Try to re-create the problem with tracing enabled.<br />
This should help to show you what was happening before the exception<br />
occured. See “Tracing” on page 185 for more information on tracing.<br />
Using a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same workstation:<br />
If you intend to use a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same<br />
workstation, remove ctgclient.jar and ctgserver.jar from the CLASSPATH<br />
setting. If you do not remove them, you are likely to receive the following<br />
error when running applications:<br />
ERROR: java.io.IOException:<br />
CCL6664E: Unable to load relevant class to support the tcp protocol<br />
The reason for the error is that Java searches the CLASSPATH environment<br />
variable before downloading classes across the network. If the required class<br />
is local, Java attempts to use it. However, using class files from the local file<br />
system breaks Java application security rules; therefore an exception is raised.<br />
Java security exceptions<br />
A message like the following is issued when using the ECI or EPI interfaces in<br />
a Java 2 Security Manager environment:<br />
java.security.AccessControlException: access denied (java.util.PropertyPermission * read,write)<br />
192 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
This might mean that your application program is trying to perform a task<br />
that is protected by the Security Manager. Refer to ″Using ECI and EPI with a<br />
Java 2 Security Manager″, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, for<br />
information on security permissions required by programs running in this<br />
environment.<br />
java.lang.OutOfMemory exception<br />
If this happens after the <strong>Gateway</strong> daemon has been running for a long time,<br />
then it could be caused by a memory leak. If it happens only when the<br />
<strong>Gateway</strong> daemon is heavily loaded, then there might be too many threads<br />
active for the available Java Virtual Machine (JVM) memory.<br />
Memory leak: Run a memory usage monitor against the <strong>Gateway</strong> daemon<br />
process. If there is a memory leak, the amount of memory used by the<br />
<strong>Gateway</strong> daemon increases over time. Make sure that all user applications<br />
that connect to the <strong>Gateway</strong> daemon close the Java<strong>Gateway</strong>() connection<br />
object when they have finished using it. If this does not resolve the problem,<br />
run the <strong>Gateway</strong> daemon debug trace and contact your IBM support<br />
organization. You can use the ctgstart -tfilesize option to limit the size of the<br />
trace output file. You can also use the ctgstart -truncationsize option to reduce<br />
to zero the size of any data blocks that will be displayed in the trace. This will<br />
reduce the effect on performance.<br />
Too many threads: You can estimate the amount of virtual memory that is<br />
required by the JVM as follows. Add together:<br />
v the number of Connection Manager threads<br />
v the number of Worker threads<br />
v the number of background threads in use by Java<br />
v the number of different network protocols in use<br />
Then multiply this total by the size of the Java stack allocated to each thread<br />
by the JVM.<br />
In this calculation, assume that the number of active Java background threads<br />
is about five. Refer to your Java documentation for a more accurate value. You<br />
set the maximum numbers of Connection Manager threads and Worker<br />
threads when you configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See “General<br />
<strong>Gateway</strong> settings” on page 53 for more information.<br />
The way that Java allocates memory depends on your JVM implementation.<br />
Most JVMs allow you to control memory allocation by setting limits on the<br />
sizes of the Java stack and the Java heap.<br />
For more information on thread limits see Table 3 on page 17. For more<br />
information on Java memory allocation refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide and to your Java documentation.<br />
Chapter 13. Problem determination and problem solving 193
|<br />
|<br />
|<br />
Diagnosing common problems: <strong>Gateway</strong> daemon<br />
On z/OS and UNIX operating systems the amount of memory available to<br />
each process might be limited. See your operating system documentation for<br />
more information.<br />
Programs using beans included in earlier versions of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
See “EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>”<br />
on page 224 for information on beans that are now provided only as sample<br />
programs.<br />
Problems with the Client daemon<br />
Messages<br />
There are two types of message in the Client daemon:<br />
1. Messages displayed to the user<br />
2. Errors written to the Client daemon error log and trace file.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages book explains all of these<br />
messages.<br />
Error log messages<br />
Any errors on the client workstation that are not caused by incorrect use of<br />
the API are written to the Client daemon error log.<br />
The error log (which has a default name of <strong>CICS</strong>CLI.LOG) is an ASCII text file<br />
that you can browse using a standard text editor.<br />
Help information for all messages is provided in two ASCII text files in the<br />
/bin subdirectory. You can view these using any standard text<br />
editor:<br />
CCLMSG.HLP Help for the end user messages, in the<br />
language you chose at installation time.<br />
CCLLOG.HLP Help for the trace and log messages. This is<br />
provided in English only.<br />
Errors resulting from incorrect use of the APIs simply result in error return<br />
codes to the application. It is the responsibility of the application to notify the<br />
end user of the error and provide guidance on corrective actions.<br />
Console messages<br />
Errors generated from within the Client daemon are displayed on the system<br />
console There may be times when you do not want messages (client error and<br />
security) to appear on the console; for example, if you leave the Client<br />
daemon running unattended overnight. To disable the display of console<br />
messages, enter the following command:<br />
194 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
cicscli -n<br />
Problems with the Client daemon<br />
When the display of console messages is disabled, the messages are still<br />
written to the Client daemon error log. To re-enable the display of console<br />
messages, enter the following command.<br />
cicscli -e<br />
You can specify the -n parameter together with the -s parameter. The display<br />
of console messages is enabled by default.<br />
Messages from the Client daemon process<br />
Messages from the the Client daemon process are sent to the system console<br />
(/dev/console).<br />
On the AIX operating system you can redirect these messages by using the<br />
swcons command.<br />
Tracing<br />
The Client daemon tracing is a very useful problem determination tool for<br />
communication problems. You can use the trace functions to collect detailed<br />
information on the execution of a certain function or transaction. A trace can<br />
show you how the execution of a particular activity is affected by, for<br />
example, the execution of other tasks in a <strong>CICS</strong> system. Each trace entry has a<br />
time stamp, which provides information on the time taken to perform certain<br />
activities.<br />
You can specify which components of the Client daemon you want to trace.<br />
You control this with the cicscli -m command, (see “cicscli command<br />
reference” on page 145), or by specifying a list of components using the<br />
configuration tool.<br />
The output from the trace function is a binary trace file called, by default,<br />
<strong>CICS</strong>CLI.BIN in the /var/cicscli subdirectory. You can specify a different<br />
name for this file, using the configuration tool. However, you cannot change<br />
the .BIN extension. Using the Maximum Client wrap size configuration<br />
setting, you can specify that the binary trace file should wrap into a second<br />
trace file, and you can also specify the maximum size of these files.<br />
To read the trace, run the cicsftrc utility to convert the binary file or files<br />
into a text file. This text file is called <strong>CICS</strong>CLI.TRC by default. The default trace<br />
files are:<br />
<strong>CICS</strong>CLI.BIN The binary trace file produced by running the<br />
Client daemon trace.<br />
<strong>CICS</strong>CLI.WRP The second binary trace file if wrapping of<br />
client trace is enabled.<br />
Chapter 13. Problem determination and problem solving 195
Problems with the Client daemon<br />
<strong>CICS</strong>CLI.TRC The name of the text trace file produced when<br />
the binary trace file is converted to a text file<br />
using the cicsftrc utility.<br />
<strong>CICS</strong>CLI.BAK The backup file of the binary trace file. A<br />
backup file is produced from any existing<br />
.BIN file when you turn tracing on.<br />
See “Formatting the binary trace file” on page 197 for information on the trace<br />
conversion utility.<br />
Starting and stopping Client daemon tracing<br />
To start Client daemon tracing, enter the cicscli command with the -d option,<br />
for example:<br />
cicscli -d=nnn<br />
where nnn is optional, and is the maximum size in bytes of the data areas to<br />
be traced. (The default value is 512.)<br />
Note: It is recommended that you set at least -d=1000 to ensure that all<br />
relevant data is included in the trace before sending it to your support<br />
organization.<br />
If you need to trace the Client daemon immediately from startup, you can<br />
specify the -s and -d parameters together in the same cicscli command. For<br />
example, the following command starts the connection to a <strong>CICS</strong> server with<br />
the name <strong>CICS</strong>TCP, enables the trace function, and sets the maximum data<br />
area size to be traced to 128 bytes:<br />
cicscli -s=<strong>CICS</strong>TCP -d=128<br />
You can specify which components are to be traced when you start tracing.<br />
See “cicscli command reference” on page 145 for details.<br />
To stop Client daemon tracing, enter the cicscli command with the -o option,<br />
for example:<br />
cicscli -o<br />
The trace is also automatically stopped if you stop the Client daemon by<br />
using the cicscli -x command.<br />
Choosing which components to trace<br />
ALL This option traces everything. It is the<br />
preferred option; use it if performance allows,<br />
and consider using the binary formatting tool<br />
to filter information. See “Formatting the<br />
binary trace file” on page 197 for details.<br />
196 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Problems with the Client daemon<br />
API.1 and API.2 These trace the boundary between the user<br />
application or Java classes, and the Client<br />
daemon. Switching on API.2 automatically<br />
switches on API.1 as well.<br />
DRV.1 and DRV.2 The protocol drivers trace the boundary<br />
between the Client daemon and the network<br />
protocol. Specify the DRV.1 and API<br />
components if you are not sure whether a<br />
problem is inside the Client daemon, and you<br />
want to minimize the impact on performance,<br />
for example when trying to determine a<br />
performance problem.<br />
You can also specify these components to help<br />
to determine which product is causing the<br />
system to lock up.<br />
CCL This component traces the main Client<br />
daemon process. Specify the API and CCL<br />
components if you believe that the problem is<br />
within the Client daemon.<br />
TRN The TRN component traces the internal<br />
interprocess transport between Client<br />
processes. Use it if entries in the Client log<br />
refer to functions such as FaarqGetMsg,<br />
FaarqPutMsg, or FaarqStart. TRN is the most<br />
verbose tracing component.<br />
Wrapping the Client daemon trace<br />
You can control the size of the binary trace file by specifying that it wraps<br />
into a second trace file. You turn on wrapping of trace using the Maximum<br />
Client wrap size configuration setting, where you specify the maximum size<br />
of the wrapping trace (in kilobytes). If this value is 0 (the default), wrapping<br />
trace is not turned on.<br />
When wrapping trace is turned on, two files (called <strong>CICS</strong>CLI.BIN and<br />
<strong>CICS</strong>CLI.WRP) are used. Each file can be up to half the size of the Maximum<br />
Client wrap size value.<br />
Formatting the binary trace file<br />
You use the Binary Trace Formatter utility cicsftrc to convert the binary trace<br />
file <strong>CICS</strong>CLI.TRC to ASCII text. The utility has the following parameters:<br />
-m=list of components<br />
Specifies that only trace points from the listed components are written to<br />
Chapter 13. Problem determination and problem solving 197
Problems with the Client daemon<br />
the text file. The components you can specify are the same as for cicscli<br />
-m. If -m is not specified, all trace points in the binary trace are written to<br />
the text file.<br />
-w[=filename]<br />
Indicates that there are two binary trace files to format and then<br />
concatenate (that is, the binary files were created with a wrapping trace).<br />
If no filename is specified with the -w parameter, cicsftrc assumes that<br />
the name of the second trace file is <strong>CICS</strong>CLI.WRP.<br />
-n Indents entry and exit points in the test trace file to make it more<br />
readable. By default, indentation is turned off.<br />
-d Specifies detailed trace formatting. If you are using EPI calls, <strong>CICS</strong>TERM<br />
or <strong>CICS</strong>PRINT, an approximation of the screen layout will be included in<br />
the trace.<br />
-i=filename<br />
Specifies the name of the input (binary) trace file, which is <strong>CICS</strong>CLI.BIN by<br />
default.<br />
-o=filename<br />
Specifies the name of the output (text) trace file. If no -o parameter is<br />
specified, the name of the text trace file is assumed to be <strong>CICS</strong>CLI.TRC.<br />
-f Overwrite any existing files.<br />
-s Do summary trace formatting. Summary trace formatting is driven from a<br />
text file (CCLSUMTR.TXT) which is read in at initialization time. This<br />
defines the set of trace points for which you want summary tracing, and<br />
the type of trace point. As DetailFormat reaches each trace point, if it is<br />
one of the ones read in from this file, a line is generated in the summary<br />
file. Use as requested by your IBM support organization; see “Program<br />
support” on page 212.<br />
The formatter can produce a summary of API calls that the user program<br />
makes, and show the progress of the calls through the Client daemon. Specify<br />
the API.2 component to produce a summary trace. Figure 25 on page 199<br />
shows an example. (The layout of your trace may be different, depending on<br />
the contents of CCLSUMTR.TXT.)<br />
198 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
-->Sample of API summary trace taken with API.2 and DRV options.<br />
[Process ,Thread ] Time ▌API Summary▐ ▌CCLCLNT▐ Summary ▌Comms Summary▐<br />
=============================================================================================================<br />
...<br />
...<br />
...<br />
[000000bf,0000017c] 12:08:32.190 --->[7315] CCL3310 ECI Call type ECI_SYNC, UOW=0<br />
[00000089,000000a4] 12:08:32.290 ▌-S->▐[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=89<br />
[000000bf,0000017c] 12:08:32.330 [7391] CCL1040 using slot = Slotp->Ctrl.ConvId = 6<br />
[000000bf,0000017c] 12:08:32.350 [7099] CCL1037 Sync ECI call, so waiting for a reply...<br />
[00000089,00000063] 12:08:32.400 ▌[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,000000a4] 12:08:32.551 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94<br />
[00000089,00000168] 12:08:32.581
Problems with the Client daemon<br />
Command = Erase/Write, so clearing main screen<br />
Command2 = Read Modified<br />
WCC = 0x32 ( Free Kbd,80 char)<br />
Set Buffer Address to (1,2)<br />
Insert Cursor @ (1,2)<br />
Set Buffer Address to (1,1)<br />
Start Field Extended (Unprotected,Alphanumeric,Display,not-pen-detectable,Foreground Colour Green)<br />
Data:’’<br />
Insert Cursor @ (1,3)<br />
Set Buffer Address to (2,1)<br />
Data : ’User ’<br />
.....<br />
.....<br />
.....<br />
.....<br />
Set Buffer Address to (24,49)<br />
Start Field Extended (Autoskip (Prot+Num),Display,not-pen-detectable,Foreground Colour Turquoise)<br />
Data : ’9’<br />
Set Buffer Address to (24,51)<br />
Start Field Extended (Unprotected,Alphanumeric,Intense,pen-detectable,Foreground Colour Red)<br />
Data : ’Messages ’<br />
1 2 3 4 5 6 7 8<br />
12345678901234567890123456789012345678901234567890123456789012345678901234567890<br />
>+----------------------------------------------------------------------------------+<br />
01| - |<br />
02| uSTATUS. . :uEnter one of the following: |<br />
03| u |<br />
04| uABend EXtract READPrev WAit |<br />
05| uADdress FEpi READQ WRITE |<br />
06| uALlocate FOrmattime RECeive WRITEQ |<br />
07| uASKtime FREE RELease Xctl |<br />
08| uASSign FREEMain RESetbr |<br />
09| uBif Getmain RETRieve |<br />
10| uCAncel Handle RETUrn |<br />
11| uCHange IGnore REWrite |<br />
12| uCONNect INquire SENd |<br />
13| uCONVerse ISsue SET |<br />
14| uDELAy LInk SIGNOFf |<br />
15| uDELETE LOad SIGNON |<br />
16| uDELETEQ PErform START |<br />
17| uDEQ POP STARTBr |<br />
18| uDUmp POSt SUspend |<br />
19| uENDbr PUsh SYncpoint |<br />
20| uENQ READ Unlock |<br />
21| uENTer READNext Verify |<br />
22| u |<br />
23| uPFu1-Help u2-HEX u3-End u4-EIB u5-Variables |<br />
24| u6-User u9-Messages |<br />
+----------------------------------------------------------------------------------+<br />
| 1BþC000 SKNIGHTS |<br />
+----------------------------------------------------------------------------------+<br />
12345678901234567890123456789012345678901234567890123456789012345678901234567890<br />
1 2 3 4 5 6 7 8<br />
Figure 26. Screen capture from a formatted trace file<br />
200 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
Problems with the Client daemon<br />
The formatter lists the commands which built the screen, and shows an<br />
approximation of the screen.<br />
In <strong>Version</strong> <strong>5.0</strong> of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the Binary Trace Formatter utility<br />
has been enhanced to format SNA and MPTN data structures within TCP62<br />
data flows.<br />
Client daemon trace analysis<br />
The Client daemon trace file records detailed information on all actions taken<br />
during the execution of a particular activity. You can use this information in<br />
your problem determination activities, and to help understand how the Client<br />
daemon performs a particular function, for example, establishing a connection<br />
to a <strong>CICS</strong> server.<br />
If you cannot interpret the trace yourself, you should contact your IBM<br />
support organization and forward the unformatted binary trace file.<br />
Some sample traces are shown in “Sample Client daemon trace” on page 202.<br />
Format of trace entries<br />
The entries in the Client daemon trace file have the following format:<br />
time [process id,thread id] [number] component trace message<br />
data<br />
where:<br />
time<br />
The time the entry was written, to millisecond accuracy.<br />
[process id, thread id]<br />
Process id is a unique number that the operating system uses to identify a<br />
process. Thread id is a unique number that the operating system uses to<br />
identify a thread within a particular process.<br />
[number]<br />
A number to aid your support organization in the diagnosis of serious<br />
problems.<br />
[component]<br />
The component of the product to which this entry applies.<br />
trace message<br />
The trace message number and text. These trace messages are explained in<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages.<br />
data<br />
Some trace entries include a dump of key data blocks in addition to the<br />
trace message.<br />
Chapter 13. Problem determination and problem solving 201
Problems with the Client daemon<br />
Sample Client daemon trace: Figure 27 shows the trace information recorded<br />
during the successful connection of a Client daemon to a <strong>CICS</strong> server using<br />
the TCP/IP protocol. The trace was generated using the commands:<br />
cicscli -s=cicstcp -d<br />
cicscli -o<br />
The trace was generated for an AIX Client daemon but is applicable to other<br />
Client daemons.<br />
17:03:57.580 [0000080c,00000908] [1007] TRC:▌CCL1042▐ *** <strong>CICS</strong> Client for AIX v<strong>5.0</strong> Service Level 00 - service trace started ***<br />
17:03:57.590 [0000080c,00000908] [2183] CCL:▌CCL2048▐ Maximum trace data size set to 512<br />
17:03:57.600 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:03:58.612 [0000080c,00000908] [2030] CCL:CCL2106 Comms Event : LINK-UP<br />
17:03:58.622 [0000080c,00000908] [2019] DRV:CCL2055 Connection with server established (linkID=1)<br />
17:03:58.622 [0000080c,00000908] [2035] CCL:CCL2109 Send server TCS data<br />
17:03:58.632 [0000080c,00000908] [3214] CCL:▌CCL3251▐ Comms Allocate request (LinkId=1, Tran=’CCIN’)<br />
17:03:58.632 [0000080c,00000908] [3217] CCL:▌CCL3238▐ Comms Allocate completed (LinkId=1, ConvId=1, Rc=0)<br />
17:03:58.632 [0000080c,00000908] [2127] CCL:CCL2143 CommsBegin - OK<br />
17:03:58.632 [0000080c,00000908] [3100] CCL:▌CCL3113▐ CCIN install request: ApplId=’* ’, Codepage=819<br />
...<br />
...<br />
...<br />
17:04:00.625 [0000080c,00000908] [3102] CCL:▌CCL3114▐ CCIN install response: ApplId=’@0Z8AAAA’, Codepage=8859-1, Rc=0<br />
17:04:00.625 [0000080c,00000908] [3241] CCL:CCL3255 Comms Complete request (ConvId=1)<br />
17:04:00.635 [0000080c,00000908] [3244] CCL:CCL3246 Comms Complete completed (ConvId=1, Rc=0)<br />
17:04:00.635 [0000080c,00000908] [3218] CCL:CCL3252 Comms Deallocate request (ConvId=1)<br />
17:04:00.645 [0000080c,00000908] [3221] CCL:CCL3239 Comms Deallocate completed (ConvId=1, Reason=0, Rc=0)<br />
17:04:00.645 [0000080c,00000908] [2042] CCL:CCL2114 Processed TCS Reply - Server connected<br />
17:04:00.645 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:04:00.655 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
17:04:00.664 [0000080c,00000908] [1004] TRC:▌CCL1043▐ *** Service trace ended ***<br />
Figure 27. Sample Client daemon trace<br />
Message ID Explanation<br />
CCL1042 Start of trace message. The trace file is overwritten each time a<br />
trace is started. You can delete the file when required. Check<br />
the date and time stamp to ensure that you are reading the<br />
correct trace.<br />
CCL2048 Maximum trace data size is at the default size of 512 bytes.<br />
You can modify this size by specifying the size value in the<br />
start command for the client trace (see “Starting and stopping<br />
Client daemon tracing” on page 196).<br />
CCL3251 The client sends a CCIN transaction to the server to install its<br />
connection definition on the server.<br />
CCL3238 Reply to message CCL3238, includes the conversation ID for<br />
this conversation.<br />
CCL3113 The client sends a CCIN transaction to the server with Appl<br />
ID set to * to install its application. The Appl ID is specified in<br />
202 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
the configuration file as Client=*. This requests the server to<br />
dynamically generate an Appl ID that is unique within the<br />
<strong>CICS</strong> server system.<br />
CCL3114 This is the response to message CCL3114 with the<br />
dynamically generated Appl ID.<br />
CCL1043 End of trace message.<br />
Figure 28 shows trace information recorded when we tried to connect to a<br />
<strong>CICS</strong> server over TCP/IP using an invalid port number. The port number<br />
specified in the CTG.INI file was not defined in the services file of the server.<br />
Hence, the connection could not be established.<br />
16:16:41.562 [0000093c,000008ec] [1007] TRC:CCL1042 *** <strong>CICS</strong> Client for Windows v<strong>5.0</strong> Service Level 00 - service trace started ***<br />
16:16:41.572 [0000093c,000008ec] [2183] CCL:CCL2048 Maximum trace data size set to 512<br />
16:16:41.582 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds<br />
16:16:41.612 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is -1 seconds<br />
16:16:41.622 [0000093c,000008ec] [3207] CCL:CCL3429 Comms Open request (Server=<strong>CICS</strong>TCP, Driver=CCLIBMIP)<br />
16:16:41.622 [0000093c,000008ec] [4408] DRV:CCL4413 ▌CCL4413▐ TCP/IP (to <strong>CICS</strong>TCP) address=192.113.36.200, ▌port=1089▐, socket=3<br />
16:16:41.622 [0000093c,000008ec] [3210] CCL:CCL3236 Comms Open completed (Server=<strong>CICS</strong>TCP, LinkId=1, Rc=0)<br />
16:16:41.633 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 3660 seconds<br />
16:16:41.633 [0000093c,000008ec] [1004] TRC:CCL1043 ***Service trace ended ***<br />
Figure 28. Client daemon trace: using an invalid port number<br />
Problems with the Client daemon<br />
Message ID Explanation<br />
CCL4413 Shows the port number used for this connection request.<br />
You must check your definitions in the SIT on the server, the configuration file<br />
on the workstation, and the services file for the port number specified.<br />
You must provide a valid port number or use the default value.<br />
Diagnosing common problems: Client daemon<br />
This section provides information to help you solve some common problems<br />
with the Client daemon. The problems are discussed under the following<br />
headings:<br />
v “Starting clients and terminals” on page 204<br />
v “TCP/IP communication problems” on page 204<br />
v “APPC communication problems” on page 205.<br />
v “TCP62 communication problems” on page 205<br />
v “Traps” on page 206<br />
v “The Client daemon stops responding” on page 206<br />
This section lists problems for all supported operating systems, to provide for<br />
cases where client and server are on different operating systems.<br />
For information on error messages, refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong><br />
Messages.<br />
Chapter 13. Problem determination and problem solving 203
Diagnosing common problems: Client daemon<br />
Starting clients and terminals<br />
The following are solutions to problems that can occur when starting clients<br />
and terminals:<br />
A cicsterm request has gone to the wrong server<br />
If you do not specify the -s=servername option on the cicsterm command, the<br />
Client daemon sends a cicsterm request to either of:<br />
v the default server<br />
v the first server listed in the configuration file<br />
even if it is not yet activated. The servername should be as specified in the<br />
configuration file.<br />
Problems loading protocol drivers<br />
The message ″Cannot load protocol driver″ in the <strong>CICS</strong>CLI.LOG file means that<br />
you are trying to use a protocol driver that does not exist. Check your<br />
CTG.INI file to make sure that the driver name is correct, and is supported in<br />
this release.<br />
The Client daemon can connect to the server, but cicsterm cannot<br />
In other words, cicscli -s=servername connects successfully, but cicsterm<br />
-s=servername does not. Check the following:<br />
v Is the CTIN transaction defined on the server?<br />
v Does cicsterm-a successfully install a terminal that is not signon capable?<br />
cicsterm attempts to install a signon capable terminal by default. If the -a<br />
option works, the server probably does not support signon capable<br />
terminals.<br />
<strong>CICS</strong> servers require APAR fixes to support terminal signon capability; see<br />
“Supported software” on page 23. Refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
README file for the latest details and check the PTFs for the <strong>CICS</strong> servers.<br />
See “APARs and fixes” on page 215 for general information about APARs.<br />
TCP/IP communication problems<br />
The following are solutions to problems that can occur when communicating<br />
over TCP/IP:<br />
Message CCL4404 TCP/IP (to ’<strong>CICS</strong>TCP’) unable to resolve name: RC=2<br />
204 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> server, in this example <strong>CICS</strong>TCP, could not be resolved by the<br />
TCP/IP protocol driver. Ensure that your domain name server and router<br />
address information is correct, and that any names and IP addresses in the<br />
TCP/IP ETC/HOSTS file are correct.<br />
Use the TCP/IP ping or nslookup commands to see if TCP/IP can resolve the<br />
hostname.<br />
APPC communication problems<br />
The following are solutions to problems that can occur when communicating<br />
over APPC:<br />
CCIN not recognized, CTIN not recognized<br />
The CCIN transaction installs your Client daemon definition on the <strong>CICS</strong><br />
server. The CTIN transaction installs your client terminal definition on the<br />
<strong>CICS</strong> server. These transactions must be available on the <strong>CICS</strong> server if it<br />
supports the EPI, because the EPI implies <strong>CICS</strong> 3270 terminal emulation and<br />
<strong>CICS</strong> 3270 printer emulation. For information on which <strong>CICS</strong> servers support<br />
EPI and hence <strong>CICS</strong> 3270 emulation, see Table 5 on page 28. You can ignore<br />
these messages if your <strong>CICS</strong> server does not support the EPI.<br />
A cicsterm command for a mainframe <strong>CICS</strong> server failed<br />
cicsterm and cicsprnt use <strong>CICS</strong> 3270 emulation. Some mainframe <strong>CICS</strong> servers<br />
do not support <strong>CICS</strong> 3270 emulation. For information on which <strong>CICS</strong> servers<br />
support <strong>CICS</strong> 3270 emulation, see Table 5 on page 28.<br />
Solaris: Cannot load protocol driver ’CCLIBMSN’ message<br />
No SNA driver is provided in this release. This message in your <strong>CICS</strong>CLI.LOG<br />
file indicates that you are still trying to use SNA. Reconfigure your CTG.INI<br />
file to use the TCP62 driver instead.<br />
SNA error log: The SNA error log can help your support organization to<br />
diagnose problems. The path to the file, if the product is installed to its<br />
default location, on AIX is as follows: /var/sna/sna.err<br />
TCP62 communication problems<br />
Diagnosing common problems: Client daemon<br />
CCL5820 TCP62: Attempt to open server ’server1’ which is a<br />
duplicate of ’server2’<br />
Multiple server definitions with identical combinations of Local LU, Partner<br />
LU, and Mode name are not permitted in CTG.INI in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>. This ensures that every connection that the <strong>CICS</strong> region<br />
Chapter 13. Problem determination and problem solving 205
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems: Client daemon<br />
and the network protocol see is represented by a unique server definition in<br />
the configuration file. Existing Client applications that use different server<br />
names to send requests to the same <strong>CICS</strong> region continue to work if a user<br />
exit is defined to redirect requests. A sample user exit that does this is<br />
provided; see /samples/samples.txt.<br />
Traps<br />
AIX<br />
If the Client daemon, or a user application terminates unexpectedly, it<br />
may produce a core dump. You can get stack traces by attaching dbx to<br />
the core dump. The procedure is similar to attaching dbx to a running<br />
process—see “dbx tool” on page 207 for details. Consult your AIX<br />
documentation for full details.<br />
When you attach dbx to the core dump you might get errors saying that<br />
the data is truncated. If so, check the following:<br />
v That there is enough space in the file system for the core dump<br />
v That userid settings do not limit the size of the core dump<br />
The Client daemon stops responding<br />
This section discusses what to do if you think the Client daemon has stopped<br />
responding, for example because:<br />
v API, ECI and EPI calls do not complete, or<br />
v cicsterm hangs<br />
Check that your <strong>CICS</strong> <strong>Transaction</strong> Server is working correctly, for example by<br />
looking at the <strong>CICS</strong> log. Insufficient storage on the <strong>CICS</strong> region may cause<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to hang.<br />
To test whether <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has stopped responding, issue<br />
cicscli -l from the command line. If the call hangs then <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> is not responding. See “If a process locks” on page 189, for<br />
information on what to do if the <strong>Gateway</strong> daemon is not responding.<br />
Try to reproduce the problem with tracing turned on. Take a client trace with<br />
as many components as possible active. As a minimum you need the API,<br />
DRV and CCL tracepoints; add TRN if possible. (Use trace wrapping if you<br />
do not want the trace file to get too large; see “Tracing” on page 185.) The<br />
summary trace shows whether the client or user application has stopped<br />
responding, and gives an indication as to whether the problem is in the client<br />
or server.<br />
206 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Diagnosing common problems: Client daemon<br />
If you can reproduce the problem, have details of how to reproduce it<br />
available for your support organization. If you cannot reproduce the problem,<br />
have available details of the circumstances that led up to the hang, for<br />
example:<br />
v Does it hang only when the system is under heavy load?<br />
v Does it hang only when there are many concurrent users?<br />
v Does it hang only under a particular configuration, or after a known<br />
sequence of events?<br />
All UNIX systems<br />
Run ps -ef and ipcs -qa on the system, piping the output to a file. This<br />
lists the following:<br />
v Processes on the system<br />
v All UNIX IPC queues<br />
v Amount of data in the queues<br />
v Owner of the queues<br />
This information is useful because the client uses IPC queues for internal<br />
communication.<br />
AIX<br />
Use the System Management Interface Tool (SMIT) to take an operating<br />
system trace of the failure.<br />
Use the syscalls event set and ipcs related trace options. Format it to<br />
show pids, tids, current system calls, and elapsed time options. Consider<br />
increasing the buffer file settings.<br />
dbx tool<br />
You can attach the dbx tool to a process that has locked, to find out<br />
what the process is doing. (Check that dbx is installed on your<br />
system, and that you have authority to connect to a process.) This<br />
example shows how to attach dbx to the Client daemon cclclnt. You<br />
can adapt the example to find out why a user application has locked.<br />
Important: Attaching dbx to a process sometimes causes the process<br />
to lock or terminate. Use it only if you are sure the<br />
process has locked.<br />
Type the following command to find out the process id (pid):<br />
ps -ef | grep cclclnt<br />
Information about the process is displayed:<br />
root 26864 27348 3 11:06:51 pts/2 0:00 grep cclclnt<br />
sknights 28266 1 0 11:06:46 pts/0 0:00 cclclnt<br />
Chapter 13. Problem determination and problem solving 207
Diagnosing common problems: Client daemon<br />
Using the information provided by the ps command, type this to<br />
attach dbx to the process:<br />
dbx -a 28266 ./cclclnt<br />
You should now see something like this:<br />
Waiting to attach to process 28266 ...<br />
Successfully attached to cclclnt.<br />
Type ’help’ for help.<br />
reading symbolic information ...warning: no source compiled with -g<br />
stopped in _pthread_ksleep at 0xd0139164 ($t2)<br />
0xd0139164 (_pthread_ksleep+0x9c) 80410014 lwz r2,0x14(r1)<br />
To get a stack back trace of the current thread, issue the where<br />
command:<br />
_pthread_ksleep(??, ??, ??, ??, ??) at 0xd0139164<br />
_pthread_event_wait(??) at 0xd01395c0<br />
_cond_wait_local(??, ??, ??) at 0xd0135494<br />
_cond_wait(??, ??, ??) at 0xd0135998<br />
pthread_cond_timedwait(??, ??, ??) at 0xd0136368<br />
OsEventTimedWait() at 0xd00a78b4<br />
.() at 0x100005b8<br />
_pthread_body(??) at 0xd012f358<br />
To list all threads in the cclclnt process, type thread :<br />
thread state-k wchan state-u k-tid mode held scope function<br />
$t1 wait 0xc0000100 running 21793 k no sys<br />
>$t2 run blocked 32425 k no sys _pthread_ksleep<br />
To make thread 1 the current thread, type thread current 1.<br />
To get a stack back trace of thread 1, type where. The screen looks like<br />
this:<br />
.() at 0x1000c784<br />
.() at 0x10000ae0<br />
.() at 0x10000ae0<br />
.() at 0x100003f4<br />
To close dbx, type quit.<br />
Solaris<br />
Run truss against the hung process; see the operating system<br />
documentation for relevant parameters. Specify options to follow forked<br />
calls, trace arguments to system calls, and show the environment strings<br />
to operating system calls.<br />
208 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Diagnosing common problems: Client daemon<br />
Ensure that the /etc/system file allows sufficient queue entries; see<br />
“Configuring message queues” on page 44. If the value is too low, the<br />
client may freeze while waiting for a queue entry to become available.<br />
Solaris system notes:<br />
1. Whenever you change the /etc/system file, you must restart your<br />
system for the changes to take effect.<br />
2. Changes to your system may not work if your workstation has less<br />
than 32MB of memory; the recommended minimum is 64MB.<br />
<strong>CICS</strong> server problem determination<br />
The most important facilities for problem determination on <strong>CICS</strong> servers are:<br />
v Traces<br />
– auxiliary<br />
– internal<br />
v Dumps<br />
v <strong>CICS</strong> message logs<br />
v Statistics information<br />
v Monitoring information<br />
v Execution diagnostic facility (EDF)<br />
v <strong>CICS</strong>-supplied transactions, CEBR and CECI<br />
v Independent software vendor (ISV) tools<br />
Information about these facilities is given in the Problem Determination books<br />
for the individual products (see “<strong>CICS</strong> <strong>Transaction</strong> Server publications” on<br />
page 239). You may need to contact the server system administrator for more<br />
information, for example, about a <strong>CICS</strong> server error log.<br />
The following shows the error message prefixes for <strong>CICS</strong> products:<br />
CCL <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> Universal Client<br />
FAA <strong>CICS</strong> for OS/2<br />
DFH <strong>CICS</strong> on System/390 ® and z/OS<br />
ERZ <strong>Transaction</strong> Server for Windows NT <strong>Version</strong> 4.0, and TXSeries<br />
AEG <strong>CICS</strong> for OS/400.<br />
Communication problem determination<br />
Even a small telecommunications network is a very complex system in which<br />
all components depend on one another. If one component fails and presents<br />
incorrect information to the other components, the latter may fail even more<br />
severely than the former. Sometimes the failure may be considerably delayed,<br />
and the error indicator may be lost before the error is detected. Thus, it is<br />
sometimes very difficult to analyze a problem in the communication part of a<br />
system.<br />
Chapter 13. Problem determination and problem solving 209
Communication problems<br />
The Client daemon generates various messages associated with the use of the<br />
supported communication protocols and the associated products. Refer to<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for a list of these messages and<br />
their explanations.<br />
The communication products themselves generate error messages. For details<br />
of these, and information on troubleshooting, you should refer to the<br />
documentation for the communication product. The following sections<br />
summarize useful commands and utilities for problem determination.<br />
TCP/IP-providing products: TCP/IP provides the following diagnostic tools:<br />
ARP Displays and modifies the IP-to-Ethernet or<br />
token ring physical address translation tables<br />
used by address resolution protocol (ARP).<br />
HOSTNAME Displays the host name of your workstation.<br />
IPCONFIG Displays all current TCP/IP network<br />
configuration values. This is helpful if you<br />
have to find out if an IP interface is active.<br />
NETSTAT Displays protocol statistics and current<br />
TCP/IP network connections. This helps you<br />
obtain information about your own IP<br />
interfaces, for example, to list IP addresses<br />
and TCP/IP routing tables in use at your<br />
workstation.<br />
NSLOOKUP Displays information from Domain Name<br />
System (DNS) name servers.<br />
PING Verifies connections to a remote computer or<br />
computers.<br />
TRACEROUTE Traces the TCP/IP path to a requested<br />
destination. It is useful for determining<br />
whether there is a problem with one of the<br />
intermediate nodes.<br />
For more information on these utilities, refer to the online help for TCP/IP.<br />
APPC-providing products: This section describes problem determination in<br />
products involved in APPC communication.<br />
VTAM Buffer Trace: You can use VTAM buffer tracing to record the flow of<br />
data between logical units in the <strong>CICS</strong> environment. The trace entries include<br />
the netname of the terminal (logical unit) to which they relate. For details on<br />
VTAM buffer tracing and other VTAM problem determination functions, see<br />
the appropriate book in the VTAM library.<br />
210 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
The APING utility: In an APPC environment, you can use the APING utility<br />
to test a connection. APING exchanges data packets with a partner computer<br />
over APPC and times how long the data transfer takes. It can be used to get a<br />
first estimate of the session setup time between two computers and the<br />
throughput and turnaround time on that APPC session. You can use APING<br />
to determine whether a session can be set up between two computers and to<br />
display extensive error information if session allocation fails. APING consists<br />
of two transaction programs: APING, which runs on the client side, and<br />
APINGD, which runs on the server side.<br />
Checking client and host configuration: If the SNA product on the Client<br />
daemon machine, and the host are both correctly configured, you should be<br />
able to activate the connection between them. Follow the steps below to<br />
activate the connection; you do not need to start the client first.<br />
1. Start the node on the SNA product on the Client daemon machine.<br />
2. Use the CEMT transaction to acquire the connection. Type CEMT I CON. The<br />
screen will look similar to this:<br />
I CON<br />
STATUS: RESULTS - OVERTYPE TO MODIFY<br />
Con(SIMD) Net(PYKS88BA) Ins ▌Rel▐ Vta Appc<br />
Con(SYSB) Net(IYCKZCCV) Ins Rel Vta Appc<br />
SYSID=SYSA APPLID=IYCKZCCU<br />
RESPONSE: NORMAL TIME: 12.2<strong>5.0</strong>4 DATE: 03.01.01<br />
PF 1 HELP 3 END 5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 SF<br />
3. Overtype ▌Rel▐ with ACQ, to acquire the connection.<br />
Communication problems<br />
If you cannot acquire the connection, SNA is wrongly configured on the<br />
product or the host.<br />
IBM Communications Server for AIX ® : IBM Communications Server for<br />
AIX writes a log file called sna.err, in /var/sna. This text file can help you to<br />
diagnose communications errors. The IBM support organization needs the file<br />
if you have SNA errors that you cannot resolve.<br />
Follow these steps to interpret sense data:<br />
1. Enter the command smitty sna to start the System Management Interface<br />
Tool (SMIT).<br />
2. Select Problem Determination Aids.<br />
3. Select Show SNA Sense Code information.<br />
4. Type the sense code into the panel to see a description of the code.<br />
Chapter 13. Problem determination and problem solving 211
Program Support<br />
Program support<br />
If you need to contact your IBM support organization, first refer to the Service<br />
and Support card supplied with the product for details of the support<br />
available to you, or visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Support link.<br />
This section provides guidance on reporting problems, detailing the<br />
information you should collect to assist your support organization. It also<br />
explains how the problem is handled through to resolution and the provision<br />
of a fix.<br />
Reporting problems<br />
Before reporting your problem to the support organization try to ensure that<br />
the error is actually occurring within your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system,<br />
even if you are unsure whether the problem is due to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> itself.<br />
In practice, many errors reported to support organizations turn out to be user<br />
errors, or they cannot be reproduced, indicating just how difficult it can be to<br />
determine the precise cause of a problem. User errors are mainly caused by<br />
faults in application programs or by errors in setting up systems.<br />
The ability of the support organization to resolve your problem quickly<br />
depends on the quality of the information you provide to them. For this<br />
reason it is good practice to collect and organize problem data before making<br />
the initial contact.<br />
Summarize your problem and the documentation/information you collect on<br />
a problem reporting sheet. This sheet provides a valuable summary to the<br />
support organization, and a copy will be useful for your own records.<br />
Level-1 support<br />
If this is your first contact regarding this problem a unique incident number<br />
will be assigned. A Problem Management Record (PMR) is opened on the<br />
RETAIN ® database system, where all activity associated with your problem is<br />
recorded. The PMR remains “open” until it is solved.<br />
Make a note of the incident number on your copy of the problem reporting<br />
sheet. You will be expected to quote the incident number in all future<br />
correspondence relating to this problem.<br />
Your initial communication with the support organization is through a Level-1<br />
representative, who uses the keywords that you have provided to search the<br />
RETAIN database for problems with similar symptoms. If your problem is<br />
212 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Program Support<br />
found to be one already known to the support organization, and a fix has<br />
been devised for it, you will be advised of the availability of corrective service<br />
software that you can install to overcome the problem, as described in<br />
“Obtaining the fix” on page 216. If the RETAIN search is unsuccessful, the<br />
problem is passed on to a Level-2 representative who will contact you for<br />
more information about your problem, to start a more detailed investigation<br />
of the cause.<br />
Level-2 support<br />
Let the Level-2 representative know if any of the following events occurred<br />
before the problem appeared:<br />
1. Changes in level of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, compiler or associated<br />
licensed programs<br />
2. Corrective service software and fixes applied to workstation software<br />
3. Problem Tracking Fixes (PTFs) applied to other associated products<br />
4. Additional features used<br />
5. Application programs changed<br />
6. Unusual operator action.<br />
At this stage you may be asked to supply more details or documentation. If<br />
this happens, the PMR is updated to show any documentation you have<br />
submitted.<br />
Based on the information you supply, the investigation then carried out can<br />
determine whether the cause of your problem is new to the support<br />
organization, or is already known.<br />
If the problem is a valid new one, an APAR may be raised, to be dealt with<br />
by the <strong>CICS</strong> service team, as described in “APARs and fixes” on page 215. If,<br />
however, the problem is already known, and a fix has been developed, you<br />
can obtain it as described in “Obtaining the fix” on page 216.<br />
Documenting problems<br />
In a communication environment, where many clients may be connected to<br />
several servers, you must obtain information from both the client and the<br />
server sides.<br />
To facilitate problem determination, try to reduce your environment to only<br />
one client workstation and one server to narrow down the range of<br />
possibilities that may cause the error.<br />
Listed below are the types of information most likely to be needed by the<br />
support organization. The list is not exhaustive; it covers the most commonly<br />
requested information.<br />
Chapter 13. Problem determination and problem solving 213
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Program Support<br />
v The version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, including details of any<br />
service releases applied.<br />
v The utility or programming language that gives the problem, for example:<br />
– ECI, EPI, ESI<br />
– C, C++, Java<br />
For languages, include the version.<br />
v The network protocols being used.<br />
v The end-to-end configuration, and product stacks at each step of the way,<br />
for example, WebSphere Application Server async ECIRequest class over<br />
SSL to ctgstart on Solaris up using TCP62 to <strong>CICS</strong> <strong>Transaction</strong> Server 2.2.<br />
v The operating system on which the problem occurs. If the Client application<br />
and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are on different operating systems, provide<br />
details of both. Details of the <strong>CICS</strong> server are also useful.<br />
v A recreate scenario, if possible.<br />
v Details of any log messages at the time the problem occurred.<br />
v A short description of the problem in terms of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
calls, including why you think it is a problem with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. For example, a specific API call hangs and never returns, or an<br />
unexpected return code on a specific API call.<br />
Locating and compiling information<br />
The advice listed below will help you compile the information required. If<br />
you are in any doubt about how to gather any of the items listed above, wait<br />
until you can seek advice from your support organization.<br />
v Try to establish which program in your system seems to be the cause of the<br />
problem. As you are reading this book, it is likely that you already believe<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to be the problem source.<br />
You also need to provide the version and release number of the product, for<br />
example <strong>Version</strong> <strong>5.0</strong>, together with the number of any PTF or other fix<br />
applied, for example UNnnnnn (where nnnnn is a valid PTF number).<br />
v You should find details of your compiler level on the product media labels<br />
or the associated documentation. Alternatively, check the panel displayed<br />
on the screen at compile time.<br />
v Give the problem a severity level. Severity levels have the following<br />
meanings:<br />
– Severity level 1 indicates that you are unable to use a program, resulting<br />
in a critical condition that needs immediate attention.<br />
– Severity level 2 indicates that you are able to use the program, but that<br />
operation is severely restricted.<br />
– Severity level 3 indicates that you are able to use the program, with<br />
limited functions, but the problem is not critical to your overall<br />
operation.<br />
214 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Program Support<br />
– Severity level 4 indicates that you are able to use the program with the<br />
problem causing negligible hindrance.<br />
When deciding the severity of the problem, take care to categorize it<br />
correctly, as the procedures followed by the support organization depend<br />
on the severity level supplied.<br />
v Also, try to classify the error and give a brief description of the problem.<br />
Include keywords associated with the problem, such as ABEND, WAIT,<br />
LOOP, PERFORMANCE, INCORROUT, and MESSAGE, corresponding to<br />
the problem classification types used in the RETAIN database. Strings<br />
containing other keywords are also useful. These are not predefined, and<br />
might include such items as a message or message number, an abend code,<br />
any parameters known to be associated with the problem, or, for example,<br />
STARTUP, INITIALIZATION, or TRANSIENT DATA.<br />
v Finally, you should include your address, relevant contact names, and<br />
details of the other products at your installation.<br />
Keep a copy of the problem reporting sheet which summarizes all the<br />
information relevant to the problem, together with any available<br />
documentation such as dumps, traces and output from programs, translators,<br />
and compilers.<br />
Submitting the documentation<br />
If you are asked to provide documentation, it will help the support<br />
organization during their investigation if you adhere to the following rules<br />
when preparing it:<br />
v Provide as much information as possible in softcopy format.<br />
v Write any notes and documents in English.<br />
v If you are asked to supply any additional trace output, provide an<br />
unformatted binary version, rather than the viewable output from the<br />
formatter.<br />
v If you upload files to a mainframe system, do so in binary rather than<br />
ASCII format.<br />
APARs and fixes<br />
Once a reported problem is confirmed as being both new and valid, An<br />
authorized program analysis report (APAR) is raised from the Problem<br />
Management Record (PMR) and becomes a permanent record describing your<br />
error, and in time, its solution. An APAR is the means of reporting to the<br />
appropriate product service team any problems you find with an IBM<br />
program.<br />
The APAR process<br />
The first step in the APAR process is that a Level-2 representative from the<br />
support organization enters an APAR containing a description of your<br />
Chapter 13. Problem determination and problem solving 215
Program Support<br />
problem into the RETAIN system. If you have a means of getting round the<br />
problem, details of this are entered as well. Your name is also entered, so that<br />
your support organization knows who to contact if the service team need to<br />
ask anything further about the APAR documentation.<br />
At this stage, you are given an APAR number. This number is always<br />
associated with the APAR and its resolution and, if a code change is required,<br />
is associated with the fix as well.<br />
The service team may ask for additional backup documentation, normally via<br />
the Level-2 representative. The specific documentation required will vary from<br />
problem to problem, and depends on what information has already been<br />
supplied during the PMR stage.<br />
During the investigation, you can ask your support organization at any time<br />
about how your APAR is progressing, particularly if it is a problem of high<br />
severity.<br />
Obtaining the fix<br />
When the service team has found a fix for your problem, you may be asked to<br />
test it on your system. If so, you may be sent a Program Temporary Fix (PTF)<br />
in the form of individual replacement modules. This is normally done through<br />
the Level-2 organization and feedback from your testing will be requested.<br />
Each PTF may contain several APAR fixes. If an individual APAR fix within a<br />
PTF is found to be in error, it may still be advisable to apply the PTF, to<br />
obtain the other APAR fixes.<br />
In time, formal corrective service software is made available, which you can<br />
order through your support organization. Traditionally, corrective service<br />
software has been supplied on Corrective Service Diskettes (CSD) ordered by<br />
CSD number. It may now be supplied on CD-ROM or via the Internet.<br />
Fixes for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are available from the <strong>CICS</strong> Support web<br />
page at: www.ibm.com/software/ts/cics/support/details.<br />
216 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Chapter 14. Migration<br />
This chapter deals with issues that can arise when you move from an earlier<br />
version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, or a product related to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. Topics covered include:<br />
v “The configuration conversion tool”<br />
v “Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4” on page 218<br />
v “Migrating from <strong>CICS</strong> Universal Client, or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
<strong>Version</strong> 3” on page 219<br />
v “Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java” on page 219<br />
v “Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong> on AIX” on page 220<br />
v “Configuring APPC for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX” on page 224<br />
v “EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>”<br />
on page 224<br />
The configuration conversion tool<br />
The configuration conversion tool (ctgconv) converts the configuration files of<br />
versions of the following to the current format:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> v3.0<br />
v <strong>CICS</strong> Universal Client v3.0<br />
If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> installation upgrades your<br />
existing product, the configuration conversion tool runs automatically if it<br />
finds configuration files in the old format. If you have to uninstall the earlier<br />
product first, or your configuration files cannot be found during the upgrade,<br />
run ctgconv after installation.<br />
The conversion tool converts the following:<br />
<strong>Gateway</strong>.properties<br />
Properties file of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 and <strong>CICS</strong><br />
<strong>Gateway</strong> for Java.<br />
<strong>CICS</strong>CLI.INI<br />
Client initialization file of <strong>CICS</strong> Clients <strong>Version</strong> 2 and <strong>Version</strong> 3.0.<br />
The conversion tool produces one output file called CTG.INI by default.<br />
Old files are renamed with the BAK extension.<br />
© Copyright IBM Corp. 1996, 2002 217
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Migration<br />
Using the conversion tool<br />
The parameters of ctgconv are:<br />
ctgconv −c=file [−g=file] [−o=file]<br />
For each parameter, file can be any of the following:<br />
v A filename and extension; the /bin directory is assumed.<br />
The extension must be INI, except for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> 3.0 and <strong>CICS</strong> <strong>Gateway</strong> for Java input files, which have the<br />
properties extension.<br />
v A full pathname.<br />
v A directory name (without a trailing /); the default filename is assumed.<br />
−c=file<br />
Specifies the Client initialization file to be converted. If file specifies a<br />
directory, a filename of <strong>CICS</strong>CLI.INI is assumed.<br />
If the parameter is not specified, the <strong>CICS</strong>CLI environment variable is<br />
used to locate the <strong>Gateway</strong> initialization file. If <strong>CICS</strong>CLI is not set, the file<br />
<strong>CICS</strong>CLI.INI, in the /bin subdirectory, is assumed.<br />
−g=file<br />
Specifies the <strong>Gateway</strong>.properties file to be converted. If you do not<br />
specify this parameter, no <strong>Gateway</strong> section is created in CTG.INI.<br />
−o=file<br />
Specifies the pathname of the converted file. The default is CTG.INI, inthe<br />
/bin subdirectory.<br />
For help on using ctgconv, enter ctgconv −?<br />
During conversion, the input files are renamed so that the last three characters<br />
of the file extension become BAK. Any file with that name is overwritten, and<br />
any output file that exists before the conversion is renamed in the same way.<br />
A banner is inserted into the renamed files stating that they are obsolete.<br />
Redundant parameters are removed from the old configuration files, and<br />
other parameters are given new names in the converted file.<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Delete file /license before attempting to install <strong>Version</strong> <strong>5.0</strong>.<br />
This file contains license information for version 4 of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. ctginstall creates a directory called /license to<br />
store license information for <strong>Version</strong> 5. If a file of the same name exists,<br />
ctginstall cannot create the directory, and the installation fails.<br />
218 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Migrating from <strong>CICS</strong> Universal Client, or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, <strong>Version</strong> 3<br />
The following are not supported:<br />
v <strong>CICS</strong>TELD<br />
v SUNLINK (Solaris). APPC protocol is no longer supported in Solaris and<br />
has been replaced by TCP62.<br />
v The <strong>CICS</strong>CLI -f parameter<br />
You might have customized versions of the following configuration files:<br />
File Default Name<br />
Keyboard mapping file <strong>CICS</strong>KEY.INI<br />
Color mapping file <strong>CICS</strong>COL.INI<br />
Windows settings <strong>CICS</strong>TERM.INI<br />
When you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> your customized files<br />
are preserved, even though <strong>CICS</strong> Universal Client <strong>Version</strong> 3.0 is deleted.<br />
In <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> the configuration file (CTG.INI),<br />
replaces the Client initialization file (<strong>CICS</strong>CLI.INI).<br />
The new file also replaces the <strong>Gateway</strong>.properties file.<br />
These files are automatically converted to the correct format when you install<br />
<strong>Version</strong> <strong>5.0</strong>, if the files are found on upgrade. To convert the <strong>Gateway</strong><br />
initialization file, run the configuration conversion tool (ctgconv), see “The<br />
configuration conversion tool” on page 217.<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java<br />
1. Take a copy of your <strong>Gateway</strong>.properties file.<br />
2. Delete the <strong>CICS</strong> <strong>Gateway</strong> for Java.<br />
3. Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>.<br />
4. Use the configuration conversion tool to convert your <strong>Gateway</strong>.properties<br />
file; see “The configuration conversion tool” on page 217.<br />
Change all import statements in your programs and recompile them. Change<br />
all occurrences of:<br />
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*<br />
import ibm.cics.jgate.epi.* to: import com.ibm.ctg.epi.*<br />
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*<br />
Modify any programs written for the <strong>CICS</strong> <strong>Gateway</strong> for Java prior to <strong>Version</strong><br />
2.0.1 that use the Session interface. This is because the parameter to the<br />
Chapter 14. Migration 219
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Session.handleReply method was changed to TerminalInterface instead of a<br />
Terminal object. Change and then recompile your programs.<br />
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user<br />
classes that implement these methods need to be changed. The TCP/IP<br />
address of the remote computer is now passed to the methods called to<br />
generate handshake data. An afterDecode method has also been added to<br />
both interfaces. See Programming in Java, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide, for more information.<br />
Migrating from the <strong>CICS</strong> Internet <strong>Gateway</strong> on AIX<br />
This section describes how to migrate from using the <strong>CICS</strong> Internet <strong>Gateway</strong><br />
to using the Terminal Servlet.<br />
Read Chapter 12, “The Terminal Servlet program” on page 163 before you<br />
perform migration, to familiarize yourself with the concepts of the Terminal<br />
Servlet.<br />
The <strong>CICS</strong> Internet <strong>Gateway</strong> reads settings from a configuration file, which is<br />
called cigd.env.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> default settings<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> Terminal Servlet equivalent<br />
Cursor The Cursor key equivalent. There is no<br />
equivalent setting for the Terminal Servlet.<br />
Instead, you can use JavaScript to set the<br />
position of the cursor. To allow this, set the<br />
servlet property screen@cursoring to true.<br />
Info Filename for the information file for the server<br />
(for AIX and Windows NT). There is no<br />
equivalent setting for the Terminal Servlet.<br />
Error Filename for the error file for the server. There<br />
is no equivalent setting for the Terminal<br />
Servlet.<br />
Trace Filename for the trace file for the server. There<br />
is no equivalent setting for the Terminal<br />
Servlet. Servlets write logging information to<br />
the servlet log provided by the Web server.<br />
See your Web server documentation to find<br />
out where this file is. If trace is turned on it is<br />
written to the standard output. Depending on<br />
your Web server, this may be directed to a file.<br />
220 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
MaxUsers The maximum number of users. The<br />
equivalent servlet property is<br />
pool@maxTerminals.<br />
TimeOut<strong>CICS</strong> The “Wait for <strong>CICS</strong> ” timeout. The servlet<br />
property servlet@allocateTimeout limits the<br />
time that the servlet will wait for a terminal to<br />
be connected to <strong>CICS</strong>. There is no limit on the<br />
time the servlet will wait for <strong>CICS</strong> to respond<br />
in other situations.<br />
TimeOut<strong>Gateway</strong> The “Wait for <strong>Gateway</strong>” timeout. There is no<br />
equivalent setting for the Terminal Servlet.<br />
TimeOutInternet The “Wait for Internet” timeout. The servlet<br />
property pool@idleTimeout limits the time<br />
that the servlet will let a terminal be unused<br />
before it is disconnected.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> override settings<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> Terminal Servlet equivalent<br />
AutoExit Normally, the Terminal Servlet does not<br />
disconnect the terminal when a transaction<br />
ends. If this is the behavior you want, set the<br />
page mapping property page@idle to the URL<br />
/servlet/TerminalServlet?request=disconnect,<br />
replacing TerminalServlet with the name of an<br />
instance of the Terminal Servlet on your Web<br />
server.<br />
ExitAid The Exit key equivalent. The servlet uses<br />
Screen Handler beans to exit running<br />
transactions. You can generate and customize<br />
Screen Handler beans for specific <strong>CICS</strong><br />
screens, and you can create a default Screen<br />
Handler that knows how to exit a range of<br />
transactions. The supplied sample<br />
DefaultScreenHandler exits using the AID PF3.<br />
ExitPage The URL for the HTML exit page. Use the<br />
page mapping property page@disconnected to<br />
specify a page to be displayed when the<br />
terminal is disconnected.<br />
ImbedHTML Allows Imbedded HTML. The servlets default<br />
behavior is to write out the contents of <strong>CICS</strong><br />
screens as is, that is, text taken from the <strong>CICS</strong><br />
screen is assumed to be correct HTML. If the<br />
Chapter 14. Migration 221
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
characters , or & are present on the <strong>CICS</strong><br />
screen, this may cause problems. To translate<br />
the characters , and & to < > and<br />
& respectively, set the request parameter<br />
translateText to true. No translation is<br />
performed when sending data to <strong>CICS</strong>.<br />
Header The filename for the HTML header. There is<br />
no equivalent setting for the Terminal Servlet.<br />
Trailer Filename for the HTML trailer. There is no<br />
equivalent setting for the Terminal Servlet.<br />
GraphicKeys Display the keys as GIFs. There is no<br />
equivalent setting for the Terminal Servlet.<br />
PAKeys Display the PA keys. There is no equivalent<br />
setting for the Terminal Servlet.<br />
PFKey24 Display extra row of PF keys. There is no<br />
equivalent setting for the Terminal Servlet.<br />
Output from the Terminal Servlet is inserted<br />
into a Web page that you provide. The sample<br />
file epissam1.shtml is provided as a starting<br />
point.<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> actions<br />
The <strong>CICS</strong> Internet <strong>Gateway</strong> is invoked by an HTML form. To invoke the<br />
Terminal Servlet instead, change the action to /servlet/servlet where<br />
servlet is TerminalServlet or another name.<br />
Query the current gateway settings<br />
You can query the various servlet properties individually. See<br />
“Displayable properties” on page 181 for details.<br />
List the available <strong>CICS</strong> systems<br />
The servlet does not provide this function. Each Terminal Servlet<br />
instance can connect to only one <strong>CICS</strong> server. You should configure an<br />
instance of Terminal Servlet for each <strong>CICS</strong> server that you want to<br />
allow users to connect to.<br />
Start a transaction<br />
You must add a hidden element setting the name ″request″<br />
to the value ″send″, as in Table 11<br />
Table 11. Terminal Servlet equivalents of actions<br />
<strong>CICS</strong> Internet <strong>Gateway</strong> Terminal Servlet equivalent<br />
element name<br />
SystemName None<br />
222 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Table 11. Terminal Servlet equivalents of actions (continued)<br />
<strong>CICS</strong> Internet <strong>Gateway</strong><br />
element name<br />
Terminal Servlet equivalent<br />
TranName transaction<br />
TranData transactionData<br />
AutoExit page@idle=/servlet/TerminalServlet?request=disconnect<br />
is equivalent to AutoExit=On<br />
ExitAID None<br />
ExitPage page@disconnected<br />
ImbedHTML translateText=true is equivalent to ImbedHTML=Off<br />
Anything else None<br />
See “Properties and parameters reference” on page 176 for more information.<br />
Administration functions<br />
You can query the number of terminals that are in use and turn trace on and<br />
off. However, these functions cannot be restricted to administrators.<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes <br />
<strong>CICS</strong> Clients <strong>Version</strong> 2 included the <strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes, also<br />
known as <strong>CICS</strong> Link for Lotus. This is not available in <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>.<br />
For inter-operation of <strong>CICS</strong> and Lotus Notes ® , IBM recommends that you use<br />
the MQSeries ® Enterprise Integrator, which offers these advantages over the<br />
<strong>CICS</strong> <strong>Gateway</strong> for Lotus Notes:<br />
v A common API that you can use to integrate Lotus Notes with IMS or<br />
MQSeries as well as <strong>CICS</strong><br />
v Support for the EPI and ECI<br />
v Use it straight from a Web browser connected to Lotus Domino<br />
MQSeries Enterprise Integrator is included in MQSeries and <strong>CICS</strong><br />
Connections for Domino. For more information, visit the Web site at:<br />
www.lotus.com/<br />
and follow the Products link.<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Chapter 14. Migration 223
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Configuring APPC for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX<br />
A LU6.2 Side Information Profile (SIP) is not required for versions later than<br />
3.0. Instead of the SIP, the Partner LU Alias Name, LocalLU Alias Name, and<br />
Mode Name are used.<br />
It is also no longer necessary to have another SIP named <strong>CICS</strong>CLI for<br />
Automatic <strong>Transaction</strong> Initiation (ATI).<br />
EPI beans provided in earlier versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
These beans, which previously were provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product, are now included with the set of sample programs:<br />
v EPIMonitor<br />
v EPIScreenButtons<br />
v EPIBasicScreenHandler<br />
Include the archive \classes\ctgsamples.jar in the classpath<br />
of any programs that use these beans. The EPIBasicScreenHandler bean<br />
includes new functions, such as font and color selection, and an improved<br />
layout.<br />
224 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Appendix A. Data conversion when using the Client<br />
daemon and a <strong>CICS</strong> server<br />
The ECI and EPI allow non-<strong>CICS</strong> applications running in a client system to<br />
gain access to <strong>CICS</strong> facilities and data managed by a <strong>CICS</strong> server system.<br />
Character data may have to be converted as it is passed between client and<br />
server; for example data is encoded in ASCII on a client system and in<br />
EBCDIC on a <strong>CICS</strong>/390 server system. Data conversion is performed by the<br />
server system.<br />
The possible ASCII and EBCDIC encoding schemes are described in detail in<br />
SC09-2190, the Character Data Representation Architecture Reference and<br />
Registry (CRDA). In summary, each encoding scheme is identified by a Coded<br />
Character Set Identifier (CCSID) which defines a set of graphic characters and<br />
the Code Page Global Identifier (CPGID) which specifies the code points used<br />
to represent the graphic characters.<br />
The data managed by the server system may be accessed from several client<br />
systems each of which uses a different ASCII encoding scheme. To support<br />
such access, each client system must be able to supply a CCSID ’tag’ in order<br />
that the data is converted correctly.<br />
Supported conversions<br />
The method used to perform data conversion depends on the server platform.<br />
The range of data conversions supported also depends on the platform. The<br />
following table has been extracted from Communicating from <strong>CICS</strong> on<br />
System/390, SC33-1697. ASCII and EBCDIC CCSIDs are assigned to geographic<br />
or linguistic groups.<br />
Data conversion is supported between ASCII and EBCDIC where both<br />
CCSIDs belong to the same group. The intent is that other <strong>CICS</strong> servers will<br />
provide equivalent support.<br />
Arabic:<br />
CCSID CPGID<br />
ASCII 00864 00864 PC data: Arabic<br />
01089 01089 ISO 8859-6: Arabic<br />
01256 01256 MS Windows: Arabic<br />
EBCDIC 00420 00420 Host: Arabic<br />
© Copyright IBM Corp. 1996, 2002 225
Data conversion<br />
Baltic Rim:<br />
CCSID CPGID<br />
ASCII 00921 00921 PC data: Latvia, Lithuania<br />
01257 01257 MS Windows: Baltic Rim<br />
EBCDIC 01112 01112 Host: Latvia, Lithuania<br />
Cyrillic:<br />
CCSID CPGID<br />
ASCII 00866 00866 PC data: Cyrillic<br />
00915 00915 ISO 8859-5: Cyrillic<br />
01251 01251 MS Windows: Cyrillic<br />
EBCDIC 01025 01025 Host: Cyrillic multilingual<br />
Estonia:<br />
CCSID CPGID<br />
ASCII 00922 00922 PC data: Estonia<br />
01257 01257 MS Windows: Baltic Rim<br />
EBCDIC 01122 01122 Host: Estonia<br />
Greek:<br />
CCSID CPGID<br />
ASCII 00869 00869 PC data: Greece<br />
00813 00813 ISO 8859-7: Grek<br />
01253 01253 MS Windows: Greek<br />
EBCDIC 00875 00875 Host: Grek<br />
Hebrew:<br />
CCSID CPGID<br />
ASCII 00856 00856 PC data: Hebrew<br />
00916 00916 ISO 8859-8: Hebrew<br />
01255 01255 MS Windows: Hebrew<br />
EBCDIC 00424 00424 Host: Hebrew<br />
Latin-1:<br />
CCSID CPGID<br />
ASCII 00437 00437 PC data: USA, many other countries<br />
00819 00819 ISO 8859-1: Latin-1 countries<br />
00850 00850 PC data: Latin-1 countries<br />
01252 01252 MS Windows: Latin-1 countries<br />
EBCDIC 00037 00037 Host: USA, Canada, etc<br />
00273 00273 Host: Austria, Germany<br />
00277 00277 Host: Denmark, Norway<br />
00278 00278 Host: Finland, Sweden<br />
00280 00280 Host: Italy<br />
00284 00284 Host: Spain, Latin America (Spanish)<br />
00285 00285 Host: United Kingdom<br />
00297 00297 Host: France<br />
00500 00500 Host: International Latin-1<br />
00871 00871 Host: Iceland<br />
01047 01047 Host: Latin-1 Open Systems<br />
226 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Latin-1 including euro support:<br />
CCSID CPGID<br />
ASCII 00858 00858 PC data: Latin-1 countries<br />
05348 01252 MS Windows: Latin-1 countries, version 2<br />
EBCDIC 01140 01140 Host: USA, Canada, etc<br />
01141 01141 Host: Austria, Germany<br />
01142 01142 Host: Denmark, Norway<br />
01143 01143 Host: Finland, Sweden<br />
01144 01144 Host: Italy<br />
01145 01145 Host: Spain, Latin America (Spanish)<br />
01146 01146 Host: United Kingdom<br />
01147 01147 Host: France<br />
01148 01148 Host: International Latin-1<br />
01149 01149 Host: Iceland<br />
Latin-2:<br />
CCSID CPGID<br />
ASCII 00852 00852 PC data: Latin-2 multilingual<br />
00912 00912 ISO 8859-2: Latin-2 multilingual<br />
01250 01250 MS windows: Latin-2<br />
EBCDIC 00870 00870 Host: Latin-2 multilingual<br />
Latin-5:<br />
CCSID CPGID<br />
ASCII 00857 00857 PC data: Latin-5 (Turkey)<br />
00920 00920 ISO 8859-9: Latin-5 (Turkey)<br />
01254 01254 MS Windows: Turkey<br />
EBCDIC 01026 01026 Host: Latin-5 (Turkey)<br />
Latin-9:<br />
CCSID CPGID<br />
ASCII 00923 00923 ISO 8859-15: Latin-9<br />
EBCDIC 00924 00924 Host: Latin-9<br />
Japanese:<br />
CCSID CPGID<br />
ASCII 00932 00897 PC data: SBCS<br />
00301 PC data: DBCS<br />
00942 01041 PC data: extended SBCS<br />
00301 PC data: DBCS<br />
00943 00897 PC data: SBCS<br />
00941 PC data: DBCS for Open environment<br />
00954 00895 G0: JIS X201 Roman<br />
00952 G1: JIS X208-1990<br />
00896 G2: JIS X201 Katakana<br />
00953 G3: JIS X212<br />
EBCDIC 00930 00290 Host: Katakana, extended SBCS<br />
00300 Host: DBCS<br />
00931 00037 Host: Latin-1, SBCS<br />
Data conversion<br />
Appendix A. Data conversion when using the Client daemon and a <strong>CICS</strong> server 227
Data conversion<br />
00300 Host:DBCS<br />
00939 01027 Host: Latin-1, extended SBCS<br />
00300 Host: DBCS<br />
Korea:<br />
CCSID CPGID<br />
ASCII 00934 00891 PC data: SBCS<br />
00926 PC data: DBCS<br />
00944 01040 PC data: extended SBCS<br />
00926 PC data: DBCS<br />
00949 01088 PC data: SBCS, IBM KS code<br />
00951 PC data: DBCS, IBM KS code<br />
00970 00367 G0: ASCII<br />
00971 G1: KSC X5601-1989<br />
01363 01126 MS Windows: Korean SBCS<br />
01362 MS Windows: Korean DBCS<br />
EBCDIC 00933 00833 Host: extended SBCS<br />
00834 Host: DBCS<br />
Simplified Chinese:<br />
CCSID CPGID<br />
ASCII 00946 01042 PC data: extended SBCS<br />
00928 PC data: DBCS<br />
01381 01115 PC data: extended SBCS, IBM GB<br />
01380 PC data: DBCS, IBMGB<br />
01383 00367 G0: ASCII<br />
01382 G1: GB 2312-80 set<br />
01386 01114 PC data: SBCS, S-Chinese GBK,<br />
T-Chinese IBM BIG-5<br />
01385 PC data: DBCS, S-Chinese GBK<br />
EBCDIC 00935 00836 Host: extended SBCS<br />
00837 Host: DBCS<br />
Traditional Chinese:<br />
CCSID CPGID<br />
ASCII 00938 00904 PC data: SBCS<br />
00927 PC data: DBCS<br />
00948 01043 PC data: extended SBCS<br />
00927 PC data: DBCS<br />
00950 01114 PC data: SBCS, IBM BIG-5<br />
00947 PC data: DBCS<br />
00964 00367 G0: ASCII<br />
00960 G1: CNS 11643 plane 1<br />
00961 G2: CNS 11643 plane 2<br />
EBCDIC 00937 00037 Host: Latin-1 SBCS<br />
00835 Host: DBCS<br />
228 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Appendix B. Hardware and software<br />
This chapter lists hardware requirements and supported software for all<br />
operating systems on which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs.<br />
Hardware requirements<br />
This section discusses the disk space requirements on z/OS, and general<br />
hardware requirements on distributed platforms.<br />
Disk space requirements on z/OS<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is normally installed into a directory such as<br />
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,<br />
during installation, the uncompressed tar file is present in the /usr/lpp<br />
directory. The HFS data set for this directory must be large enough to take the<br />
25MB (40 cylinders) that this file occupies. You can delete the files once<br />
installation is complete. Installation also requires 25MB (40 cylinders) in the<br />
/tmp directory.<br />
Once installed, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> occupies 27MB. You need enough<br />
disk space for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and any logging and tracing files.<br />
IBM recommends that you use a separate HFS data set with a primary<br />
allocation of 40 cylinders for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software. Increase this<br />
to 50 cylinders if the logging and trace files will be stored in the same HFS<br />
data set. Increase it further if many instances of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will run, or if much logging is required. Alternatively, you can use a separate<br />
HFS data set, with a primary allocation of 5 cylinders, for each instance of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
If you use the existing /usr/lpp HFS data set, ensure it has enough space to<br />
take the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software.<br />
Table 12. Hardware requirements on UNIX systems<br />
AIX LINUX SOLARIS HP-UX<br />
Processor v IBM RISC<br />
System/6000 ®<br />
v IBM RS/6000 ®<br />
G5, G6, MP3000 or<br />
above<br />
SPARC PA-RISC 1.1 or 2.0<br />
Scalable<br />
POWERParallel<br />
System (SP2).<br />
© Copyright IBM Corp. 1996, 2002 229
Table 12. Hardware requirements on UNIX systems (continued)<br />
AIX LINUX SOLARIS HP-UX<br />
Terminals Any type of Any standard Any type of Any standard<br />
terminal or telnet or X based terminal or telnet or X based<br />
X/Terminal that terminal that can X/Terminal that terminal that can<br />
can attach to the access Linux. can attach to the access HP-UX.<br />
processor.<br />
processor.<br />
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB<br />
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB<br />
for temporary files for temporary files for temporary files for temporary files<br />
used during used during used during used during<br />
installation. installation. installation. installation.<br />
Table 13. Hardware requirements on Windows systems<br />
Processor Any processor capable of running the appropriate<br />
operating system and other prerequisite software.<br />
Network adapters To connect workstations to the LAN, you need a<br />
suitable adapter such as an ethernet adapter.<br />
Memory At least 64 MB.<br />
Disk space You need 30 MB of free disk space for your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (including documentation in US<br />
English only).<br />
Supported software<br />
The following products are supported.<br />
You need a further 30 MB for temporary files used<br />
during installation. At least 12 MB of this must be on<br />
your system partition.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v AIX V4.3.3 with Service Pack 25<br />
v AIX 5.1<br />
v HP-UX 11.0<br />
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)<br />
v Linux for S/390 - SuSE 7.0 (Kernel level 2.2.16)<br />
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)<br />
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
230 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)<br />
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)<br />
v OS/390 V2.10<br />
v z/OS V1.2<br />
v Windows XP Professional<br />
v Windows 2000 Professional with a minimum of Service Pack 1<br />
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a<br />
minimum of Service Pack 1<br />
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a<br />
v Windows NT Server V4.0 with a minimum of Service Pack 6a.<br />
Notes:<br />
– Windows NT 4 Terminal Server is not supported<br />
– The setting of multiple user interface languages, under Windows<br />
2000 MultiLanguage <strong>Version</strong>, is not supported.<br />
– If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> under load, and<br />
using remote protocols, it is strongly recommended that you use<br />
a server version, rather than a workstation version, of Windows.<br />
Web browsers<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
v HotJava Browser V 1.1 (for Solaris)<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
Telnet clients<br />
If you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> over telnet, certain telnet clients can<br />
cause problems with the display. For example, your telnet session might<br />
Appendix B. Hardware and software 231
|<br />
|<br />
|<br />
|<br />
|<br />
truncate message lines over a certain length. This is usually a problem with<br />
the telnet client that you are using, or the terminal type that you are going in<br />
as. Currently there is no solution to this problem.<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v AIX: IBM Java SDK 1.3 (service release 6)<br />
v HP-UX: Java SDK 1.3.0.02<br />
v Solaris: Sun Java SDK SE 1.3.0_04.<br />
v z/OS: IBM Java SDK 1.3<br />
If using the IBM Persistent Reusable JVM, you are recommended to run at a<br />
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable<br />
functionality of this JVM.<br />
If using Java under DBCS code pages, especially IBM-939, install service<br />
refresh 14 or later.<br />
v Windows: IBM Java SDK 1.3 (service release 6)<br />
JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– AIX: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
– HP-UX: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Linux for S/390: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Solaris: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– z/OS with JRE 1.3.1: includes a version of JSSE that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> supports<br />
– Windows: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
232 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied.<br />
v <strong>CICS</strong> for MVS/ESA V4.1, with communication through SNA. (with APAR<br />
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for<br />
EPI emulation. APAR PN79262 is needed for DBCS support.<br />
v <strong>CICS</strong> for OS/400 V4.4<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for OS/2 V4.1 with CSD 3<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA 1.1.0 (with APAR PQ30170, for<br />
signon capable terminals, applied), or a minimum service level of 1.1.1<br />
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)<br />
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)<br />
v TXSeries V<strong>5.0</strong> (Windows, AIX)<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,<br />
AIX and Solaris.<br />
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.<br />
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF<br />
UQ99329 (Service Level W401030).<br />
SNA communications<br />
Customers wishing to use SNA communications should install one of the<br />
following products:<br />
Windows operating systems<br />
Any one of:<br />
v IBM eNetwork Communications Server V6.1, with a minimum of<br />
service level 1<br />
v IBM eNetwork Personal Communications V<strong>5.0</strong>, with a minimum of<br />
service level 2<br />
v IBM eNetwork Personal Communications V5.5<br />
v Microsoft SNA Server V4.0 with a minimum of SP4<br />
AIX<br />
IBM eNetwork Communications Server V6.1, with a minimum of service<br />
level 1 (AIX).<br />
Appendix B. Hardware and software 233
|<br />
|<br />
SNA is not supported on other UNIX operating systems.<br />
TCP/IP communications<br />
TCP/IP support is provided by the operating system.<br />
TCP62 communications<br />
TCP62 support is provided by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Compilers and application development tools<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following compilers and<br />
application development tools:<br />
AIX<br />
v IBM C for AIX V4.4<br />
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6<br />
v IBM VisualAge C++ Professional V4.0<br />
v IBM VisualAge C++ Professional V<strong>5.0</strong> (requires AIX version 4.2 or later)<br />
HP-UX<br />
v HP ANSI C B.11.01, with a minimum of service level 7<br />
v HP aC++ B.11.01, with a minimum of service level 6<br />
Linux for S/390<br />
v GNU compiler C runtime V2.95, with a minimum of service level 2<br />
v GNU compiler C++ runtime V2.95, with a minimum of service level 2<br />
Solaris<br />
Sun WorkShop C++ V<strong>5.0</strong><br />
Note: The C++ compiler must have all available service patches applied.<br />
Windows<br />
v IBM VisualAge COBOL V3.0<br />
v Microsoft Visual C++ V6.0<br />
v Microsoft Visual Basic V6.0<br />
v Microsoft Visual Basic Script (VBScript) V<strong>5.0</strong><br />
Note: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support use of the COM<br />
libraries with Microsoft <strong>Transaction</strong> Server (MTS), or the MTS<br />
component of COM+.<br />
Screen readers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with JAWS.<br />
234 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
Other tools<br />
These tools are available for viewing the PDF online documents:<br />
v Adobe Acrobat Reader V<strong>5.0</strong><br />
v GhostView V4.0 on Linux<br />
GPL licence and copyright issues on Linux<br />
This product uses the following libraries from the glibc package: libnsl.so,<br />
libm.so, libdl.so, ld.so, libc.so and libpthread.so. Refer to the glibc package on<br />
your machine for the various copyright statements and licensing terms for<br />
these libraries.<br />
This product also uses libncurses.so from the ncurses package. Again, refer to<br />
this package on your machine for the copyright statement and licensing terms<br />
applicable to this library.<br />
IMPORTANT: Your use of the libstdc++ or egcs-c++ packages is subject to the<br />
GNU GPL licence terms which could require you to provide source code in<br />
certain circumstances. Note that IBM will not supply source code, for example<br />
for the <strong>CICS</strong> <strong>Gateway</strong>s C++ libraries.<br />
Appendix B. Hardware and software 235
236 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 238<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks” on page 239 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 239 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 240 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 1996, 2002 237
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX for IBM eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
238 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Redbooks<br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT: Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA: Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400: Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 239
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
240 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
iKeyMan<br />
Samples<br />
and follow the Library link.<br />
See this Web site for information:<br />
www.tivoli.com<br />
The samples are not accessible.<br />
Configuration tool accessibility<br />
Components<br />
Each component in the configuration tool has a name and description for<br />
screen readers.<br />
Keys<br />
You can use the following keys to operate the configuration tool:<br />
Alt, Space<br />
Press and release the Alt key, then press Space, to open the window<br />
menu. This allows you to move, size, maximize or minimize the window.<br />
Ctrl+letter<br />
Certain actions have shortcuts assigned to them. Hold down the Ctrl key<br />
and type the letter to do the action.<br />
Ctrl+letter Action<br />
C Copies the selected value.<br />
N Creates a new configuration.<br />
© Copyright IBM Corp. 1996, 2002 241
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Ctrl+letter Action<br />
O Opens an existing configuration.<br />
P Pastes.<br />
S Saves the current configuration.<br />
U Cuts the selected value.<br />
V Pastes.<br />
W Creates a new server definition.<br />
X Cuts the selected value.<br />
Arrows (left and right)<br />
1. (Applies if the menus are active.) Move to a different menu.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the tree is active.) If a node contains subnodes, the left<br />
arrow collapses the node, the right arrow expands it. If a node cannot<br />
be expanded further, pressing the right arrow moves down to the next<br />
node. If a subnode is selected, pressing the left arrow moves to the<br />
parent node.<br />
Arrows (up and down)<br />
1. (Applies if the tree is active.) Move up and down through the tree.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the Authorized Hosts list box is active.) Move through the<br />
entries in the list. If only one entry is in the list, press the Home key<br />
to select it.<br />
Control+Page Up<br />
Scroll left.<br />
Control+Page Down<br />
Scroll right.<br />
Control+Tab<br />
Use this (rather than Tab) on panels that contain a table to cycle between<br />
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to<br />
move backwards.<br />
Enter<br />
Activates a button in the Task Guide.<br />
Escape<br />
Closes the menu.<br />
F2 Select and change an editable number field in a table, for example the<br />
Bias value field on the Program definition for managing workload panel.<br />
242 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
F6 (Applies if the tree or the panel is active.) Toggles between the tree and<br />
the panel.<br />
F8 (Applies if the tree or the panel is active.) Allows you to gain control of<br />
the split between the tree and panel areas. After pressing F8, use the<br />
arrow keys to move the split:<br />
v Press the left arrow key to move the split left (decrease the width of the<br />
tree, increase the width of the panel).<br />
v Press the right arrow key to move the split right (increase the width of<br />
the tree, decrease the width of the panel).<br />
F10<br />
Opens the file menu.<br />
Home<br />
Selects the first entry in the Authorized Hosts list box.<br />
Page Up<br />
Scroll up.<br />
Page Down<br />
Scroll down.<br />
Shift+Tab<br />
If the cursor is on a field in the panel other than the first field, moves<br />
backwards through the fields. Otherwise, toggles between the tree and the<br />
panel.<br />
Space<br />
1. Activates a button.<br />
2. Selects a checkbox.<br />
3. Selects a node in the tree.<br />
Tab<br />
Cycles through the tree, fields in the panel, and the buttons.<br />
Customizing colors and fonts<br />
Use the Settings option on the menu to change colors and fonts. Settings are<br />
not applied consistently on the Task Guide.<br />
To make them more noticeable, the names of items that contain errors are<br />
displayed in the original typeface, in red and underlined.<br />
Using help<br />
Screen readers read the entire page in the help window, rather than the area<br />
required by a user who has pressed F1. Also, the help window is not<br />
navigable by the keyboard. The solution is to open the help files, which are<br />
html files, in a browser outside the configuration tool. The help file index is<br />
cclhlp15.htm in directory:<br />
Accessibility 243
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
/bin/resource/<br />
where represents the directory containing the help files in these<br />
languages:<br />
Language <br />
English html<br />
German html_de<br />
Spanish html_es<br />
French html_fr<br />
Italian html_it<br />
Japanese html_ja<br />
Korean html_ko<br />
Turkish html_tr<br />
Simplified Chinese html_zh<br />
Task Guide<br />
Screenreaders cannot read the Task Guide; do not use the Task Guide if you<br />
use a screenreader. Use the menu in the configuration tool to add servers<br />
(Tools —> New server). Use the tree structure to enable protocols that the<br />
Java gateway will use.<br />
244 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans.<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 1996, 2002 245
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX, TXSeries<br />
for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390. A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA, <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
246 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 247
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
248 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 249
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
250 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed. The default keyboard mapping file for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is <strong>CICS</strong>KEY.INI.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.<br />
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
Glossary 251
Glossary<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
252 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
R<br />
RACF. Resource Access Control Facility. An IBM<br />
licensed program that provides access control by<br />
identifying users to the system; verifying users of<br />
the system; authorizing access to protected<br />
resources; logging detected, unauthorized<br />
attempts to enter the system; and logging<br />
detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.<br />
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
Glossary 253
Glossary<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
254 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for OS/2,<br />
<strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.<br />
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 255
Glossary<br />
256 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Index<br />
Special characters<br />
x<br />
<strong>CICS</strong>CLI.BIN 195, 197, 198<br />
<strong>CICS</strong>CLI.LOG 69<br />
<strong>CICS</strong>CLI.TRC 195<br />
A<br />
accessibility 241<br />
Acrobat 26, 235<br />
adapters 230<br />
administration 135<br />
Adobe 26, 235<br />
advanced program-to-program communication<br />
(APPC) 27, 42<br />
Anynet domain name suffix configuration setting 76<br />
APAR (authorized program analysis report)<br />
authorization 215<br />
closing 216<br />
documentation needed 213<br />
process 215<br />
submitting 215<br />
API (Application Programming Interface) 3<br />
APPC (advanced program-to-program<br />
communication) 27, 42<br />
application development tools 25, 234<br />
Application Programming Interface (API) 3<br />
application servers 25, 233<br />
application tracing 186<br />
Applid configuration setting 66<br />
asymmetric keys 7<br />
authentication 10<br />
Authorized Hosts configuration setting 64<br />
B<br />
beans, Java 14<br />
binary trace formatter 197<br />
BMS Map Conversion Utility 170, 181<br />
books 237<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 237<br />
browsers 23, 231<br />
C<br />
CA (certification authority) 8<br />
CCLLOG.HLP 194<br />
CCLMSG.HLP 194<br />
CCLSNWTP.EXE 205<br />
certification authority (CA) 8<br />
cfwk.zip 191<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java 219<br />
<strong>CICS</strong> gateway for Lotus Notes; 223<br />
<strong>CICS</strong> resource adapters 81<br />
<strong>CICS</strong> server problem determination 209<br />
<strong>CICS</strong> server PTF requirements 26<br />
<strong>CICS</strong> servers 24, 232<br />
<strong>CICS</strong> servers, communicating with 37<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>CICS</strong> gateway for Lotus Notes; 223<br />
hardware requirements 22<br />
local 92<br />
migration 217, 218<br />
problem determination 183<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with preset<br />
options 132<br />
starting <strong>Gateway</strong> with user-specified options 132<br />
startup options 132<br />
stopping 134<br />
cicscli command 139<br />
<strong>CICS</strong>CLI environment variable 50, 218<br />
<strong>CICS</strong>CLI.LOG 194<br />
<strong>CICS</strong>COL environment variable 90<br />
cicseci.rar 81<br />
cicsepi.rar 81<br />
cicsftrc utility 197<br />
cicsjava script 92<br />
<strong>CICS</strong>KEY environment variable 88<br />
cicsprnt command 157<br />
cicsterm command 151<br />
CLASSPATH 48, 224<br />
CLASSPATH environment variable 114, 191, 192<br />
CLASSPATH setting 48<br />
client control 5<br />
Client daemon<br />
trace analysis 201<br />
Client daemon tracing 196<br />
Client daemon, restarting 141<br />
Client daemon, starting 140<br />
Client daemon, stopping 140, 141<br />
client security 143<br />
client trace file 201<br />
Client trace file configuration setting 80<br />
client tracing 142<br />
security considerations 142<br />
client/server connections 28<br />
ClientSecurity 82, 84<br />
Codepage identifier override configuration setting 68<br />
codepage problems 189<br />
color mapping file 90, 152<br />
© Copyright IBM Corp. 1996, 2002 257
commands<br />
cicscli 139<br />
cicsprnt 157<br />
cicsterm 151<br />
Common Client Interface (CCI) 16<br />
Common Object Request Broker (CORBA)<br />
standard 19<br />
Communicating with <strong>CICS</strong> servers 37<br />
communication<br />
problems 209<br />
communication protocols 25, 233<br />
APPC 27<br />
TCP/IP 27<br />
Communications server 211<br />
compilers 25, 234<br />
configuration<br />
CLASSPATH 48<br />
configuration file 49<br />
configuration tool 49<br />
<strong>Gateway</strong>.properties file 49<br />
programming environment 48<br />
configuration conversion tool 217<br />
configuration file 49<br />
referencing 50<br />
renaming 87<br />
configuration file, referencing 149<br />
configuration settings<br />
Anynet domain name suffix 76<br />
Applid 66<br />
Authorized Hosts 64<br />
Client trace file 80<br />
Codepage identifier override 68<br />
Connection timeout 72<br />
Connection timeout (ms) 58<br />
Description 70<br />
Display TCP/IP hostnames 55<br />
Drop working connections 58<br />
Enable protocol handler 57<br />
Enable reading input from console 54<br />
Fully qualified CP name or template 75<br />
<strong>Gateway</strong> trace file 79<br />
<strong>Gateway</strong> trace wrap size 80<br />
Handler wakeup timeout (ms) 57<br />
Hostname or IP address 72<br />
Idle timeout (ms) 58<br />
Initial number of Connection Manager threads 53<br />
Initial number of Worker threads 54<br />
Initial transaction 71<br />
IP address mask for CP name (optional) 75<br />
IP address mask for LU name template<br />
(optional) 74<br />
Java clients obtaining generic ECI replies 55<br />
KeyRing or Keystore name 61<br />
KeyRing or Keystore password 61<br />
Local LU name 73<br />
258 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
configuration settings (continued)<br />
Local LU name or template 74<br />
Log client connections and disconnections 56<br />
Log file 69<br />
Max dedicated connections 64<br />
Maximum buffer size 67<br />
Maximum Client wrap size 80<br />
Maximum logical SNA sessions 76<br />
Maximum number of Connection Manager<br />
threads 54<br />
Maximum number of Worker threads 54<br />
Maximum requests 67<br />
Maximum servers 67<br />
Maximum SNA RU size 77<br />
Mode name 73, 75<br />
Model terminal definition 71<br />
Partner LU name 73, 74<br />
Ping time frequency (ms) 58<br />
Port 57, 72<br />
Print command 68<br />
Print file 68<br />
Remote node inactivity poll interval 76<br />
Require clients to use security classes 59<br />
Send TCP/IP Keepalive packets 72<br />
Server name 70<br />
Server retry interval 69<br />
SNA pacing size 77<br />
SO_LINGER setting 58<br />
Terminal exit 67<br />
Timeout for in-progress requests to complete<br />
(ms) 56<br />
Trace 78<br />
Trace settings 195<br />
Use client authentication 60<br />
Use LU alias names 72<br />
Use upper case security 71<br />
Validate message qualifiers 55<br />
Validate Units of Work 55<br />
Worker thread available timeout (ms) 56<br />
configuration tool 49<br />
configuration tool help 243<br />
connecting to <strong>CICS</strong> servers 140, 145<br />
Connection timeout (ms) configuration setting 58<br />
Connection timeout configuration setting 72<br />
ConnectionURL 82, 83<br />
console messages, disabling the display of 144<br />
console messages, enabling the display of 144<br />
CORBA (Common Object Request Broker) standard 19<br />
Corrective Service Diskette (CSD) 216<br />
CRSR transaction 42<br />
CSD (Corrective Service Diskette) 216<br />
CTG_JNI_TRACE 79, 187<br />
ctgclient.jar 192<br />
ctgconv, conversion tool 218<br />
ctgikey 94, 105
ctgsamples.jar 224<br />
ctgserver.jar 192<br />
ctgstart command 132<br />
customizing<br />
keyboard 88<br />
screen colors 90<br />
D<br />
Data conversion 44<br />
dbx 207<br />
defining 3270 printer terminal emulator<br />
characteristics 157<br />
defining 3270 terminal emulator characteristics 152<br />
Description configuration setting 70<br />
development tools 25, 234<br />
DeviceType 85<br />
diagnosing common problems<br />
Client daemon 203<br />
codepage problems 189<br />
<strong>Gateway</strong> daemon 188<br />
if a process locks 189<br />
Java exceptions 192<br />
Java security exceptions 192<br />
java.lang.OutOfMemory exception 193<br />
SSL exceptions 190<br />
diagnostic tools<br />
APING 211<br />
digital certificates 8, 10<br />
externally signed 95, 105<br />
maintaining 94, 105<br />
self-signed 100, 110<br />
digital signatures 8<br />
disability 241<br />
disabling the display of console messages 144<br />
disabling the display of messages 144<br />
disk space required 230<br />
DISPLAY environment variable 35<br />
Display TCP/IP hostnames configuration setting 55<br />
displaying command syntax 145<br />
distinguished name (DN) 8<br />
DN (distinguished name) 8<br />
documentation 237<br />
documenting problems 213<br />
Drop working connections configuration setting 58<br />
dynamic name generation (TCP62) 75<br />
E<br />
ECI (External Call Interface) 1, 3, 4<br />
ECI resource adapter 82<br />
Enable protocol handler configuration setting 57<br />
Enable reading input from console configuration<br />
setting 54<br />
enabling the display of console messages 144<br />
Encoding 85<br />
encryption 7, 10<br />
Enterprise Information Systems (EIS) 15<br />
environment variables 87<br />
<strong>CICS</strong>CLI 50, 218<br />
<strong>CICS</strong>COL 90<br />
<strong>CICS</strong>KEY 88<br />
CLASSPATH 48, 114, 191<br />
CTG_JNI_TRACE 79, 187<br />
JAVA_HOME 94, 105<br />
LD_LIBRARY_PATH 92<br />
PATH 92<br />
SHLIB_PATH 92<br />
EPI (External Presentation Interface) 1, 3, 4<br />
EPI resource adapter 83<br />
EPIBasicScreenHandler 224<br />
EPIMonitor 224<br />
EPIScreenButtons 224<br />
error log 211<br />
<strong>CICS</strong>CLI.LOG 194<br />
client error log 194<br />
server error log 209<br />
ESI (External Security Interface) 1, 3, 4<br />
Euro support 68<br />
EXEC <strong>CICS</strong> RETURN TRANSID IMMEDIATE<br />
command 153, 158<br />
External Call Interface (ECI) 1, 3, 4<br />
External Presentation Interface (EPI) 1, 3, 4<br />
External Security Interface (ESI) 1, 3, 4<br />
externally-signed certificates 9<br />
F<br />
firewalls 14<br />
free memory 67<br />
Fully qualified CP name or template configuration<br />
setting 75<br />
G<br />
<strong>Gateway</strong> daemon tracing 185<br />
<strong>Gateway</strong> trace file configuration setting 79<br />
<strong>Gateway</strong> trace wrap size 80<br />
<strong>Gateway</strong>.properties file 49<br />
generic ECI replies<br />
Configuration 55<br />
GhostView 26, 235<br />
glossary of terms and abbreviations 245<br />
H<br />
Handler wakeup timeout (ms) configuration<br />
setting 57<br />
hangs 189, 206<br />
hardware requirements 22<br />
help 243<br />
Hostname or IP address configuration setting 72<br />
HTTP (Hypertext Transfer Protocol) 2<br />
HTTP over SSL (HTTPS) 2<br />
HTTPS 12<br />
HTTPS (HTTP over SSL) 2<br />
Index 259
Hypertext Transfer Protocol (HTTP) 2<br />
I<br />
IBM Communications Server 211<br />
Idle timeout (ms) configuration setting 58<br />
IIOP (Internet InterOrb Protocol) 19<br />
iKeyMan 94, 105<br />
distributing to client workstations 94<br />
inactivity poll interval 41<br />
Initial number of Connection Manager threads<br />
configuration setting 53<br />
Initial number of Worker threads configuration<br />
setting 54<br />
initial transaction 152, 157<br />
Initial transaction configuration setting 71<br />
initialization files<br />
<strong>CICS</strong>COL.INI 90<br />
<strong>CICS</strong>KEY.INI 88<br />
install_path x<br />
installation<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 31<br />
path x<br />
installation path x<br />
InstallTimeout 85<br />
internal client communication in UNIX systems 44<br />
Internet InterOrb Protocol (IIOP) 19<br />
IP address mask for CP name (optional) configuration<br />
setting 75<br />
IP address mask for LU name template (optional)<br />
configuration setting 74<br />
J<br />
J2EE<br />
resource adapter files 81<br />
resource adapters 3<br />
Java<br />
applet 13<br />
application 13<br />
beans 14<br />
classes 3<br />
firewall 14<br />
Java language 12<br />
samples 224<br />
servlet 13<br />
Java development kit 24, 232<br />
Java exceptions 192<br />
Java Secure Socket Extension (JSSE) 24, 232<br />
Java security exceptions 192<br />
JAVA_HOME environment variable 94, 105<br />
java.lang.OutOfMemory exception 193<br />
JDK levels 24, 232<br />
JNI tracing 78, 135, 186<br />
JSSE 9, 11, 24, 104, 105, 232<br />
installation 104<br />
migration from SSLight 104<br />
260 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
K<br />
KeepAlive packets 41<br />
keyboard 241<br />
keyboard mapping file 88, 152<br />
KeyRing or Keystore name configuration setting 61<br />
KeyRing or Keystore password configuration<br />
setting 61<br />
KeyRingClass 83, 85<br />
KeyRingPassword 83, 85<br />
KeyRings 9, 94<br />
KeyStores 9, 105<br />
L<br />
LD_LIBRARY_PATH 92<br />
license file 32<br />
listing connected servers 144<br />
local <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 92<br />
local gateway connection 13<br />
Local LU name configuration setting 73<br />
Local LU name or template configuration setting 74<br />
locks 189<br />
Log file configuration setting 69<br />
logical unit (LU) 42<br />
LogonLogoffClass 85<br />
LU6.2 27<br />
M<br />
mapping files<br />
renaming 87<br />
Max dedicated connections configuration setting 64<br />
Maximum buffer size configuration setting 67<br />
Maximum Client wrap size configuration setting 80<br />
Maximum logical SNA sessions configuration<br />
setting 76<br />
Maximum number of Connection Manager threads<br />
configuration setting 54<br />
Maximum number of Worker threads configuration<br />
setting 54<br />
Maximum requests configuration setting 67<br />
Maximum servers configuration setting 67<br />
Maximum SNA RU size configuration setting 77<br />
memory leak 193<br />
memory requirements 67<br />
message queues 44<br />
messages 184, 194<br />
messages, disabling the display of 144<br />
migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java 219<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong><br />
4 218<br />
migration<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java 219<br />
<strong>CICS</strong> Universal Client <strong>Version</strong> 3.0 219<br />
migration issues 217, 218<br />
mode definitions, APPC 42<br />
Mode name configuration setting 73, 75
Model terminal definition configuration setting 71<br />
N<br />
national language support 33<br />
network gateway connection 13<br />
network security<br />
authentication 10<br />
certification authority (CA) 8<br />
concepts 6<br />
ctgikey 94, 105<br />
digital certificates 8, 10<br />
externally signed 95, 105<br />
maintaining 94, 105<br />
self-signed 100, 110<br />
digital signatures 8<br />
distinguished name (DN) 8<br />
encryption 7, 10<br />
externally-signed certificates 9<br />
HTTPS 12, 114<br />
iKeyMan 94, 105<br />
distributing to client workstations 94<br />
JSSE 9, 11, 104, 105<br />
installation 104<br />
migration from SSLight 104<br />
KeyRings 9, 94<br />
keys 7<br />
KeyStores 9, 105<br />
migrating old self-signed certificates 104, 114<br />
security exits 12<br />
self-signed certificates 9<br />
signer certificate 8<br />
SSL 10, 114<br />
SSL handshaking 10<br />
SSLight 11, 94<br />
System SSL 11<br />
trusted root key 8<br />
X.509 protocol 8, 10<br />
O<br />
object request broker (ORB) 19<br />
online help, for end user messages, 194<br />
onlne help, for trace and log messages 194<br />
operating systems 23, 230<br />
operation<br />
starting the <strong>Gateway</strong> 132<br />
stopping the <strong>Gateway</strong> 134<br />
options<br />
cicscli command 145<br />
cicsprnt command 159<br />
cicsterm command 154<br />
ORB (object request broker) 19<br />
P<br />
Partner LU name configuration setting 73, 74<br />
Password 82, 84<br />
password expiry management (PEM) 4, 119<br />
PATH 92<br />
PEM (password expiry management) 4, 119<br />
performance<br />
assessing 125<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration 126<br />
Java considerations 128<br />
monitoring 130<br />
other system factors 128<br />
tracing 129<br />
Ping time frequency (ms) configuration setting 58<br />
planning 21<br />
PMR (Problem Management Record) 212<br />
Port configuration setting 57, 72<br />
PortNumber 82, 84<br />
Print command configuration setting 68<br />
Print file configuration setting 68<br />
print file, processing 152, 157<br />
print terminal emulator, starting 157<br />
printer support 5<br />
printer terminal emulator characteristics, defining 157<br />
problem determination 183<br />
application tracing 186<br />
diagnosing common problems<br />
<strong>Gateway</strong> daemon 188<br />
<strong>Gateway</strong> daemon tracing 185<br />
JNI tracing 186<br />
messages 184, 194<br />
preliminary checks 183<br />
servlet tracing and logging in WebSphere 187<br />
tracing<br />
Client daemon 195<br />
<strong>Gateway</strong> daemon 185<br />
Problem Management Record (PMR) 212<br />
problem reporting<br />
documenting problems 213<br />
information needed 214<br />
support organization 212<br />
problems, communication 209<br />
process locks 189<br />
program support 212<br />
protocols<br />
HTML 16<br />
HTTP 2<br />
HTTPS 2<br />
SSL 2, 10<br />
TCP/IP 2<br />
PTF (Program Temporary Fix) 216<br />
public key encryption 7<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 237<br />
R<br />
railroad diagrams x<br />
re-authentication support 83, 86<br />
README file 21<br />
ReadTimeout 85<br />
Index 261
Remote Method Invocation (RMI) 19<br />
Remote node inactivity poll interval 41<br />
Remote node inactivity poll interval configuration<br />
setting 76<br />
Require clients to use security classes configuration<br />
setting 59<br />
requirements, hardware 22<br />
resource adapter files 81<br />
resource adapters 81<br />
resource adapters, J2EE 3<br />
Restarting the Client daemon 141<br />
restrictions, using <strong>CICS</strong> servers 28<br />
RETAIN database 212<br />
RETAIN problem management system<br />
APARs 215<br />
Problem Management Record 212<br />
RMI (Remote Method Invocation) 19<br />
S<br />
samples text file 171<br />
samples, Java 224<br />
Samples.txt 171, 172<br />
screen readers 234<br />
Secure Sockets Layer (SSL) 2, 10<br />
security 71<br />
External Security Interface (ESI) 4<br />
password expiry management (PEM) 4<br />
security exits 12<br />
self-signed certificates 9<br />
Send TCP/IP Keepalive packets configuration<br />
setting 72<br />
Server name configuration setting 70<br />
Server retry interval configuration setting 69<br />
ServerName 82, 84<br />
servers<br />
application 25, 233<br />
<strong>CICS</strong> 24, 232<br />
web 25, 233<br />
servers, listing 144<br />
ServerSecurity 83, 84<br />
servlet tracing and logging in WebSphere 187<br />
servlets 13<br />
SHLIB_PATH 92<br />
shortcut keys 241<br />
signer certificate 8<br />
signon capable terminals 26<br />
SignonType 85<br />
SMIT 207, 211<br />
smitty 207, 211<br />
SNA 25, 233<br />
checking configuration 211<br />
configuring 42<br />
SNA (Systems Network Architecture) 27<br />
SNA pacing size configuration setting 77<br />
sna.err 211<br />
262 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
SO_LINGER setting configuration setting 58<br />
SSL (Secure Sockets Layer) 2, 10<br />
SSL exceptions 190<br />
SSL handshaking 10<br />
SSLight 11, 94<br />
starting a 3270 print terminal emulator 157<br />
starting a 3270 terminal emulator 152<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 132<br />
Starting the Client daemon 140<br />
stopping a terminal emulator 153<br />
Stopping the Client daemon 140, 141<br />
stopping the <strong>Gateway</strong> 134<br />
support organization<br />
program support 212<br />
sending documentation to 215<br />
symmetric keys 7<br />
syntax notation x<br />
System SSL 11<br />
Systems Network Architecture (SNA) 27<br />
T<br />
TCP/IP (Transmission Control Protocol/Internet<br />
Protocol) 2, 25, 27, 37, 234<br />
TCP/IP communication problems 204<br />
TCP62 25, 234<br />
communication problems 205<br />
port number 76<br />
TCP62 protocol 38<br />
TCP62 support 29<br />
TCPAdmin protocol settings 64<br />
Telnet 23, 231<br />
terminal emulation 4<br />
terminal emulator characteristics, defining 152<br />
terminal emulator, starting 152<br />
terminal emulator, stopping 153<br />
Terminal exit configuration setting 67<br />
Terminal Servlet 4<br />
the system locks up 206<br />
thread limits 17<br />
timeout 85<br />
Timeout for in-progress requests to complete (ms)<br />
configuration setting 56<br />
tools<br />
application development 25, 234<br />
other 26, 235<br />
TPNName 82<br />
Trace configuration setting 78<br />
Trace settings, configuration tool 195<br />
TraceLevel 83, 86<br />
tracing 86<br />
Client daemon 195<br />
dynamic 135<br />
<strong>Gateway</strong> daemon 135, 185<br />
JNI 135<br />
levels 86
tracing (continued)<br />
performance considerations 186<br />
query current trace settings 135<br />
tracing, JNI 186<br />
TranName 82<br />
transaction programs (TP), APPC 42<br />
transaction support 83, 86<br />
transmission control protocol/internet protocol<br />
(TCP/IP) 27<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP) 2, 27, 37<br />
traps 206<br />
troubleshooting<br />
hangs 206<br />
starting clients and terminals 204<br />
traps 206<br />
trusted root key 8<br />
U<br />
uninstalling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 35<br />
upgrading 218<br />
Use client authentication configuration setting 60<br />
Use LU alias names configuration setting 72<br />
Use upper case security configuration setting 71<br />
Userid 82, 84<br />
V<br />
Validate message qualifiers 55<br />
Validate Units of Work 55<br />
variables, environment 87<br />
VTAM<br />
buffer trace 210<br />
W<br />
web browsers 23, 231<br />
web servers 25, 233<br />
Web servers 15<br />
Worker thread available timeout (ms) configuration<br />
setting 56<br />
X<br />
X-Windows 35<br />
X.509 protocol 8, 10<br />
XAResource 83<br />
Index 263
264 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 1996, 2002 265
Trademarks<br />
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
AIX Anynet<br />
<strong>CICS</strong> eNetwork<br />
IBM MQSeries<br />
MVS MVS/ESA<br />
OS/390 OS/400<br />
RETAIN TXSeries<br />
VisualAge VSE/ESA<br />
VTAM WebSphere<br />
266 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Lotus Domino, Lotus Notes, and Domino Go Webserver are trademarks of<br />
Lotus Development Corporation.<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of<br />
Microsoft Corporation in the United States, other countries, or both.<br />
Java and all Java-based trademarks and logos are trademarks or registered<br />
trademarks of Sun Microsystems, Inc. in the United States, other countries, or<br />
both.<br />
UNIX is a registered trademark in the United States and other countries<br />
licensed exclusively through X/Open Company Limited.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
Notices 267
268 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 1996, 2002 269
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6139-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> UNIX Administration <strong>Version</strong> <strong>5.0</strong>
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
z/OS Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6191-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
z/OS Administration<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6191-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 191.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong> for z/OS ® program number 5724-D12. It will also<br />
apply to all subsequent versions, releases, and modifications until otherwise indicated in new editions.<br />
This edition replaces SC34-5935. Vertical lines at the left side of the page indicate material that is new to this edition.<br />
© Copyright International Business Machines Corporation 1996, 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
|<br />
Contents<br />
About this book . . . . . . . . . . vii<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . viii<br />
Installation path . . . . . . . . . . x<br />
Programming language specific . . . . . x<br />
Operating system specific . . . . . . . x<br />
Syntax notation . . . . . . . . . . x<br />
Summary of changes . . . . . . . . xiii<br />
Chapter 1. Overview . . . . . . . . . 1<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides . . 3<br />
A <strong>Gateway</strong> daemon. . . . . . . . . 3<br />
The <strong>Gateway</strong> classes . . . . . . . . 3<br />
J2EE resource adapters . . . . . . . . 3<br />
The external access interfaces (ECI, EXCI) . 3<br />
Network security. . . . . . . . . . . 4<br />
Encryption . . . . . . . . . . . . 5<br />
Digital signatures and digital certificates . . 5<br />
Obtaining a digital certificate. . . . . . 6<br />
KeyRings and KeyStores . . . . . . . 7<br />
Authentication using SSL . . . . . . . 8<br />
HTTPS . . . . . . . . . . . . . 10<br />
Security exits. . . . . . . . . . . 10<br />
Java technology . . . . . . . . . . . 10<br />
The Java language . . . . . . . . . 11<br />
Java applets . . . . . . . . . . . 11<br />
Java servlets . . . . . . . . . . . 11<br />
Java applications . . . . . . . . . 12<br />
Firewalls . . . . . . . . . . . . 12<br />
Web servers . . . . . . . . . . . 13<br />
The J2EE resource adapters . . . . . . . 13<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses<br />
<strong>CICS</strong> . . . . . . . . . . . . . . 14<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading<br />
model . . . . . . . . . . . . . . 14 15<br />
Chapter 2. Planning your installation . . . 19<br />
Disk space requirements . . . . . . . . 19<br />
Software requirements . . . . . . . . 20<br />
Operating systems . . . . . . . . . 20<br />
Web browsers . . . . . . . . . . 20<br />
JDK levels. . . . . . . . . . . . 21<br />
JSSE. . . . . . . . . . . . . . 21<br />
<strong>CICS</strong> Servers. . . . . . . . . . . 21<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Web servers . . . . . . . . . . . 21<br />
Application servers . . . . . . . . 21<br />
Checking the z/OS shell environment . . . 22<br />
National Language Support . . . . . . . 22<br />
Coexistence with other products . . . . . 22<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java (MVS) 23<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
OS/390 <strong>Version</strong> 3 . . . . . . . . . . 24<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
<strong>Version</strong> 4 . . . . . . . . . . . . . 24<br />
Chapter 3. Installation . . . . . . . . 25<br />
Installation: overview . . . . . . . . . 26<br />
OMVS features . . . . . . . . . . 26<br />
Installation: detail . . . . . . . . . . 27<br />
Step 1: Gather information and obtain the<br />
necessary permissions. . . . . . . . 27<br />
Step 2: (Optional) Make a safe home for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . . . . 28<br />
Step 3: Upload, unpack and install . . . 31<br />
Installing into a locale other than 1047 (U.S.<br />
English) . . . . . . . . . . . . . 32<br />
Changing the code page after installation 33<br />
Directory structure . . . . . . . . . . 33<br />
Uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for z/OS . . . . . . . . . . . . . 34<br />
Using X-Windows from a remote system . . 34<br />
Extracting and installing the PDF library . . 35<br />
Service and updates . . . . . . . . . 36<br />
Chapter 4. Configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS . . . . . . 37<br />
<strong>CICS</strong> server connection definition . . . . . 37<br />
<strong>CICS</strong> server sessions definition. . . . . . 40<br />
Open interregion communication . . . . . 42<br />
EXCI user-replaceable module DFHXCURM 42<br />
Chapter 5. Configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> . . . . . . . . 43<br />
Editing the sample configuration files . . . 43<br />
General <strong>Gateway</strong> settings in CTG.INI . . . 45<br />
Protocol settings . . . . . . . . . 45<br />
Summary of environment variables . . . 46<br />
Setting environment variables . . . . . . 47<br />
The environment variables . . . . . . 48<br />
© Copyright IBM Corp. 1996, 2002 iii
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Customizing EXCI options . . . . . . 50<br />
Using the configuration tool . . . . . . 52<br />
Running the configuration tool on a<br />
different operating system . . . . . . 53<br />
The configuration tool interface . . . . 53<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings . . . . . . . . . . . . 56<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
use with RACF ®<br />
. . . . . . . . . . 65<br />
Problems . . . . . . . . . . . . 67<br />
J2EE setup and configuration . . . . . . 67<br />
Deploying <strong>CICS</strong> resource adapters . . . 68<br />
Tracing. . . . . . . . . . . . . 71<br />
Other configuration tasks: . . . . . . . 73<br />
Increasing the CPUTIME timeout when the<br />
volume of traffic is high . . . . . . . . 73<br />
Chapter 6. Network Security . . . . . . 75<br />
Determining your use of SSLight or JSSE for<br />
the SSL and HTTPS protocols . . . . . . 76<br />
SSLight . . . . . . . . . . . . . 76<br />
Conflict with JSSE . . . . . . . . . 76<br />
Maintaining your digital certificates for<br />
SSLight . . . . . . . . . . . . 76<br />
Using externally signed certificates under<br />
SSLight . . . . . . . . . . . . 77<br />
Using self-signed certificates under SSLight 82<br />
Java Secure Socket Extension (JSSE) . . . . 86<br />
Migration from SSLight . . . . . . . 86<br />
Installation . . . . . . . . . . . 86<br />
Maintaining your digital certificates for<br />
JSSE. . . . . . . . . . . . . . 87<br />
Using externally signed certificates under<br />
JSSE. . . . . . . . . . . . . . 87<br />
Using self-signed certificates under JSSE 91<br />
System SSL . . . . . . . . . . . . 95<br />
Maintaining your digital certificates for<br />
System SSL . . . . . . . . . . . 95<br />
Using externally signed certificates under<br />
System SSL . . . . . . . . . . . 96<br />
Using self-signed certificates under<br />
System SSL . . . . . . . . . . . 101<br />
Mapping client certificates to RACF userids 105<br />
Associate a client certificate with a RACF<br />
userid. . . . . . . . . . . . . 105<br />
Map a certificate to its associated RACF<br />
userid. . . . . . . . . . . . . 106<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
SSL and HTTPS . . . . . . . . . . 107<br />
SSL and HTTPS configuration settings 107<br />
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Specifying a client KeyRing or KeyStore 107<br />
Using the SSL and HTTPS protocols . . 108<br />
Other security considerations . . . . . . 108<br />
Chapter 7. Performance . . . . . . . 109<br />
Assessing system performance . . . . . 109<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration . . 110<br />
Java considerations . . . . . . . . . 112<br />
Other system factors . . . . . . . . . 113<br />
Tracing . . . . . . . . . . . . . 114<br />
Performance monitoring tools . . . . . . 114<br />
Chapter 8. Operation . . . . . . . . 117<br />
Testing your configuration . . . . . . . 117<br />
Starting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. . . 117<br />
Starting from a command line. . . . . 117<br />
Automatic restart management . . . . 119<br />
Starting with JCL . . . . . . . . . 121<br />
Starting multiple <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>s . . . . . . . . . . . 124<br />
Stopping the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> . . 127<br />
Administering your system . . . . . . 128<br />
Setting the <strong>Gateway</strong> trace . . . . . . 128<br />
Setting the JNI trace . . . . . . . . 128<br />
Querying trace settings . . . . . . . 128<br />
Parameters . . . . . . . . . . . 129<br />
Chapter 9. Problem determination . . . 131<br />
Preliminary checks . . . . . . . . . 131<br />
What to do next . . . . . . . . . . 131<br />
Messages . . . . . . . . . . . . 132<br />
Sources of information . . . . . . . . 132<br />
Tracing . . . . . . . . . . . . . 133<br />
<strong>Gateway</strong> tracing . . . . . . . . . 134<br />
Application tracing . . . . . . . . 135<br />
JNI tracing . . . . . . . . . . . 135<br />
J2EE Tracing . . . . . . . . . . 136<br />
EXCI trace . . . . . . . . . . . 137<br />
Diagnosing common problems . . . . . 139<br />
Installation . . . . . . . . . . . 139<br />
The configuration tool . . . . . . . 139<br />
EDC5111I PERMISSION DENIED<br />
message . . . . . . . . . . . . 139<br />
CEE3250C ABEND S806 message . . . 140<br />
Multiple Address Spaces . . . . . . 140<br />
Automatic Restart Manager (ARM)<br />
problems. . . . . . . . . . . . 140<br />
Conflicts with default ports . . . . . 141<br />
EXCI pipe limitations . . . . . . . 141<br />
Java exceptions . . . . . . . . . 142
|<br />
|<br />
java.lang.OutOfMemory exception . . . 143<br />
Authorization failure using servlets with<br />
WebSphere . . . . . . . . . . . 145<br />
If a process locks . . . . . . . . . 145<br />
SSL problems . . . . . . . . . . 145<br />
Shortage of resources on the <strong>CICS</strong> server 147<br />
ECI_ERR_SECURITY_ERROR return code 147<br />
ECI_ERR_SYSTEM_ERROR return code 148<br />
Dirty address space problems . . . . . 148<br />
Program support . . . . . . . . . . 149<br />
Reporting problems . . . . . . . . 149<br />
Documenting problems . . . . . . . 150<br />
Locating and compiling information . . 151<br />
Submitting the documentation . . . . 152<br />
APARs and fixes . . . . . . . . . 152<br />
Appendix A. Hardware and software. . . 155<br />
Hardware requirements. . . . . . . . 155<br />
Supported software . . . . . . . . . 156<br />
Operating systems . . . . . . . . 156<br />
Web browsers . . . . . . . . . . 157<br />
Telnet clients . . . . . . . . . . 157<br />
JDK levels . . . . . . . . . . . 158<br />
JSSE . . . . . . . . . . . . . 158<br />
<strong>CICS</strong> Servers . . . . . . . . . . 158<br />
Web servers. . . . . . . . . . . 159<br />
Application servers . . . . . . . . 159<br />
SNA communications . . . . . . . 159<br />
TCP/IP communications . . . . . . 160<br />
TCP62 communications . . . . . . . 160<br />
Compilers and application development<br />
tools . . . . . . . . . . . . . 160<br />
Screen readers . . . . . . . . . . 160<br />
Other tools . . . . . . . . . . . 161<br />
GPL licence and copyright issues on<br />
Linux . . . . . . . . . . . . . 161<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Appendix B. Supported code pages . . . 163<br />
The product library and related literature 165<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 165<br />
Sample configuration documents. . . . . 166<br />
Redbooks . . . . . . . . . . . . 167<br />
Other Useful Books . . . . . . . . . 167<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 167<br />
APPC-related publications . . . . . . 168<br />
TCP62–related publications . . . . . 168<br />
Obtaining books from IBM. . . . . . . 168<br />
Accessibility . . . . . . . . . . . 169<br />
Documentation . . . . . . . . . . 169<br />
iKeyMan. . . . . . . . . . . . . 169<br />
Samples . . . . . . . . . . . . . 169<br />
Configuration tool accessibility . . . . . 169<br />
Components . . . . . . . . . . 169<br />
Keys . . . . . . . . . . . . . 169<br />
Customizing colors and fonts . . . . . 171<br />
Using help . . . . . . . . . . . 171<br />
Task Guide . . . . . . . . . . . 172<br />
Glossary . . . . . . . . . . . . 173<br />
Index . . . . . . . . . . . . . 185<br />
Notices . . . . . . . . . . . . . 191<br />
Trademarks . . . . . . . . . . . . 192<br />
Sending your comments to IBM . . . . 195<br />
Contents v
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
About this book<br />
This book describes the planning, installation, configuration, and operation, of<br />
the IBM ® <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> product.<br />
You should be familiar with the operating system on which your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> runs, and also with Internet terminology.<br />
Summary of changes Read this for information on functional changes made in this<br />
version of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Chapter 1, “Overview” Read this for an overview of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and<br />
the functions it provides.<br />
Chapter 2, “Planning<br />
your installation”<br />
Chapter 3,<br />
“Installation”<br />
Chapter 4,<br />
“Configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> Server for<br />
z/OS”<br />
Chapter 5,<br />
“Configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>”<br />
Chapter 6, “Network<br />
Security”<br />
Chapter 7,<br />
“Performance”<br />
Chapter 8,<br />
“Operation”<br />
Chapter 9, “Problem<br />
determination”<br />
Migrating from <strong>CICS</strong><br />
<strong>Gateway</strong> for Java<br />
(MVS)Migrating from<br />
<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for OS/390<br />
<strong>Version</strong> 3<br />
Read this for information on planning your installation,<br />
including the hardware and software you need to run <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to install <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Read this for information on how to configure EXCI<br />
connections, to allow <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to connect<br />
to a <strong>CICS</strong> region.<br />
Read this for information on how to configure your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to set up <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> to use the network security protocols SSL and<br />
HTTPS.<br />
Read this for information on how to tune your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, and other system components, to<br />
achieve the best possible performance.<br />
Read this for information on how to operate the <strong>Gateway</strong><br />
daemon.<br />
Read this for information on problem determination and<br />
problem solving.<br />
Read these if you are currently using an earlier version of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
© Copyright IBM Corp. 1996, 2002 vii
The product library<br />
and related literature<br />
Read this for information on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
product library and related literature, and the various forms<br />
in which it is available.<br />
Accessibility Read this for information on the accessibility features of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Notices Read this for important information on the availability of<br />
IBM products and service in different countries, and also on<br />
issues concerning patents, licenses, and trademarks.<br />
Sending your<br />
comments to IBM<br />
Read this for information on how to send your comments to<br />
IBM.<br />
Conventions and terminology used in this book<br />
A number of parts, both internal and external to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, are used when creating a business solution using the product.<br />
Figure 1 on page ix shows some of the possible scenarios you will encounter,<br />
and the terminology used in each case.<br />
viii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Distributed platforms running in remote mode<br />
Java client<br />
application<br />
z/OS running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Distributed platforms running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
Client<br />
daemon<br />
Distributed platforms running non-Java applications<br />
Client<br />
application<br />
Client<br />
daemon<br />
z/OS running in remote mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Client<br />
daemon<br />
<strong>CICS</strong><br />
server<br />
<strong>CICS</strong><br />
server<br />
Figure 1. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses, with their associated terminology<br />
<strong>CICS</strong><br />
server<br />
The following explains the terms used in Figure 1:<br />
<strong>Gateway</strong> daemon<br />
Used only in remote mode, the <strong>Gateway</strong> daemon listens on protocols<br />
defined in CTG.INI for gateway requests from remote Java client<br />
applications. It issues these requests to the Client daemon on<br />
distributed platforms, and directly to <strong>CICS</strong> over the EXCI on z/OS.<br />
The <strong>Gateway</strong> daemon runs the protocol listener threads, the worker<br />
threads and the connection manager threads. It uses the GATEWAY<br />
section of CTG.INI (and on z/OS the ctgenvvar script) for its<br />
configuration.<br />
Client daemon<br />
The Client daemon (process cclclnt) exists only on distributed<br />
platforms. It manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending and receiving the<br />
appropriate flows from the <strong>CICS</strong> server to satisfy the application<br />
requests. It uses the CLIENT section of CTG.INI for its configuration.<br />
About this book ix
<strong>Gateway</strong> classes<br />
The interface for Java Client applications to connect to the <strong>Gateway</strong><br />
daemon. The <strong>Gateway</strong> classes, which are supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, must be in the classpath for Java Client<br />
applications to run.<br />
Client application<br />
A user application, written in a supported programming language<br />
other than Java, that communicates directly with the Client daemon.<br />
Java Client application<br />
A Java application, servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Installation path<br />
The term is used in file paths to represent the directory where<br />
you installed the product. The default installation locations for each operating<br />
system are shown in Table 1:<br />
Table 1. Default <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> installation locations<br />
Operating System Default installation location<br />
Windows ®<br />
c:\Program Files\IBM\IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
AIX ®<br />
/usr/lpp/ctg<br />
Linux, HP-UX, Solaris /opt/ctg<br />
z/OS A ctg subdirectory of the directory from which the<br />
installation was run. For example, if the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> was installed by the command<br />
ctginstall in the /usr/lpp directory, the<br />
is /usr/lpp/ctg<br />
Programming language specific<br />
The term C refers to both the C and C++ programming languages.<br />
Operating system specific<br />
Unless otherwise specified, the term Windows refers to Windows NT ® ,<br />
Windows 2000, and Windows XP.<br />
The term Windows 2000 Terminal Server means a server with the Terminal<br />
Services feature installed.<br />
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.<br />
Syntax notation<br />
The syntax of commands is shown in a standard way. This syntax, commonly<br />
known as railroad syntax, is described in Table 2 on page xi. You interpret the<br />
syntax by following the arrows from left to right, and from top to bottom,<br />
x <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
along the main path line.<br />
Table 2. Command syntax conventions<br />
Symbol Meaning<br />
Required items appear on the main path line.<br />
►► AB ►◄<br />
►► A<br />
B<br />
C<br />
►►<br />
►►<br />
►►<br />
A B<br />
A<br />
B<br />
C<br />
A<br />
B<br />
C<br />
►► ▼ A<br />
►► ▼<br />
A<br />
B<br />
C<br />
B<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
►◄<br />
Punctuation and uppercase<br />
characters<br />
Lowercase characters appearing<br />
like this<br />
If there is more than one required item to choose<br />
from, the items are stacked vertically. This is a set of<br />
alternatives—one of which you must specify.<br />
Optional items appear below the main path line.<br />
If there is more than one optional item to choose<br />
from, the items are stacked vertically below the<br />
main path line. This is a set of alternatives—one of<br />
which you may specify.<br />
If one item in a set of alternatives is the default, this<br />
item appears above the main path line and all other<br />
items are stacked vertically below the line.<br />
An arrow returning to the left above items on the<br />
main path line means that the items can be repeated.<br />
Such items may be either required or optional.<br />
An arrow returning to the left above a set of items<br />
means that more than one item can be selected or<br />
that a single item can be repeated.<br />
Note: For <strong>CICS</strong>, unless otherwise stated, this<br />
representation means only that more than one item<br />
can be selected.<br />
Code exactly as shown.<br />
Code your own text, as appropriate. For example,<br />
with FILE(name) you must specify FILE and ()<br />
unchanged, but are free to specify any valid text<br />
string for the name of your file.<br />
About this book xi
xii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Summary of changes<br />
The following functional changes have been made for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>:<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports z/OS Automatic Restart Manager<br />
(ARM); see “Automatic restart management” on page 119.<br />
v A systems administration function allows you to set options for <strong>Gateway</strong><br />
and JNI traces, to start and stop these traces, and to query trace settings;<br />
see “Administering your system” on page 128. Using the CTG_JNI_TRACE<br />
environment variable to enable JNI tracing is supported only for migration<br />
purposes.<br />
v The way that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes log messages has changed:<br />
– Each message entry begins with the current date in the format<br />
month/day/year.<br />
– <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes error and warning messages to<br />
standard error (stderr), and information messages to standard output<br />
(stdout); see “Messages” on page 132.<br />
– A new gateway configuration setting, Log client connections and<br />
disconnections, controls whether <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes a<br />
message each time that a client application program connects to, or<br />
disconnects from, the <strong>Gateway</strong> daemon. See “Log client connections and<br />
disconnections” on page 58.<br />
v Java Secure Socket Extension (JSSE) is supported.<br />
This gives 128 bit encryption capability and is IBM’s recommended solution<br />
for SSL. For compatibility with previous versions of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, this version supports both JSSE and SSLight. However, support<br />
for SSLight might be removed in a future release.<br />
This edition replaces SC34-5935.<br />
Vertical lines at the left side of the page indicate material that is new to this<br />
edition.<br />
© Copyright IBM Corp. 1996, 2002 xiii
xiv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 1. Overview<br />
IBM <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides secure, easy access from Web<br />
browsers and network computers to <strong>CICS</strong> applications, using standard<br />
Internet protocols in a range of configurations. It is a robust and scalable<br />
complement to a Web server. You can implement it as an e-business connector<br />
for IBM WebSphere ® Application Server, which is a J2EE-compliant runtime<br />
environment for Java servlets. An API is provided that allows Java<br />
programmers to take advantage of features provided in J2EE-compliant<br />
runtime environments.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs on a wide variety of operating systems. On<br />
the Windows and UNIX ® operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
access many different types of <strong>CICS</strong> server. On z/OS <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> can access only <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS. See “Software<br />
requirements” on page 20 for information on supported operating systems and<br />
<strong>CICS</strong> servers.<br />
On the Windows and UNIX operating systems, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
uses a Client daemon to route External Call Interface (ECI), External Presentation<br />
Interface (EPI), and External Security Interface (ESI) requests to a <strong>CICS</strong> server<br />
(see “The external access interfaces (ECI, EXCI)” on page 3). On z/OS, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can route only ECI requests, and has no Client daemon.<br />
On z/OS, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> actually uses the <strong>CICS</strong> External Call<br />
Interface (EXCI) to pass requests to <strong>CICS</strong> (see “<strong>CICS</strong> External Call Interface<br />
(EXCI)” on page 3). However, to a Java applet or application, these appear to<br />
be ECI requests.<br />
© Copyright IBM Corp. 1996, 2002 1
Overview<br />
Network<br />
computer<br />
Figure 2 shows how a web client can access <strong>CICS</strong> programs and data. Note<br />
that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is shown as installed on a Web server<br />
machine. This is necessary only if you are using the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> with Java applets or servlets.<br />
HTTP<br />
Web server<br />
System SSL<br />
HTTPS<br />
Java-enabled<br />
browser<br />
HTTPS<br />
SSL<br />
<strong>CICS</strong><br />
<strong>Transaction</strong><br />
<strong>Gateway</strong><br />
Figure 2. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
TCPAdmin<br />
System SSL<br />
TCP<br />
HTTP<br />
Local<br />
Local<br />
Java application<br />
Server machine<br />
EXCl<br />
<strong>CICS</strong><br />
server<br />
Communication between <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the client application<br />
uses the following protocols:<br />
v Transmission control protocol/Internet protocol (TCP/IP) sockets<br />
v Hypertext Transfer Protocol (HTTP)<br />
v Secure Sockets Layer (SSL)<br />
v HTTP over SSL (HTTPS)<br />
TCP/IP sockets and SSL provide an efficient method of communication for<br />
intranet applications. Where firewalls exist, HTTP, and its secure alternative<br />
HTTPS, are effective communication protocols for internet applications. See<br />
“Network security” on page 4.<br />
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can manage many concurrent links to connected<br />
Web browsers. The multithreaded architecture of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> enables a single gateway to support multiple concurrently connected<br />
users.<br />
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
Overview<br />
A <strong>Gateway</strong> daemon<br />
This communicates with <strong>CICS</strong> applications running on <strong>CICS</strong> servers through<br />
EXCI.<br />
The <strong>Gateway</strong> classes<br />
This Java library includes classes that:<br />
v provides an Application Programming Interface (API) for ECI<br />
This allows communication between Java applications, or Java servlets, and<br />
the <strong>Gateway</strong> daemon.<br />
v allow client applications to communicate with transactions on a server<br />
v allow your applications to use the SSL network security protocol<br />
J2EE resource adapters<br />
Use these to provide a J2EE-compliant interface to <strong>CICS</strong> for your applications.<br />
The external access interfaces (ECI, EXCI)<br />
The external access interfaces allow non-<strong>CICS</strong> applications to access and<br />
update <strong>CICS</strong> resources by initiating <strong>CICS</strong> transactions, or by calling <strong>CICS</strong><br />
programs. When used in conjunction with the <strong>CICS</strong> communication facilities,<br />
they enable non-<strong>CICS</strong> programs to access and update resources on any <strong>CICS</strong><br />
system. This supports such activities as developing graphical user interface<br />
(GUI) front ends for <strong>CICS</strong> applications, and allows the integration of <strong>CICS</strong><br />
systems and non-<strong>CICS</strong> systems.<br />
These APIs are provided for both Java and non-Java programming languages.<br />
External Call Interface (ECI)<br />
The ECI enables a non-<strong>CICS</strong> client application to call a <strong>CICS</strong> program<br />
synchronously, or asynchronously. It enables the design of new applications to<br />
be optimized for client/server operation, with the business logic on the server<br />
and the presentation logic on the client.<br />
<strong>CICS</strong> External Call Interface (EXCI)<br />
The external <strong>CICS</strong> interface (EXCI) is analogous to the ECI. It is an application<br />
programming interface that enables a program running on z/OS, such as<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, to call a program running in a <strong>CICS</strong> region. The<br />
programs can transfer data between each other using a communication area.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports <strong>Version</strong> 2 of the EXCI.<br />
Chapter 1. Overview 3
What <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides<br />
Network security<br />
The EXCI allows a user to allocate and open sessions (or pipes) to a <strong>CICS</strong><br />
region, and to pass distributed program link (DPL) requests over them. The<br />
multiregion operation (MRO) facility of <strong>CICS</strong> inter-region communication (IRC)<br />
facility supports these requests, and each pipe maps onto one MRO session,<br />
with a limit of 100 pipes per EXCI address space.<br />
For more information on ECI, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference.<br />
For more information on EXCI, see <strong>CICS</strong> <strong>Transaction</strong> Server for OS/390 V1R3<br />
<strong>CICS</strong> Intercommunication Guide.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides comprehensive support for secure<br />
communication, which is critical to successful Internet operation. The secure<br />
network protocols SSL and HTTPS allow your client applications to<br />
communicate securely with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Network security<br />
and its implementation on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is discussed in detail in<br />
Chapter 6, “Network Security” on page 75; the following sections summarize<br />
the functions provided by SSL and HTTPS.<br />
The characteristics of secure communication are:<br />
Confidentiality<br />
The content of messages remains private as they pass over the<br />
Internet, or your intranet.<br />
Data exchanged between the client and the server is encrypted. Only<br />
your client (your application or servlet) and your server (the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>) can make sense of the data.<br />
Integrity<br />
Messages are not altered during transmission.<br />
Integrity guarantees that the message you sent reaches the recipient<br />
intact. Encryption and digital signatures ensure integrity.<br />
Accountability<br />
The sender and the receiver both agree that the exchange took place.<br />
Accountability settles any disputes over whether the message was<br />
sent and received. Digital signatures ensure accountability, so that you<br />
can identify who is responsible if something goes wrong.<br />
Authenticity<br />
You know who you are talking to and you can trust that person.<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Network security<br />
Authenticity requires verification of identities, so that you can be sure<br />
that others are who they say they are. Digital signatures and digital<br />
certificates ensure authenticity.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s implementation of the SSL protocol<br />
provides server authentication. This means that when a client<br />
establishes a connection with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, it must<br />
authenticate the server’s details. You can also enable client<br />
authentication. This means that the server will authenticate the client’s<br />
details.<br />
Encryption<br />
Encryption ensures confidentiality in transmissions sent over the Internet. In<br />
its simplest form, encryption is the scrambling of a message so that it cannot<br />
be read until it is unscrambled later by the receiver. The sender uses an<br />
algorithmic pattern, or key, to encrypt the message, and the receiver uses a<br />
decryption key to unscramble the message.<br />
Two kinds of key can be used for encryption:<br />
1. Symmetric keys<br />
The sender and receiver use the same key to encrypt and decrypt the<br />
message. The risk with symmetric keys is that you need a safe<br />
transportation method to use when sending your key to the people with<br />
whom you want to communicate.<br />
2. Asymmetric keys<br />
These consists of a pair of keys: a public key and a private key. Unlike<br />
symmetric keys, these are different from each other. The private key holds<br />
more of the secret encryption pattern than the public key.<br />
A sender sends its public key to anyone it wants to communicate with<br />
securely. It retains the private key and protects it with a password. Only<br />
the sender can decrypt a received message encrypted with its public key,<br />
because only it has the private key.<br />
Asymmetric key encryption is also known as public key encryption.<br />
SSL uses both asymmetric and symmetric key encryption. It uses public key<br />
(asymmetric) encryption as a safe way of sharing a symmetric key between<br />
server and client. This symmetric key is then used to encrypt and decrypt all<br />
data transferred on the SSL connection. This encryption protects the data from<br />
other parties that try to eavesdrop and ensures that private information, such<br />
as credit card numbers, can be transferred securely. See “Authentication using<br />
SSL” on page 8.<br />
Digital signatures and digital certificates<br />
A digital signature is a unique, mathematically computed, signature that<br />
ensures accountability.<br />
Chapter 1. Overview 5
Network security<br />
A digital certificate allows unique identification of an entity; it is essentially an<br />
electronic ID card, issued by a trusted third party. Digital certificates form part<br />
of the ISO authentication framework, also known as the X.509 protocol. This<br />
framework provides for authentication across networks.<br />
A digital certificate serves two purposes: it establishes the owner’s identity,<br />
and it makes the owner’s public key available. A digital certificate is issued by<br />
a certification authority (CA), for example VeriSign, or Thawte. It is issued for<br />
only a limited time, and when its expiry date has passed, it must be replaced.<br />
A digital certificate consists of:<br />
v The public key of the person being certified<br />
v The name and address of the person being certified, also known as the<br />
Distinguished Name (DN)<br />
v The digital signature of the CA<br />
v The issue date<br />
v The expiry date<br />
The Distinguished Name is the name and address of a person or organization.<br />
You enter your Distinguished Name as part of requesting a certificate. The<br />
digitally-signed certificate includes not only your own Distinguished Name,<br />
but the Distinguished Name of the CA, which allows verification of the CA.<br />
To communicate securely, the receiver in a transmission must trust the CA<br />
that issued the certificate that the sender is using. This means that, when a<br />
sender signs a message, the receiver must have the corresponding CA’s signer<br />
certificate and public key designated as a trusted root key. For example, your<br />
Web browser has a default list of signer certificates for trusted CAs. If you<br />
want to trust certificates from another CA, you must receive a certificate from<br />
that CA and designate it as a trusted root key.<br />
If you send your digital certificate containing your public key to someone<br />
else, what keeps that person from misusing your digital certificate and posing<br />
as you? The answer is: your private key.<br />
A digital certificate alone is not proof of anyone’s identity. The digital<br />
certificate allows verification only of the owner’s identity, by providing the<br />
public key needed to check the owner’s digital signature. Therefore, the digital<br />
certificate owner must protect the private key that belongs with the public key<br />
in the digital certificate. If the private key were stolen, anyone could pose as<br />
the legitimate owner of the digital certificate.<br />
Obtaining a digital certificate<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows you to obtain digital certificates in two<br />
ways. You can buy externally-signed certificates from a CA, or you can<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Network security<br />
establish yourself as a CA to allow you to issue self-signed X.509 certificates.<br />
Externally-signed certificates are more suitable for Internet use, while<br />
self-signed certificates might be suitable for internal use within an<br />
organization.<br />
Buying a certificate from a certification authority<br />
If you plan to conduct commercial business on the Internet, buy a server<br />
certificate from a CA such as VeriSign or Thawte.<br />
When you submit a certificate request to a CA, they require you to prove who<br />
you are before they issue you a certificate. The approval process is necessary<br />
to protect you, your organization, and the CA. The CA will digitally sign your<br />
certificate request and return the unique certificate to you by e-mail.<br />
Issuing certificates yourself<br />
If you act as a CA, you can sign your own or anyone else’s certificate request.<br />
This is a good choice if you need the certificates only within your own<br />
organization, and not for external Internet commerce. You may choose to<br />
allow access to only a carefully controlled group of key people within your<br />
intranet.<br />
Your key people should have browsers, such as Netscape Navigator, that can<br />
receive your self-signed CA certificate and designate it as a trusted root. They<br />
can then trust your communications and share information safely.<br />
See Chapter 6, “Network Security” on page 75 for more information on<br />
obtaining digital certificates.<br />
KeyRings and KeyStores<br />
Digital certificates, public keys, private keys, and trusted root keys are kept in<br />
special types of file which the security protocols can use:<br />
v SSLight, System SSL, and HTTPS use Java class files called KeyRings<br />
v Java Secure Socket Extension (JSSE) uses files called KeyStores<br />
For SSLight and JSSE: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses KeyRings and<br />
KeyStores to hold information about certificates and keys on both the SSL<br />
server and SSL clients. See “SSLight” on page 76, and “Java Secure Socket<br />
Extension (JSSE)” on page 86, for information on how to create these files. The<br />
SSL and HTTPS protocols require access to these files to establish secure<br />
connections. See “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS”<br />
on page 107 for information on how to provide this access.<br />
For System SSL: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses a key database file to hold<br />
information about certificates and keys on the SSL server. See “System SSL”<br />
on page 95, for information on how to create the key database file. The SSL<br />
and HTTPS protocols require access to this key database file to establish<br />
Chapter 1. Overview 7
Network security<br />
secure connections. See “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and<br />
HTTPS” on page 107, for information on how to provide this access.<br />
Authentication using SSL<br />
SSL allows the client to authenticate the identity of the server. This is called<br />
server authentication.<br />
SSL <strong>Version</strong> 3 also allows the server to authenticate a client. This is called<br />
client authentication, and is used if the server needs to check who a client is<br />
before responding. If SSL client authentication is enabled, the server requests<br />
the client’s certificate whenever the client makes an SSL connection. The<br />
server validates the DN information in the client request against the DN<br />
information in the client’s certificate before serving the document.<br />
SSL uses public key (asymmetric) encryption for a security “handshake” when<br />
establishing a TCP/IP connection between the client and the server. Figure 3<br />
on page 9 illustrates SSL handshaking with server authentication. During the<br />
handshake, the client receives the server’s digital (X.509) certificate. The client<br />
authenticates the server, using a list of known CAs. Also, if the client requests<br />
a document protected by SSL client authentication, the server requests the<br />
client’s certificate. The client then generates a random symmetric key and<br />
encrypts it using server’s public key. SSL then uses the symmetric key to<br />
encrypt and decrypt all of the information in both the client request and the<br />
server response, including:<br />
v The URL the client is requesting<br />
v The contents of any form being submitted<br />
v Authentication information, such as user names and passwords<br />
v All data sent between the client and the server<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Client Server<br />
Client issues secure session request<br />
(https.//someserver.org/somedata.html)<br />
Server sends X.509 certificate containing server’s public key<br />
Client authenticates certificate against list of known CA’s<br />
(If CA is unknown browser can give user option to accept certificate at user’s risk)<br />
Client generates random symmetric key and encrypts it using server’s public key<br />
Client and server now both know the symmetric key<br />
and encrypt end-user data using symmetric key for duration of session<br />
Figure 3. SSL handshaking with server authentication<br />
Network security<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports the following implementations of SSL:<br />
SSLight<br />
An implementation of SSL that is written in pure Java.<br />
This protocol is supported for compatibility with previous<br />
versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for<br />
SSLight might be removed in a future release.<br />
JSSE<br />
Another Java implementation, that provides support for 128<br />
bit encryption.<br />
IBM recommends that you use JSSE in preference to SSLight.<br />
See “Migration from SSLight” on page 86, for more<br />
information.<br />
System SSL<br />
Chapter 1. Overview 9
Network security<br />
This implementation, which is written in native code, is<br />
supported only for SSL servers on z/OS. It supports hardware<br />
encryption technology available to the z/OS operating system.<br />
Client side code always uses SSLight. However, IBM<br />
recommends that you use System SSL on the server side, in<br />
preference to SSLight, because it improves performance<br />
significantly. The strongest level of cryptographic strength that<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports is DES 56-bit. However,<br />
on z/OS it is possible to import a VeriSign Step-Up Server<br />
certificate that enables the SSLight client code, and other<br />
export-strength SSL clients, to increase their cryptographic<br />
strength dynamically to 128-bit.<br />
HTTPS<br />
HTTPS is a protocol that combines SSL and HTTP, and is used for handling<br />
secure transactions. You specify https:// as an anchor in HTML documents<br />
that link to documents protected by SSL. A client user can also open a URL by<br />
specifying https:// to request an SSL-protected document.<br />
Because HTTPS and HTTP are different protocols, and usually use different<br />
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests<br />
at the same time. This allows you to provide information to all users using no<br />
security, and specific information only to browsers which make secure<br />
requests. This is how retail companies on the Internet allow users to look<br />
through the merchandise without security, but then fill out order forms and<br />
send their credit card numbers using security.<br />
Security exits<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides exits that enable the user to define<br />
security operations such as public key encryption. They may also be used for<br />
data compression. Some example source files are provided in this directory:<br />
/samples/java/com/ibm/ctg/samples/security<br />
Java technology<br />
You can also use the security exits to authenticate an X.509 client certificate<br />
when client authentication is enabled.<br />
For more information, refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide book.<br />
This section discusses the Java language, including the types of program that<br />
can be developed, and the security implications.<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
The Java language<br />
Java is an interpreted object-oriented language, similar to C++. It can be used<br />
to build programs that are independent of operating systems in both source<br />
and object form. Its unique operational characteristics, which span Web<br />
browsers as well as Web servers, enable new and powerful functions in<br />
Internet applications.<br />
To achieve operating system independence, the Java language allows no<br />
operations that are dependent on specific operating system. Also, it excludes<br />
some C++ functions such as a preprocessor, operator overloading, multiple<br />
inheritances, and pointers. All Java programming is encapsulated within<br />
classes, and the Java Development Kit (JDK) includes special classes that are<br />
critical to assuring operating system independence, including GUI functions,<br />
input/output functions, and network communications.<br />
The Java compiler produces an intermediate bytecode format that is machine<br />
independent. This, in turn, is processed at run time by a Java interpreter. The<br />
interpreter also inspects the bytecode at run time to ensure its validity and<br />
safety to the machine environment. Because of the isolation the Java<br />
interpreter provides, it is sometimes referred to as a Java Virtual Machine<br />
(JVM).<br />
The Java language can be used to construct Java servlets, Java applets, and Java<br />
applications.<br />
Java applets<br />
Java applets are supported for compatibility with previous versions of <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be removed in a<br />
future release. It is recommended that you use Java applications, or Java<br />
servlets, when developing new solutions.<br />
Java servlets<br />
Java servlets are small Java applications that run on a Web server machine,<br />
unlike Java applets, which are downloaded to a Web browser.<br />
Java servlets have become popular as a replacement for CGI (Common<br />
<strong>Gateway</strong> Interface) programs. The advantage of Java servlets over CGI<br />
applications is that they can execute more quickly since they are invoked as<br />
threads in a daemon process, meaning that they are persistent in memory and<br />
can fulfill multiple requests.<br />
Note that servlets must ensure references to the gateway objects are<br />
thread-safe.<br />
Java technology<br />
Chapter 1. Overview 11
Java technology<br />
Java applications<br />
A Java application is a program that executes locally on a computer. It has<br />
operating system dependent capabilities in addition to those of an applet. It<br />
can access local files, create and accept general network connections, and call<br />
native C or C++ functions in machine-specific libraries.<br />
Java applications can use the <strong>CICS</strong>-provided Java classes to perform<br />
transaction processing in <strong>CICS</strong> systems. They can use the Java<strong>Gateway</strong> class<br />
to establish two kinds of connection:<br />
v A network gateway connection is a connection across a network to a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
v A local gateway enables a Java application to communicate directly with a<br />
<strong>CICS</strong> <strong>Transaction</strong> Server, without the need for a network.<br />
When the connection between the application and the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> has been established, an application can use the ECIRequest class,<br />
for example, to do transaction processing.<br />
Firewalls<br />
A current design consideration in the use of Java applet communication is the<br />
impact of firewalls. This is the term given to a configuration of software that<br />
prevents unauthorized traffic between a trusted network and an untrusted<br />
network. Firewalls are put in place to protect company assets from outside<br />
intrusion, but they can also limit legitimate communications. Firewalls have<br />
two functions:<br />
1. To restrict access to a server by outside users - inbound restrictions<br />
2. To limit the ability of users inside a firewall to perform certain network<br />
functions outside their firewall - outbound restrictions.<br />
A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration is well suited to avoid problems in<br />
the first area since the <strong>Gateway</strong> processor can be placed outside the firewall<br />
and be connected through the firewall to the <strong>CICS</strong> server. Outbound firewalls<br />
that users may have to contend with can be a problem. A large company<br />
might use a firewall to limit the types of connections and protocols that can<br />
be used.<br />
The use of Java on an intranet (a local implementation of the Internet) works<br />
very well since firewalls are typically not a factor. If you are designing<br />
applications to run over the Internet (rather than an intranet), determine<br />
whether your potential users are behind firewalls. If so, consider alternative<br />
processing for those users, such as executing the Java code as a Java servlet<br />
on the Web server. Also consider using HTTP and HTTPS protocols supported<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Authentication using SSL” on page 8 and<br />
“HTTPS” on page 10.<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Java technology<br />
Web servers<br />
A Web server is a software program that responds to information requests<br />
generated by Web browsers. When a request from a browser is received, the<br />
Web server processes the request to determine the action to take:<br />
v Return the requested document.<br />
v Deny the request.<br />
v Pass the request through for further processing by an external application.<br />
The request might be, for example, to a database to perform a search<br />
request, or to a more dynamic form of information delivery such as Lotus ®<br />
Domino .<br />
Communication between a Web server and an external application is<br />
transparent; you need to know only the URL of the Web server to direct a<br />
request to it. Also, all Web servers can handle requests from many browsers<br />
concurrently.<br />
Specialized servers can also be configured to limit access to a restricted set of<br />
users, or to provide security for purchase of goods or services.<br />
Web servers exist for almost every operating system and are available from<br />
many suppliers. For information on the Web servers supported by <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, see “Software requirements” on page 20.<br />
The J2EE resource adapters<br />
An API in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java programmers to take<br />
advantage of features provided in J2EE-compliant runtime environments (e.g.<br />
IBM WebSphere Application Server). The J2EE resource adapter defines a<br />
standard architecture for connecting the Java 2 Platform, Enterprise Edition<br />
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as <strong>CICS</strong>.<br />
The resource adapter architecture defines a set of scalable, secure, and<br />
transactional mechanisms that enable the integration of EISs with application<br />
servers and enterprise applications.<br />
A proprietary application server, such as IBM WebSphere, can be extended to<br />
support the resource adapter architecture, and is then assured of a seamless<br />
connectivity to multiple EISs. Similarly, a vendor provides a standard resource<br />
adapter that can connect any application server that supports the resource<br />
adapter architecture to an EIS.<br />
The resource adapter architecture defines a Common Client Interface (CCI) for<br />
EIS access. The CCI defines a client API for interacting with heterogeneous<br />
EISs. The resource adapter architecture enables a vendor such as IBM to<br />
provide a standard resource adapter to allow access to its product. This<br />
Chapter 1. Overview 13
Introduction<br />
resource adapter connects to an application server and provides connectivity<br />
between the EIS, the application server, and the enterprise application.<br />
The Programming using J2EE chapter in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide describes the J2EE resource adapters. The chapter includes information<br />
on the J2EE samples which are provided.<br />
The samples.txt file, in the \samples subdirectory, provides<br />
additional information on the J2EE sample programs.<br />
How <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> accesses <strong>CICS</strong><br />
This section describes how <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> allows Java servlets to<br />
access <strong>CICS</strong> programs and data.<br />
1. The Web server loads and initializes the servlet. This could be when the<br />
Web server starts, or when the first request is made to the servlet by the<br />
Web browser or network computer.<br />
2. The servlet creates a Java<strong>Gateway</strong> object to connect to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. This establishes communication between the browser<br />
and the long running <strong>Gateway</strong> daemon process using Java’s sockets<br />
protocol.<br />
3. When a HTTP request from the Web browser or network computer<br />
invokes the servlet, the Web server calls its Service method with details of<br />
the request.<br />
4. The servlet creates an ECIRequest object, that contains ECI calls, and<br />
sends it to the <strong>CICS</strong> server using the Java<strong>Gateway</strong>.flow method.<br />
5. The <strong>CICS</strong> server processes the calls, including verification of the userid<br />
and password if required, and passes control and user data to the <strong>CICS</strong><br />
application program.<br />
6. When the <strong>CICS</strong> application program has finished processing, it returns<br />
control and data to <strong>CICS</strong>.<br />
7. The <strong>CICS</strong> server returns control and data to the Java servlet.<br />
8. When the servlet receives the results, it generates a HTTP response to<br />
return to the Web browser.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a multithreaded model for handling<br />
network connections, and for assigning threads for requests from, and replies<br />
to, Java clients. The threading model uses the following objects:<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
ConnectionManagers<br />
A ConnectionManager manages all the connections from a particular Java<br />
client. When it receives a request, it allocates a Worker thread from a pool of<br />
available Worker threads to execute the request.<br />
Workers<br />
A Worker is the object that actually executes a request from a Java client<br />
application. Each Worker object has its own thread, which is activated when<br />
there is some work to do. When a worker thread has finished processing it<br />
returns to the pool of available worker threads.<br />
You can set both the initial and maximum sizes of the resource pools for these<br />
objects; see “General <strong>Gateway</strong> settings” on page 56 for information on setting<br />
configuration parameters. You can also specify these limits when you start the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see “Starting from a command line” on page 117.<br />
Table 3 shows thread limits that should be considered when setting the<br />
number of Connection Manager and Worker threads on the various operating<br />
systems:<br />
Table 3. Thread limits on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> operating systems<br />
Operating<br />
system<br />
System-wide limit of<br />
the maximum number<br />
of threads<br />
z/OS This may be restricted<br />
by the total number of<br />
MVS ® Task Control<br />
Blocks (one is created<br />
per UNIX System<br />
Services thread)<br />
Process limit of the number of threads<br />
Governed by the UNIX System Services<br />
parameters: MAXTHREADS and<br />
MAXTHREADTASKS<br />
Windows No limit Limited by the amount of virtual memory<br />
available for the process (by default a<br />
thread has 1M of stack meaning that 2028<br />
threads can be created per process)<br />
AIX 262 143 32 768<br />
HP-UX No limit (30 000 kernel<br />
threads)<br />
Linux Equal to the maximum<br />
number of processes<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
Solaris No limit No limit<br />
30 000 (refer to Configurable Kernel<br />
Parameters in the SAM utility)<br />
1024 (refer to your LinuxThreads<br />
documentation for more information)<br />
You can determine what values have been set for the UNIX System Services<br />
parameters MAXTHREADS and MAXTHREADSTASK by examining the<br />
Chapter 1. Overview 15
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model<br />
Applet/application<br />
Java<strong>Gateway</strong>.open<br />
JG.flow(ECIRequest)<br />
appropriate BPXPRMxx member of SYS1.PARMLIB. For more information<br />
about these parameters, refer to the Z/OS UNIX System Services Planning book.<br />
For more information on the way Java allocates memory for threads, refer to<br />
“Performance issues” in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
book.<br />
The threading model is illustrated in the following figures:<br />
Network<br />
handshake<br />
tcp:/ssl:<br />
Protocol<br />
handlers<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Connection<br />
managers Workers<br />
ready for<br />
new work<br />
EXCI<br />
wait<br />
<strong>CICS</strong><br />
server<br />
Figure 4. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for TCP/IP and SSL. These protocols have a persistent socket.<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
EXCI<br />
reply
Applet/application<br />
Java<strong>Gateway</strong>.open<br />
JG.flow(ECIRequest)<br />
Network<br />
handshake<br />
http:/https:<br />
Protocol<br />
handlers<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Connection<br />
managers Workers<br />
ready for<br />
new work<br />
EXCI<br />
wait<br />
<strong>CICS</strong><br />
server<br />
EXCI<br />
reply<br />
Figure 5. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> threading model for HTTP/HTTPS. These protocols do not have a persistent<br />
socket.<br />
Chapter 1. Overview 17
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 2. Planning your installation<br />
This chapter helps you plan the installation of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for z/OS by listing the software, Web Servers and browsers that are<br />
supported. It also has information for those who are using an earlier version<br />
of the product.<br />
For information on supported software and hardware requirements for other<br />
CTG platforms, see Appendix A, “Hardware and software” on page 155.<br />
“Disk space requirements” Read this for information on disk space<br />
needed to install and run the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Software requirements” on page 20 Read this for information on the software<br />
you need to run the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
“Checking the z/OS shell environment”<br />
on page 22<br />
Read this for information on how to<br />
check that your z/OS shell environment<br />
is set up correctly.<br />
“National Language Support” on page 22 Read this for information on languages<br />
that are supported.<br />
“Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java<br />
(MVS)” on page 23<br />
“Migrating from <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for OS/390 <strong>Version</strong> 3” on<br />
page 24<br />
Read these if you currently using an<br />
earlier version of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
See the product readme file for any late changes to hardware and software<br />
requirements.<br />
If you are installing from CD, the readme file is README.ZOS in the root<br />
directory.<br />
If you have downloaded the product, the packaged file that you downloaded<br />
contains the product code and the readme file for your operating system.<br />
Disk space requirements<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is normally installed into a directory such as<br />
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,<br />
during installation, the uncompressed tar file is present in the /usr/lpp<br />
directory. The HFS data set for this directory must be large enough to take the<br />
© Copyright IBM Corp. 1996, 2002 19
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Disk space requirements<br />
25MB (40 cylinders) that this file occupies. You can delete the files once<br />
installation is complete. Installation also requires 25MB (40 cylinders) in the<br />
/tmp directory.<br />
Once installed, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> occupies 27MB. You need enough<br />
disk space for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and any logging and tracing files.<br />
IBM recommends that you use a separate HFS data set with a primary<br />
allocation of 40 cylinders for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software. Increase this<br />
to 50 cylinders if the logging and trace files will be stored in the same HFS<br />
data set. Increase it further if many instances of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will run, or if much logging is required. Alternatively, you can use a separate<br />
HFS data set, with a primary allocation of 5 cylinders, for each instance of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
If you use the existing /usr/lpp HFS data set, ensure it has enough space to<br />
take the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software.<br />
Software requirements<br />
The following products are supported.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v OS/390 V2.10<br />
v z/OS V1.2<br />
Web browsers<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft ® Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v z/OS: IBM Java SDK 1.3<br />
If using the IBM Persistent Reusable JVM, you are recommended to run at a<br />
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable<br />
functionality of this JVM.<br />
If using Java under DBCS code pages, especially IBM-939, install service<br />
refresh 14 or later.<br />
JSSE<br />
Software requirements<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– z/OS with JRE 1.3.1: includes a version of JSSE that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> supports<br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied. Apply z/OS APAR PQ38644, for EXCI, if you<br />
are using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF<br />
UQ99329 (Service Level W401030).<br />
Chapter 2. Planning your installation 21
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Checking the z/OS shell environment<br />
Checking the z/OS shell environment<br />
1. Before you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, ensure that the z/OS shell<br />
environment is set up correctly. The default system-wide user environment<br />
is specified in the /etc/profile file. User overrides to this are in the user’s<br />
~/.profile file. Check the following:<br />
v The PATH statement includes the binary directory where java is located,<br />
for example:<br />
export PATH=/usr/lpp/java/J1.3/bin:$PATH<br />
If you are also running an older version of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>,<br />
the path to JDK 1.3 must appear before the JDK for the older version of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v The JAVA_COMPILER environment variable is set to jitc and the<br />
LIBPATH is set appropriately, if the Java JIT compiler is to be used.<br />
Note: JIT compilers may cause problems with the HTTPS and SSL<br />
protocols and therefore may need to be disabled if you wish to<br />
use these secure protocols.<br />
export JAVA_COMPILER=none<br />
2. If you will run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> applications in local mode, or<br />
you have set AUTH_USERID_PASSWORD to Yes, set the following<br />
environment variable, in the environment under which the Java<br />
applications will run:<br />
JAVA_PROPAGATE=NO<br />
If you do not do this, ECI calls will fail with an<br />
ECI_ERR_SECURITY_ERROR return code.<br />
For more information about setting the z/OS shell environment, see the Z/OS<br />
UNIX System Services User’s Guide, SC28-1891 book.<br />
National Language Support<br />
Only English, Japanese and Simplified Chinese are supported. (These are the<br />
languages supported by <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS.) See Appendix B,<br />
“Supported code pages” on page 163 for supported code pages.<br />
Coexistence with other products<br />
WebSphere Application Server for OS/390 v3.5<br />
WebSphere Application Server for OS/390 v3.5 fully supports servlets that<br />
use the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Common Connector Framework (CCF)<br />
ECI connector or ECIRequest class, but does not support the J2EE <strong>CICS</strong><br />
ECI connector.<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Coexistence with other products<br />
WebSphere Application Server for z/OS v4.0 plugin<br />
The plugin provides a WAS v3.5 SE runtime environment that fully<br />
supports v3.5 servlets that use the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> CCF ECI<br />
connector or ECIRequest class. You are recommended to run existing<br />
applications under the plugin. The J2EE <strong>CICS</strong> ECI connector is not<br />
supported within this environment. The plugin is provided for migration<br />
purposes only.<br />
WebSphere Application Server for z/OS v4.0 runtime migration issues<br />
Under the WAS v4.0 Runtime environment, the following restrictions<br />
apply:<br />
1. In the WAS v3.5 environment (or under the WAS v4.0 Plugin), the<br />
userid that has been authenticated by the HTTP server is automatically<br />
passed to <strong>CICS</strong> when using the CCF ECI connector or ECIRequest<br />
class, if a null userid and password are specified on the ECI call. This<br />
mechanism does not work under the WAS v4.0 Runtime environment<br />
as the authenticated userid is not available on the ACEE associated<br />
with the WebSphere thread on which the CTG runs in local mode.<br />
2. The WAS v4.0 Runtime provides limited support for CCF <strong>CICS</strong><br />
Connector and ECIRequest calls that form part of an extended LUW.<br />
These calls must all be issued from the same thread, otherwise an<br />
error of ECI_ERR_LUW_TOKEN will be returned. Also, there must<br />
only be one outstanding LUW on any given thread at a time.<br />
For CCF solutions, it is recommended that you use the WAS v4.0 Plugin<br />
and then migrate to using J2EE.<br />
If you are using the ECIRequest class extended LUW mode, it is<br />
recommended that you use the WAS v4.0 Plugin and then migrate to J2EE<br />
or to a non-extended LUW solution.<br />
There is a new EciRequest class method SetGlobalTranSupport. If this<br />
method is called on a non-extended ECIRequest, and a global transaction<br />
is associated with the current RRS context, the request will join the global<br />
transaction. Otherwise the request will be issued with sync on return. This<br />
gives two-phase commit capability.<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java (MVS)<br />
If you have customized the <strong>Gateway</strong>s.properties or the JGate script, save a<br />
copy of them before you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
In <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for OS/390 <strong>Version</strong> 3.1, the <strong>Gateway</strong>.properties<br />
file was renamed to CTG.INI and the JGate script to ctgstart. Convert old<br />
Chapter 2. Planning your installation 23
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java (MVS)<br />
<strong>Gateway</strong>.properties files to the new format. See “Using the configuration tool”<br />
on page 52 for the new settings, and refer to the CTGSAMP.INI file for the<br />
correct format.<br />
Change all import statements in your programs and recompile them. Change<br />
all occurrences of:<br />
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*<br />
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*<br />
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user<br />
classes that implement these interfaces need to be changed. The TCP/IP<br />
address of the remote computer is now passed to the methods called to<br />
generate handshake data. An afterDecode method has also been added to<br />
both interfaces.<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for OS/390 <strong>Version</strong> 3<br />
If you have customized the JGate script (used to set environment variables),<br />
save a copy before you install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS <strong>Version</strong><br />
<strong>Version</strong> <strong>5.0</strong>.<br />
In <strong>Version</strong> 3.1, the <strong>Gateway</strong>.properties file was renamed to CTG.INI, and the<br />
JGate script to ctgstart. Convert old <strong>Gateway</strong>.properties files to the new<br />
format. See “Using the configuration tool” on page 52 for the new settings,<br />
and refer to the CTGSAMP.INI file for the correct format.<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4<br />
Delete file /license before attempting to install <strong>Version</strong> <strong>5.0</strong>.<br />
This file contains license information for version 4 of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. ctginstall creates a directory called /license to<br />
store license information for <strong>Version</strong> 5. If a file of the same name exists,<br />
ctginstall cannot create the directory, and the installation fails.<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Chapter 3. Installation<br />
This chapter describes how to install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS. It<br />
consists of the following:<br />
Table 4.<br />
“Installation: overview” on page 26 Read this for an overview of the steps<br />
involved in installing the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Installation: detail” on page 27 Read this for detailed instructions on how<br />
to install the <strong>Gateway</strong>.<br />
“Installing into a locale other than 1047<br />
(U.S. English)” on page 32<br />
Read this for information about installing<br />
in Japanese or Simplified Chinese.<br />
“Directory structure” on page 33 Read this for information on the directory<br />
structure that is created during<br />
installation.<br />
“Uninstalling the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for z/OS” on page 34<br />
“Using X-Windows from a remote<br />
system” on page 34<br />
“Extracting and installing the PDF<br />
library” on page 35<br />
Read this if you want to uninstall the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Read this for information on how to<br />
access z/OS applications from a remote<br />
system.<br />
Read this for information on how to view<br />
the manuals on the CD.<br />
“Service and updates” on page 36 Read this for information on obtaining<br />
service and updates to the program.<br />
© Copyright IBM Corp. 1996, 2002 25
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
Installation: overview<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is provided as the compressed file<br />
ctg-500m.tar.Z, which contains the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software that is<br />
to be installed in the hierarchical file system (HFS). This section outlines the<br />
steps that you need to take to install the software on your system. For<br />
detailed instructions see “Installation: detail” on page 27.<br />
v If you are installing into a test environment, you can omit steps marked<br />
(Optional) . Step 2 is optional, because you do not need to create a<br />
separate HFS data set for installation into a test environment.<br />
v If you are installing into a production environment, follow all the steps in<br />
“Installation: detail” on page 27. In a production environment, you are<br />
recommended to install into a separate HFS data set.<br />
__ Step 1. Step 1: Gather information and obtain the necessary permissions.<br />
__ Step 2. Step 2: (Optional) Make a safe home for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. You will install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> into this<br />
data set.<br />
__ Step 3. Step 3: Upload, unpack and install.<br />
After you have installed the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, follow these steps to<br />
configure and test your installation:<br />
__ Step 4. Configure your <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS; see Chapter 4,<br />
“Configuring the <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS” on page 37.<br />
__ Step 5. Configure your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> by creating files:<br />
v CTG.INI<br />
v ctgenvvar<br />
See “Editing the sample configuration files” on page 43.<br />
__ Step 6. Test your configuration; “Testing your configuration” on page 117.<br />
You are recommended to print the instructions, and check off completed steps<br />
in the “Installation: overview” section.<br />
OMVS features<br />
Some responses take a long time to complete, and the terminal mode changes<br />
from RUNNING to INPUT before the command has finished. If you see<br />
INPUT in the bottom right of your screen, press ENTER to receive more<br />
output.<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation: detail<br />
This section gives detailed instructions on installing the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Step 1: Gather information and obtain the necessary permissions<br />
You are recommended to record the following:<br />
Variable Explanation Required<br />
in<br />
The directory to which your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> will be<br />
installed. This is always<br />
/ctg<br />
The directory to which you will<br />
upload the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, for example usr/lpp<br />
The HFS data set where the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> will be kept,<br />
for example OMVS.USR.LPP.CTG500<br />
The HFS dataset which will be<br />
used for the logs, for example<br />
OMVS.USR.LPP.CTGLOGS<br />
The Netname for the MRO<br />
connection on <strong>CICS</strong>.; see Figure 6<br />
on page 38. This is the same as<br />
the DFHJVPIPE environment<br />
variable, set through ctgenvvar.<br />
See Figure 6 on page 38; the <strong>CICS</strong><br />
that appears in the<br />
bottom right of the CEDA<br />
transaction screen.<br />
The location of the installed <strong>CICS</strong><br />
EXCI load library, for example,<br />
<strong>CICS</strong>TS22.<strong>CICS</strong>.SDFHEXCI<br />
The location of any optional user<br />
override options for EXCI, for<br />
example, USERID.LOAD.LIB<br />
Steps 2<br />
and 3.<br />
Steps 2<br />
and 3.<br />
Your value<br />
Step 2 (Optional)<br />
Step 2 (Optional)<br />
Steps 4<br />
and 5<br />
Steps 4<br />
and 5<br />
Step 5<br />
Step 5<br />
Installation<br />
You need to be logged in as root, or have superuser authority (UID=0) to<br />
perform the steps marked (Optional)<br />
Chapter 3. Installation 27
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
For the CTG and logs datasets, you are recommended to use a naming<br />
convention that reflects the location of the datasets in the USS structure, and<br />
that allows for different versions of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. If the<br />
for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong> is /usr/lpp/ctg, the<br />
following names would be suitable:<br />
<br />
OMVS.USR.LPP.CTG500<br />
<br />
OMVS.USR.LPP.CTG.LOGS<br />
The HFS data set that you choose to allocate to hold the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> HFS can be any data set name, but to mount it into the root file<br />
system the UNIX System Services kernel task must have UPDATE access to<br />
the data set that you create. Normally, the high-level qualifier that you use for<br />
(shown as OMVS in the example), is the same as that for the<br />
HFS data set of the root file system. Consequently RACF will probably<br />
already allow OMVS the necessary access to data sets with that high-level<br />
qualifier. However, if you choose a data set high-level qualifier that differs<br />
from that of the root file system you must issue RACF commands to give the<br />
OMVS kernel task userid UPDATE access to your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
HFS data set.<br />
You have completed this step. Mark as completed checklist Step 1 on page 26.<br />
Step 2: (Optional) Make a safe home for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
The “Installation: overview” on page 26 section explains why this step is<br />
optional.<br />
Stage A — make the directory<br />
The directory is always the ctg subdirectory of the<br />
. Create this directory if it does not already exist, using one of<br />
these methods:<br />
OMVS and Telnet<br />
1. Issue this command to change to the :<br />
cd <br />
2. Create the subdirectory:<br />
mkdir ctg<br />
3. Allow yourself read and write access to the directory. Other users have<br />
read access:<br />
chmod 755 ctg<br />
TSO ISHELL<br />
1. Issue the command N, for new.<br />
2. On the Create a New File dialog box, set the following:<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Pathname :<br />
Permissions :755<br />
File type :1 (Directory)<br />
The command fails if the does not already exist, or you<br />
do not have permission to write to it. In these cases:<br />
v Modify the steps above to create the directory; or<br />
v Request write permissions from the owner of the directory<br />
Stage B — create and mount an HFS data set to hold the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong><br />
requires 25 MB, or 40 cylinders. Sample JCL, which does<br />
everything in this stage, is provided in file<br />
/samples/CTGMAKE.JCL; this file is available if you have<br />
previously installed into a test environment.<br />
1. Use either TSO or ISPF to create the data set.<br />
TSO<br />
Issue the following command:<br />
ALLOC DA(’’) DSNTYPE(HFS) SPACE(40,5) DSORG(PO) CYL<br />
ISPF<br />
a. Use the Data Set Utility screen (option 3.2):<br />
Option : A<br />
Dataset name : ’’<br />
b. Set the following on the Allocate New Data Set screen:<br />
Space Units :CYLS<br />
Primary quantity :40<br />
Secondary quantity :5<br />
Data set name type :HFS<br />
2. Use the following TSO command to mount the data sets in to existing<br />
directories:<br />
MOUNT TYPE(HFS)<br />
MODE(RDWR)<br />
MOUNTPOINT(’’)<br />
FILESYSTEM(’’)<br />
3. The mount will be lost at the next IPL. To mount the data set permanently,<br />
add the above command to the member BPXPRMxx in SYS1.PARMLIB,<br />
where xx is the suffix referenced by the BPX= option in the IEASYSxx<br />
member of SYS1.PARMLIB.<br />
Stage C — make the /logs directory<br />
This has to be done now as mounting the in “Stage B —<br />
create and mount an HFS data set to hold the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>”<br />
replaces any data already in the .<br />
Use one of these methods to create the directory, if it does not exist:<br />
Installation<br />
Chapter 3. Installation 29
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
OMVS and Telnet<br />
1. Issue this command to change to the :<br />
cd <br />
2. Create the subdirectory:<br />
mkdir logs<br />
3. Allow yourself read and write access to the directory. Other users have<br />
read access:<br />
chmod 755 logs<br />
TSO ISHELL<br />
1. Issue the command N, for new.<br />
2. On the Create a New File dialog box, set the following:<br />
Pathname :/logs<br />
Permissions :755<br />
File type :1 (Directory)<br />
The command fails if the does not already exist, or<br />
you do not have permission to write to it. In these cases:<br />
v Modify the steps above to create the directory; or<br />
v Request write permissions from the owner of the directory<br />
Stage D — create and mount an HFS data set to hold the logs<br />
1. Use either ISPF or TSO to create the dataset.<br />
requires less than 5 MB, or 5 cylinders, for each <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> running. Increase the primary allocation if you will<br />
run more than one instance of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
TSO<br />
Issue the following command:<br />
ALLOC DA(’’) DSNTYPE(HFS) SPACE(5,5) DSORG(PO) CYL<br />
ISPF<br />
a. Use the Data Set Utility screen (option 3.2):<br />
Option :A<br />
Dataset name :’’<br />
b. Set the following on the Allocate New Data Set screen:<br />
Space Units :CYLS<br />
Primary quantity :5<br />
Secondary quantity :5<br />
Data set name type :HFS<br />
2. Use the following TSO command to mount the log data set:<br />
MOUNT TYPE(HFS)<br />
MODE(RDWR)<br />
MOUNTPOINT(’//logs’)<br />
FILESYSTEM(’’)<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
3. The mount will be lost at the next IPL. To mount the data set permanently,<br />
add the above command to the member BPXPRMxx in SYS1.PARMLIB,<br />
where xx is the suffix referenced by the BPX= option in the IEASYSxx<br />
member of SYS1.PARMLIB.<br />
You have completed this step. Mark as completed checklist Step 2 on page 26.<br />
Step 3: Upload, unpack and install<br />
Installation<br />
1. To upload file ctg-500m.tar.Z, mount the CD on either a workstation<br />
connected to the System/390 ® , or another system with access to the<br />
System/390. Use one of the following methods to upload the file:<br />
Workstation file transfer<br />
a. Pre-allocate a data set of 30 cylinders to hold the compressed file,<br />
for example CTG-500M.TAR.Z.<br />
b. Upload the file to that data set, using the terminal emulator<br />
transfer options for a binary file.<br />
c. Use the OPUT command on TSO to put the data set in HFS, for<br />
example:<br />
OPUT ’CTG-500M.TAR.Z’ ’/ctg-500m.tar.Z’ BINARY<br />
FTP<br />
v Use an FTP client to upload the compressed TAR file to the<br />
directory.<br />
v Specify an HFS (not z/OS) data set as the destination.<br />
v Transfer the file in binary mode.<br />
v Do not specify any attributes appropriate to a z/OS data set, such<br />
as lrecl.<br />
2. To uncompress the file, use these commands from an OMVS or Telnet<br />
screen:<br />
cd <br />
uncompress ctg-500m.tar.Z<br />
3. To extract the file that you uncompressed in the previous step, use the<br />
command<br />
tar -xopvf ctg-500m.tar<br />
where:<br />
v -x specifies that all files are extracted.<br />
v -o allows the original file permission bits for owner, group and all to be<br />
restored. This is useful for all the execute bits.<br />
v -p does not try to restore the original owner and group id when<br />
extracting files. The default is to do this, but most likely the person<br />
doing the extract will not have permission, or the user id will not exist<br />
on the system.<br />
Chapter 3. Installation 31
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
v -v specifies verbose messages (optional). This generates many messages,<br />
but gives useful information on what is happening.<br />
v -f Specifies the file name of the archive file.<br />
4. Use a program like OEDIT to view file /ctginstall.readme,<br />
containing the latest instructions on installation.<br />
5. Type ctginstall to begin installation. The script checks the level of z/OS<br />
you have installed.<br />
If any of the prerequisites are not available, the ctginstall script generates<br />
information messages and terminates. Fix any problems before you run the<br />
script again.<br />
6. Type 1 to continue installation by reading and accepting the license<br />
agreement. You must accept the license to install the product; if you select<br />
2 the installation program ends.<br />
Note: If the word INPUT appears in the bottom right corner of your<br />
screen while you are reading the license, press Enter to continue<br />
viewing.<br />
7. If the agreement does not display properly, restart the installation using<br />
the command ctginstall 40. This sets your screen width to 40 characters<br />
during installation.<br />
After you have accepted the agreement, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
installed into the directory. All necessary subdirectories are<br />
created.<br />
8. Print and read the README.TXT file, which may contain information not in<br />
the books.<br />
9. (Optional) Create a job if you want to run the <strong>Gateway</strong> as a batch job.<br />
You can use the sample JCL at “Starting with JCL” on page 121 as a<br />
starting point.<br />
You have completed your installation. Mark as completed checklist Step 3 on<br />
page 26.<br />
Installing into a locale other than 1047 (U.S. English)<br />
You can install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS in Japanese or<br />
Simplified Chinese, but the limitations of Unix System Services (USS) and the<br />
EBCDIC character set require you to take extra steps. See<br />
/ctginstall.readme for details of converted versions of the<br />
ctginstall script.<br />
Whichever locale is used, the datastream flows between a client application<br />
and <strong>CICS</strong> Server are not affected.<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
See “The configuration tool” on page 139 for restrictions on using the<br />
configuration tool in DBCS environments.<br />
Changing the code page after installation<br />
Whether installed as IBM-1047 or another code page (code set), the installation<br />
can be converted to another code page by running the command:<br />
/bin/ctgmsgs <br />
in the current code page of the installation. To display the supported language<br />
and code set combinations, issue the command:<br />
/bin/ctgmsgs -?<br />
Directory structure<br />
The following is the directory structure of the installed <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>:<br />
Table 5. Contents of directories<br />
Relative path Contents<br />
A ctg subdirectory in a location defined<br />
by the user. For example:/usr/lpp/ctg.<br />
/bin <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> executable<br />
code.<br />
/classes Java classes.<br />
/deployable RAR files.<br />
/docs Documentation for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. This contains the documentation<br />
Library in PDF format, and the javadoc<br />
directory.<br />
/license License files. To view your license, issue<br />
the command ctgbrowse. If the agreement<br />
does not display properly, issue the<br />
command ctgbrowse 40. This sets your<br />
screen width to 40 characters while you<br />
are viewing the agreement.<br />
/msgs NLS message files, used by scripts.<br />
/samples Java source files for samples.<br />
/bin/resource NLS resource files.<br />
After installation, you may want to browse these files in the<br />
/bin subdirectory:<br />
CTGSAMP.INI Sample configuration file<br />
Installation<br />
Chapter 3. Installation 33
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Installation<br />
ctgenvvarsamp Sample environment variables file<br />
ctgcfg Script to start configuration tool<br />
ctgikey Script to start ikeyman<br />
ctgstart Script to start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
itself.<br />
The files in the /samples/java/com/ibm/ctg/samples/security<br />
subdirectory contain samples to demonstrate the basic functionality of the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security exits. The samples demonstrate<br />
compression of the client/server data flows using the java.util.zip package.<br />
Uninstalling the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS<br />
To uninstall <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, use this command:<br />
/bin/ctguninst<br />
Using X-Windows from a remote system<br />
You can use X-Windows on a remote system to access applications under<br />
z/OS. The X-Windows System is a network-transparent protocol that supports<br />
windowing and graphics. The protocol is communicated between an X client<br />
(application) and an X server over a TCP/IP network. X-Windows support is<br />
provided as part of the AIX product, and on Windows platforms by, for<br />
example, the Hummingbird ® Exceed product.<br />
In an X-Windows System environment, the X server is usually located on the<br />
workstation, and this distributes user input to, and accepts requests from, one<br />
or more X client programs located either on the same system or elsewhere on<br />
a network. This is an important point, as z/OS users will usually regard<br />
anything that runs on the host as the server and any application on the<br />
workstation as the client.<br />
Java and UNIX System Services do not fully support GUI (Swing and AWT<br />
based) applications running in double byte character systems (Japanese and<br />
Simplified Chinese). They do not provide easy access to the correct fonts. In<br />
this environment you can use the configuration tool only in English. Start it<br />
with the -LANG US option:<br />
ctgcfg -LANG US<br />
When using X-Windows from a remote system, for example, to access the<br />
configuration tool and iKeyman, you must set up the DISPLAY environment<br />
variable to allow the application to display its windows on that system.<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
On the display system (that is the one that will display the windows), enter<br />
the command:<br />
xhost +appl<br />
where appl is the network name of the system being used to run the<br />
application.<br />
On the application system, before you run the application, enter the<br />
command:<br />
DISPLAY=disp:0.0<br />
followed by<br />
export DISPLAY<br />
where disp is the host name or IP address of the system where the windows<br />
will be displayed (followed by a colon and the display id—normally 0.0). The<br />
application windows are then displayed on the disp system.<br />
To find the IP address on Windows platforms, enter the ipconfig command.<br />
To find the host name on UNIX platforms, enter the hostname command.<br />
You can add the statement:<br />
export DISPLAY=disp:0.0<br />
to your .profile file.<br />
Extracting and installing the PDF library<br />
Using X-Windows from a remote system<br />
The PDF library (CTG_Library.pdf) for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is located in<br />
the /docs subdirectory.<br />
Transfer the library to a system that can run the Adobe Acrobat Reader.<br />
(Currently no Adobe Acrobat Reader is available for z/OS.) For information<br />
about the Adobe Acrobat Reader, see www.adobe.com.<br />
If you have the product CD-ROM, you will also find this PDF book in the PDF<br />
directory.<br />
To transfer the PDF file to a Windows workstation, use FTP in binary mode,<br />
or proceed as follows:<br />
1. Use ISPF option 3.2 to allocate a data set with the name<br />
userid.CTGLIB.PDF, and which has the following attributes:<br />
Chapter 3. Installation 35
Using X-Windows from a remote system<br />
Service and updates<br />
Organization . . . : PS<br />
Record format . . . : VB<br />
Record length . . . : 32756<br />
Block size . . . . : 32760<br />
1st extent tracks . : 170<br />
Secondary tracks . : 10<br />
2. Enter the TSO command:<br />
OGET ’/docs/CTG_Library.pdf’<br />
’userid.CTGLIB.PDF’ BINARY<br />
to copy the CTG_Library.pdf file from UNIX System Services to the z/OS<br />
sequential data set userid.CTGLIB.PDF.<br />
3. Transfer userid.CTGLIB.PDF to your workstation, either by using FTP, or:<br />
a. Go to TSO READY on the z/OS system.<br />
b. Select Transfer on the top bar.<br />
c. Select Receive Files from Host.<br />
d. Specify:<br />
Host file : ’userid.CTGLIB.PDF’<br />
PC file : C:\temp\CTG_Library.pdf<br />
Transfer type : binary<br />
and select RECEIVE. When the RECEIVE has completed, you should<br />
have file CTG_Library.pdf in the temp directory on your workstation.<br />
You can then delete userid.CTGLIB.PDF from the z/OS system.<br />
Service and updates are available at the following Web site:<br />
www.software.ibm.com/ts/cics/support/details<br />
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 4. Configuring the <strong>CICS</strong> <strong>Transaction</strong> Server for<br />
z/OS<br />
This chapter describes how to configure EXCI connections, to allow the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to connect to a <strong>CICS</strong> region. It contains these topics:<br />
“<strong>CICS</strong> server connection definition” Read this for information on defining<br />
connections.<br />
“<strong>CICS</strong> server sessions definition” on<br />
page 40<br />
“Open interregion communication” on<br />
page 42<br />
“EXCI user-replaceable module<br />
DFHXCURM” on page 42<br />
For each connection, you need to provide<br />
information about the sessions.<br />
After you have defined your connections<br />
and session, you need to install the group<br />
and set interregion communication open.<br />
You might also wish to modify the EXCI<br />
user-replaceable module DFHXCURM.<br />
<strong>CICS</strong> server connection definition<br />
<strong>CICS</strong> <strong>Transaction</strong> Server provides example EXCI connection and session<br />
definitions (EXCG and EXCS) in the sample group DFH$EXCI. You can<br />
choose to:<br />
v Use them as they are; or<br />
v Copy them to form the basis of your own definitions; or<br />
v Create your own definitions using the instructions that follow<br />
The following are examples of a connection definition:<br />
© Copyright IBM Corp. 1996, 2002 37
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
VIEW GROUP(MYEXCI) CONNECTION(JCOS)<br />
OBJECT CHARACTERISTICS <strong>CICS</strong> RELEASE = 0620<br />
CEDA View Connection( JCOS )<br />
Connection : JCOS<br />
Group : MYEXCI<br />
DEscription : Sample EXCI Specific connection<br />
CONNECTION IDENTIFIERS<br />
Netname : JGATE400<br />
INDsys :<br />
REMOTE ATTRIBUTES<br />
REMOTESYSTem :<br />
REMOTEName :<br />
REMOTESYSNet :<br />
CONNECTION PROPERTIES<br />
ACcessmethod : IRc Vtam | IRc | INdirect | Xm<br />
PRotocol : Exci Appc | Lu61 | Exci<br />
Conntype : Specific Generic | Specific<br />
SInglesess : No No | Yes<br />
DAtastream : User User | 3270 | SCs | STrfield | Lms<br />
+ RECordformat : U U | Vb<br />
SYSID=CW2C APPLID=IYCWZCFY<br />
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL<br />
Figure 6. Connection definition—screen 1<br />
OBJECT CHARACTERISTICS <strong>CICS</strong> RELEASE = 0620<br />
CEDA View Connection( JCOS )<br />
Queuelimit : No No | 0-9999<br />
Maxqtime : No No | 0-9999<br />
OPERATIONAL PROPERTIES<br />
AUtoconnect : No No | Yes | All<br />
INService : Yes Yes | No<br />
SECURITY<br />
SEcurityname :<br />
ATtachsec : Identify Local | Identify | Verify | Persistent | Mixidpe<br />
BINDPassword : PASSWORD NOT SPECIFIED<br />
BINDSecurity : No No | Yes<br />
Usedfltuser : No No | Yes<br />
RECOVERY<br />
PSrecovery : Sysdefault | None<br />
Xlnaction : Keep Keep | Force<br />
SYSID=CW2C APPLID=IYCWZCFY<br />
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL<br />
Figure 7. Connection definition—screen 2<br />
The relevant parameters (shown in bold in the figures) are:<br />
Netname<br />
If you enter a Netname, the connection will use a specific pipe. If you<br />
leave it blank, the EXCI connection will use a generic pipe. Generally it is<br />
best to use a specific pipe, since this helps to manage multiple<br />
connections, and to identify problems.<br />
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
If you use specific pipes, set Netname to be the same as the pipe specified<br />
in the EXCI client program. (This is specified on the user_name parameter<br />
of an Initialize_User EXCI call.) Set the DFHJVPIPE environment variable<br />
to allow the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to pass this value to the EXCI; see<br />
“Setting environment variables” on page 47.<br />
Note: If you use the sample DFH$EXCI, set the DFHJVPIPE environment<br />
variable to BATCHCLI to use the specific pipe.<br />
If a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to connect to more than one<br />
<strong>CICS</strong> region, use the same Netname for all EXCI connections.<br />
ACcessmethod<br />
Specify IRC (interregion communication).<br />
PRotocol<br />
Specify EXCI.<br />
Conntype<br />
This defines the type of EXCI connection used for non-<strong>CICS</strong> jobs to<br />
communicate with a <strong>CICS</strong> region on z/OS. It is a type of multiregion<br />
operation (MRO) request and can be either Generic or Specific.<br />
Generic<br />
An MRO link with a number of sessions to be shared by multiple<br />
EXCI users. Only one generic EXCI connection can be installed in each<br />
region. Specify Generic if you left the Netname attribute blank.<br />
Specific<br />
An MRO link with one or more sessions dedicated to a single user in<br />
a client program. Specify Specific if you completed the Netname<br />
attribute.<br />
ATtachsec<br />
This causes a check to be made against the flowed user ID. Specify either<br />
Local or Identify.<br />
Local<br />
The remote system does not flow a user identifier; only the link user<br />
ID (if specified) is used. If no link user ID is supplied then all requests<br />
are run under the <strong>CICS</strong> default user ID as specified in the DFLTUSER<br />
SIT parameter.<br />
Identify<br />
A user ID is flowed on every request, but no password is expected, as<br />
<strong>CICS</strong> trusts the user ID as having been already authenticated. For<br />
security reasons verify the user ID and password with RACF before<br />
the EXCI request is made. The userid is either:<br />
v The user named in the ECIRequest object<br />
Chapter 4. Configuring the <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS 39
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
v (If null) the user ID of the thread under which the <strong>Gateway</strong> request<br />
runs.<br />
For details of how to produce these definitions see the <strong>CICS</strong> External Interfaces<br />
Guide.<br />
<strong>CICS</strong> server sessions definition<br />
For each EXCI connection definition, you create a sessions definition.<br />
VIEW GROUP(MYEXCI) SESSIONS(JCOS)<br />
OBJECT CHARACTERISTICS <strong>CICS</strong> RELEASE = 0620<br />
CEDA View Sessions( JCOS )<br />
Sessions : JCOS<br />
Group : MYEXCI<br />
DEscription : Sample EXCI Specific sessions definition<br />
SESSION IDENTIFIERS<br />
Connection : JCOS<br />
SESSName :<br />
NETnameq :<br />
MOdename :<br />
SESSION PROPERTIES<br />
Protocol : Exci Appc | Lu61 | Exci<br />
MAximum : 000 , 000 0-999<br />
RECEIVEPfx : JG<br />
RECEIVECount : 004 1-999<br />
SENDPfx :<br />
SENDCount : 1-999<br />
SENDSize : 04096 1-30720<br />
+ RECEIVESize : 04096 1-30720<br />
SYSID=CW2C APPLID=IYCWZCFY<br />
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL<br />
Figure 8. Sessions definition—screen 1<br />
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
OBJECT CHARACTERISTICS <strong>CICS</strong> RELEASE = 0620<br />
CEDA View Sessions( EXC1SESS )<br />
SESSPriority : 000 0-255<br />
<strong>Transaction</strong> :<br />
OPERATOR DEFAULTS<br />
OPERId :<br />
OPERPriority : 000 0-255<br />
OPERRsl : 0 0-24,...<br />
OPERSecurity : 1 1-64,...<br />
PRESET SECURITY<br />
USERId :<br />
OPERATIONAL PROPERTIES<br />
Autoconnect : No No | Yes | All<br />
INservice : Yes No | Yes<br />
Buildchain : Yes Yes | No<br />
USERArealen : 000 0-255<br />
IOarealen : 04096 , 04096 0-32767<br />
RELreq : No No | Yes<br />
DIscreq : No No | Yes<br />
SYSID=CW2C APPLID=IYCWZCFY<br />
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL<br />
Figure 9. Sessions definition—screen 2<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
The relevant parameters (shown in bold in the figures) are:<br />
Connection<br />
This sessions definition is associated with the JCOS connection.<br />
Protocol<br />
Specify EXCI.<br />
RECEIVEPfx<br />
This is a one or two character prefix for the receive session names. <strong>CICS</strong><br />
creates the remainder of the four character names from the alphanumeric<br />
characters A through Z, and 1 through 9. These two or three character<br />
identifiers begin with the letters AAA, and continue in ascending<br />
sequence until the number of session entries reaches the limit set by the<br />
RECEIVECount value (in our example JGAA, JGAB, JGAC, and so on).<br />
The default receive prefix is the < symbol.<br />
RECEIVECount<br />
This defines the number of sessions that receive before sending. Since all<br />
EXCI sessions are receive sessions, this defines the number of pipes that<br />
can be used simultaneously. Because the EXCI imposes a maximum of 100<br />
pipes for each EXCI address space, set RECEIVECount to 100 or less,<br />
unless multiple EXCI clients use the same EXCI connection to connect to<br />
the same <strong>CICS</strong> region. This could be the case if cloned <strong>Gateway</strong> daemon<br />
connect to the same <strong>CICS</strong> region.<br />
SENDCount<br />
Leave blank. Because EXCI sessions can only receive, there are no send<br />
sessions.<br />
Chapter 4. Configuring the <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS 41
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS<br />
USERId<br />
This defines the preset user identifier to be used for link security<br />
checking. It provides an additional security check for each transaction in<br />
addition to the flowed user ID. If you do not specify a preset user ID for<br />
link security, <strong>CICS</strong> uses the flowed user ID.<br />
Open interregion communication<br />
After you install the CONNECTION definitions, set interregion<br />
communication (IRC) open:<br />
CEDA INSTALL GROUP(groupname)<br />
to install the group containing the definitions, and:<br />
CEMT SET IRC OPEN<br />
to set IRC open. For more information refer to the <strong>CICS</strong> Resource Definition<br />
Guide.<br />
EXCI user-replaceable module DFHXCURM<br />
The user-replaceable module DFHXCURM is invoked on EXCI Allocate_Pipe<br />
requests, and also after detection of EXCI retryable errors. This occurs in one<br />
of three circumstances:<br />
v the target <strong>CICS</strong> region is not available<br />
v there are no pipes available on the target <strong>CICS</strong> region<br />
v IRC has not been active since the last initial program load (IPL)<br />
In early releases of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, an EXCI pipe was established,<br />
used, and deallocated, for each ECI flow. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> now<br />
creates a pipe only for the first ECI flow. Later calls then reuse this pipe. As a<br />
result, it is no longer possible to perform workload management using the<br />
EXCI user-replaceable module DFHXCURM, because the code would only be<br />
called on the first ECI flow.<br />
An alternative way of performing workload balancing, is to:<br />
1. route all your ECI flows to the same <strong>CICS</strong> region<br />
2. perform the routing there, using, for example, a round-robin approach to<br />
distribution<br />
Although reusing the same pipe for EXCI calls has an impact on previously<br />
written workload management code, there are benefits in <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> performance. This is because the Initialize_User and Allocate_Pipe<br />
EXCI commands are only called once per server. In the past they were called<br />
at the start of every ECI flow.<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
To configure the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you create two files: ctgenvvar<br />
and CTG.INI. You can create the files in either of the following ways:<br />
v By running the configuration tool. This creates both files for you, and is the<br />
recommended way if you have X-Windows.<br />
v By editing copies of sample files.<br />
Read these topics for information on configuring your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>:<br />
“Editing the sample configuration files” How to configure the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> by copying and editing sample<br />
configuration files.<br />
“Setting environment variables” on<br />
page 47<br />
How to set environment variables, for<br />
example, to control the use of EXCI pipes,<br />
and the names of <strong>CICS</strong> servers that callers<br />
can access.<br />
“Using the configuration tool” on page 52 How to configure the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> by using the configuration tool.<br />
“Other configuration tasks:” on page 73 Contains information about other tasks<br />
you have to do to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for use with RACF ® ” on page 65<br />
Read this if your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> will use RACF.<br />
See also these sources of information:<br />
v IBM Redbooks (see “Redbooks” on page 167)<br />
v Chapter 4, “Configuring the <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS” on page 37<br />
Editing the sample configuration files<br />
To configure the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, you create two files: ctgenvvar<br />
and CTG.INI. Sample files are provided in the /bin directory:<br />
© Copyright IBM Corp. 1996, 2002 43
Configuration<br />
Sample version<br />
()<br />
Working version<br />
()<br />
Used by<br />
ctgenvvarsamp ctgenvvar All applications that use the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
communicate with <strong>CICS</strong> in local<br />
mode.<br />
CTGSAMP.INI CTG.INI The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
only.<br />
Note: The filenames are case-sensitive.<br />
To create working versions, copy the to<br />
/bin/, and then edit the new file. Do the<br />
following for both ctgenvvarsamp and CTGSAMP.INI:<br />
From Telnet or OMVS<br />
To copy the file, issue these commands:<br />
cd /bin<br />
cp <br />
To edit the new file, issue one of the following commands:<br />
On Telnet:<br />
vi <br />
On OMVS:<br />
oedit <br />
From TSO ISHELL<br />
To copy the file:<br />
1. Set the pathname to /bin/<br />
2. Issue the N command.<br />
3. Set the following in the Create a New File dialog box:<br />
Permissions :755<br />
File Type :2 (Regular file)<br />
File source for regular file:2 (Copy file)<br />
4. In the Replace a File dialog box accept the source as 1 (File).<br />
5. Type the following on the Enter the Pathname dialog box:<br />
/bin/<br />
6. Set the file permissions to 755 in the dialog box that opens.<br />
To edit the new file:<br />
1. Leave the pathname as /bin/<br />
2. Issue the command E (Edit).<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Note: Some lines of the INI file are longer than 72 characters; take care when<br />
editing them.<br />
In the following sections relevant settings for each file are shown, together<br />
with their corresponding definition in “Using the configuration tool” on<br />
page 52.<br />
General <strong>Gateway</strong> settings in CTG.INI<br />
Entry in CTG.INI Corresponding field in the configuration<br />
tool<br />
closetimeout “Timeout for in-progress requests to<br />
complete (ms)” on page 58<br />
connectionlogging “Log client connections and<br />
disconnections” on page 58<br />
ecigenericreplies “Let Java clients obtain generic ECI<br />
replies” on page 58<br />
initconnect “Initial number of Connection Manager<br />
threads” on page 56<br />
initworker “Initial number of Worker threads” on<br />
page 56<br />
maxconnect “Maximum number of Connection<br />
Manager threads” on page 56<br />
maxworker “Maximum number of Worker threads”<br />
on page 57<br />
noinput “Enable reading input from console” on<br />
page 57<br />
nonames “Display TCP/IP hostnames” on page 57<br />
notime (No equivalent field)<br />
uowvalidation “Validate Units of Work” on page 58<br />
workertimeout “Worker thread available timeout (ms)”<br />
on page 58<br />
Protocol settings<br />
Protocol settings take this form:<br />
protocol@tcp.handler=com.ibm.ctg.server.TCPHandler<br />
protocol@tcp.parameters=connecttimeout=2000;idletimeout=600000;...<br />
Figure 10. Extract from TCP protocol entry in CTG.INI<br />
Configuration<br />
A protocol is enabled if an entry for it exists in the CTG.INI file. Entries for<br />
each protocol must be in the form shown:<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 45
Configuration<br />
v Two lines are allowed for each protocol. If you will use the configuration<br />
tool, do not split long lines. If you do not intend to use the configuration<br />
tool, you may split long lines by placing the backslash character \ after a<br />
semicolon, as shown:<br />
protocol@tcp.parameters=connecttimeout=2000;\<br />
idletimeout=600000;<br />
v The first line defines the protocol.<br />
v The second line defines the parameters.<br />
v Parameters are separated by a semicolon.<br />
The following table shows how parameters in the CTG.INI file map to fields in<br />
the configuration tool:<br />
Entry in CTG.INI Equivalent field in the configuration<br />
tool<br />
allowaddr Authorized Hosts. If specifying more than<br />
one host, the format of the entry is as<br />
follows:<br />
allowaddr=host1;\<br />
allowaddr=host2;<br />
clientauth Use client authentication<br />
connecttimeout Connection timeout (ms)<br />
dropworking Drop working connections<br />
idletimeout Idle timeout (ms)<br />
keyring KeyRing database (System SSL,<br />
System HTTPS)<br />
KeyRing or Keystore name (SSL,<br />
keyringpw KeyRing or Keystore password<br />
keyringpwscrambled (No equivalent)<br />
maxconn Maximum dedicated connections<br />
pingfrequency Ping time frequency (ms)<br />
port Port<br />
requiresecurity Require clients to use security classes<br />
solinger SO_LINGER setting<br />
sotimeout Handler wakeup timeout (ms)<br />
Summary of environment variables<br />
Table 6 on page 47 shows how the environment variables relate to the<br />
configuration tool settings (see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
settings” on page 56) and the variables contained in the ctgenvvar script.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Table 6. Environment variables<br />
Environment variable ctgenvvar environment variables configuration tool setting<br />
AUTH_USERID_PASSWORD AUTH_USERID_PASSWORD Use RACF Authentication<br />
<strong>CICS</strong>CLI - (defaults to CTG.INI in the<br />
current directory from where the<br />
<strong>Gateway</strong> is run — normally<br />
ctg/bin)<br />
-<br />
CLASSPATH Concatenation of: CLASSPATH,<br />
CTG_USER_CLASSPATH,<br />
CTG_CLASSPATH<br />
CTG User Classpath<br />
CTG_RRMNAME RRMNAME RRM Name<br />
DFHJVPIPE DFHJVPIPE EXCI Net Name<br />
DFHJVSYSTEM_nn DFHJVSYSTEM_nn <strong>CICS</strong> Server, <strong>CICS</strong> Description<br />
LD_LIBRARY_PATH Concatenation of:<br />
LD_LIBRARY_PATH,<br />
CTG_USER_LIBPATH,<br />
CTG_LIBPATH<br />
CTG User Libpath<br />
LIBPATH Concatenation of:<br />
CTG_USER_LIBPATH,<br />
CTG_LIBPATH, and current<br />
LIBPATH<br />
STEPLIB Concatenation of: STEPLIB,<br />
EXCI_OPTIONS, EXCI_LOADLIB<br />
CTG User Libpath<br />
Configuration<br />
EXCI Load Library (High Level<br />
Qualifier, Library Name), EXCI<br />
Options<br />
Setting environment variables<br />
Environment variables control how the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> functions.<br />
Use the ctgenvvar script to set environment variables for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for z/OS. The ctgenvvar script can be executed alone or referenced<br />
by the ctgstart script to set the variables.<br />
You can create the ctgenvvar script in two ways:<br />
v By using the configuration tool to define the environment settings and to<br />
create the ctgenvvar script; see “z/OS Environment settings” on page 64.<br />
This is the recommended way if you have X-Windows.<br />
The values in the ctgenvvarsamp are loaded as defaults.<br />
v By editing the supplied ctgenvvarsamp script, and then copying or<br />
renaming to ctgenvvar script, see “Editing the sample configuration files”<br />
on page 43.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 47
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
If a ctgenvvar script is not found when ctgstart runs, settings for the<br />
environment variables in the ctgstart script itself are used.<br />
You can also set the environment variables by:<br />
v Entering commands on an z/OS UNIX System Services command line. For<br />
example, the following command sets the DFHJVPIPE environment variable<br />
to use a specific pipe called JAVAGAT1.<br />
export DFHJVPIPE=JAVAGAT1<br />
If the value of an environment variable contains spaces, enclose it in single<br />
or double quotes. For example:<br />
export DFHJVSYSTEM_00="MY<strong>CICS</strong>-Test <strong>CICS</strong> system"<br />
v By creating a JCL job that includes environment variable settings to start<br />
the gateway. See “Starting with JCL” on page 121. If you set environment<br />
variables in the ctgenvvar or ctgstart script, these override settings in the<br />
JCL.<br />
All <strong>CICS</strong> regions refer to the same instance of a variable except<br />
DFHJVSYSTEM_nn which is unique to the region. This consists of the server<br />
name and description.<br />
After you have installed the product, you can use ctgenvvar to establish the<br />
environment that Java applications running in local mode will use, for<br />
example:<br />
./bin/ctgenvvar<br />
Because ctgenvvar searches for ctgstart, ensure that /bin is<br />
in the path for the current environment.<br />
The environment variables<br />
You can export the following environment variables for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. Refer to Table 6 on page 47 for details of how these relate to<br />
configuration tool and ctgenvvar settings.<br />
AUTH_USERID_PASSWORD<br />
Specifies whether the user ID and password is authenticated with<br />
RACF.<br />
If you set AUTH_USERID_PASSWORD to Yes you must also set<br />
_BPX_SHAREAS to Yes, and JAVA_PROPAGATE to NO. If you set<br />
AUTH_USERID_PASSWORD through the Use RACF Authentication<br />
check box in the configuration tool, file ctgenvvar is updated for you.<br />
If you set this variable see also “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for use with RACF ® ” on page 65.<br />
<strong>CICS</strong>CLI<br />
48 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
You can specify a different path to the configuration file by setting the<br />
<strong>CICS</strong>CLI environment variable. (The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> log<br />
indicates the location of CTG.INI.) The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will<br />
not run if a configuration file is not found.<br />
CLASSPATH<br />
Includes the path in HFS for the <strong>CICS</strong>-provided Java jar files, that is,<br />
/ctg/classes. You must set CLASSPATH to compile and run Java<br />
applications.<br />
CTG_RRMNAME<br />
The name of the resource manager managing this instance of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. For Resource Recovery Services, the name must<br />
be unique across a sysplex.<br />
The name can consist of the following printable characters:<br />
1. Alphanumeric characters: A-Z and 0-9<br />
2. National characters: $ (X'5B'), # (X'7B'), @ (X'7C')<br />
3. The period (.)<br />
4. The underscore (_)<br />
The name cannot start with a blank or contain embedded blanks.<br />
Lower case characters are converted to upper case characters.<br />
The name must end with these characters:<br />
.IBM.UA<br />
Configuration<br />
To avoid naming conflicts, use A-C or G-I as the first character.<br />
The length of CTG_RRMNAME must not exceed 32 characters.<br />
DFHJVPIPE<br />
The name of the specific pipe that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is to<br />
use for EXCI calls. If this variable is not set, the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> uses a generic pipe.<br />
DFHJVSYSTEM_nn<br />
You may set up to 100 environment variables of the form<br />
DFHJVSYSTEM_nn, where nn ranges from 00 to 99. The first variable<br />
must be DFHJVSYSTEM_00, and subsequent variables must have<br />
consecutive numbers, or they will not be recognized. The value of the<br />
variable is the name and description of a <strong>CICS</strong> system to be returned<br />
in response to a request for the <strong>CICS</strong>_EciListSystems function.<br />
The value is a string containing the uppercase APPLID of the <strong>CICS</strong><br />
system, followed by a hyphen (-), followed by a description of the<br />
<strong>CICS</strong> system. The description may not be more than 60 bytes long.<br />
For example if you specify:<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 49
|<br />
|<br />
|<br />
|<br />
|<br />
Configuration<br />
DFHJVSYSTEM_00="MY<strong>CICS</strong>-Test <strong>CICS</strong> system"<br />
<strong>CICS</strong>_EciListSystems returns details of a <strong>CICS</strong> system called MY<strong>CICS</strong><br />
with description Test <strong>CICS</strong> system.<br />
LD_LIBRARY_PATH<br />
Includes the path in HFS for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> executable<br />
code. Set it to /ctg/bin.<br />
LIBPATH<br />
This is the path in HFS for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> executable<br />
code. It is a concatenation of the LD_LIBRARY_PATH and any other<br />
existing libraries in LIBPATH. Ensure that as a minimum it is set to<br />
/ctg/bin, the same as LD_LIBRARY_PATH.<br />
STEPLIB<br />
The library containing the default EXCI options and the EXCI load<br />
modules. STEPLIB is a concatenation of the EXCI_OPTIONS and<br />
EXCI_LOADLIB variables. EXCI_OPTIONS references the data set that<br />
contains the EXCI options table DFHXCOPT. The default supplied<br />
table is contained in SDFHEXCI. EXCI_LOADLIB should reference the<br />
SDFHEXCI and SDFHLOAD libraries.<br />
Customizing EXCI options<br />
The EXCI options table, DFHXCOPT, allows you to specify a number of<br />
parameters for the EXCI. There is no suffixed version of this program, so the<br />
first DFHXCOPT table located in the STEPLIB concatenation is loaded.<br />
Figure 11 shows the default parameters for the DFHXCOPT macro.<br />
DFHXCO TYPE=CSECT,<br />
TIMEOUT=0, No timeout<br />
TRACE=OFF, Only Exception trace entries<br />
TRACESZE=16, 16K trace table<br />
DURETRY=30, Retry SDUMPS for 30 seconds<br />
TRAP=OFF, DFHXCTRA - OFF<br />
GTF=OFF, GTF - OFF<br />
MSGCASE=MIXED, Mixed case messages<br />
<strong>CICS</strong>SVC=0, EXCI will obtain <strong>CICS</strong> SVC number<br />
CONFDATA=SHOW, Show user commarea data in trace<br />
SURROGCHK=YES Perform surrogate-user check @P1C<br />
END DFHXCOPT<br />
Figure 11. EXCI options table DFHXCOPT<br />
For full details see the <strong>CICS</strong> External Interfaces Guide. The relevant parameters<br />
(shown in bold in Figure 11) are:<br />
TRACE<br />
The default value OFF means that EXCI tracing is not required. Exception<br />
trace entries are always written to the internal trace table.<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Configuration<br />
GTF<br />
If you want to copy entries in the EXCI trace table to the generalized trace<br />
facility (GTF), specify GTF=ON.<br />
<strong>CICS</strong>SVC<br />
This specifies the <strong>CICS</strong> type 3 SVC number being used for MRO<br />
communication. EXCI must use the same SVC number that is used by the<br />
<strong>CICS</strong> MRO regions that reside in the MVS image where the client<br />
program is running. If you do not specify a specific <strong>CICS</strong> SVC number,<br />
the external <strong>CICS</strong> interface determines the SVC in use for MRO by means<br />
of an MVS VERIFY command.<br />
The default value zero means that EXCI will get the <strong>CICS</strong> SVC number<br />
from MVS. Specify 0 only when you are sure that at least one <strong>CICS</strong> region<br />
has logged on to DFHIRP during the life of the MVS IPL. If you use the<br />
default, and the external <strong>CICS</strong> interface requests the SVC from MVS, the<br />
request will fail if no <strong>CICS</strong> region has logged on to DFHIRP.<br />
In other circumstances, specify the <strong>CICS</strong> SVC number, in the range<br />
200–255, that is in use for <strong>CICS</strong> interregion communications. This must be<br />
the SVC number that is installed in the MVS image in which the client<br />
program is running (the local MVS).<br />
Note: All <strong>CICS</strong> regions using MRO within the same MVS image must use<br />
the highest level of both DFHIRP and the <strong>CICS</strong> SVC, DFHCSVC. If<br />
your MRO <strong>CICS</strong>plex consists of <strong>CICS</strong> regions at different release<br />
levels, the DFHIRP and DFHCSVC installed in the LPA must be<br />
from highest release level of <strong>CICS</strong> within the <strong>CICS</strong>plex.<br />
CONFDATA<br />
The default value SHOW allows user data to be traced. If you wish to<br />
hide it, set this value to HIDETC.<br />
SURROGCHK<br />
The default value YES means that a surrogate security check will be<br />
performed in the EXCI client address space if the flowed user ID is<br />
different from the user ID of the client address space. This occurs<br />
regardless of the <strong>CICS</strong> security settings. This means that if you flow a<br />
user ID in an EXCI request (including flowing a user ID with an External<br />
Call Interface [ECI] request using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS), you need either to add an RACF surrogate profile, or disable<br />
surrogate security checks by setting this parameter to NO.<br />
Note: If the <strong>CICS</strong> region has no security (SEC=NO), specify<br />
SURROGCHK=NO. For more information, refer to the <strong>CICS</strong> RACF<br />
Security Guide.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 51
|<br />
|<br />
|<br />
Configuration<br />
Referencing your customized EXCI options<br />
If you customized the EXCI options in DFHXCOPT, update the<br />
EXCI_OPTIONS environment variable to specify the library that contains the<br />
customized options table. You can do this either by:<br />
v Using the configuration tool to set EXCI Options; see “z/OS Environment<br />
settings” on page 64.<br />
v Editing the ctgenvvar script. Find the line:<br />
EXCI_OPTIONS="your.user.loadlib"<br />
and change it to specify the appropriate library.<br />
For more information about the EXCI options and how to customize them, see<br />
the <strong>CICS</strong> External Interfaces Guide.<br />
You must update the name of the library specified in the EXCI_LOADLIB<br />
environment variable. This library contains:<br />
v The default EXCI options.<br />
v The EXCI load modules.<br />
You can update EXCI_LOADLIB by:<br />
v Using the configuration tool to set High Level Qualifier and Library<br />
Name, see “z/OS Environment settings” on page 64.<br />
v Editing the ctgenvvar script. Find the line:<br />
EXCI_LOADLIB="<strong>CICS</strong>TS22.<strong>CICS</strong>.SDFHEXCI"<br />
and change it to specify the appropriate library and high-level qualifier.<br />
The EXCI_OPTIONS and EXCI_LOADLIB variables are used in the definition<br />
of the STEPLIB environment variable.<br />
Using the configuration tool<br />
Use the configuration tool to set configuration parameters for the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
To use the configuration tool, export the display using the commands<br />
described in “Using X-Windows from a remote system” on page 34.<br />
To start the configuration tool, enter the ctgcfg command.<br />
The configuration is stored by default in the CTG.INI file in the<br />
/bin subdirectory. You can edit this file directly, if you find<br />
this preferable to using the configuration tool. If a configuration file already<br />
exists when you start the configuration tool, the settings in the file are loaded<br />
into the configuration tool.<br />
52 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
You can specify a different path to the configuration file by setting the<br />
<strong>CICS</strong>CLI environment variable. (The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> log indicates<br />
the location of CTG.INI.) The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will not run if a<br />
configuration file is not found.<br />
You must restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for any changes to the<br />
configuration file to take effect.<br />
Running the configuration tool on a different operating system<br />
You can use the configuration tool on any of the other <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> operating systems to generate a configuration file for your operating<br />
system. See Appendix A, “Hardware and software” on page 155 for other<br />
supported operating systems.<br />
1. Install <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the workstation on which you want<br />
to run the configuration tool.<br />
2. To edit an existing configuration, copy CTG.INI, and ctgenvvar, tothe<br />
/bin subdirectory on the workstation, using FTP in ASCII<br />
mode.<br />
3. Issue the following command:<br />
ctgcfg -PLAT ZOS<br />
This makes the configuration tool run as if it is on your operating system.<br />
4. Make the required entries and click Save. This creates or updates the<br />
CTG.INI file and the ctgenvvar file.<br />
5. Use FTP in ASCII mode to transfer the files to your system. Ensure that<br />
the z/OS ftp agent is using the same code page as the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> will use; see Appendix B, “Supported code pages” on page 163<br />
for supported code pages.<br />
The configuration tool interface<br />
The screen has four input areas (described separately below):<br />
1. Menu bar<br />
2. Toolbar<br />
3. Tree structure<br />
4. Settings panel<br />
Using the configuration tool<br />
A fifth area, the status bar, shows which configuration file and operating<br />
system you are using. The status bar is display only.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 53
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
Figure 12. The configuration tool<br />
Tree structure<br />
The tree structure (see Figure 12) allows you to navigate through all of the<br />
settings in your configuration. The types of root node are as follows:<br />
Java <strong>Gateway</strong> Contains a subnode for each protocol that the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can use (TCP, SystemSSL, SSL, HTTP,<br />
SystemHTTPS, HTTPS and TCPAdmin).<br />
EXCI Client Contains a subnode for each of your server definitions.<br />
Menu bar<br />
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.<br />
The File pulldown has the following options:<br />
New Creates a new configuration.<br />
Open Opens an existing configuration.<br />
Save Saves the current configuration. If a new configuration has<br />
been created, the file name is CTG.INI (in the<br />
/bin subdirectory).<br />
54 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Save As Allows you to override the default path and name of the<br />
configuration file.<br />
Exit Exits the configuration tool. If you have made any alterations<br />
you are asked whether you want to save the configuration.<br />
The Edit pulldown has Cut, Copy and Paste options, which perform the<br />
standard text functions.<br />
The Tools pulldown has the following options:<br />
Trace Settings Displays the Trace Settings dialog.<br />
New Server Defines a new server named New Serv.<br />
Delete Server Deletes a server node from the tree structure.<br />
Using the configuration tool<br />
The Settings pulldown has these options:<br />
Color Changes the background color on panels and fields. If you<br />
change the color, all fields (except check boxes and radio<br />
buttons) take on the same background color as the main<br />
panel.<br />
Font Changes the typeface, size, style and color of text.<br />
Any changes that you make to color and font settings are lost when you close<br />
the configuration tool.<br />
The Help pulldown has the following options:<br />
Context Help Displays online help information according to the current<br />
screen context, for example, for a particular configuration<br />
setting.<br />
Contents Displays the contents list for online help.<br />
Keys Help Displays information on keyboard alternatives, and other<br />
information to help users with a disability to use the software.<br />
See also “Accessibility” on page 169.<br />
Index Displays a subject index for online help.<br />
About Displays the version number and other information about the<br />
configuration tool.<br />
Toolbar<br />
The toolbar provides some of the functionality available from the menu bar in<br />
a set of icons. These icons have hover help, so that when you place the cursor<br />
over them, a text box describing the option appears.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 55
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
Settings panels<br />
When you select nodes in the tree structure, the relevant settings panel is<br />
displayed. The settings in these panels correspond to parameters in the<br />
CTG.INI and ctgenvvar files.<br />
On each settings panel there is an Undo Changes button that allows you to<br />
undo changes you have made.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings<br />
Using the configuration tool, you can provide preset values for any parameter<br />
that can be specified using a <strong>Gateway</strong> command line option.<br />
If a parameter defined using the configuration tool is specified via the<br />
associated command line option when the <strong>Gateway</strong> is started, the command<br />
line setting takes precedence.<br />
General <strong>Gateway</strong> settings<br />
The general <strong>Gateway</strong> settings are:<br />
Initial number of Connection Manager threads: Enter the initial number of<br />
ConnectionManager threads. The default is 1.<br />
Set this to the normal number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients.<br />
You can override this setting with the ctgstart -initconnect command.<br />
Maximum number of Connection Manager threads: Enter the maximum<br />
number of ConnectionManager threads. The default is 100.<br />
This limits the maximum number of Java<strong>Gateway</strong> objects opened by all<br />
connected Java clients. Set this to the maximum number of Java<strong>Gateway</strong><br />
objects that could be open at any one time from all the remotely-connected<br />
Java clients.<br />
You can override this setting with the ctgstart -maxconnect command.<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
ConnectionManager threads.<br />
For information on threading limits, see Table 3 on page 15.<br />
Initial number of Worker threads: Enter the initial number of Worker<br />
threads. The default is 1.<br />
Set this to the normal number of concurrent requests expected to be processed<br />
concurrently by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> daemon.<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
You can override this setting with the ctgstart -initworker command.<br />
Maximum number of Worker threads: Enter the maximum number of<br />
Worker threads. The default is 100.<br />
This limits the maximum number of parallel ECI requests that the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can process. Set it to:<br />
v Less than or equal to maxconnect (for single Java<strong>Gateway</strong> programs)<br />
v Less than or equal to the RECEIVECOUNT set in the <strong>CICS</strong> sessions<br />
definition<br />
v Less than or equal to 100 since this is the maximum number of EXCI pipes<br />
that a z/OS address space can allocate<br />
As there is a limit of 100 pipes per MVS address space, it is recommended<br />
that you set the Maximum number of Worker threads to (100 divided by the<br />
number of unique applids in communication with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>). This is because a pipe is allocated per thread per applid. See “EXCI<br />
pipe limitations” on page 142 for more information. To increase throughput,<br />
consider starting multiple instances of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> (see<br />
“Starting multiple <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s” on page 124).<br />
If you select the Unrestricted checkbox, no limits are applied to the number of<br />
Worker threads.<br />
You can override this setting with the ctgstart -maxworker command.<br />
For information on threading limits, see Table 3 on page 15.<br />
Enable reading input from console: Select this check box to enable the<br />
reading of input from the console.<br />
Reading of input from the console is enabled by default.<br />
Using the configuration tool<br />
You can override this setting with the ctgstart -noinput command.<br />
Display TCP/IP hostnames: Select this check box to enable the display of<br />
TCP/IP hostnames in messages.<br />
This option allows you to choose how TCP/IP addresses are displayed in<br />
messages. By default, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> displays TCP/IP addresses<br />
in messages in numeric form. If you enable this option, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> uses the Domain Name System (DNS) to convert numeric TCP/IP<br />
addresses to symbolic TCP/IP hostnames in messages. This makes the<br />
messages easier to read.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 57
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
Note: Selecting this option might cause severe performance reduction on<br />
some systems.<br />
Let Java clients obtain generic ECI replies: Select this check box if you wish<br />
Java clients to be able to obtain generic ECI replies from the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Generic replies are those obtained using the Call_Type: ECI_GET_REPLY or<br />
ECI_GET_REPLY_WAIT. Specific replies are those obtained using the<br />
Call_Type: ECI_GET_SPECIFIC_REPLY or ECI_GET_SPECIFIC_REPLY_WAIT.<br />
This setting does not apply to local <strong>Gateway</strong>s.<br />
Validate Units of Work: Select this check box if you want the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> to validate logical units of work (LUWs). This ensures<br />
that a LUW ID can be used only on the Java<strong>Gateway</strong> connection to which it<br />
was allocated. If you clear this check box, you disable validation:<br />
v LUWs can be accessed by any connection to the same remote <strong>Gateway</strong>.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> cannot clean up used LUWs when a<br />
connection is closed or breaks.<br />
The default is that LUW validation is enabled.<br />
Log client connections and disconnections: Select this check box if you want<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to write a message to the log each time that a<br />
client application program connects to, or disconnects from, the <strong>Gateway</strong><br />
daemon. The default is for these messages not to be written.<br />
Timeout for in-progress requests to complete (ms): Enter a value in<br />
milliseconds.<br />
When a Java-client program disconnects from the <strong>Gateway</strong>, the <strong>Gateway</strong> may<br />
still be processing requests on behalf of that program. If work is still in<br />
progress, the ConnectionManager that was managing requests on behalf of<br />
that Java-client waits for the requests to complete for up to the timeout<br />
period. If there are still requests in progress after the timeout has expired, the<br />
ConnectionManager continues its processing and marks itself as available for<br />
use by a new connection. The default timeout is 10 000 milliseconds, but you<br />
may enter a value to override the default.<br />
If this value is set to zero, the ConnectionManager does not wait for<br />
in-progress requests to complete.<br />
Worker thread available timeout (ms): Enter a value in milliseconds.<br />
When a ConnectionManager accepts a request, it must allocate a Worker<br />
thread to execute that request. If a Worker does not become available within<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
the timeout period, an error message is sent rejecting that request and the<br />
request is not executed. The default timeout is set to 10 000 milliseconds, but<br />
you can enter a value to override that default.<br />
If you set this value to zero, the request is rejected unless a Worker is<br />
immediately available.<br />
TCP protocol settings<br />
Select the TCP subnode to display the settings for TCP:<br />
Enable protocol handler: Select this check box to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for use with this protocol.<br />
Port: Enter the TCP/IP port number.<br />
The default port for TCP/IP is 2006.<br />
You can override this setting with the ctgstart -port command.<br />
Handler wakeup timeout (ms): Enter a value in milliseconds.<br />
This setting controls how frequently the protocol handler wakes from<br />
accepting inbound connections. When it wakes, it checks to see whether the<br />
<strong>Gateway</strong> is being stopped, and so this value affects the time taken for the<br />
<strong>Gateway</strong> to shutdown cleanly. If you set this value to zero then the handler<br />
only wakes when a new connection is accepted, and so the <strong>Gateway</strong> will not<br />
shutdown cleanly until that time.<br />
Connection timeout (ms): Enter a value in milliseconds.<br />
When a new connection has been accepted, this value specifies how long the<br />
protocol handler waits for a ConnectionManager thread to become available.<br />
If a ConnectionManager thread does not become available within this time,<br />
then the connection is refused. If this value is set to zero, a connection is<br />
refused if a ConnectionManager is not immediately available.<br />
Idle timeout (ms): Enter a value in milliseconds.<br />
Using the configuration tool<br />
This setting specifies how long a connection is allowed to remain dormant.<br />
The idle timeout period is counted from when a request was last flowed<br />
down the connection. When the idle timeout has expired, the connection is<br />
disconnected, though if work is still in progress on behalf of the connection, it<br />
may be left connected. If this value is not set, or is set to zero, then idle<br />
connections will not be disconnected.<br />
Cleanup processing will only result after a timeout if the server has support<br />
for this function installed.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 59
Using the configuration tool<br />
Ping time frequency (ms): Enter a value in milliseconds.<br />
This value specifies how often a PING message is sent by the <strong>Gateway</strong> to an<br />
attached client to check that client is still active. If a PONG response has not<br />
been received by the time the next PING message is due to be sent, then the<br />
connection is disconnected. Again, if work is still in progress on behalf of the<br />
connection it may (depending on the drop working connections value setting)<br />
be left connected. If this value is not set, or is set to zero, then PING messages<br />
are not sent.<br />
Drop working connections: Select this check box to specify that a connection<br />
can be disconnected, due to an idle timeout or a PING/PONG failure even if<br />
work is still in progress on behalf of this connection.<br />
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this<br />
handler. The SO_LINGER setting specifies a delay value in seconds for closing<br />
a socket. If this value is not entered, or set to zero, then SO_LINGER is<br />
disabled for any sockets used by this protocol handler.<br />
If SO_LINGER is enabled, and data transmission has not finished, a Close call<br />
blocks the calling program until the data is transmitted or until the connection<br />
times out. If SO_LINGER is disabled, a Close call returns without blocking the<br />
caller and TCP/IP still tries to send the data. Normally this transfer is<br />
successful, but it cannot be guaranteed, because TCP/IP repeats the Send<br />
request for only a specified period of time.<br />
Require clients to use security classes: Select this check box if you wish<br />
your <strong>Gateway</strong> to accept only connections that use security classes.<br />
When a Java-client program connects to the <strong>Gateway</strong>, it can specify a pair of<br />
security classes for use on the connection. However, by default a <strong>Gateway</strong><br />
also accepts connections from programs that do not specify this pair of<br />
security classes.<br />
For more information on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security exits, see<br />
“Security exits” on page 10.<br />
System SSL protocol settings<br />
Select the System SSL subnode to display the settings for System SSL. The<br />
settings are the same as for TCP except that SSL also has the following<br />
settings:<br />
Use client authentication: Select this check box to enable client<br />
authentication for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The default is that client<br />
authentication is disabled.<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
When client authentication is enabled, any connection attempted to either the<br />
ssl: or https: handler requires the client to present its own Client Certificate<br />
(also known as a Digital ID).<br />
For information on how to obtain Client Certificates for the clients, see<br />
“Configuring your SSL clients” on page 80.<br />
KeyRing database: Enter the database file name (.kdb) of the server<br />
KeyRing.<br />
The server KeyRing should consist of a valid x.509 certificate that is used to<br />
identify this server to connecting clients. This KeyRing database is generated<br />
using the System SSL tool (GSKKYMAN).<br />
For more information about SSL and its associated KeyRing databases, see<br />
Chapter 6, “Network Security” on page 75.<br />
KeyRing or Keystore password: Enter the password that you specified for<br />
the server KeyRing or KeyStore.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the password to the configuration file in a<br />
form that prevents a casual observer from easily reading it.<br />
The default port for System SSL is 8050.<br />
Using the configuration tool<br />
SSL protocol settings<br />
Select the SSL subnode to display the settings for JSSE or SSLight. The<br />
settings are the same as for System SSL except for the following setting, which<br />
is used instead of KeyRing database.<br />
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,<br />
or the server KeyStore name for JSSE.<br />
For a KeyStore, give either the full path name, or the relative path name of<br />
the file. Use either a forward slash (/) character, or double back slash (\\)<br />
characters, as a separator in the path name on all operating systems. For<br />
example:<br />
/mykeys/jsse/keystore.jks<br />
\\mykeys\\jsse\\keystore.jks<br />
The server KeyRing or KeyStore consists of a valid x.509 certificate that<br />
identifies this server to connecting clients. This KeyRing or KeyStore is<br />
generated using the SSL tools supplied with this product.<br />
For more information about SSL and its associated KeyRings or KeyStores, see<br />
Chapter 6, “Network Security” on page 75.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 61
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
The default port for SSL is 8050.<br />
HTTP protocol settings<br />
Select the HTTP subnode to display the settings for HTTP. The settings are<br />
the same as for TCP.<br />
The default port for HTTP is 8080.<br />
System SSL HTTPS protocol settings<br />
Select the System SSL HTTPS subnode to display the settings for HTTPS<br />
over System SSL. The settings are the same as for HTTP except that System<br />
SSL HTTPS also has Use client authentication, KeyRing database, and<br />
KeyRing or Keystore password settings.<br />
The default port for HTTPS is 443.<br />
TCPAdmin protocol settings<br />
Select the TCPAdmin subnode to display the settings for administration. The<br />
settings are the same as for TCP except for the following:<br />
v The default port is 2810<br />
v There is no Require clients to use security classes field.<br />
v TCPAdmin also has the following settings:<br />
Max dedicated connections: Enter a value specifying the maximum number<br />
of simultaneous dedicated client connections that can be made to the <strong>Gateway</strong><br />
administration handler.<br />
Authorized Hosts: Enter a host name or IP address in the entry field. Click<br />
Add to add the host to the Authorized Hosts list, below the entry field. Click<br />
Remove to remove all selected hosts from the Authorized Hosts list.<br />
If there are entries in the Authorized Hosts list, only those hosts are allowed<br />
to access the administration protocol handler. Be aware: If the list is empty, all<br />
hosts are allowed access.<br />
The default entry is 127.0.0.1, which represents the host on which the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is installed. IP address 127.0.0.1 and the host name<br />
localhost are considered to be different from the real IP address or host name<br />
of the system.<br />
For information about administering your system, see “Administering your<br />
system” on page 128.<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
HTTPS protocol settings<br />
Select the HTTPS subnode to display the settings for HTTPS over JSSE or<br />
SSLight. The settings are the same as for HTTP except that HTTPS also has<br />
Use client authentication, KeyRing or Keystore name, and KeyRing or<br />
Keystore password settings.<br />
The default port for HTTPS is 443. However, on some operating systems,<br />
processes require special privileges to access port numbers between 1 and<br />
1024. If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> without these required<br />
privileges, change the port number to a value greater than 1024.<br />
Trace settings<br />
To configure the trace settings, select the Trace settings option from the Tools<br />
menu.<br />
<strong>Gateway</strong>: Select this checkbox to enable tracing of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
This is equivalent to specifying the -trace option on the ctgstart command.<br />
JNI trace: You cannot enable JNI trace through the configuration tool. Use<br />
one of the following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
Using the configuration tool<br />
where filename is the name of the file to which trace output is to be sent.<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin protocol<br />
handler (see “TCPAdmin protocol settings” on page 62). See “Administering<br />
your system” on page 128 for details of how to enable JNI trace<br />
dynamically.<br />
v For Java Client applications running in local mode, use Java to launch your<br />
application and set the system property gateway.T.setJNITFile, as shown in<br />
the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 63
|<br />
Using the configuration tool<br />
<strong>Gateway</strong> trace file: Enter the pathname of a trace file to which trace<br />
messages will be written, if tracing is enabled. If no path is specified, the trace<br />
is written as follows:<br />
/bin/ctg.trc<br />
You can also specify a trace file using the tfile option on the ctgstart<br />
command.<br />
The trace file is overwritten (not appended to) each time the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> starts.<br />
Performance: Turning on the <strong>Gateway</strong> trace has a significant impact on<br />
performance. It is not recommended that <strong>Gateway</strong> trace is<br />
enabled in a production environment.<br />
<strong>Gateway</strong> trace wrap size: Enter a value in the range 0 through 1 000 000<br />
kilobytes.<br />
This value specifies the size in kilobytes to which the gateway trace file will<br />
grow. Subsequent trace entries will continue to be written from the beginning<br />
of the file. The default value of 0 disables wrapping.<br />
z/OS Server settings<br />
To configure a new <strong>CICS</strong> Server, select New Server from the Tools menu, or<br />
from the toolbar.<br />
You can define a maximum of 100 servers.<br />
<strong>CICS</strong> Server: Enter a name of between 1 and 8 characters. This is the name<br />
of a <strong>CICS</strong> system that is returned in response to a request for the<br />
<strong>CICS</strong>_EciListSystems function.<br />
<strong>CICS</strong> Description: Enter a description of between 1 and 60 characters. This<br />
is the description of a <strong>CICS</strong> system that is returned in response to a request<br />
for the <strong>CICS</strong>_EciListSystems function.<br />
z/OS Environment settings<br />
To configure the z/OS environment settings, select a <strong>CICS</strong> Server node.<br />
For more information about the environment variables associated with these<br />
settings, refer to “Setting environment variables” on page 47.<br />
Use RACF Authentication: Select this check box to specify that the userid<br />
and password passed on an EXCI call should be authenticated with RACF. If<br />
you select this option, refer to the “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
use with RACF ® ” for further information about tasks to be completed when<br />
authentication is required.<br />
High Level Qualifier: Enter the high level qualifier for the library that<br />
contains the default EXCI load modules. The default is <strong>CICS</strong>TS22.<strong>CICS</strong>.<br />
Library Name: Enter the name of the library that contains the default EXCI<br />
load modules. The default is SDFHEXCI.<br />
RRM Name: Enter the name of the resource manager that is managing this<br />
instance of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS. The maximum length of<br />
this name is 32 characters. For Resource Recovery services, the name must be<br />
unique across a sysplex.<br />
Important: To avoid naming conflicts, you should use A-C or G-I as the first<br />
character.<br />
EXCI Options: Enter the name of the library containing the default EXCI<br />
options.<br />
CTG User Classpath: Enter a pathname to be added to the current<br />
CLASSPATH environment setting. Note that the configuration tool<br />
automatically sets the path for ctgclient.jar, ctgserver.jar, and cfwk.zip.<br />
CTG User Libpath: Enter a pathname to be added to the current LIBPATH<br />
environment setting. Note that the configuration tool automatically sets the<br />
path for the location of ctgstart.<br />
EXCI Net Name: Enter name of the specific pipe that the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> is to use for EXCI calls. If you do not specify a specific pipe, the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses a generic pipe.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for use with RACF ®<br />
Using the configuration tool<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides support for user ID and password<br />
authentication with RACF, together with the option to map a registered X.509<br />
certificate to a RACF user ID (see “Mapping client certificates to RACF<br />
userids” on page 105). Both of these features use the z/OS UNIX C/C++<br />
pthread_security_np function to call RACF.<br />
Preliminary checks<br />
In the instructions that follow, you will use the extattr +p command to<br />
mark HFS files as program controlled. To use this command, you must be<br />
the owner of the files, or a superuser. The user ID that installed the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> normally owns the files. You also need READ access<br />
to the BPX.FILEATTR.PROGCTL FACILITY class. See OS/390 UNIX System<br />
Services Planning for more information. Your user id must have the RACF<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 65
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
SPECIAL attribute to perform the actions in step 3. Follow these steps to<br />
check that you have the necessary authority:<br />
1. Log on to MVS.<br />
2. Run ISPF.<br />
3. Choose option 6 (Command).<br />
4. Issue the following command:<br />
SR CLASS(FACILITY)<br />
Check that these entries are in the list that appears:<br />
BPX.SERVER<br />
BPX.FILEATTR.PROGCTL<br />
5. Issue the following command:<br />
SR CLASS(SURROGAT)<br />
Check that this entry is in the list that appears:<br />
*.DFHEXCI<br />
Configuring the system<br />
1. Mark the load modules used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> as<br />
program controlled. Use these commands from an OMVS or Telnet<br />
screen:<br />
extattr +p /bin/lib*.so<br />
extattr +p /bin/SECURES<br />
2. If necessary, activate program control by issuing these commands:<br />
SETROPTS CLASSACT(PROGRAM)<br />
RDEFINE PROGRAM * UACC(READ)<br />
SETROPTS WHEN(PROGRAM)<br />
3. Mark as program controlled the <strong>CICS</strong> SDFHEXCI library, which<br />
provides the EXCI for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. For example, if<br />
this library was installed as <strong>CICS</strong>TS22.<strong>CICS</strong>.SDFHEXCI, use the<br />
following RACF command:<br />
RALTER PROGRAM *ADDMEM(’<strong>CICS</strong>TS22.<strong>CICS</strong>.SDFHEXCI’//NOPADCHK)<br />
SETROPTS WHEN(PROGRAM)REFRESH<br />
4. Specify that the ctgstart script does not share its address space with<br />
any other processes, to ensure that the calling address space (JVM) is<br />
not contaminated by a non-program-controlled load module. Enter:<br />
extattr -s /bin/ctgstart<br />
5. If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to use System SSL,<br />
mark as program controlled the binaries and data sets provided by<br />
this separate product. See “System SSL” on page 95 for information<br />
about System SSL. The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is not configured to<br />
use System SSL by default. If your system has been configured for this<br />
protocol, an entry similar to this appears in CTG.INI:<br />
66 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
protocol@systemssl_ssl.handler=com.ibm.ctg.server.GskSslHandler<br />
Issue commands like the following:<br />
extattr +p /usr/lpp/gskssl/lib/*<br />
extattr +p /usr/lpp/gskssl/bin/*<br />
Also mark as program controlled any .kdb keyring files generated<br />
using System SSL, that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses.<br />
6. Give the user ID under which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs<br />
READ access to the BPX.SERVER FACILITY profile. For more<br />
information, see the __passwd() section in OS/390 V2R10.0 C/C++<br />
Run-Time Library Reference, (SC28-1663-08).<br />
7. Give the user ID under which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs<br />
READ access to the RACF profile that protects the<br />
TCPIP.STANDARD.TCPXLBIN data set. This contains tables for<br />
translating from ASCII to EBCDIC and from EBCDIC to ASCII.<br />
8. Use one of the following options to configure the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>:<br />
Editing ctgenvvar<br />
Ensure that these entries appear in the file:<br />
export AUTH_USERID_PASSWORD=Yes<br />
export _BPX_SHAREAS=Yes<br />
export JAVA_PROPAGATE=No<br />
Using the configuration tool<br />
Select the Use RACF Authentication option in the Environment<br />
Settings panel; see “z/OS Environment settings” on page 64.<br />
Problems<br />
If you have problems after configuring your system as described above, see<br />
“ECI_ERR_SECURITY_ERROR return code” on page 147.<br />
J2EE setup and configuration<br />
Using the configuration tool<br />
This topic discusses the administration of <strong>CICS</strong> resource adapters. Two<br />
resource adapters are supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The<br />
/deployable directory contains two resource adapter files:<br />
cicseciRRS.rar<br />
v This requires WebSphere Application Server for z/OS v4.01 with PTF<br />
UQ99329 (Service Level W401030).<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 67
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using the configuration tool<br />
v It contains J2EE <strong>CICS</strong> ECI connector support that is designed<br />
specifically to work with the resource recovery (RRS) component of<br />
z/OS or OS/390, so that applications can benefit from two-phase<br />
commit capability for transactions.<br />
v It must be run in the WebSphere Application Server v4.0 Runtime<br />
environment, not the WebSphere Application Server v4.0 plugin<br />
environment.<br />
v It can be deployed only in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> local mode.<br />
v The getLocal<strong>Transaction</strong> method of the ECIConnection class is not<br />
supported.<br />
v The interaction types SYNC_SEND and SYNC_RECEIVE are not<br />
supported.<br />
cicseci.rar<br />
v This is designed for use with all J2EE servers, other than WebSphere<br />
Application Server for z/OS, which support the J2EE Connector<br />
Architecture version 1.0.<br />
v Do not use this rar file with WebSphere Application Server for z/OS v4.<br />
Any value set by the setExecuteTimeout method of the ECIInteractionSpec<br />
class is ignored; neither connector supports timeout. An alternative is to set<br />
the TIMEOUT parameter in the external <strong>CICS</strong> interface options table,<br />
DFHXCOPT. See the <strong>CICS</strong> External Interfaces Guide for more information.<br />
Deploying <strong>CICS</strong> resource adapters<br />
Before you can use a J2EE resource adapter in a server runtime environment<br />
you must supply parameters for its internal ManagedConnectionFactory class.<br />
In a managed environment you set these parameters when you deploy the<br />
resource adapter to your server. For instructions on how to do this consult<br />
your server’s documentation.<br />
<strong>CICS</strong> resource adapters are provided in standard resource adapter modules<br />
ready for deployment into a J2EE server environment. They can be packaged<br />
in J2EE applications along with other components such as Enterprise Beans,<br />
and used to create larger, more complex systems.<br />
Deployment parameters for the ECI resource adapters<br />
This section describes the available deployment parameters for both the<br />
cicseci and cicseciRRS resource adapters, and their effect on the final deployed<br />
resource adapter. The tools used to configure these parameters are<br />
server-specific. Not all parameters are required; the default value is shown<br />
where appropriate.<br />
ConnectionURL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with which the resource<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Deployment parameters for the ECI resource adapters<br />
adapter will communicate. The URL takes the form<br />
protocol://address. These protocols are available:<br />
v tcp<br />
v http<br />
v ssl<br />
v local<br />
So, for example, you might specify a URL of tcp://ctg.business.com.<br />
For the local protocol simply specify local:.<br />
For the cicseciRRS resource adapter, only the local protocol is valid.<br />
PortNumber<br />
The port to connect to where the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
running. This parameter is not relevant if you are using the local<br />
protocol.<br />
This parameter is not valid for the cicseciRRS resource adapter,<br />
because it operates only in local mode.<br />
ServerName<br />
The name of the <strong>CICS</strong> server to connect to for all interactions through<br />
this resource adapter. This is the name as defined in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file. To use multiple servers within<br />
an environment you must deploy several resource adapters, each with<br />
a different ServerName attribute set.<br />
TranName<br />
The name of the <strong>CICS</strong> <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run.<br />
TPNName<br />
The name of the <strong>CICS</strong> TPN <strong>Transaction</strong> under which you want all<br />
programs started by the resource adapter to run. Note that TPNName<br />
takes precedence if both TranName and TPNName are specified.<br />
UserName<br />
The <strong>CICS</strong> userid to be used if no other security credentials are<br />
available. See the J2EE section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide for more information.<br />
Password<br />
The password for the <strong>CICS</strong> userid defined above.<br />
ClientSecurity<br />
The fully qualified name of the ClientSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ClientSecurity class is used. For more information on what<br />
ClientSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 69
Deployment parameters for the ECI resource adapters<br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
This parameter is not valid for the cicseciRRS resource adapter,<br />
because it operates only in local mode.<br />
ServerSecurity<br />
The fully qualified name of the ServerSecurity class to use in each<br />
interaction with <strong>CICS</strong>. This parameter is optional; if no value is given<br />
then no ServerSecurity class is used. For more information on what<br />
ServerSecurity classes are used for, and how to write them, see <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> security classes in the Java chapter of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Programming Guide.<br />
This parameter is not valid for the cicseciRRS resource adapter,<br />
because it operates only in local mode.<br />
KeyRingClass<br />
The fully qualified name of the SSL keyring class to use. This only<br />
applies when using the SSL protocol.<br />
This parameter is not valid for the cicseciRRS resource adapter,<br />
because it operates only in local mode.<br />
KeyRingPassword<br />
The password for the class defined in KeyRingClass. Because it is<br />
linked to KeyRingClass, it is also optional, and applies only to the SSL<br />
protocol.<br />
This parameter is not valid for the cicseciRRS resource adapter,<br />
because it operates only in local mode.<br />
TraceLevel<br />
The level of trace to be output by the resource adapter. For more<br />
details on trace levels and tracing see “Tracing” on page 71.<br />
As well as these user-definable properties, the cicseci resource adapter has a<br />
set of predefined attributes that each deployed resource adapter will inherit.<br />
These properties are defined in the J2EE/CA specification and are as follows:<br />
<strong>Transaction</strong> Support<br />
The cicseci resource adapter is defined as Local<strong>Transaction</strong>. If your<br />
server supports LastResourceOptimization, the resource adapter can<br />
participate in a global transaction, provided it is the only<br />
Local<strong>Transaction</strong> resource that has been enlisted.<br />
Re-Authentication Support<br />
The cicseci resource adapter supports re-authentication. This is the<br />
ability to change the security credentials when a connection is<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
equested from the server and an already existing one is allocated<br />
without having to disconnect and reconnect to the EIS. This improves<br />
performance.<br />
Deploying the cicseciRRS resource adapter<br />
Instructions for deploying the J2EE ECI resource adapter in WebSphere<br />
Application Server for z/OS are given below. A full configuration PDF is<br />
available from www.ibm.com/software/ts/cics/library/manuals/ in the<br />
Configuration booklets section.<br />
1. Install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
2. Create a work directory in your WebSphere installation directory, for<br />
example /WebSphere390/CB390/jbo.<br />
3. Move the file cicseciRRS.rar file from /deployable to the<br />
directory that you created in step 2.<br />
4. Extract the archive inside the working directory using the command:<br />
jar -xvf cicseciRRS.rar<br />
5. Grant permissions on the files extracted:<br />
chmod ugo+x *<br />
Deployment parameters for the ECI resource adapters<br />
6. Create a new conversation in the WebSphere Application Server z/OS<br />
Administration tool.<br />
7. Modify your SYSPLEX definition by selecting the Connection<br />
Management check box.<br />
8. Modify the J2EE Servers environment variables to add the following to<br />
the CLASSPATH:<br />
/ /cicseciRRS.jar<br />
/ /cicsframe.jar<br />
/ /ctgclient.jar<br />
/ /ctgserver.jar<br />
9. Modify the LIBPATH statement to point to the working directory created<br />
in step 2.<br />
10. Add a J2EE resource and give it a suitable name. Select the J2EE resource<br />
type <strong>CICS</strong>_ECIConnectionFactory.<br />
11. Add a J2EE Resource instance to the newly created resource. The name of<br />
the resource instance (<strong>CICS</strong>_ECIConnectionFactory instance name) will be<br />
the name that your bean looks up to get a connection.<br />
12. Fill in the fields appropriate to your system.<br />
13. Ensure you have saved all updates, and then activate your conversation.<br />
Tracing<br />
To help you in problem determination with any J2EE resource adapter<br />
applications that use the <strong>CICS</strong> resource adapters, a detailed tracing function is<br />
provided in the ECI resource adapter. The <strong>CICS</strong> resource adapters support<br />
four levels of trace:<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 71
Tracing<br />
0 No trace messages<br />
1 Exception tracing only (default level)<br />
2 Exception and method entry/exit trace messages<br />
3 Exception, method entry/exit and debug trace messages<br />
To provide more control over tracing, these system properties are available:<br />
com.ibm.connector2.cics.tracelevel<br />
This allows you to override the deployed trace level for the resource<br />
adapters without having to redeploy or deploy another <strong>CICS</strong> resource<br />
adapter.<br />
com.ibm.connector2.cics.dumpoffset<br />
The offset into a byte array that a hex dump will start at.<br />
com.ibm.connector2.cics.dumplength<br />
The maximum length of data displayed in a hex dump.<br />
com.ibm.connector2.cics.outputerr<br />
Declaring this directive sends trace output to standard error, if no<br />
other trace location has been specified either by the J2EE server, or by<br />
the application developer working in a nonmanaged environment. In<br />
other circumstances the provided logwriter takes precedence.<br />
Control of where trace is output is handled by the ConnectionManager being<br />
used by your environment. In a managed environment an option should be<br />
provided to allow you to set the path of the file that will be used for storing<br />
trace. Depending on how your environment allocates ConnectionManagers to<br />
resource adapters this file may contain messages from other resource adapters<br />
using the same ConnectionManager.<br />
When you deploy the <strong>CICS</strong> resource adapters into your environment, security<br />
restrictions are set up to allow access to the local file system for the purpose<br />
of writing trace files. The permissions used restrict access to this path:<br />
${user.home}${file.separator}IBM${file.separator}CTG${file.separator}-<br />
This might map to:<br />
/u/ctguser/IBM/CTG/-<br />
Therefore, when setting the name and path of the trace file in your J2EE<br />
environment, use a location below this directory structure to store your trace.<br />
Otherwise the resource adapters will not have security permissions to write to<br />
the file.<br />
72 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Other configuration tasks:<br />
To complete the configuration of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, do the following:<br />
v Configure <strong>CICS</strong> for the EXCI requests from the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Information about this task is given in the <strong>CICS</strong> External Interfaces Guide.<br />
v Create conversion templates to be used to translate the communication area<br />
used by the <strong>CICS</strong> programs requested by Web browsers. Information for<br />
this task is given in <strong>CICS</strong> Family: Communicating from <strong>CICS</strong> on System/390.<br />
Increasing the CPUTIME timeout when the volume of traffic is high<br />
The BPXPRMxx parmlib member contains the parameters that control<br />
processing and the file system. The system uses these values during<br />
initialization.<br />
Tracing<br />
It may be necessary to change the MAXCPUTIME value in the BPXPRMxx<br />
member in SYS1.PARMLIB if there is a high volume of traffic. This value<br />
determines the maximum amount of CPU time in seconds that a process may<br />
use. BPXPRMxx is used to set an initial value at IPL, which you can modify<br />
using the SETOMVS command.<br />
From OS/390 <strong>Version</strong> 2.8 onwards, you can set this value on a user ID basis<br />
using the CPUTIMEMAX value in the RACF user ID profile’s OMVS segment.<br />
For more information, see the OS/390 UNIX System Services Planning. book.<br />
Chapter 5. Configuring the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 73
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Chapter 6. Network Security<br />
This chapter describes how to set up <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to use the<br />
network security protocols SSL and HTTPS. For information on using RACF<br />
to authenticate ECI userids and passwords, see “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for use with RACF ® ” on page 65. This chapter consists of the<br />
following:<br />
“Determining your use of SSLight or JSSE<br />
for the SSL and HTTPS protocols” on<br />
page 76<br />
“Maintaining your digital certificates for<br />
SSLight” on page 76<br />
“Using externally signed certificates<br />
under SSLight” on page 77<br />
“Using self-signed certificates under<br />
SSLight” on page 82<br />
Read this for information on how <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> determines whether<br />
you are using SSLight or JSSE.<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under SSLight.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
SSLight.<br />
“Migration from SSLight” on page 86 Read this for information on migrating<br />
from SSLight to JSSE.<br />
“Installation” on page 86 Read this for information on installing<br />
JSSE.<br />
“Maintaining your digital certificates for<br />
JSSE” on page 87<br />
“Using externally signed certificates<br />
under JSSE” on page 87<br />
“Using self-signed certificates under JSSE”<br />
on page 91<br />
Read this for information on using the<br />
IBM Key Management utility iKeyMan<br />
for managing your digital certificates for<br />
JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under JSSE.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
JSSE.<br />
© Copyright IBM Corp. 1996, 2002 75
|<br />
|<br />
Security<br />
“Maintaining your digital certificates for<br />
System SSL” on page 95<br />
“Using externally signed certificates<br />
under System SSL” on page 96<br />
“Using self-signed certificates under<br />
System SSL” on page 101<br />
“Mapping client certificates to RACF<br />
userids” on page 105<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for SSL and HTTPS” on page 107<br />
“Other security considerations” on<br />
page 108<br />
Read this for information on using<br />
gskkyman, the System SSL tool provided<br />
by z/OS for managing your digital<br />
certificates.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use externally signed digital certificates<br />
under System SSL.<br />
Read this for information on how to<br />
configure an SSL server and SSL clients to<br />
use self-signed digital certificates under<br />
System SSL.<br />
Read this for information on mapping<br />
client certificates to RACF userids.<br />
Read this for information on how to<br />
configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
use the secure protocols.<br />
Read this for information on other<br />
security considerations.<br />
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> determines whether you wish to use SSLight or<br />
JSSE as follows:<br />
v If you pass a KeyRing class to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using SSLight.<br />
v If you pass a KeyStore file to the <strong>Gateway</strong> daemon, <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> assumes that you are using JSSE.<br />
SSLight<br />
Conflict with JSSE<br />
SSLight might not function correctly if JSSE is installed on your system. If<br />
JSSE is installed, rename file gskikm.jar, intheJRE/EXT directory.<br />
Maintaining your digital certificates for SSLight<br />
iKeyMan<br />
Use the ctgikey command to invoke iKeyMan for certificate management.<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 77.<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Maintaining your digital certificates for SSLight<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 82.<br />
v Add certificates to your KeyRing files.<br />
v Change your KeyRing password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyRing.<br />
Distributing iKeyMan to client workstations<br />
Although you perform most of the KeyRing management on the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> machine, you might need to distribute the iKeyMan tool<br />
to clients connecting to your SSL server. The client machines must have the<br />
minimum level of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Java support; see “Software<br />
requirements” on page 20. They might also require a script or command file to<br />
invoke the iKeyMan Java startup class.<br />
These examples assume that the client workstation has the following files in<br />
the ikeyman directory:<br />
v cfwk.zip<br />
v cfwk.sec<br />
v gsk5cls.jar<br />
v ikminit.properties<br />
All of these files are in the /classes subdirectory.<br />
Using iKeyman in DBCS environments<br />
If you have trouble running iKeyman in your locale, you can use this<br />
command to run it in English:<br />
java -classpath "/classes/cfwk.zip:<br />
/classes/gsk5cls.jar:"<br />
-Dkeyman.javaOnly=true<br />
-Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman<br />
Using externally signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyRing class<br />
2. Creating a certificate request<br />
3. Obtaining a digital certificate<br />
Chapter 6. Network Security 77
Using externally signed certificates under SSLight<br />
4. Receiving the digital certificate into the KeyRing<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyRings, or, in the case of HTTPS connections, the repository in<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyRing<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Using externally signed certificates under SSLight<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 80.<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site and request a Test<br />
Server Certificate:<br />
a. Point your Web browser at: www.verisign.com and navigate to their<br />
request Test Server Certificate application pages.<br />
b. Open the certificate request file you created earlier, using an ASCII text<br />
editor.<br />
Figure 13 on page 80 shows an example of a certificate request.<br />
c. During the Test Server Certificate request process you will be asked to<br />
submit your CSR — Copy and paste the contents of the file into the<br />
text box in the Web page.<br />
d. Verify the contents of your certificate request and provide the personal<br />
details when requested.<br />
If you are requesting a full VeriSign Server ID, rather than a test<br />
version, these details are used to authenticate your application.<br />
e. VeriSign processes your enrollment and sends an e-mail to the address<br />
specified in your personal details.<br />
This e-mail contains your Test Server Certificate, and instructions on<br />
how to:<br />
Chapter 6. Network Security 79
Using externally signed certificates under SSLight<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
-----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u<br />
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC<br />
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP<br />
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF<br />
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx<br />
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH<br />
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq<br />
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh<br />
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW<br />
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY<br />
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ<br />
-----END NEW CERTIFICATE REQUEST-----<br />
Figure 13. Example certificate request<br />
4. Receive the Server Certificate into the server KeyRing<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyRing.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyRing MyServerKeyRing.class is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyRing class, or in the case of HTTPS, the browser certificate<br />
repository, must contain the signer certificate of the Server Certificate. In our<br />
example, the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Using externally signed certificates under SSLight<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following sections describes how to obtain a VeriSign Digital ID.<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyRing class<br />
using the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
Chapter 6. Network Security 81
Using externally signed certificates under SSLight<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyRing class.<br />
3. Import the Client Certificate into the client KeyRing<br />
To import the #PKCS12 file containing the Client Certificate:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Your client KeyRing MyClientKeyRing.class is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under SSLight<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyRing classes<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyRing<br />
The first step is to create a server KeyRing class. This will contain your<br />
Server Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan using the command ctgikey.<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyServerKeyRing.class<br />
e. In Location, type a suitable location to store your server KeyRing<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK.<br />
The generated file MyServerKeyRing.class contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
Using self-signed certificates under SSLight<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 80.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyRing class:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
Chapter 6. Network Security 83
Using self-signed certificates under SSLight<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyRing<br />
A client KeyRing class contains as a minimum, the signer certificate of the<br />
SSL server, and a client X.509 certificate, if client authentication is required.<br />
The process for creating a client KeyRing class is similar to that for a<br />
server:<br />
a. Start iKeyMan using the command ctgikey<br />
b. Select Key Database File —> New.<br />
c. From Key Database Type, select SSLight key database class.<br />
d. In File name type a name for your keyring, such as<br />
MyClientKeyRing.class<br />
e. In Location, type a suitable location to store your client KeyRing<br />
The default location is the /bin subdirectory.<br />
f. Select OK.<br />
g. Type a password for the KeyRing file.<br />
h. Select OK.<br />
Like the server KeyRing class, the client KeyRing class contains a default<br />
selection of popular signer certificates.<br />
2. Import the server’s signer certificate<br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Using self-signed certificates under SSLight<br />
a. In iKeyMan select Add<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyRing need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyRing.class file with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support<br />
server authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyRing class also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
Chapter 6. Network Security 85
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under SSLight<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Migrating old self-signed certificates<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyRing class files, created with <strong>Version</strong> 3.0,<br />
using the iKeyMan tool.<br />
Restricting access to the server KeyRing<br />
The contents of the server KeyRing are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyRing class files have appropriate security access<br />
permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Java Secure Socket Extension (JSSE)<br />
Migration from SSLight<br />
To avoid possible conflicts between the different versions of iKeyMan used in<br />
SSLight and JSSE, IBM strongly recommends that you perform all migration<br />
actions before you install JSSE.<br />
To migrate from SSLight to JSSE:<br />
v Create new KeyStores and use these instead of existing KeyRing classes<br />
v Change existing security exits that implement the SSLightServerSecurity<br />
interface to implement the JSSEServerSecurity interface<br />
Installation<br />
See “Software requirements” on page 20 for details of environments in which<br />
JSSE is supported.<br />
You might need to update the lib/security/java.security file. In this file,<br />
locate the lines which begin security.provider and add a line like the<br />
following if it does not already exist:<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
security.provider.=com.ibm.crypto.provider.IBMJCE<br />
where is the next number in sequence following any existing entries.<br />
Maintaining your digital certificates for JSSE<br />
iKeyMan<br />
Use the following command to start the iKeyMan program:<br />
java com.ibm.ikeyman.Ikeyman<br />
With iKeyMan, you can:<br />
v Request and receive a digital certificate from a Certification Authority (CA),<br />
see “Using externally signed certificates under SSLight” on page 77.<br />
v Generate self-signed certificates, see “Using self-signed certificates under<br />
SSLight” on page 82.<br />
v Add certificates to your KeyStore files.<br />
v Change your KeyStore password.<br />
v Set a private key as the default.<br />
v Delete a key.<br />
v Export a key by copying it to a file.<br />
v Import a key from an exported copy and add it to a KeyStore.<br />
Using externally signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can act as an SSL server, with the ability to<br />
authenticate SSL clients and accept externally signed certificates from<br />
Certification Authorities (CAs) such as VeriSign. The following sections<br />
describe how to configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. Creating a KeyStore<br />
2. Creating a certificate request<br />
3. Obtaining a digital certificate<br />
4. Receiving the digital certificate into the KeyStore<br />
Installing JSSE<br />
Configuring your SSL server<br />
This section describes how to obtain a Test Server Certificate from the<br />
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a<br />
period of 14 days. As this certificate is for demonstration only it is not signed<br />
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All<br />
SSL clients need the VeriSign Test signer certificate root key to be installed in<br />
their client KeyStores, or, in the case of HTTPS connections, the repository in<br />
the browser. Obtaining a full VeriSign Server Certificate follows the same<br />
procedures as described here for the test version.<br />
1. Create a server KeyStore<br />
Chapter 6. Network Security 87
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 89.<br />
2. Create a Certificate Request<br />
Before you can obtain a Server Certificate from VeriSign, you must make a<br />
Certificate Request and store it locally:<br />
a. From iKeyMan, select Create —> New Certificate Request.<br />
b. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label verisignServerCert<br />
Key Size select 1024<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
c. Specify the name of a file in which to store the certificate request, or<br />
accept the default.<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
3. Obtain a Server Certificate<br />
The next step is to connect to the VeriSign Web site (www.verisign.com)<br />
and request a Test Server Certificate. You will be asked to paste in the<br />
contents of the certificate request file you created earlier (Figure 13 on<br />
page 80 shows an example of a certificate request) and agree to their<br />
licensing conditions. VeriSign will then send you a confirmation e-mail.<br />
This e-mail contains your Test Server Certificate, and instructions on how<br />
to:<br />
v install a Test Server ID<br />
v install a special Test CA Root<br />
4. Receive the Server Certificate into the server KeyStore<br />
When you have obtained the Server Certificate, you use iKeyMan to<br />
receive it into the server KeyStore.<br />
a. Copy and paste the Server Certificate data into a blank text file, using<br />
an ASCII text editor; save the file as verisignServerID.arm.<br />
b. From iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
c. Select Receive...<br />
d. In the Data type pull-down, select Base64-encoded ASCII<br />
e. Type the name and location of the text file containing your Server<br />
Certificate data<br />
f. Select OK.<br />
g. Select Key Database File then Exit.<br />
Your server KeyStore MyServerKeyStore.jks is now ready for use with<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificates, as<br />
well as your VeriSign Server Certificate and its corresponding private key.<br />
Configuring your SSL clients<br />
In normal operation, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses only server<br />
authentication when performing an SSL handshake; the client need only<br />
accept the presented Server Certificate. For server authentication to work, the<br />
client KeyStore, or in the case of HTTPS, the browser certificate repository,<br />
Chapter 6. Network Security 89
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
must contain the signer certificate of the Server Certificate. In our example,<br />
the signer certificate is the VeriSign Test signer certificate.<br />
In addition to server authentication, the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> also<br />
supports client authentication. With this option enabled, any connection<br />
attempted to either the ssl: or https: handler requires the client to present its<br />
own Client Certificate, which is also known as a Digital ID.<br />
The following instructions describe how to obtain a VeriSign Digital ID.<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Obtain a Client Certificate<br />
Unlike Server Certificates, you do not need to create a certificate request to<br />
obtain a Client Certificate. VeriSign provides a method of obtaining a Class<br />
1 Digital ID using either Netscape or Internet Explorer browsers.<br />
When you have obtained the Client Certificate and installed it in the<br />
browser repository, you can export the certificate data, together with its<br />
associated private key, into a secure file known as a #PKCS12 file. This file<br />
is password protected and can be imported into a client KeyStore using<br />
the iKeyMan tool.<br />
a. Point your Web browser at: www.verisign.com<br />
b. Follow the links on their Web site to buy a Class 1 Digital ID from<br />
their Secure E-Mail certificates product area.<br />
c. Complete the enrollment form as requested. The details will be used by<br />
VeriSign to authenticate the client application.<br />
90 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using externally signed certificates under JSSE<br />
d. VeriSign will send information for downloading and installing the<br />
Class 1 Digital ID to the e-mail address you supplied in your<br />
application.<br />
During the installation process, your browser allows you to store the<br />
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool<br />
supports #PKCS12 files and allows you to import certificates, along with<br />
their private key, into a client KeyStore.<br />
3. Import the Client Certificate into the client KeyStore<br />
To import the #PKCS12 file containing the Client Certificate:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select Import...<br />
c. Set Key file type to PKCS12 file.<br />
d. Type the name and location of the #PKCS12<br />
e. Select OK.<br />
f. Select Key Database File —> Close<br />
g. Select Key Database File —> Exit<br />
Your client KeyStore MyClientKeyStore.jks is now ready for use with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. It contains the default signer certificate, as well as your<br />
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding<br />
private-key.<br />
Using self-signed certificates under JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides a way for you to “self-sign” your<br />
certificates. You establish yourself as your own Certification Authority and<br />
generate the X.509 digital certificates for the server (<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>) and client (browser) side. The following sections describe how to<br />
configure an SSL server and SSL clients using iKeyMan.<br />
Configuring your SSL server and clients involves:<br />
1. creating KeyStores<br />
2. creating digital certificates<br />
3. exporting and importing the certificates<br />
Configuring your SSL server<br />
1. Create a server KeyStore<br />
The first step is to create a server KeyStore. This will contain your Server<br />
Certificate, with its associated private-key, and a number of signer<br />
certificates. The Server Certificate is a digital certificate that SSL uses to<br />
identify the server to connecting clients.<br />
a. Start iKeyMan<br />
Chapter 6. Network Security 91
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyServerKeyStore.jks<br />
e. In Location, type a suitable location to store your server KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file<br />
iKeyMan gives you an indication of the “strength” of your password.<br />
IBM recommends that you use a mixture of letters and numbers for<br />
your password; this makes the password more resistant to “brute<br />
force” dictionary attacks.<br />
h. Select OK<br />
The generated file MyServerKeyStore.jks contains, by default, a selection<br />
of popular signer certificates as follows:<br />
VeriSign Class 3 Public Primary Certification Authority<br />
VeriSign Class 2 Public Primary Certification Authority<br />
VeriSign Class 1 Public Primary Certification Authority<br />
RSA Secure Server Certification Authority<br />
Thawte Personal Basic CA<br />
VeriSign Test CA Root Certificate<br />
Thawte Personal Premium CA<br />
Thawte Premium Server CA<br />
Thawte Server CA<br />
Thawte Personal Freemail CA<br />
The VeriSign Class 1 through 3 Public Primary Certification Authority<br />
signer certificates enable the server to verify clients with VeriSign Client<br />
Certificates. This is explained in more detail in “Configuring your SSL<br />
clients” on page 89.<br />
2. Create a Server Certificate<br />
Now you are ready to create the self-signed Server Certificate and store it<br />
along with its private key in your server KeyStore:<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. Select New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleServerCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Server Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleServerCert.<br />
f. With exampleServerCert highlighted, select View/Edit.<br />
Notice that the information in the issued to (certificate requester)<br />
textbox is the same as that in the issued by (signer) textbox. To<br />
establish SSL connections with a server presenting this certificate, the<br />
client must trust the signer. To do this the client key repository must<br />
contain the signer certificate of the server presenting exampleServerCert.<br />
3. Export the server’s signer certificate<br />
a. With exampleServerCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleServercert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. Import it into any client<br />
repository that needs to handshake with this SSL server.<br />
Configuring your SSL clients<br />
1. Create a client KeyStore<br />
A client KeyStore class contains as a minimum, the signer certificate of the<br />
SSL server, and a client x.509 certificate, if client authentication is required.<br />
The process for creating a client KeyStore class is similar to that for a<br />
server:<br />
a. Start iKeyMan<br />
b. Select Key Database File —> New<br />
c. From Key Database Type, select JKS<br />
d. In File name type a name for your KeyStore, such as<br />
MyClientKeyStore.jks<br />
e. In Location, type a suitable location to store your client KeyStore<br />
f. Select OK<br />
g. Type a password for the KeyStore file.<br />
h. Select OK<br />
Chapter 6. Network Security 93
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Using self-signed certificates under JSSE<br />
Like the server KeyStore, the client KeyStore contains a default selection of<br />
popular signer certificates.<br />
2. Import the server’s signer certificate<br />
a. In iKeyMan select Add<br />
b. Locate the stored Server Base64-encoded ASCII certificate file. In our<br />
example, this is exampleServercert.arm.<br />
c. Select OK.<br />
d. Give this signer certificate a unique label, for example, My Self-Signed<br />
Server Authority.<br />
e. Select OK.<br />
This new signer certificate is added to the list of default signers.<br />
If the SSL handler used by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is configured to<br />
support only server authentication, skip step 3; the client KeyStore need<br />
contain only the signer certificate of the Server, which you have now<br />
imported. You can use the generated MyClientKeyStore.jks file with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>’s SSL protocol, which is configured to support server<br />
authentication.<br />
3. Create a Client Certificate<br />
Client authentication requires the client KeyStore also to contain a<br />
self-signed Certificate that is used to identify the connecting client.<br />
a. In iKeyMan, select Personal Certificates from the pull-down menu<br />
below the Key database content label.<br />
b. New Self-Signed...<br />
c. Complete the certificate request. Some fields are optional, but you must<br />
fill in at least the following (examples are shown):<br />
Key Label exampleClientCert<br />
<strong>Version</strong> select X509 V3<br />
Key Size select 1024<br />
Common Name This defaults to the name of the<br />
machine you are using<br />
Organization The name of your organization<br />
Country Select a two character ID from the list<br />
Validity Period The default is 365 days<br />
d. Select OK.<br />
iKeyMan generates a public/private key pair.<br />
e. The self-signed Client Certificate appears in the Personal Certificates<br />
window. The certificate has the name you typed in the Key Label field,<br />
in this example exampleClientCert.<br />
94 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
System SSL<br />
Using self-signed certificates under JSSE<br />
4. Export the client’s signer certificate<br />
a. With exampleClientCert highlighted, select Extract Certificate...<br />
b. In the Data type pull-down, select Base64-encoded ASCII<br />
c. Type the name and location of the text file containing your Server<br />
Certificate data. Our example uses exampleClientcert.arm<br />
d. Select OK.<br />
Store the exported certificate in a safe place. It must be imported into any<br />
server repository that needs to handshake with this SSL client.<br />
Migrating old self-signed certificates<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.0 supported only self-signed certificates,<br />
and not externally signed certificates. You can use your old self-signed<br />
certificates by importing the KeyStore files, created with <strong>Version</strong> 3.0, using the<br />
iKeyMan tool.<br />
Restricting access to the server KeyStore<br />
The contents of the server KeyStore are encrypted and protected by a<br />
password. However IBM recommends that you:<br />
v ensure that the KeyStore files have appropriate security access permissions<br />
v restrict access, where applicable, to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> machine<br />
Do not share certificates among servers. Do not allow servers to share a<br />
private key, particularly if they are running on different machines. Never send<br />
a private key to someone else.<br />
Maintaining your digital certificates for System SSL<br />
System SSL is part of Cryptographic Services, an optional feature of the z/OS<br />
operating system. It includes the gskkyman utility for maintaing your digital<br />
certificates. The gskkyman utility runs in either an rlogin shell environment or<br />
in the OMVS shell command line environment.<br />
With gskkyman you can:<br />
v Create a key database<br />
v Create a certificate request (and public/private key pair)<br />
v Create a self-signed certificate<br />
v Export a certificate request to a file<br />
v Receive a certificate after a certificate request has been fulfilled<br />
v Export a certificate to a file<br />
v Import a certificate from a file<br />
Chapter 6. Network Security 95
Maintaining your digital certificates for System SSL<br />
v Mark a certificate as a trusted CA certificate<br />
v Mark a certificate (and private key) as the default certificate for the key<br />
database<br />
v List certificate information<br />
v Remove a certificate (and private key) from a key database<br />
v Remove a key database.<br />
For further information on gskkyman, type the following command to display<br />
help information:<br />
gskkyman -h<br />
or see Cryptographic Services System Secure Sockets Layer Programming Guide and<br />
Reference. SC24–5877.<br />
Using externally signed certificates under System SSL<br />
The following sections describe how to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
as a System SSL server to use externally signed certificates. This involves:<br />
1. Creating a key database<br />
2. Creating a certificate request<br />
3. Receiving the certificate after the request has been fulfilled<br />
4. Storing the certificate as a Trusted CA Certificate<br />
Configuring your System SSL server<br />
1. Create a key database<br />
a. Type gskkyman<br />
This displays the IBM Key Management Utility menu:<br />
IBM Key Management Utility<br />
Choose one of the following options to proceed.<br />
1 - Create new key database<br />
2 - Open key database<br />
3 - Change database password<br />
0 - Exit program<br />
Enter your option number: 1<br />
b. Type 1 (Create new key database), then respond to the prompts as<br />
follows:<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
Enter key database name or press ENTER for "key.kdb":<br />
mykey.kdb<br />
Enter password for the key database.......> mypasswd<br />
Enter password again for verification.....> mypasswd<br />
Should the password expire? (1 = yes, 0 = no) [1]:<br />
Enter password expiration time (number of days) or press ENTER<br />
for 60 days: 35
Using externally signed certificates under System SSL<br />
Press Enter to save these values.<br />
c. The following message and prompt appears:<br />
The database has been<br />
successfully created, do you want to continue to work<br />
with the database now? (1 = yes, 0 = no) [1]:<br />
Type 1 or press Enter<br />
This displays the Key Database menu, which allows you to continue<br />
configuring the SSL server:<br />
Key database menu<br />
Current key database is /u/home/mykey.kdb<br />
1 - List/Manage keys and certificates<br />
2 - List/Manage request keys<br />
3 - Create new key pair and certificate request<br />
4 - Receive a certificate issued for your request<br />
5 - Create a self-signed certificate<br />
6 - Store a CA certificate<br />
7 - Show the default key<br />
8 - Import keys<br />
9 - Export keys<br />
10 - List all trusted CAs<br />
11 - Store encrypted database password<br />
0 - Exit program<br />
Enter option number (or press ENTER to return to the parent menu):<br />
The gskkyman utility creates the key database as a file, mykey.kdb in our<br />
example, in the hierarchical file system (HFS) of z/OS Unix System Services.<br />
You must include this file in the system LIBPATH environment variable.<br />
2. Create a certificate request (and public/private key pair)<br />
a. From the Key Database menu, type 3 (Create new key pair and<br />
certificate request)<br />
b. Respond to the prompts as follows:<br />
Chapter 6. Network Security 97
Using externally signed certificates under System SSL<br />
Enter certificate request file name or press ENTER for "certreq.arm": servercertreq.arm<br />
Enter a label for this key................> My CA<br />
Select desired key size from the following options (512):<br />
1: 512<br />
2: 1024<br />
Enter the number corresponding to the key size you want: 1<br />
Enter certificate subject name fields in the following.<br />
Common Name (required)................> myserver<br />
Organization (required)...............> my org<br />
Organization Unit (optional)..........><br />
City/Locality (optional)..............><br />
State/Province (optional).............><br />
Country Name (required 2 characters)..> UK<br />
Please wait while key pair is created...<br />
Your request has completed successfully, exit gskkyman?<br />
(1 = yes, 0 = no) [0]: 0<br />
Some fields are optional, but you must fill in at least the following<br />
(examples are shown):<br />
Request file name The default is servercertreq.arm<br />
Key label For example: My CA<br />
Key size select 512<br />
Common name The name of the server machine<br />
Organization The name of your organization<br />
Country A two character ID<br />
When you complete the certificate request, gskkyman creates a file,<br />
servercertreq.arm in our example, in the current working directory.<br />
The file is in Base64-encoded format. This is the format usually<br />
required by Certification Authorities (CAs). You can display the<br />
contents of the file using the cat servercertreq.arm command; Figure 14<br />
on page 99 shows an example of a certificate request.<br />
c. Send the request to a CA<br />
Ether transfer the file directly, as a text file, or copy it into an e-mail<br />
message.<br />
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Using externally signed certificates under System SSL<br />
-----BEGIN NEW CERTIFICATE REQUEST-----<br />
MIH7MIGmAgEAMEExCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsT<br />
CEVuZGljb3R0MREwDwYDVQQDEwhKb2huIERvZTBcMA0GCSqGSIb3DQEBAQUAA0sA<br />
MEgCQQCrIZdRnXhH1EMAwTuKMKYznCFp4CFk0YG66BhvMGgfTwql9aSRWkVcer8I<br />
I7Qk9aYzQ2LIpRhloJ9ugojy1I9VAgMBAAGgADANBgkqhkiG9w0BAQQFAANBAFc1<br />
xOfunjyt54dUqGDdPgbnMr5A3trUhzHHkX8xlfH9Albrpsv2a3FjvnmYWFPuFXAf<br />
3ABCD5nnsbk3AP++ic5UTM=<br />
-----END NEW CERTIFICATE REQUEST-----<br />
Figure 14. Example certificate request<br />
3. Receive the certificate<br />
When the CA returns a certificate to you, use gskkyman to receive it into<br />
the key database. Usually the CA sends an e-mail message containing a<br />
Base64-encoded certificate.<br />
To receive a certificate:<br />
a. Store the certificate in an HFS file on your z/OS operating system<br />
This file should be in the current working directory when you start<br />
gskkyman. This example assumes that you stored the certificate as<br />
servercert.arm.<br />
b. Type gskkyman<br />
c. Type 2 (Open key database)<br />
d. At the prompt, type the name of your key database<br />
In our example, the name is mykey.kdb.<br />
e. At the prompt, type your password<br />
f. In the Key Database menu, type 4 (Receive a certificate issued for your<br />
request)<br />
g. Respond to the prompts as follows:<br />
Enter certificate file name or press ENTER for "cert.arm": servercert.arm<br />
Do you want to set the key as the default in your key database?<br />
(1 = yes, 0 = no) [1]:<br />
Please wait while certificate is received......<br />
Your request has completed successfully, exit gskkyman?<br />
(1 = yes, 0 = no) [0]: 0<br />
4. Store the certificate<br />
Some well-known CA certificates are stored in the key database when you<br />
create it. You can display the list of stored CAs by typing 10 (List all<br />
trusted CAs) in the Key Database menu. The default list of stored CAs is:<br />
Chapter 6. Network Security 99
Using externally signed certificates under System SSL<br />
Trust CA certificate list<br />
Key database name is /home/mykey.kdb<br />
Please choose one of the following keys to work with.<br />
1 - Integrion Certification Authority Root<br />
2 - IBM World Registry Certification Authority<br />
3 - Thawte Personal Premium CA<br />
4 - Thawte Personal Freemail CA<br />
5 - Thawte Personal Basic CA<br />
6 - Thawte Premium Server CA<br />
7 - Thawte Server CA<br />
8 - Verisign Test CA Root Certificate<br />
9 - RSA Secure Server Certification Authority<br />
10 - Verisign Class 1 Public Primary Certification Authority<br />
11 - Verisign Class 2 Public Primary Certification Authority<br />
12 - Verisign Class 3 Public Primary Certification Authority<br />
Enter a key number or press ENTER to return to parent menu:<br />
To use a CA that is not one of the defaults you must store the CA’s<br />
certificate in your key database file.<br />
To use client authentication on your SSL connection you must store the<br />
CA’s certificate in the key database of the server program. You must also<br />
store the CA’s certificate in the key database of the client program<br />
regardless of whether the SSL connection uses client authentication.<br />
To store the certificate in your key database as a CA certificate:<br />
a. Store the certificate in an HFS file on your z/OS operating system.<br />
This file should be in the current working directory when you start<br />
gskkyman.<br />
b. Type gskkyman<br />
c. Type 2 (Open key database)<br />
d. At the prompt, type the name of your key database<br />
In our example, the name is mykey.kdb.<br />
e. At the prompt, type your password<br />
f. In the Key Database menu, type 6 (Store a CA certificate)<br />
g. Respond to the prompts as follows:<br />
Enter certificate file name or press ENTER for "cert.arm": servercert.arm<br />
Enter a label for this key................> My CA<br />
Please wait while certificate is stored...<br />
Your request has completed successfully, exit gskkyman?<br />
(1 = yes, 0 = no) [0]: 0<br />
When stored, the certificate is treated as ″trusted″ so that it can be used to<br />
verify incoming certificates.<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Using externally signed certificates under System SSL<br />
For a program acting as an SSL server, this certificate is used to verify a<br />
client’s certificate.<br />
For a program acting as an SSL client, this certificate is used to verify the<br />
server’s certificate, which is sent to the client during the SSL handshake<br />
processing.<br />
Using self-signed certificates under System SSL<br />
The following sections describe how to configure <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
as a System SSL server to use self-signed certificates. This involves:<br />
1. Creating a key database<br />
2. Creating a self-signed certificate<br />
3. Exporting the certificate to SSL clients<br />
Configuring your System SSL server<br />
1. Create a key database<br />
a. Type gskkyman<br />
This displays the IBM Key Management Utility menu:<br />
IBM Key Management Utility<br />
Choose one of the following options to proceed.<br />
1 - Create new key database<br />
2 - Open key database<br />
3 - Change database password<br />
0 - Exit program<br />
Enter your option number: 1<br />
b. Type 1 (Create new key database), then respond to the prompts as<br />
follows:<br />
Enter key database name or press ENTER for "key.kdb":<br />
mykey.kdb<br />
Enter password for the key database.......> mypasswd<br />
Enter password again for verification.....> mypasswd<br />
Should the password expire? (1 = yes, 0 = no) [1]:<br />
Enter password expiration time (number of days) or press ENTER<br />
for 60 days: 35<br />
Press Enter to save these values.<br />
c. The following message and prompt appears:<br />
The database has been<br />
successfully created, do you want to continue to work<br />
with the database now? (1 = yes, 0 = no) [1]:<br />
Type 1 or press Enter<br />
Chapter 6. Network Security 101
Using self-signed certificates under System SSL<br />
This displays the Key Database menu, which allows you to continue<br />
configuring the SSL server:<br />
Key database menu<br />
Current key database is /u/home/mykey.kdb<br />
1 - List/Manage keys and certificates<br />
2 - List/Manage request keys<br />
3 - Create new key pair and certificate request<br />
4 - Receive a certificate issued for your request<br />
5 - Create a self-signed certificate<br />
6 - Store a CA certificate<br />
7 - Show the default key<br />
8 - Import keys<br />
9 - Export keys<br />
10 - List all trusted CAs<br />
11 - Store encrypted database password<br />
0 - Exit program<br />
Enter option number (or press ENTER to return to the parent menu):<br />
The gskkyman utility creates the key database as a file, mykey.kdb in our<br />
example, in the hierarchical file system (HFS) of z/OS Unix System Services.<br />
You must include this file in the system LIBPATH environment variable.<br />
2. Create a self-signed certificate<br />
a. From the Key Database menu, type 5 (Create a self-signed certificate)<br />
b. Respond to the prompts as follows:<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Enter version number of the certificate to be created (1, 2, or 3) [3]: 3<br />
Enter a label for this key................> My Self-signed CA<br />
Select desired key size from the following options (512):<br />
1: 512<br />
2: 1024<br />
Enter the number corresponding to the key size you want: 1<br />
Enter certificate subject name fields in the following.<br />
Common Name (required)................> myserver<br />
Organization (required)...............> my org<br />
Organization Unit (optional)..........><br />
City/Locality (optional)..............><br />
State/Province (optional).............><br />
Country Name (required 2 characters)..> UK<br />
Enter number of valid days for the certificate [365]: 244<br />
Do you want to set the key as the default in your key database? (1 = yes, 0 =<br />
no) [1]:<br />
Do you want to save the certificate to a file? (1 = yes, 0 = no) [1]: 1<br />
Should the certificate binary data or Base64 encoded ASCII data be saved? (1 =<br />
ASCII, 2 = binary) [1]: 1<br />
Enter certificate file name or press ENTER for "cert.arm": servercert.arm<br />
Please wait while self-signed certificate is created...<br />
Your request has completed successfully, exit gskkyman?<br />
(1 = yes, 0 = no) [0]: 0<br />
Using self-signed certificates under System SSL<br />
Some fields are optional, but you must fill in at least the following<br />
(examples are shown):<br />
<strong>Version</strong> number The X.509 standard version number.<br />
Choose 3.<br />
Key label For example: My Self-signed CA<br />
Key size select 512<br />
Common name The name of the server machine<br />
Organization The name of your organization<br />
Country A two character ID<br />
Validity period The default is 365 days<br />
Set key as default? Setting the key as the default certificate<br />
allows the SSL Toolkit to use the<br />
certificate without having to specify the<br />
distinguished name in calls to System<br />
SSL APIs.<br />
Save certificate to file? Save the certificate in a separate file, as<br />
well as in the key database. You need<br />
Chapter 6. Network Security 103
Using self-signed certificates under System SSL<br />
-----BEGIN NEW CERTIFICATE REQUEST-----<br />
to do this to export the certificate to<br />
your SSL clients; see step 3.<br />
Binary or ASCII? Choose Base64-encoded ASCII. This is<br />
the default.<br />
Certificate file name The default is cert.arm for ASCII and<br />
cert.crt for binary.<br />
If you chose to save the certificate to a file, gskkyman creates the file,<br />
servercert.arm in our example, in the current working directory. You can<br />
display the contents of the file using the cat servercert.arm command;<br />
Figure 15 shows an example of a certificate file in Base64-encoded ASCII<br />
format.<br />
MIH7MIGmAgEAMEExCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsT<br />
CEVuZGljb3R0MREwDwYDVQQDEwhKb2huIERvZTBcMA0GCSqGSIb3DQEBAQUAA0sA<br />
MEgCQQCrIZdRnXhH1EMAwTuKMKYznCFp4CFk0YG66BhvMGgfTwql9aSRWkVcer8I<br />
I7Qk9aYzQ2LIpRhloJ9ugojy1I9VAgMBAAGgADANBgkqhkiG9w0BAQQFAANBAFc1<br />
xOfunjyt54dUqGDdPgbnMr5A3trUhzHHkX8xlfH9Albrpsv2a3FjvnmYWFPuFXAf<br />
3ABCD5nnsbk3AP++ic5UTM=<br />
-----END NEW CERTIFICATE REQUEST-----<br />
Figure 15. Example certificate file in Base64-encoded ASCII format<br />
3. Export certificates to client programs<br />
All SSL client programs connecting to your SSL server must be able to<br />
treat the self-signed certificate as a trusted CA certificate. For this you<br />
must export the self-signed certificate to all SSL client programs.<br />
a. From the Key Database menu, type 1 (List/Manage keys and<br />
certificates)<br />
This displays the Key and certificate list menu:<br />
Key and certificate list<br />
Key database name is /u/home/mykey.kdb<br />
Please choose one of the following keys to work with.<br />
1 - My Self-signed CA<br />
2 - Integrion Certification Authority Root<br />
3 - IBM World Registry Certification Authority<br />
4 - Thawte Personal Premium CA<br />
5 - Thawte Personal Freemail CA<br />
6 - Thawte Personal Basic CA<br />
7 - Thawte Premium Server CA<br />
8 - Thawte Server CA<br />
9 - Verisign Test CA Root Certificate<br />
Enter a key number or press ENTER for more labels:<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
. Type the key number of the certificate you created, My Self-signed CA<br />
in our example.<br />
This displays the Key menu:<br />
Key Menu<br />
Currently selected key: My Self-signed CA<br />
Choose one of the following options to proceed.<br />
1 - Show key information<br />
2 - Set the selected key as default<br />
3 - View certificate of the key<br />
4 - Remove trust root status<br />
5 - Copy the certificate of this key to a file<br />
6 - Copy the certificate request of this key to a file<br />
7 - Delete the key<br />
8 - Export the key to another database<br />
9 - Export the key to a file<br />
0 - Exit program<br />
Using self-signed certificates under System SSL<br />
Enter option number (or press ENTER to return to the parent menu):<br />
c. Type 5 (Copy the certificate of this key to a file.)<br />
d. Respond to the prompts as follows:<br />
Should the certificate binary data or Base64 encoded ASCII data be saved? (1 =<br />
ASCII, 2 = binary) [1]:1<br />
Enter certificate file name or press ENTER for "cert.arm": servercert.arm<br />
Please wait while the certificate is written to a file...<br />
Your request has completed successfully, exit gskkyman?<br />
(1 = yes, 0 = no) [0]: 1<br />
e. Transfer the file, servercert.arm in our example, to the system where<br />
the SSL client program will run.<br />
f. Store the certificate in the SSL client’s key database as a trusted CA<br />
certificate.<br />
Mapping client certificates to RACF userids<br />
This involves:<br />
1. Using the RACF command RACDCERT to associate client certificates with<br />
RACF userids<br />
2. Using a Java class supplied by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to map<br />
certificates to their associated RACF userids<br />
Associate a client certificate with a RACF userid<br />
1. Perform the actions described in “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for use with RACF ® ” on page 65.<br />
2. Copy the certificate that you wish to process into an MVS sequential file.<br />
Chapter 6. Network Security 105
Mapping client certificates to RACF userids<br />
The file should have variable length, blocked records (RECFM=VB) and be<br />
accessible from TSO.<br />
3. Run the RACDCERT command in TSO.<br />
This command does not run in the UNIX System Services shell.<br />
The syntax of RACDCERT is:<br />
RACDCERT ADD(’datasetname’) TRUST [ ID(userid) ]<br />
where:<br />
datasetname is the name of the data set containing the client certificate.<br />
userid is the userid to be associated with the certificate.<br />
This parameter is optional. If omitted, the certificate is<br />
associated with the user issuing the RACDCERT<br />
command.<br />
When you issue the RACDCERT command, RACF creates a profile in the<br />
DIGTCERT class. This profile associates the certificate with the userid. You<br />
can then use the profile to translate a certificate to a userid without giving a<br />
password.<br />
For further information on the RACDCERT command, including the format<br />
of data allowed in the downloaded certificate data set, see Z/OS Security<br />
Server (RACF) Command Language Reference.<br />
Map a certificate to its associated RACF userid<br />
Use the Java class com.ibm.ctg.util.RACFUserid to map a certificate to a<br />
RACF userid. The class has the following methods:<br />
v setCertificate(byte[] clientCertificateData);<br />
v getRACFUserid();<br />
IBM recommends that you create a RACFUserid as follows:<br />
RACFUserid myUseridObject = new RACFUserid(myCertificate);<br />
This creates an object and automatically populates it with certificate data,<br />
without needing to call the setCertificate(byte[] clientCertificateData);<br />
method. When the object is created, getRACFUserid() makes a native z/OS<br />
call and tries to map the certificate to a RACF userid. If successful, it returns a<br />
string containing the RACF userid.<br />
The SystemSSLServerCompression.java class in the<br />
/samples/java/com/ibm/ctg/samples/security subdirectory<br />
shows an example of creating the RACFUserid object.<br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
For more information on the com.ibm.ctg.util.RACFUserid class, refer to <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
To use the SSL and HTTPS protocols, enable them using the configuration<br />
tool; see “Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> settings” on page 56. You<br />
can specify that either or both of the protocols is used, and you can use SSL<br />
and System SSL at the same time. When you enable the protocols, by default,<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> listens for SSL requests on port 8050, and for<br />
HTTPS requests on port 443. Howevever, to use SSLight and System SSL at<br />
the same time, you must specify unique port numbers for each.<br />
SSL and HTTPS configuration settings<br />
The following configuration settings are specific to the SSL and HTTPS<br />
protocols:<br />
KeyRing database Specifies the name of the System SSL server<br />
key database.<br />
KeyRing or KeyStore name Specifies the name of the server KeyRing or<br />
KeyStore.<br />
For a KeyRing, you must also add the<br />
classname to the CLASSPATH environment<br />
variable.<br />
KeyRing or KeyStore password<br />
Specifies the password used to read the<br />
encrypted server KeyRing or KeyStore.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes the<br />
password to the configuration file in a form<br />
that prevents a casual observer from easily<br />
reading it.<br />
Use client authentication Enables client authentication. The default is<br />
that only server authentication is enabled.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides two default KeyRing class files,<br />
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS<br />
connections under SSLight. Both KeyRings have been encrypted using the<br />
password default. Use them only in testing environments.<br />
Specifying a client KeyRing or KeyStore<br />
Your choice of secure protocol determines whether or not you need a<br />
KeyRing, or KeyStore, for both server and client:<br />
HTTPS<br />
Specify a KeyRing or KeyStore only in the server.<br />
Mapping client certificates to RACF userids<br />
Chapter 6. Network Security 107
Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for SSL and HTTPS<br />
SSL<br />
The SSL protocol requires you to specify KeyRings, or KeyStores for both the<br />
server and the client.<br />
For more information see SSL Java<strong>Gateway</strong>, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide.<br />
Using the SSL and HTTPS protocols<br />
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP<br />
protocols. To make a connection to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, your client<br />
application flows a request using the appropriate URL. For example, for SSL<br />
use a URL like:<br />
ssl://trans<strong>Gateway</strong>Machine:8050<br />
Similarly, for HTTPS:<br />
https://trans<strong>Gateway</strong>Machine:443<br />
For more information on the design and implementation of client-side<br />
programs, see <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> programming interface HTML pages.<br />
Other security considerations<br />
You can find information about other security considerations as follows:<br />
The AUTH_USERID_PASSWORD<br />
environment variable<br />
See “The environment variables” on<br />
page 48<br />
Setting extended attributes on HFS files See “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for use with RACF ® ” on page 65<br />
Setting surrogate options in DFHXCOPT, the<br />
EXCI options module<br />
See “Customizing EXCI options” on<br />
page 50<br />
<strong>CICS</strong> security for ECI/EXCI calls See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Chapter 7. Performance<br />
This chapter helps you to:<br />
v understand the factors that affect <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> performance<br />
v achieve the best performance from your system<br />
“Assessing system performance” Read this for an overview of the things to<br />
consider when assessing the performance<br />
of your system.<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
configuration” on page 110<br />
Read this for information on <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
parameters which affect performance.<br />
“Java considerations” on page 112 Read this for information on Java factors<br />
which affect performance.<br />
“Other system factors” on page 113 Read this for information on other system<br />
factors which affect performance.<br />
“Tracing” on page 114 Read this for information on using tracing<br />
to measure performance.<br />
“Performance monitoring tools” on<br />
page 114<br />
Read this for information on performance<br />
monitoring tools.<br />
Assessing system performance<br />
To assess the overall performance of your system you need to understand<br />
how all system components, including <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, affect<br />
performance. These system components might include:<br />
v browser<br />
v routers and firewalls<br />
v WebServer or Web Application Server<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
v <strong>CICS</strong> server<br />
The information you collect to assess performance should include:<br />
v processor loading<br />
v data transfer rates<br />
v response times<br />
Response times are particularly useful indicators. They help you to<br />
understand which system components most affect performance.<br />
© Copyright IBM Corp. 1996, 2002 109
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
IBM has chosen default values for configuration and tuning to give a<br />
compromise between:<br />
v limiting the system resources used by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> after it<br />
has started<br />
v giving <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> the flexibility to handle increases in<br />
workload<br />
The following factors affect performance; you might need to alter the default<br />
configuration to suit your system environment:<br />
Connection Manager threads<br />
If the value specified for Initial number of Connection Manager<br />
threads is too high, your system will waste resources managing the<br />
threads that are not needed.<br />
The design of your applications determines the number of Connection<br />
Manager threads you need. Incoming connections to <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> could be from a servlet, with each copy of the servlet issuing<br />
its own ECI requests, but sharing a single Connection Manager<br />
thread. Alternatively, the application could create a pool of<br />
connections, and ECI requests could be issued onto any connection<br />
from the pool.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new Connection Manager thread,<br />
and TCP/IP connection, each time a Java client side application<br />
creates a new Java<strong>Gateway</strong> object. This means that system<br />
performance is better if your applications issue many ECI requests<br />
using the same Java<strong>Gateway</strong> object, and from within the same thread,<br />
than if they create a new Java<strong>Gateway</strong> object for each request.<br />
Flowing multiple requests through the same Java<strong>Gateway</strong> object also<br />
reduces the system resources required to create, and to destroy,<br />
Java<strong>Gateway</strong> objects.<br />
If the number of threads needed by applications exceeds the value<br />
specified for Maximum number of Connection Manager threads,<br />
each new request that requires a Connection Manager thread must<br />
wait until a thread becomes available. If the waiting time exceeds the<br />
value specified in the Connection timeout parameter, <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> refuses the connection.<br />
Worker threads<br />
Worker threads handle outbound connections between <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> and your <strong>CICS</strong> server. The design of your<br />
applications, and the workload that you need to support, affects the<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
number of Worker threads you need: the longer your <strong>CICS</strong><br />
transactions remain in process, the more Worker threads you need to<br />
maintain a given transaction rate.<br />
v If the value specified for Initial number of Worker threads is too<br />
high, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to manage threads<br />
that it does not need<br />
v If the value is too low, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses resources to<br />
search for available Worker threads.<br />
When using ECI to call the same <strong>CICS</strong> program, you can estimate the<br />
number of Worker threads you need to support a given workload by<br />
multiplying the following values:<br />
v number of transactions per second passing through <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong><br />
v average transaction response time through <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> in seconds<br />
An MVS address space can open a maximum of 100 EXCI pipes. This<br />
means that you cannot improve performance by specifying a value<br />
greater than 100 for Maximum number of Worker threads. However,<br />
if your <strong>CICS</strong> transactions remain in process for a long time, all of the<br />
EXCI connections could become busy, leaving no Worker threads<br />
available. For example, if the average transaction response time<br />
through <strong>CICS</strong> is 0.5 seconds, the maximum achievable transaction rate<br />
through a single <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is about 200 transactions<br />
per second.<br />
You can increase throughput by starting multiple gateways; see<br />
“Starting multiple <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s” on page 124.<br />
Communication protocols<br />
Your choice of protocol depends on the nature of your client<br />
applications. However, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does considerably<br />
more processing to handle the HTTP and HTTPS protocols than it<br />
does to handle the TCP and SSL protocols. In addition, when using<br />
HTTP or HTTPS, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> creates a new TCP/IP<br />
connection with each client request. For better performance, use TCP<br />
or SSL in preference to HTTP or HTTPS where possible.<br />
Display TCP/IP hostnames<br />
Selecting this option might cause severe performance reduction on<br />
some systems. See “Display TCP/IP hostnames” on page 57.<br />
Timeout values<br />
It is unlikely that you can improve performance by changing the<br />
default timeout values. However, you may need to change them for<br />
Chapter 7. Performance 111
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
Java considerations<br />
particular applications. Refer to “Configuring <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> settings” on page 56 for more information on these and all<br />
other configuration parameters.<br />
Connection logging<br />
The gateway configuration setting, Log client connections and<br />
disconnections, controls whether or not <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
writes a message each time that a client application program connects<br />
to, or disconnects from, the <strong>Gateway</strong> daemon. The default is for these<br />
messages not to be written. Selecting this setting can significantly<br />
reduce performance, especially in a system where client application<br />
programs connect and disconnect frequently. See “Log client<br />
connections and disconnections” on page 58.<br />
Maximum Java heap size<br />
If your system requires large numbers of Connection Manager threads<br />
you might need to increase the heap size to improve performance; see<br />
also “java.lang.OutOfMemory exception” on page 143. How you set<br />
the heap size depends on your JVM. Refer to the documentation for<br />
your JVM for more information.<br />
Just-In-Time (JIT) compiler<br />
Use the java -version command to find whether or not the JIT is<br />
enabled; it is enabled by default in JDK 1.3.1. Performance<br />
immediately after a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has started might be<br />
relatively slow because of JIT overheads. The JIT threshold is 2000 on<br />
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to<br />
run 2000 times before it is ’JITed‘. Refer to your JVM documentation<br />
for information on JIT techniques.<br />
Java<strong>Gateway</strong> objects<br />
Performance is better if you flow multiple requests using the same<br />
Java<strong>Gateway</strong> object than if you create a new Java<strong>Gateway</strong> object with<br />
each request. Each time you create, and destroy, a new Java<strong>Gateway</strong><br />
object you use additional system resources for:<br />
v creation and destruction of the object itself<br />
v creation and destruction of any associated sockets<br />
v garbage collection<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Other system factors<br />
Other system factors<br />
EXCI connections<br />
When you define your EXCI connections you can chooose between<br />
generic EXCI pipes and specific EXCI pipes. Specific EXCI pipes give<br />
slightly better performance. See “<strong>CICS</strong> server connection definition”<br />
on page 37 for more information on selecting your EXCI connections.<br />
Region size<br />
The JVM runs within the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> address space.<br />
This means that, if your application requires <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> to create large numbers of threads, for example Connection<br />
Manager threads, you might need to increase the region size. You<br />
define the region size with the REGION parameter in the EXEC<br />
statement in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> start JCL. See “Region size<br />
considerations” on page 123 for more information on this parameter.<br />
ECI COMMAREA size<br />
The size of the ECI COMMAREA has a large effect on performance. If<br />
you make the COMMAREA larger, you need more system resources<br />
to process it, and your response times are longer. Refer to <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for information on how to<br />
specify COMMAREA parameters in ECI requests.<br />
The setCommareaOutboundLength method, which is part of the<br />
EciRequest object, is particularly important to performance. The<br />
amount of data that an application sends in the COMMAREA flow to<br />
<strong>CICS</strong> may be small , and the amount of data expected from <strong>CICS</strong> in<br />
return may be unknown. To improve performance significantly, and<br />
reduce network loading:<br />
v Use the setCommareaOutboundLength method to ensure that you<br />
send only the required data in the outbound flow to <strong>CICS</strong>, and not<br />
the full Commarea_Length.<br />
<strong>CICS</strong> removes any null data from the COMMAREA in the return<br />
flow, and the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> automatically pads out the<br />
nulls and returns the full COMMAREA to the application.<br />
v Use the getInboundDataLength method to show the amount of<br />
non-null data returned.<br />
v Do not use the deprecated setCommareaInboundLength method<br />
because it prevents automatic commarea null stripping.<br />
<strong>CICS</strong> server transactions<br />
The design of your <strong>CICS</strong> server transactions affects the performance of<br />
your system. The response time through <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
might increase if your transactions:<br />
v need to wait for shared resources, for example data sets or<br />
applications, to become available<br />
Chapter 7. Performance 113
Other system factors<br />
Tracing<br />
v make remote links to other <strong>CICS</strong> systems<br />
v are unnecessarily complex<br />
Refer to the Performance and Tuning documentation for your <strong>CICS</strong><br />
server system for information on how to get the best performance.<br />
Synchronous or asynchronous ECI calls<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has to do less processing to handle a<br />
synchronous ECI call than to handle an equivalent asynchronous call.<br />
Also, synchronous ECI calls create fewer network flows than<br />
asynchronous calls. This means that synchronous ECI calls give better<br />
performance than asynchronous calls.<br />
Extended logical units of work<br />
Take care when extending a logical unit of work across multiple<br />
program link calls that may span a long time period (for example,<br />
user thinking time). The logical unit of work holds various locks, and<br />
other <strong>CICS</strong> resources, on the server. This may cause delays to other<br />
users who are waiting for the same locks and resources.<br />
Also, each logical unit of work occupies one <strong>CICS</strong> non-facility task for<br />
the duration of its execution. This means that you must define enough<br />
free tasks in the <strong>CICS</strong> server to service the maximum expected<br />
number of concurrent calls.<br />
Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more<br />
information.<br />
IBM does not recommend the use of the full <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace<br />
to monitor performance in a production environment. This is because the<br />
trace itself significantly decreases performance.<br />
Where possible, try to measure response times, without using tracing, through<br />
the different parts of your system, to find where delays are happening. For<br />
example, you could measure response times at the client application, and also<br />
through <strong>CICS</strong> and WebSphere.<br />
Performance monitoring tools<br />
Resource Management Facility (RMF )<br />
This is a measurement collection tool. It measures selected areas of<br />
system activity which is collected in the form of System Management<br />
Facilty (SMF) records. You can use it to measure processor and I/O<br />
activity in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> address space, and also to<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Performance monitoring tools<br />
measure similar activity in, for example, the <strong>CICS</strong> server and<br />
WebSphere. For more information see<br />
Refer also to the performance and tuning documentation for WebSphere,<br />
TCP/IP, <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS, and TXSeries .<br />
Chapter 7. Performance 115
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
Chapter 8. Operation<br />
This chapter describes how to start and stop the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for z/OS. The startup options that you can specify are described.<br />
Testing your configuration<br />
Sample JCL is provided to check that ctgenvvar and CTG.INI are correctly<br />
configured. See /samples/samples.txt for details.<br />
Starting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
You can start the gateway:<br />
v From an z/OS UNIX System Services command line.<br />
v By submitting JCL to start a batch job. If you choose this option you can<br />
register with the automatic restart manager component of MVS; see<br />
“Automatic restart management” on page 119.<br />
You can start the gateway with default values for the options, or with<br />
user-supplied values. The options and their values are described in “Starting<br />
the <strong>Gateway</strong> with user-specified options”.<br />
Starting from a command line<br />
To start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with the default options, type ctgstart<br />
at the command prompt and press Enter.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, Port = 2006<br />
Starting the <strong>Gateway</strong> with user-specified options<br />
The user definable options on the start command are:<br />
-port=port_number<br />
The TCP/IP port number assigned to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
-initconnect=number<br />
The initial number of ConnectionManager threads.<br />
-maxconnect=number<br />
The maximum number of ConnectionManager threads. If this value is set<br />
to -1, no limits are applied to the number of ConnectionManager threads.<br />
© Copyright IBM Corp. 1996, 2002 117
Operation<br />
-truncationsize=nnn<br />
Specifies the maximum size of any data blocks shown in the trace, where<br />
nnn is any positive integer. You can use this option in addition to either<br />
-trace or -x and this overrides the default size set by these options. For<br />
example, to switch on standard tracing and dump a maximum of 20,000<br />
bytes:<br />
ctgstart -trace -truncationsize=20000<br />
If you specify a value of 0, no data blocks are shown in the trace.<br />
-dumpoffset=offset<br />
Specifies the offset from which displays of any data blocks start. If the<br />
specified offset is greater than the total length of data, the data is dumped<br />
as if the offset were 0.<br />
-initworker=number<br />
The initial number of Worker threads.<br />
-maxworker=number<br />
The maximum number of Worker threads. If this value is set to -1, no<br />
limits are applied to the number of Worker threads.<br />
-trace<br />
This is the standard trace option (see “Tracing” on page 133). It only traces<br />
the first 80 bytes of the COMMAREA by default.<br />
If you used the configuration tool to configure your <strong>Gateway</strong>, the default<br />
destination for the trace output is the file CTG.TRC in the<br />
/bin subdirectory. Otherwise, trace output is written to<br />
stderr.<br />
-stack<br />
Enables exception stack tracing only. All checked Java exceptions are<br />
traced, including exceptions that are expected during normal operation of<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, but no other tracing is done.<br />
-tfile=pathname<br />
If tracing is enabled, writes the trace messages to the file specified in<br />
pathname. This overrides the default destination for trace output (see the<br />
-trace option).<br />
-tfilesize=number<br />
Specifies the maximum size, in kilobytes, of the trace text file.<br />
-noinput<br />
Disables the reading of input from the console. In this case, you can not<br />
stop the <strong>Gateway</strong> by input to the console session, “Stopping the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>” on page 127.<br />
-x Enables full debug tracing. This includes everything traced by the -trace<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
option, plus additional information including information about the<br />
internal workings of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. This option traces the<br />
entire COMMAREA by default.<br />
This option will decrease performance significantly.<br />
-dnsnames<br />
Enables the display of symbolic TCP/IP hostnames in messages.<br />
-j Pass an argument to the JVM. For example, -j-D= sets a<br />
JVM system property. See the JVM command line interpreter help for<br />
guidance in using this switch.<br />
To override the startup defaults, type: ctgstart at the command prompt,<br />
followed by the startup options you require, and press Enter.<br />
A <strong>Gateway</strong> console session starts, and the following messages are displayed<br />
showing the values being used:<br />
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,<br />
CCL6502I: Initial Workers = 1, Maximum Workers = 100, Port = 2006<br />
To get help for the startup options, enter: ctgstart ?<br />
For more information about the start options related to tracing, see “Tracing”<br />
on page 133.<br />
Automatic restart management<br />
See /samples/samples.txt for details of sample JCL provided.<br />
If you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with JCL (see “Starting with JCL”<br />
on page 121), you can register the job with z/OS Automatic Restart Manager<br />
(ARM). This allows MVS to restart the <strong>Gateway</strong> automatically if it fails, or if<br />
the system on which it was running fails.<br />
MVS automatic restart management is a sysplex-wide integrated automatic<br />
restart mechanism that:<br />
v Restarts an MVS subsystem in place if it abends (or if a monitor program<br />
notifies ARM of a stall condition)<br />
v Restarts all the elements of a workload (for example, <strong>CICS</strong> TORs, AORs,<br />
FORs, DB2 ® , and so on) on another MVS image after an MVS failure<br />
v Restarts <strong>CICS</strong> data sharing servers in the event of a server failure<br />
v Restarts a failed MVS image<br />
The main benefits of ARM are that it:<br />
v Eliminates the need for operator-initiated restarts, or restarts by other<br />
automatic packages, thereby:<br />
Operation<br />
Chapter 8. Operation 119
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
– Improving emergency restart times<br />
– Reducing errors<br />
– Reducing complexity<br />
v Provides cross-system restart capability. It ensures that the workload is<br />
restarted on MVS images with spare capacity, by working with the MVS<br />
workload manager.<br />
v Allows all elements within a restart group to be restarted in parallel. Restart<br />
levels (using the ARM WAITPRED protocol) ensure the correct starting<br />
sequence of dependent or related subsystems.<br />
Prerequisites<br />
To use ARM you need ARM and a Sysplex controller. You need to define<br />
policies for automatic restart management; see z/OS MVS Programming: Sysplex<br />
Services Guide, SA22-7617.<br />
Use the ctgarm command to register the <strong>Gateway</strong>; see “Starting with JCL” on<br />
page 121 for examples of how to use the command. This comand file is<br />
installed into the /bin subdirectory. You must mark ctgarm as<br />
APF-authorized. To issue the following command, you must be the owner of<br />
the ctgarm file, or a superuser. You also need authority to update RACF group<br />
BPX.FILEATTR.APF:<br />
extattr +a /bin/ctgarm<br />
To verify that you have the necessary authority, proceed as follows:<br />
1. Log on to MVS.<br />
2. Run ISPF.<br />
3. Choose option 6 (Command).<br />
4. Issue the following command:<br />
SR CLASS(FACILITY)<br />
Check that this entry appears in the list:<br />
BPX.FILEATTR.APF<br />
The ctgarm command takes one of the following parameters:<br />
v ’R[egister] ARM_ID [ARM_TYPE]’<br />
v ’D[eregister]’<br />
ARM_ID is a unique 16–character ID. ARM_TYPE is an 8–character restart<br />
level; the default is SYSLVL2. Valid characters for both ARM_ID and<br />
ARM_TYPE are:<br />
v Uppercase alphabetic characters<br />
v The numbers 0 through 9<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v $, #, @, and underscore (_).<br />
The first character may not be a number.<br />
The ctgarm command returns the following codes:<br />
0 No errors.<br />
4 Restarting.<br />
8 Miscellaneous error, including already registered or not unique ID.<br />
12 Severe error, for example ARM is not installed.<br />
Operation<br />
For ARM error codes see z/OS MVS Programming: Sysplex Services Reference,<br />
SA22-7618.<br />
For more information about Automatic Restart Management, see z/OSV1R2.0<br />
MVS Setting up a Sysplex, SA22–7625.<br />
Starting with JCL<br />
See /samples/samples.txt for details of sample JCL provided.<br />
Table 7 is a sample of the JCL you can use to start the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> as a batch job. The job is shown here as a series of stages so that you<br />
can modify it if you do not wish to use ARM. Code the job in the normal<br />
way; do not include the entries in the Stage column.<br />
Table 7. Sample JCL to register the <strong>Gateway</strong> with ARM and start it as a batch job<br />
Stage Code<br />
1. //DFHJGATE JOB (Accounting info),CLASS=A,USER=user,PASSWORD=passwd,<br />
// MSGCLASS=H<br />
2a. //* Name to identify this JCL run<br />
// SET CTGNAME=’CTG’<br />
2b. //* Unique ID for ARM and used to identify this JCL run<br />
// SET CTGNAME=’CTG_RESTART_ARM1’<br />
3a. //* Fixed file names for log files<br />
// SET CTGLOG=’/logs/ctgo.log’<br />
// SET CTGERR=’/logs/ctge.log’<br />
// SET CTGDIR=’/bin/’<br />
3b. //* File names based on date this JCL starts (or restarts)<br />
//* The variable Q allows mixed case to be used in other variables<br />
// SET Q=’’’’<br />
// SET INSTDIR=’/’<br />
// SET CTGDIR=&Q.&INSTDIR.bin/&Q.<br />
// SET LOGDIR=&Q.&INSTDIR.logs/&Q.<br />
// SET CTGLOG=&Q.&LOGDIR.&CTGNAME.o.&YYMMDD..log&Q.<br />
// SET CTGERR=&Q.&LOGDIR.&CTGNAME.e.&YYMMDD..log&Q.<br />
Chapter 8. Operation 121
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
Table 7. Sample JCL to register the <strong>Gateway</strong> with ARM and start it as a batch<br />
job (continued)<br />
Stage Code<br />
4. //TIMESTMP EXEC PGM=BPXBATCH,<br />
// PARM=’SH echo Starting &CTGNAME. on $(date)’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU<br />
5. //REG EXEC PGM=BPXBATCH,<br />
// PARM=’PGM &CTGDIR.ctgarm REGISTER &CTGNAME.’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
//<br />
//*<br />
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU<br />
// IF RC < 5 THEN<br />
6. //CTG EXEC PGM=BPXBATCH,<br />
// PARM=’SH &CTGDIR.ctgstart -noinput’,<br />
// REGION=8M<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU<br />
//STDERR DD PATH=’&CTGERR.’,<br />
//<br />
//*<br />
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU<br />
7. //DEREG EXEC PGM=BPXBATCH,<br />
// PARM=’PGM &CTGDIR.ctgarm DEREGISTER’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
//<br />
// ENDIF<br />
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU<br />
8. //<br />
Stages:<br />
1. Include this stage.<br />
2. Choose one of the following stages to identify the JCL run:<br />
a. If you are not using ARM, any name is acceptable.<br />
b. If you are using ARM, the name must be unique across the sysplex.<br />
3. Choose one of the following stages to define the log files:<br />
a. This stage uses a fixed name for the log files. Messages are written to<br />
the same files whenever the JCL is run. Stage 4 on page 123 tells you<br />
how to overwrite the files, or append messages to them.<br />
b. In this stage, the log file names include the date on which the JCL was<br />
run. Unique log files are created for each day on which the JCL is run.<br />
If you run the JCL more than once a day, messages are written to the<br />
log files from the first run.<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
Consider setting the location of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace file to<br />
the same location. Make an entry like the following in the <strong>Gateway</strong> section<br />
of the CTG.INI file:<br />
tfile=/logs/ctg.trace<br />
4. TIMESTMP enters the date and time into the standard output log file STDOUT.<br />
With the OAPPEND option specified in PATHOPTS, ARM and the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> append messages to the existing log file. To<br />
overwrite the log file at each restart, remove the OAPPEND option from<br />
PATHOPTS.<br />
5. This stage registers your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with ARM; omit it if<br />
you do not wish to use ARM. BPXBATCH is the MVS program that runs a<br />
z/OS UNIX System Services script as a batch job.<br />
6. This stage starts the <strong>Gateway</strong> daemon. The PARM field specifies that the<br />
shell, SH, runs the ctgstart command with the -noinput option. To reduce<br />
the number of messages written to the standard output log file, do not<br />
select the gateway setting Log client connections and disconnections. See “Log<br />
client connections and disconnections” on page 58 for more information.<br />
The OAPPEND option in PATHOPTS causes the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
append messages to existing log files.<br />
7. This stage deregisters the <strong>Gateway</strong> with ARM. It is only called if the<br />
<strong>Gateway</strong> is closed down correctly. Omit this stage if you do not wish to<br />
use ARM.<br />
8. End of job.<br />
Note: When the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is started with JCL, a number of<br />
other jobs are started in addition to the specified job. For example, for a<br />
jobname <strong>CICS</strong>TGQ, there would also be a number of jobs named<br />
<strong>CICS</strong>TGQ1 through <strong>CICS</strong>TGQn.<br />
If the JCL terminates unexpectedly<br />
If the JCL terminates immediately, and diagnosis of the JCL output shows that<br />
ctgstart terminated, examine file STDERR for details of why ctgstart failed.<br />
Region size considerations<br />
Set the REGION parameter on the EXEC card in the JCL according to the<br />
number of threads that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> will run.<br />
The following parameters might also affect the values that you can choose for<br />
the REGION parameter.<br />
v The ASSIZEMAX parameter of the OMVS segment of a RACF userid; see<br />
the RACF Command Language Reference for more information.<br />
v The UNIX System Services MAXASSIZE parameter found in<br />
SYS1.PARMLIB(BPXPRMxx); see the UNIX System Services Planning book for<br />
more information.<br />
Chapter 8. Operation 123
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
The value specified for ASSIZEMAX overrides any value provided by the<br />
MAXASSIZE parameter<br />
Note: A setting of REGION=0M may cause a java.lang.OutOfMemoryError;<br />
see “java.lang.OutOfMemory exception” on page 143.<br />
Starting multiple <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s<br />
See /samples/samples.txt for details of sample JCL provided.<br />
To start multiple copies of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> requires a separate<br />
CTG.INI file for each one; see “The environment variables” on page 48 for<br />
details of how to do this using the <strong>CICS</strong>CLI environment variable.<br />
The following example shows you how to start multiple copies of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> using a started task. Run the example as a job:<br />
//CTG24 JOB CLASS=A<br />
/*JOBPARM SYSAFF=P24<br />
// COMMAND ’S CTG,JOBNAME=CTGT2401,ID=01,SYSID=T24A’<br />
// COMMAND ’S CTG,JOBNAME=CTGT2402,ID=02,SYSID=T24A’<br />
// COMMAND ’S CTG,JOBNAME=CTGT2403,ID=01,SYSID=T24B’<br />
// COMMAND ’S CTG,JOBNAME=CTGT2404,ID=02,SYSID=T24B’<br />
// EXEC PGM=IEFBR14<br />
Each <strong>Gateway</strong> running on the sysplex must have a unique ID.<br />
This starts the following JCL for each <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The job is<br />
shown here as a series of stages so that you can modify it if you do not wish<br />
to use ARM. Code the job in the normal way; do not include the entries in the<br />
Stage column.<br />
Table 8. Sample JCL to register the <strong>Gateway</strong> with ARM and start it as a batch job<br />
Stage Code<br />
1. //CTG PROC ID=’01’,SYSID=’T24A’<br />
//*<br />
//*ID -UNIQUE ID FOR THIS INSTANCE OF THE CTG<br />
//*<br />
//* The variable Q allows mixed case to be used in other variables<br />
// SET Q=’’’’<br />
2a. //* Name to identify this JCL run<br />
// SET CTGNAME=’CTG’<br />
2b. //* Unique ID for ARM and used to identify this JCL run<br />
// SET CTGNAME=&Q.CTGARM_&SYSID.&ID.&Q.<br />
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Table 8. Sample JCL to register the <strong>Gateway</strong> with ARM and start it as a batch<br />
job (continued)<br />
Stage Code<br />
3a. //* Fixed file names for log files<br />
// SET CTGLOG=&Q./logs/CTG&SYSID.&ID.o.log&Q.<br />
// SET CTGERR=&Q./logs/CTG&SYSID.&ID.e.log&Q.<br />
// SET CTGDIR=&Q./bin/&Q.<br />
// SET CTGENV=&Q./bin/ctgenv&SYSID.&ID.&Q.<br />
3b. //* File names based on date this JCL starts (or restarts)<br />
// SET INSTDIR=’/’<br />
// SET CTGDIR=&Q.&INSTDIR.bin/&Q.<br />
// SET LOGDIR=&Q.&INSTDIR.logs/&Q.<br />
// SET CTGLOG=&Q.&LOGDIR.&CTGNAME.&SYSID.&ID.o.&YYMMDD..log&Q.<br />
// SET CTGERR=&Q.&LOGDIR.&CTGNAME.&SYSID.&ID.e.&YYMMDD..log&Q.<br />
// SET CTGENV=&Q.&CTGDIR.ctgenv&SYSID.&ID.&Q.<br />
4. //TIMESTMP EXEC PGM=BPXBATCH,<br />
// PARM=’SH echo Starting &CTGNAME. on $(date)’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),<br />
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)<br />
5. //REG EXEC PGM=BPXBATCH,<br />
// PARM=’PGM &CTGDIR.ctgarm REGISTER &CTGNAME.’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),<br />
//<br />
//*<br />
PATHMODE=(SIRWXU,SIRWXG,SIRWXO)<br />
// IF RC < 5 THEN<br />
6. //CTG EXEC PGM=BPXBATCH,<br />
// PARM=’SH &CTGDIR.ctgstart -noinput’,<br />
// REGION=8M<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),<br />
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)<br />
//STDERR DD PATH=’&CTGERR.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),<br />
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)<br />
//*SETERR DD PATH=’/dev/null’<br />
//STDENV DD PATH=’&CTGENV.’,<br />
//<br />
//*<br />
PATHOPTS=(ORDONLY)<br />
7. //DEREG EXEC PGM=BPXBATCH,<br />
// PARM=’PGM &CTGDIR.ctgarm DEREGISTER’<br />
//STDOUT DD PATH=’&CTGLOG.’,<br />
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),<br />
//<br />
// ENDIF<br />
PATHMODE=(SIRWXU,SIRWXG,SIRWXO)<br />
Operation<br />
Chapter 8. Operation 125
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
Table 8. Sample JCL to register the <strong>Gateway</strong> with ARM and start it as a batch<br />
job (continued)<br />
Stage Code<br />
8. //PEND<br />
//<br />
Stages:<br />
1. Include this stage.<br />
2. Choose one of the following stages to identify the JCL run:<br />
a. If you are not using ARM, any name is acceptable.<br />
b. If you are using ARM, the name must be unique across the sysplex.<br />
3. Choose one of the following stages to define the log files:<br />
a. This stage uses fixed names for the log files; messages are written to<br />
the same files whenever the JCL is run. The name of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is used in the log file name, so it is clear which<br />
log belongs to which <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. If you adopt a similar<br />
convention it should always be possible to identify which messages<br />
belong to which <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
b. In this stage, the log file names include the date on which the JCL was<br />
run. Unique log files are created for each day on which the JCL is run.<br />
If you run the JCL more than once a day, messages are written to the<br />
log files from the first run.<br />
4. TIMESTMP enters the date and time into the STDOUT log.<br />
5. This stage registers your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with ARM. Omit it if<br />
you do not wish to use ARM.<br />
6. This stage starts the <strong>Gateway</strong> daemon.<br />
7. This stage deregisters the <strong>Gateway</strong> daemon with ARM. It is called only if<br />
the <strong>Gateway</strong> daemon is closed down correctly. Omit this stage if you do<br />
not wish to use ARM.<br />
8. End of procedure.<br />
Note the changes for PATHMODE and PATHOPTS compared to the JCL for a<br />
single <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> instance. Without these you have to have<br />
the same userid as that under which the jobs run, or have superuser authority<br />
to read the log files. Also, coding STDERR to /dev/null results in no trace file<br />
being written. This is necessary as you cannot stop the connect/disconnect<br />
trace entries going to STDERR. The commented out definition of STDERR is<br />
provided as an example of this alternative.<br />
The above JCL also pulls in a unique STDENV data set for each instance of<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. You also need to change ctgstart to avoid<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
modifying or overwriting STEPLIB for this STEPLIB definition to take place.<br />
This is an example file /bin/ctgenvT24A01:<br />
DFHJVPIPE=BATCHCLI<br />
DFHJVSYSTEM_00=<strong>CICS</strong>T24A<br />
DFHJVSYSTEM_01=<strong>CICS</strong>T24B<br />
DFHJVSYSTEM_02=<strong>CICS</strong>T25A<br />
DFHJVSYSTEM_03=<strong>CICS</strong>T25B<br />
STEPLIB=<strong>CICS</strong>TS22.SDFHEXCI:<strong>CICS</strong>TS22.SDFHLOAD<br />
<strong>CICS</strong>CLI=/bin/CTGT24A01.INI<br />
Operation<br />
Each of the other three instances of the <strong>Gateway</strong> in the started task example<br />
would have its STDENV file (T24A02, T24B01 and T24B02). Each of these files<br />
would reference a separate CTG.INI file through the <strong>CICS</strong>CLI environment<br />
variable, to define a minimum of a unique TCP/IP port number.<br />
If you are using TCP/IP port sharing as a form of workload management in<br />
an MVS image, consider using port 2006 (the default) for each <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
To allow the client the freedom of not specifying a specific <strong>CICS</strong> APPLID on<br />
the incoming request, modify the DFHXCURM sample by removing the<br />
branch in the sample and code giving it a list of the <strong>CICS</strong> regions. One<br />
DFHXCURM exit is needed for each <strong>CICS</strong> region. As you cannot change the<br />
name of the exit, place the exit into unique Partitioned Data Sets and ensure<br />
they are placed first in the STEPLIB environment variable (in the above file).<br />
To start multiple <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s from OMVS with console input<br />
when directed to a port that is portshared, define the jobname ″OMVS″ as<br />
having access to the shared port in the TCP/IP profile. If console input is not<br />
required, then start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s via JCL and define the JCL<br />
jobname in the TCPIP profile.<br />
See “EDC5111I PERMISSION DENIED message” on page 139, for information<br />
on a problem that can be caused when the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
jobname is shorter than eight characters.<br />
Stopping the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
If you started the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> from the command line, and if<br />
you did not specify the -noinput parameter, you can stop the <strong>Gateway</strong> by<br />
typing Q and pressing Enter in the <strong>Gateway</strong> console session.<br />
If you have used the -noinput parameter, or if you used JCL to start the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, you must stop the <strong>Gateway</strong> process by using the JES<br />
CANCEL command.<br />
Chapter 8. Operation 127
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Operation<br />
Note: When you cancel the main <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> job, all other jobs<br />
are cancelled. For example, for a jobname <strong>CICS</strong>TGQ, the jobs named<br />
<strong>CICS</strong>TGQ1 through <strong>CICS</strong>TGQn would also be cancelled.<br />
Administering your system<br />
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on<br />
page 62), you can perform the following administrative functions without<br />
having to restart the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
v Set the <strong>Gateway</strong> trace<br />
v Set JNI trace<br />
v Query the current trace settings<br />
You execute the Java archive ctgadmin.jar from a command prompt to set<br />
trace or to query trace settings. You can administer the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> remotely from a workstation that has this JAR file and the supported<br />
level of Java; you do not need to install the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the<br />
workstation. See “TCPAdmin protocol settings” on page 62 for details of how<br />
to define which hosts have permission to administer your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
The following sections describe the commands. Parameters are not case<br />
sensitive; those in brackets are optional.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier than version <strong>5.0</strong>.<br />
Earlier versions cause the administration program to lock. If this<br />
happens, terminate the process, for example by pressing Ctrl+C.<br />
Setting the <strong>Gateway</strong> trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]<br />
[-tfilesize=number] [-tlevel=number]<br />
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]<br />
See “Parameters” on page 129 for an explanation of parameters.<br />
Setting the JNI trace<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address<br />
-a=setjnitrace -tfile=path [-tlevel=number]<br />
See “Parameters” on page 129 for an explanation of parameters.<br />
Querying trace settings<br />
From a command prompt, issue the following command:<br />
java -jar ctgadmin.jar -ctg=address -a=qtrace<br />
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Parameters<br />
See “Parameters” for an explanation of parameters.<br />
Administering your system<br />
ctg Mandatory. Specifies the <strong>Gateway</strong> which is to be<br />
administered. You can specify either a hostname, for example<br />
tcp://myserver:2810, or an IP address, for example<br />
tcp://127.0.0.1:2810. In these examples, 2810 is the port you<br />
specified for TCPAdmin; see “TCPAdmin protocol settings” on<br />
page 62.<br />
Warning: Do not specify a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> earlier<br />
than version <strong>5.0</strong>. Earlier versions cause the<br />
administration program to lock. If this happens,<br />
terminate the process, for example by pressing<br />
Ctrl+C.<br />
a Mandatory. Defines the action to take. Permitted values are:<br />
v setgwtrace to control <strong>Gateway</strong> tracing<br />
v setjnitrace to control JNI tracing<br />
v qtrace to determine what trace settings are active<br />
tfile Specifies the output file for <strong>Gateway</strong> or JNI tracing, for<br />
example ./tracefile.trc. Do not specify the same file for<br />
<strong>Gateway</strong> and JNI trace output.<br />
<strong>Gateway</strong> tracing<br />
If you do not specify a value for this tag, trace output is<br />
sent to the console.<br />
JNI tracing<br />
You must specify a value for this tag. If you do not, an<br />
error is displayed.<br />
tlevel Specifies the trace level. Permitted values are:<br />
<strong>Gateway</strong> tracing:<br />
0 Off. No trace information is output.<br />
1 Exception tracing. Only exceptions are traced.<br />
Equivalent to ctgstart -stack; see “Starting the<br />
<strong>Gateway</strong> with user-specified options” on page 117.<br />
2 Trace exceptions, and entry and exit of methods.<br />
3 Trace exceptions, some internals, and entry and<br />
exit of methods (equivalent to ctgstart -trace).<br />
4 Full debug tracing (all trace points, equivalent to<br />
ctgstart -x).<br />
Chapter 8. Operation 129
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Administering your system<br />
JNI tracing:<br />
0 Off. No trace information is output.<br />
1 On.<br />
tfilesize Specifies the maximum size, in kilobytes, of the trace output<br />
file, for example 50000.<br />
dumpoffset Specifies the offset from which displays of any data blocks<br />
start, for example 512. If the offset is greater than the total<br />
length of data to be displayed, an offset of 0 is used. You<br />
cannot use this together with the fulldatadump parameter.<br />
truncationsize Specifies the byte at which to stop the hex dump, for example<br />
2000. It defines the end point, not the number of bytes to<br />
display. So if on a dump of size 40 you set the dumpoffset to<br />
11, and the truncationsize to 25, you will see 15 bytes (from<br />
11 to 25).<br />
You cannot use this together with the fulldatadump parameter.<br />
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in<br />
truncationsize.<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Chapter 9. Problem determination<br />
Preliminary checks<br />
What to do next<br />
Problem determination is not to be confused with problem solving, although<br />
while investigating a problem you may find enough information to solve the<br />
problem. Examples of the types of problem that can arise are:<br />
v End-user errors<br />
v Programming errors<br />
v Configuration errors.<br />
Before investigating the problem, it is worth checking to see whether there is<br />
an obvious cause:<br />
v Has the system run successfully before?<br />
v Have you made any changes to the configuration of the system or added<br />
new features or programs?<br />
v If you have migrated from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for OS/390 <strong>Version</strong> 3,<br />
are you sure that the configuration file (<strong>Gateway</strong>.properties), and JGate<br />
script were migrated successfully?<br />
v Are your environment variables, such as CLASSPATH and LIBPATH set<br />
correctly? (See “Setting environment variables” on page 47.)<br />
The CLASSPATH variable is displayed at the top of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> trace output. See “Tracing” on page 133 for information on starting<br />
the <strong>Gateway</strong> with tracing enabled.<br />
v Are there any messages explaining the failure?<br />
See “Messages” on page 132.<br />
v Can the failure be reproduced?<br />
If you think the problem is with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, see<br />
“Diagnosing common problems” on page 139. Here you will find information<br />
on diagnosing common configuration and other errors, as well as advice on<br />
the documentation you need to collect in specific situations.<br />
See “Program support” on page 149 for information on how to contact IBM.<br />
See “Documenting problems” on page 150 for the information that you will be<br />
asked to provide.<br />
© Copyright IBM Corp. 1996, 2002 131
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
Messages<br />
If you think the problem is in another product, follow the problem<br />
determination procedures provided with that product. For <strong>CICS</strong> servers, see<br />
the <strong>CICS</strong> Problem Determination Guide.<br />
The <strong>Gateway</strong> daemon writes log messages to standard output (stdout) orto<br />
standard error (stderr). If <strong>Gateway</strong> daemon tracing is enabled, it also writes<br />
log messages to the trace output file.<br />
Messages have the format:<br />
CCLnnnnt: <br />
where nnnn is a number, and t is one of:<br />
I for information messages, written to standard output<br />
E for error messages, written to standard error<br />
W for warning messages, written to standard error<br />
See “Starting with JCL” on page 121 for examples of redirecting standard<br />
output and standard error to files. You can choose to redirect both standard<br />
output and standard error to the same file.<br />
Refer to the documentation for your operating system for more information<br />
on redirecting output.<br />
See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for an explanation of all <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> messages.<br />
Sources of information<br />
You can get problem determination information from the following sources:<br />
v The standard output (stdout) and standard error (stderr) files. As well as<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> messages (see “Messages”), these files also<br />
contain other messages as follows:<br />
– Standard output contains any messages returned to EXCI from <strong>CICS</strong>.<br />
– Standard error contains error messages from the Java virtual machine<br />
(JVM). The JVM messages are documented in the Java development<br />
toolkit (JDK).<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace, see the following section.<br />
v EXCI trace: This shows the EXCI activity. A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace<br />
is part of the EXCI trace and the trace points are listed in Table 9 on<br />
page 137. For details of EXCI tracing, see the <strong>CICS</strong> External Interfaces Guide<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Tracing<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
v JNI log: check file ctgjnilog. for JNI error codes. The location<br />
of the file is as follows:<br />
– Normally in /ibm/ctg, where is the<br />
directory defined in the user’s $HOME environment variable.<br />
– If the $HOME environment variable is not set, the log file is written to<br />
the user’s current directory.<br />
If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not have the necessary write<br />
permission, the log is not created.<br />
See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages for an explanation of the<br />
codes.<br />
v <strong>CICS</strong> trace: This shows the progress of the request through:<br />
– The <strong>CICS</strong> mirror transaction that handles the EXCI request<br />
– The called <strong>CICS</strong> program.<br />
Examine the AP trace points in the <strong>CICS</strong> trace.<br />
To route messages and trace information to a file, specify:<br />
ctgstart -trace -tfile=pathname<br />
when starting the <strong>Gateway</strong>, which generates a file in the pathname directory.<br />
To produce a full debug trace, you can use the ctgstart -x option.<br />
There are three main levels of <strong>Gateway</strong> and application tracing:<br />
Stack tracing Trace entries are written only when a Java<br />
exception occurs. They can help to determine<br />
the source of the exception. Use this when it is<br />
important to maintain performance.<br />
Standard tracing Java exceptions and the main <strong>Gateway</strong><br />
functions and events are traced. By default,<br />
the <strong>Gateway</strong> displays only the first 128 bytes<br />
of any data blocks (for example the<br />
COMMAREA, or network flows) in the trace.<br />
Debug tracing Java exceptions and the main <strong>Gateway</strong><br />
functions and events are traced in greater<br />
detail than with stack or standard tracing. By<br />
default, the <strong>Gateway</strong> displays the whole of<br />
any data blocks in the trace. Use this only<br />
when performance is not important or if<br />
standard tracing did not give enough<br />
information to solve the problem.<br />
Chapter 9. Problem determination 133
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
<strong>Gateway</strong> tracing<br />
You can start tracing in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> process, or in the user<br />
application that makes calls to the <strong>Gateway</strong>.<br />
You use options on the ctgstart command to enable and control tracing in the<br />
<strong>Gateway</strong>. For example, to enable the standard trace, type the following<br />
command when starting the <strong>Gateway</strong>:<br />
ctgstart -trace<br />
If you used the configuration tool to configure your <strong>Gateway</strong>, (or set the<br />
TFILE parameter in the CTG.INI file), then the default destination for trace<br />
output is file ctg.trc in the /bin subdirectory. Otherwise, trace<br />
output is written to stderr. You can override the default destination for trace<br />
output by using the ctgstart -tfile option. For example, the command:<br />
ctgstart -x -tfile pathname<br />
starts the <strong>Gateway</strong> with debug tracing enabled and writes the trace output to<br />
the file specified by pathname.<br />
The options you can specify on ctgstart are:<br />
-trace<br />
Enables standard tracing. It only traces the first 80 bytes of the<br />
COMMAREA by default.<br />
-stack<br />
Enables exception stack tracing only. Most Java exceptions are traced,<br />
including exceptions that are expected during normal operation of the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, but no other tracing is done.<br />
-x Enables full debug tracing. This includes everything traced by the -trace<br />
option, plus additional information including information about the<br />
internal workings of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. This option traces the<br />
entire COMMAREA by default.<br />
This option will decrease performance significantly.<br />
-tfile=pathname<br />
If tracing is enabled, writes the trace messages to the file specified in<br />
pathname. This overrides the default destination for trace output (see the<br />
-trace option).<br />
-tfilesize=number<br />
Specifies the maximum size, in kilobytes, of the trace file.<br />
-truncationsize=nnn<br />
Specifies the maximum size of any data blocks shown in the trace, where<br />
nnn is any positive integer. You can use this option in addition to either<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
-trace or -X and this overrides the default size set by these options. For<br />
example, to switch on standard tracing and dump a maximum of 20,000<br />
bytes:<br />
ctgstart -trace -truncationsize=20000<br />
If you specify a value of 0, no data blocks are shown in the trace.<br />
-dumpoffset=offset<br />
Specifies the offset from which displays of any data blocks start. If the<br />
specified offset is greater than the total length of data, the data is dumped<br />
as if the offset were 0.<br />
Performance considerations<br />
Tracing, especially debug tracing, decreases performance. The following<br />
changes were made in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 4.0 to reduce the<br />
effect of tracing on performance:<br />
v Trace output is not also written to stderr if you use the -tfile option to<br />
specify a trace output file.<br />
v Only the first line of any data block in the trace output is time-stamped.<br />
v The -truncationsize and -dumpoffset options allow you to limit the size of<br />
any data blocks that are written in the trace.<br />
v The -tfilesize option allows you to limit the size of the trace output file.<br />
Time stamps<br />
If the time stamps in console messages and trace files are approximately 20<br />
seconds different from the system clock, apply IBM Java APAR PQ47736. This<br />
APAR is recommended if you are using <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> tracing. It<br />
is available in Java PTF UQ56153 (included in Service Refresh 9).<br />
Application tracing<br />
You can enable tracing in the application in two ways: either use a Java<br />
directive when you start the JVM, or add calls to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> tracing API. Use the -D option on the Java command to specify Java<br />
directives. The tracing API comprises several static methods in the T class of<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide book for further information.<br />
JNI tracing<br />
You cannot enable JNI trace through the configuration tool. Use one of the<br />
following methods to enable it:<br />
v When you start the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, issue the command<br />
ctgstart -j-Dgateway.T.setJNITFile=filename<br />
where filename is the name of the file to which trace output is to be sent.<br />
Chapter 9. Problem determination 135
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
v While the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is running, use the system<br />
administration functions. You must have enabled the TCPAdmin protocol<br />
handler (see “TCPAdmin protocol settings” on page 62). See “Administering<br />
your system” on page 128 for details of how to enable JNI trace<br />
dynamically.<br />
v For Java Client applications running in local mode, use Java to launch your<br />
application and set the system property gateway.T.setJNITFile, as shown in<br />
the following example:<br />
java -Dgateway.T.setJNITFile=filename application<br />
where<br />
– filename is the name of the file to which trace output is to be sent<br />
– application is the application to launch<br />
Using the CTG_JNI_TRACE environment variable to enable JNI trace is<br />
supported only for migration purposes.<br />
To obtain a JNI trace for a local mode connection from a servlet under<br />
WebSphere Application Server, do the following:<br />
1. Set CTG_JNI_TRACE=filename in the httpd.envvars file<br />
2. Modify the IHS JCL to specify parameters to the Language Environments<br />
(LE) as follows:<br />
LEPARM=’ENVAR("_CEE_ENVFILE=/your/httpd.envvars")’<br />
3. Ensure the user ID under which WebSphere Application Server is running<br />
has write permission to the trace output file.<br />
For more information refer to the WebSphere Application Server<br />
documentation.<br />
J2EE Tracing<br />
Refer to “Tracing” on page 71 for information on using the tracing function<br />
provided with the ECI and EPI resource adapters.<br />
Issues with tracing if ConnectionFactory serialized<br />
As described above, if you use the serializable interface to store your<br />
ConnectionFactory then you lose the reference to your LogWriter. This is<br />
because LogWriters are not serializable and cannot be stored. When you<br />
deserialize your ConnectionFactory it will not contain a reference to the<br />
LogWriter. To ensure that your LogWriters are stored on any connections<br />
created from this ConnectionFactory you must do the following. This only<br />
applies in a nonmanaged environment.<br />
DefaultConnectionManager.setLogWriter(new java.io.PrintWriter(System.err));<br />
Connection Conn = (Connection)cxf.getConnection();<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
The setLogWriter method on the DefaultConnectionManager, which is<br />
supplied with the resource adapters, is a static method. The example above<br />
shows how to set the log to output the System.err. The trace level applied to<br />
the ManagedConnectionFactory remains.<br />
EXCI trace<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> writes trace entries to the EXCI trace. The<br />
trace entries are in the <strong>CICS</strong> trace EXCI format, so the trace entries in a dump<br />
can be printed using standard z/OS utilities. You can use the following<br />
operating procedure from the SDSF operator console:<br />
1. Use the command<br />
/D OMVS,A=ALL<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
to display OMVS tasks.<br />
2. Find the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> task, and note the ASID.<br />
3. Enter the DUMP command with a suitable comment. For example:<br />
/DUMP COMM=(JGATE DUMP)<br />
4. Reply to the message with the ASID as follows:<br />
/R nn,ASID=aa,END<br />
where nn is the message number for the reply, and aa is the ASID.<br />
Table 9 shows the trace points written to the EXCI trace by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Table 9. EXCI trace points for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Point ID Module Lvl Type Data<br />
8000 JVDLL EX 1 ECI parameters passed 1 Thread name<br />
2 Call_Type<br />
3 Extend_Mode<br />
4 Luw_Token<br />
5 Commarea_Length<br />
6 Cics_Rc<br />
7 Message_Qualifier<br />
8001 JVDLL Exc GetStringPlatform error 1 Return code<br />
2 Data area<br />
3 Length<br />
8002 JVDLL Exc GetStringPlatformLength<br />
error<br />
1 Return code<br />
8003 JVDLL EX 1 Converted parameter 1 Thread name<br />
2 Parameter name<br />
3 Parameter value<br />
Chapter 9. Problem determination 137
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS problem determination<br />
Table 9. EXCI trace points for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> (continued)<br />
Point ID Module Lvl Type Data<br />
8004 JVDLL EX 1 Inbound COMMAREA 1 Thread name<br />
2 Communication<br />
area length<br />
3 Communication<br />
area address<br />
4 250 bytes of data<br />
8006 JVDLL EX 1 Outbound COMMAREA 1 Thread name<br />
2 Communication<br />
area length<br />
3 Communication<br />
area address<br />
4 250 bytes of data<br />
8007 JVDLL EX 1 ECI parameters output 1 Thread name<br />
2 Call_Type<br />
3 Extend_Mode<br />
4 Luw_Token<br />
5 Commarea_Length<br />
6 Cics_Rc<br />
7 Message_Qualifier<br />
8010 JVDLL Exc Error response received 1 Function number<br />
2 EXCI response<br />
3 EXCI reason<br />
4 EXCI subreason<br />
field-1<br />
5 EXCI subreason<br />
field-2<br />
6 Cics_Rc<br />
8011 JVDLL Exc DPL_REQUEST error 1 RESP<br />
2 RESP2<br />
3 ABCODE<br />
4 Cics_Rc<br />
8012 JVDLL Exc WBA1 parameters 1 malloc length<br />
allocation error<br />
2 Cics_Rc<br />
8013 JVDLL Exc Invalid call type 1 Thread name<br />
2 Call_Type<br />
3 Cics_Rc<br />
8014 JVDLL Exc Invalid COMMAREA 1 Thread name<br />
length<br />
2 Commarea_Length<br />
3 Size of Commarea<br />
4 Cics_Rc<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
Installation<br />
During installation, you might see messages indicating that files are missing<br />
or corrupt:<br />
Phase 1 of 6 complete,<br />
Phase 2 of 6 complete,<br />
FSUM8746 line 205726: Line too short (44 bytes, expecting 62)<br />
Phase 3 of 6 complete,<br />
uncompress: ctg.tar.Z: FSUM6639 compressed file is corrupt<br />
Phase 4 of 6 complete,<br />
tar: opening archive "ctg.tar": EDC5129I No such file or directory.<br />
rm: FSUM9195 cannot unlink entry "ctg.tar": EDC5129I No such file or directory.<br />
Phase 5 of 6 complete,<br />
chmod: FSUM6188 stat file "ctg": EDC5129I No such file or directory.<br />
Phase 6 of 6 complete.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> installed.<br />
This indicates that there is insufficient space in the /tmp directory. Either clear<br />
out the directory, or increase it to the minimum recommended size; see “Disk<br />
space requirements” on page 19.<br />
The configuration tool<br />
Diagnosing common problems<br />
The <strong>Gateway</strong> daemon fails to find Turkish configuration settings<br />
When you run the configuration tool under a Turkish locale for the first<br />
time, by default the configuration settings are saved in file CTG.INI.ini.<br />
Rename the file to CTG.INI to allow the <strong>Gateway</strong> daemon to find the<br />
settings automatically. You only have to do this once, when the<br />
configuration tool is first run.<br />
Known limitations<br />
v On startup, the configuration tool displays a color exception.<br />
v The tool can read a configuration file only if it has fewer than 65<br />
servers.<br />
v USS does not fully support DBCS in graphical user interfaces. Until a<br />
solution is found run the tool in English:<br />
ctgcfg -LANG US<br />
EDC5111I PERMISSION DENIED message<br />
This message can be generated because:<br />
v A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> port is already in use by another task.<br />
v A port is reserved for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> job in the<br />
TCPIP.PROFILE, but the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> jobname is less than 8<br />
characters. In this case the job that attempts to open the port will have a<br />
jobname with a numeric suffix allocated by UNIX System Services and will<br />
not match the TCPIP.PROFILE jobname. To solve this problem:<br />
Chapter 9. Problem determination 139
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
1. Do not reserve the port<br />
2. Use an eight character jobname<br />
3. Add ’OMVS’ to the list of IDs allocated the port in the TCPIP.PROFILE.<br />
It is not advisable to anticipate the numeric character added by UNIX<br />
System Services as an ID.<br />
CEE3250C ABEND S806 message<br />
The following message might be received when starting the <strong>Gateway</strong> if the<br />
Userid does not have sufficient authority to access the system product and<br />
load libraries:<br />
CEE3250C The system or user abend S806 R=00000004 was issued.<br />
From entry point MVS_CcicsInit at compile unit offset -FFFF8D84<br />
at address 1AEB158C.<br />
The message is also displayed if the STEPLIB variable does not point to the<br />
correct <strong>CICS</strong> EXCI load library, see “The environment variables” on page 48<br />
for more information.<br />
Multiple Address Spaces<br />
When running the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, two address spaces may be<br />
used. One is used for the ctgstart shell script, and the other for the Java<br />
Virtual Machine containing the CTG. Some users may consider this to be<br />
undesirable.<br />
Take the following actions to resolve the situation:<br />
v Place the follwing two variables in the JCL:<br />
_BPX_SHAREAS=YES<br />
_BPX_SPAWN_SCRIPT=YES<br />
v Ensure that all the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s files have the extended<br />
attribute ’s’ set:<br />
1. To display the extended attributes for files, use ls -E<br />
2. To set the ’s’ attribute on files use the extattr +s command<br />
Note: If you wish to use the CTG’s support for RACF user/password<br />
authentication, the JVM which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs in<br />
MUST be in it’s own address space.<br />
Automatic Restart Manager (ARM) problems<br />
Different region used following a restart<br />
When ARM tries to restart a job after a failure, it uses any suitable region.<br />
This might be a different region to that in which you started <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. If you are not running with TCP/IP port sharing, so that the shared<br />
port is routed to whichever region is up and supporting that port number,<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
when the JCL restarts on a new MVS image it has a new URL and address. To<br />
avoid this, modify the ARM profile for the ARM_ID you are using so that it<br />
restarts only in the same region.<br />
For more information, see z/OSV1R2.0 MVS Setting up a Sysplex, SA22–7625.<br />
Conflicts with default ports<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses default ports for its supported protocols.<br />
These may conflict with ports already in use, and if this is the case, one or<br />
more protocols fail to start successfully. You can change port number in the<br />
CTG.INI file, see “Using the configuration tool” on page 52.<br />
EXCI pipe limitations<br />
You may experience problems due to EXCI pipe limitations when using<br />
servlets when running <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> in local mode.<br />
A single z/OS address space is limited by <strong>CICS</strong> interregion communication<br />
(IRC) to allocating a maximum of 100 EXCI pipes to all attached <strong>CICS</strong> regions.<br />
In contrast, the maximum pipe usage in a <strong>CICS</strong> region is limited only by the<br />
number of sessions defined in the <strong>CICS</strong> multiregion operation (MRO) sessions<br />
definition, which can specify up to 999. Thus the following limitations apply<br />
to the use of the EXCI by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> from a servlet:<br />
v The Web server directive MaxActiveThreads sets the maximum number of<br />
concurrent requests that can be serviced. This is not the same as the<br />
maximum number of users, because the z/OS Web server will queue<br />
requests to use threads, according to the setting of the TCP/IP<br />
SOMAXCONN parameter or the Web server ListenBackLog directive.<br />
v Each thread that services an ECI request will allocate an EXCI pipe, and<br />
this pipe remains allocated until either a failure occurs or the <strong>CICS</strong> MRO<br />
connection is terminated. Such pipes is used by subsequent requests to the<br />
servlet. Pipes however, cannot be shared across different Web server<br />
threads.<br />
v If the number of threads using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> exceeds 100,<br />
the 101st EXCI Allocate_Pipe call fails with a SYSTEM_ERROR response<br />
code, and a reason code 608. The ECI application receives a return code -9<br />
(ECI_ERR_SYSTEM_ERROR). This means a limitation in the sending<br />
address space has been reached, therefore you should consider configuring<br />
MaxActiveThreads in your Web server to be less than or equal to 100.<br />
v If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> tries to allocate more pipes than there are<br />
available sessions defined in the <strong>CICS</strong> sessions definition, the EXCI<br />
Open_Pipe call fails with a RETRYABLE response code, and a reason code<br />
202. The ECI application receives a return code -16<br />
(ECI_ERR_SYSTEM_ERROR) and DFHXCURM is invoked. In this case,<br />
Chapter 9. Problem determination 141
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
consider setting the RECEIVECOUNT parameter in the <strong>CICS</strong> sessions to at<br />
least 100. For more information, refer to “<strong>CICS</strong> server sessions definition”<br />
on page 40.<br />
v Applids are specified in EXCI calls. The EXCI user exit can change an<br />
applid, but does not affect the number of pipes allocated. Unless the 100<br />
pipe limit has been reached, the number of pipes allocated on a thread<br />
depends only on the number of unique applids as specified in the EXCI<br />
requests.<br />
If the requests are non-extended, and have no affinity to the region in<br />
which they will run, the user exit can distribute them across regions. To do<br />
this, specify the same dummy applid on all requests, and write a user exit<br />
that redirects requests to the required applid. If you do not use a single<br />
dummy applid, the maximum number of concurrent transactions may be<br />
reduced when the user exit runs. For example, if some requests come in<br />
with applid1 and some with applid2, the maximum number of concurrent<br />
transactions that can run is 100 /2=50.(For n applids the formula is<br />
100/n.) This is because each thread could have two allocated pipes (one for<br />
applid1 and one for applid2). Since EXCI requests are synchronous, each<br />
thread can use only one of its two pipes, and the maximum number of<br />
concurrent transactions is halved. This is true in:<br />
– local mode when the thread issuing the EXCI calls is the java application<br />
thread<br />
– remote mode where the EXCI requests are issued by worker threads<br />
v If you discover that you require more than 100 threads in your Web server,<br />
it is recommended that you balance workload across Web servers using<br />
TCP/IP port sharing, or use the Web server in scalable mode, which allows<br />
the usage of multiple HTTP Q server address spaces (each of which can use<br />
100 pipes with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>).<br />
Java exceptions<br />
If the application or the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not handle an<br />
exception, then the Java Virtual Machine (JVM) writes a Java stack dump. The<br />
destination for the dump output depends on your JVM implementation; check<br />
your Java documentation for more information.<br />
Disable the Just-In-Time (JIT) compiler to increase the information written to<br />
the Java stack dump. This information might include the line of Java source<br />
code where the exception happened. How you disable the JIT compiler<br />
depends on your JVM implementation; check your Java documentation for<br />
more information.<br />
Figure 16 on page 143 shows a sample Java stack dump taken with the JIT<br />
compiler disabled.<br />
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Exception in thread "main" java.lang.OutOfMemoryError<br />
at java.lang.Thread.start(Native Method)<br />
at com.ibm.ctg.server.ThreadManager.createObject<br />
(ThreadManager.java:345)<br />
at com.ibm.ctg.server.ThreadManager.(ThreadManager.java:131)<br />
at com.ibm.ctg.server.ManagedResources.<br />
(ManagedResources.java:106)<br />
at com.ibm.ctg.server.JGate.main(JGate.java:895)<br />
Figure 16. Sample Java stack dump<br />
Diagnosing common problems<br />
If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> handles an exception, a Java stack dump is<br />
written only if tracing is enabled. Try to reproduce the problem with tracing<br />
enabled. This should help to show you what was happening before the<br />
exception occurred. See “Tracing” on page 133 for more information on<br />
tracing.<br />
Using a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same workstation<br />
If you intend to use a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same<br />
workstation, remove ctgclient.jar and ctgserver.jar from the CLASSPATH<br />
setting. If you do not remove them, you are likely to receive the following<br />
error when running applications:<br />
ERROR: java.io.IOException:<br />
CCL6664E: Unable to load relevant class to support the tcp protocol<br />
The reason for the error is that Java searches the CLASSPATH environment<br />
variable before downloading classes across the network. If the required class<br />
is local, Java attempts to use it. However, using class files from the local file<br />
system breaks Java application security rules; therefore an exception is raised.<br />
java.lang.OutOfMemory exception<br />
If this happens after the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been running for a<br />
long time, then it could be caused by a memory leak. If it happens only when<br />
the <strong>Gateway</strong> is heavily loaded, then there might be too many threads active<br />
for the available Java Virtual Machine (JVM) memory.<br />
Memory leak<br />
Run a memory usage monitor against the <strong>Gateway</strong> process. If there is a<br />
memory leak, the amount of memory used by the <strong>Gateway</strong> increases over<br />
time. Make sure that all user applications that connect to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> close the Java<strong>Gateway</strong>() connection object when they have finished<br />
using it. If this does not resolve the problem, run the <strong>Gateway</strong> debug trace<br />
and contact your IBM support organization. You can use the ctgstart -tfilesize<br />
option to limit the size of the trace output file. You can also use the ctgstart<br />
-truncationsize option to reduce to zero the size of any data blocks that will<br />
be displayed in the trace. This will reduce the effect on performance.<br />
Chapter 9. Problem determination 143
Diagnosing common problems<br />
Too many threads<br />
These symptoms may be caused by:<br />
1. The BPXPRMxx value for MAXTHREADS being reached. The solution is<br />
to increase the value of MAXTHREADS. For more information, see “The<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: threading model” on page 14.<br />
2. Use of REGION=0M in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> startup JCL. The<br />
actual region size available when 0M is used is unpredictable and may be<br />
less than required for the number of threads being run by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. The solution is to allocate an explicit region size.<br />
This value is dependent on the number of threads required to be run by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> (see “Region size considerations” on<br />
page 123.)<br />
3. Use of the JVM default stack size values -ss (256 KB) and -oss (400 KB),<br />
which results in a memory allocation of 656 KB per thread. Halving these<br />
values on the exec java statement in the ctgstart script reduces memory<br />
consumption.<br />
You can estimate the amount of virtual memory that is required by the JVM<br />
as follows. Add together:<br />
v the number of Connection Manager threads<br />
v the number of Worker threads<br />
v the number of background threads in use by Java<br />
v the number of different network protocols in use<br />
Then multiply this total by the size of the Java stack allocated to each thread<br />
by the JVM.<br />
In this calculation, assume that the number of active Java background threads<br />
is about five. Refer to your Java documentation for a more accurate value. You<br />
set the maximum numbers of Connection Manager threads and Worker<br />
threads in the configuration of your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. See “General<br />
<strong>Gateway</strong> settings” on page 56 for more information.<br />
The way that Java allocates memory depends on your JVM implementation.<br />
Most JVMs allow you to do the following:<br />
v Set the amount of memory available to the JVM by using the java -mx<br />
option.<br />
v Set the amount of memory that Java allocates to each thread by using the<br />
java -oss and java -ss options. The size of the Java stack is the sum of these<br />
two values..<br />
For more information on thread limits see Table 3 on page 15. For more<br />
information on Java memory allocation refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide book and to your Java documentation.<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
On z/OS systems, the amount of memory available to each process might be<br />
limited. See your operating system documentation for more information.<br />
Authorization failure using servlets with WebSphere<br />
Servlets that use the WebSphere autostart function do not have the required<br />
authority to access <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. The following message appears<br />
in the JNI trace:<br />
CcicsECI: Authorise userid/password with RACF. Return code = -1, errno = 157<br />
If this happens, use user-driven servlets, where the initialization is performed<br />
in the servlet’s init() method.<br />
If a process locks<br />
To determine where the lock is happening, enable tracing in the application,<br />
and in the <strong>Gateway</strong>, see “Tracing” on page 133. If the lock is in the <strong>Gateway</strong>,<br />
contact your IBM support organization and provide them with the <strong>Gateway</strong><br />
trace.<br />
On some Java Virtual Machine (JVM)s, including the z/OS JVM, you can force<br />
Java to write a stack trace showing the states of the current threads. For<br />
example, on IBM Java SDK 1.3.1 you can send a SIGQUIT (-3) signal to a<br />
Java process to make it write a stack trace to stderr. This shows the states of<br />
the current threads. Do not do this on a working production system but only<br />
on a system which is completely locked.<br />
SSL problems<br />
In general<br />
Enable stack tracing in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. This will show you<br />
what was happening when the exception occurred. It will also give you<br />
information about the configuration, such as the value of the CLASSPATH<br />
variable. If this does not give you enough information to diagnose the<br />
problem, obtain a standard trace and contact your IBM support organization.<br />
SSLight<br />
Diagnosing common problems<br />
When starting the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: The following message is<br />
issued when starting the <strong>Gateway</strong>:<br />
CCL6525W: Unable to start handler for the ssl: protocol.<br />
[java.lang.ClassNotFoundException:<br />
server KeyRing class name]<br />
This message shows that the <strong>Gateway</strong> could not load the server KeyRing<br />
class. Start the <strong>Gateway</strong> with stack tracing enabled. Check that the<br />
CLASSPATH variable, which is displayed at the top of the trace output,<br />
includes an entry for the directory that contains the class. Also check that the<br />
Chapter 9. Problem determination 145
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
CLASSPATH includes an entry for file cfwk.zip. If the <strong>Gateway</strong> cannot find<br />
this file, it cannot load the KeyRing files.<br />
You specify the name of the server KeyRing class in the KeyRing classname<br />
field in the SSL protocol settings panel in the configuration tool. Do not<br />
include the directory or file extension when you specify the KeyRing class<br />
name. The CLASSPATH should include an entry for the directory that<br />
contains the KeyRing class.<br />
In a user application: The API call<br />
SslJava<strong>Gateway</strong>.setKeyRing("ClientKeyRingName", "thePassword"); fails with<br />
the following error in a user application:<br />
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing<br />
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This<br />
file is supplied with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
JSSE<br />
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore<br />
name to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, but the class does not load, or cannot be<br />
found, the <strong>Gateway</strong> daemon assumes that you are using JSSE and not<br />
SSLight.<br />
iKeyMan locks with ″class not found″ exception: A message like the<br />
following is received by the application:<br />
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException<br />
This happens if the IBM Java Cryptography Extension (JCE) package is not<br />
installed. Ensure that you have installed the JCE supplied with <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> in the ibm-jce.zip file. See “Installation” on page 86.<br />
Application receives an ″access denied″ exception: A message like the<br />
following is received by the application:<br />
java.io.IOException: CCL6651E: Unable to connect to the <strong>Gateway</strong>.<br />
[address = killerb2b, port = 8050]<br />
[java.security.AccessControlException: access denied<br />
(java.io.FilePermission \jssekeys\testclient.jks read)]<br />
This happens if your application does not have permission to read from the<br />
file system containing the keystore. See Using ECI, EPI, and ESI with a Java 2<br />
Security Manager, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, for more<br />
information.<br />
KeyStore name not recognized: Java interprets the back slash (\) character<br />
as a parameter delimitter. If you used the back slash character as a directory<br />
separator when entering the path name of the KeyStore file during<br />
146 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Diagnosing common problems<br />
configuration, Java cannot recognize the name. Use either a forward slash (/)<br />
character, or double back slash (\\) characters, as a separator in the path<br />
name on all operating systems. For example:<br />
/mykeys/jsse/keystore.jks<br />
\\mykeys\\jsse\\keystore.jks<br />
Shortage of resources on the <strong>CICS</strong> server<br />
You may receive intermittent ECI_ERR_RESOURCE_SHORTAGE return codes<br />
from ECI calls you may to <strong>CICS</strong> servers. If this is the case, you must increase<br />
the RECEIVECOUNT value on the SESSIONS resource definition on the <strong>CICS</strong><br />
server to a value substantially greater than is theoretically necessary, that is,<br />
100. For more information, see “<strong>CICS</strong> server sessions definition” on page 40.<br />
ECI_ERR_SECURITY_ERROR return code<br />
Possible causes for this return code from an ECI call include:<br />
v Surrogate checking has been enabled in the EXCI options table<br />
DFHXCOPT.<br />
The SURROGCHK option in the DFHXCOPT table enables surrogate<br />
checking, and this defaults to YES. Refer to the <strong>CICS</strong> External Interfaces<br />
Guide for more information about using this option.<br />
v RACF program control must be active for the SDFHEXCI data set.<br />
To activate program control:<br />
SETROPTS CLASSACT(PROGRAM)<br />
RDEFINE PROGRAM * UACC(READ)<br />
SETROPTS WHEN(PROGRAM)<br />
To add the <strong>CICS</strong> library when program control is active:<br />
RALTER PROGRAM * ADDMEM*’hlq.SDFHEXCI’/volser/NOPADCHK)<br />
SETROPTS WHEN(PROGRAM) REFRESH<br />
v Extended attributes settings are not specified for certain HFS files.<br />
The following extattr commands mark the load modules used by the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> as program controlled. Issue commands like the<br />
following from an OMVS shell or a Telnet session:<br />
extattr +p /bin/lib*.so<br />
extattr +p /bin/SECURES<br />
You must specify that the ctgstart script does not share its address space<br />
with any other processes. This is to ensure that the calling address space<br />
(JVM) is not “contaminated” by a non-program-controlled load module. To<br />
force the JVM to use its own non-sharable address space, enter:<br />
extattr -s /bin/ctgstart<br />
The JVM must also be program controlled. (By default, JVM 1.3 or later is<br />
installed as program controlled.) If necessary issue the command<br />
extattr +p javapath/bin/*<br />
Chapter 9. Problem determination 147
|<br />
|<br />
Diagnosing common problems<br />
where javapath is the location of the JVM. For further information, see<br />
“Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for use with RACF ® ” on page 65.<br />
v The ctgstart script does not have the ’Share Address Space’ extended<br />
attribute bit turned off with extattr -s. If this is not the case, the error occurs<br />
on ECI_SYNC or ECI_STATE-SYNC calls due to a ’dirty’ address space. See<br />
also “Dirty address space problems”.<br />
v A RACF facility class is not defined.<br />
If you are using userids and passwords that are to be verified by <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> itself, and not passed to <strong>CICS</strong> for verification, then<br />
you must define a RACF facility class. The name of the facility class must<br />
match the netname parameter on the CONNECTION definition for the<br />
EXCI link, and the value of the DFHJVPIPE environment variable used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. For more information, refer to “<strong>CICS</strong> server<br />
connection definition” on page 37.<br />
v The JAVA_PROPAGATE environment variable has not been set for a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> application running in local:// mode. You must set:<br />
JAVA_PROPAGATE=NO<br />
in the environment that the java application runs under.<br />
If the environment variable is not set, z/OS traces show that a<br />
pthread_security_np call with the CREATE_SECURITY_ENV parameter has<br />
failed with a 157 (EMVSERR) return code.<br />
ECI_ERR_SYSTEM_ERROR return code<br />
This return code can be generated as a result of problems in the <strong>CICS</strong> address<br />
space. For example, PGMIDERR, a security violation, or program-autoinstall<br />
veto.<br />
It can also be generated in the EXCI code if the userid of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> host address space is not PERMITted to the DFHAPPL.dfhjvpipe or<br />
the DFHAPPL.applid facilities.<br />
Dirty address space problems<br />
This problem can result in different ways depending on how the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> loses its privileged status:<br />
v The ctgstart script still has the ’s’ bit set.<br />
v The SDFHEXCI load library, and any load library defined in the<br />
EXCI_OPTIONS environment variable are not program-controlled.<br />
v The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> HFS is mounted with NOSETUID. The <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> HFS must be mounted with the default of SETUID.<br />
148 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Program support<br />
If you need to contact your IBM support organization, first refer to the Service<br />
and Support card supplied with the product for details of the support<br />
available to you, or visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Support link.<br />
Program Support<br />
This section provides guidance on reporting problems, detailing the<br />
information you should collect to assist your support organization. It also<br />
explains how the problem is handled through to resolution and the provision<br />
of a fix.<br />
Reporting problems<br />
Before reporting your problem to the support organization try to ensure that<br />
the error is actually occurring within your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> system,<br />
even if you are unsure whether the problem is due to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> itself.<br />
In practice, many errors reported to support organizations turn out to be user<br />
errors, or they cannot be reproduced, indicating just how difficult it can be to<br />
determine the precise cause of a problem. User errors are mainly caused by<br />
faults in application programs or by errors in setting up systems.<br />
The ability of the support organization to resolve your problem quickly<br />
depends on the quality of the information you provide to them. For this<br />
reason it is good practice to collect and organize problem data before making<br />
the initial contact.<br />
Summarize your problem and the documentation/information you collect on<br />
a problem reporting sheet. This sheet provides a valuable summary to the<br />
support organization, and a copy will be useful for your own records.<br />
Level-1 support<br />
If this is your first contact regarding this problem a unique incident number<br />
will be assigned. A Problem Management Record (PMR) is opened on the<br />
RETAIN ® database system, where all activity associated with your problem is<br />
recorded. The PMR remains “open” until it is solved.<br />
Make a note of the incident number on your copy of the problem reporting<br />
sheet. You will be expected to quote the incident number in all future<br />
correspondence relating to this problem.<br />
Your initial communication with the support organization is through a Level-1<br />
representative, who uses the keywords that you have provided to search the<br />
RETAIN database for problems with similar symptoms. If your problem is<br />
Chapter 9. Problem determination 149
Program Support<br />
found to be one already known to the support organization, and a fix has<br />
been devised for it, you will be advised of the availability of corrective service<br />
software that you can install to overcome the problem, as described in<br />
“Obtaining the fix” on page 153. If the RETAIN search is unsuccessful, the<br />
problem is passed on to a Level-2 representative who will contact you for<br />
more information about your problem, to start a more detailed investigation<br />
of the cause.<br />
Level-2 support<br />
Let the Level-2 representative know if any of the following events occurred<br />
before the problem appeared:<br />
1. Changes in level of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, compiler or associated<br />
licensed programs<br />
2. Corrective service software and fixes applied to workstation software<br />
3. Problem Tracking Fixes (PTFs) applied to other associated products<br />
4. Additional features used<br />
5. Application programs changed<br />
6. Unusual operator action.<br />
At this stage you may be asked to supply more details or documentation. If<br />
this happens, the PMR is updated to show any documentation you have<br />
submitted.<br />
Based on the information you supply, the investigation then carried out can<br />
determine whether the cause of your problem is new to the support<br />
organization, or is already known.<br />
If the problem is a valid new one, an APAR may be raised, to be dealt with<br />
by the <strong>CICS</strong> service team, as described in “APARs and fixes” on page 152. If,<br />
however, the problem is already known, and a fix has been developed, you<br />
can obtain it as described in “Obtaining the fix” on page 153.<br />
Documenting problems<br />
In a communication environment, where many clients may be connected to<br />
several servers, you must obtain information from both the client and the<br />
server sides.<br />
To facilitate problem determination, try to reduce your environment to only<br />
one client workstation and one server to narrow down the range of<br />
possibilities that may cause the error.<br />
Listed below are the types of information most likely to be needed by the<br />
support organization. The list is not exhaustive; it covers the most commonly<br />
requested information.<br />
150 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Program Support<br />
v The version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, including details of any<br />
service releases applied.<br />
v The utility or programming language that gives the problem, for example:<br />
– ECI, EPI, ESI<br />
– C, C++, Java<br />
For languages, include the version.<br />
v The network protocols being used.<br />
v The end-to-end configuration, and product stacks at each step of the way,<br />
for example, WebSphere Application Server async ECIRequest class over<br />
SSL to ctgstart on Solaris up using TCP62 to <strong>CICS</strong> <strong>Transaction</strong> Server 2.2.<br />
v The operating system on which the problem occurs. If the Client application<br />
and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are on different operating systems, provide<br />
details of both. Details of the <strong>CICS</strong> server are also useful.<br />
v A recreate scenario, if possible.<br />
v Details of any log messages at the time the problem occurred.<br />
v A short description of the problem in terms of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
calls, including why you think it is a problem with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. For example, a specific API call hangs and never returns, or an<br />
unexpected return code on a specific API call.<br />
Locating and compiling information<br />
The advice listed below will help you compile the information required. If<br />
you are in any doubt about how to gather any of the items listed above, wait<br />
until you can seek advice from your support organization.<br />
v Try to establish which program in your system seems to be the cause of the<br />
problem. As you are reading this book, it is likely that you already believe<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to be the problem source.<br />
You also need to provide the version and release number of the product, for<br />
example <strong>Version</strong> <strong>5.0</strong>, together with the number of any PTF or other fix<br />
applied, for example UNnnnnn (where nnnnn is a valid PTF number).<br />
v You should find details of your compiler level on the product media labels<br />
or the associated documentation. Alternatively, check the panel displayed<br />
on the screen at compile time.<br />
v Give the problem a severity level. Severity levels have the following<br />
meanings:<br />
– Severity level 1 indicates that you are unable to use a program, resulting<br />
in a critical condition that needs immediate attention.<br />
– Severity level 2 indicates that you are able to use the program, but that<br />
operation is severely restricted.<br />
– Severity level 3 indicates that you are able to use the program, with<br />
limited functions, but the problem is not critical to your overall<br />
operation.<br />
Chapter 9. Problem determination 151
Program Support<br />
– Severity level 4 indicates that you are able to use the program with the<br />
problem causing negligible hindrance.<br />
When deciding the severity of the problem, take care to categorize it<br />
correctly, as the procedures followed by the support organization depend<br />
on the severity level supplied.<br />
v Also, try to classify the error and give a brief description of the problem.<br />
Include keywords associated with the problem, such as ABEND, WAIT,<br />
LOOP, PERFORMANCE, INCORROUT, and MESSAGE, corresponding to<br />
the problem classification types used in the RETAIN database. Strings<br />
containing other keywords are also useful. These are not predefined, and<br />
might include such items as a message or message number, an abend code,<br />
any parameters known to be associated with the problem, or, for example,<br />
STARTUP, INITIALIZATION, or TRANSIENT DATA.<br />
v Finally, you should include your address, relevant contact names, and<br />
details of the other products at your installation.<br />
Keep a copy of the problem reporting sheet which summarizes all the<br />
information relevant to the problem, together with any available<br />
documentation such as dumps, traces and output from programs, translators,<br />
and compilers.<br />
Submitting the documentation<br />
If you are asked to provide documentation, it will help the support<br />
organization during their investigation if you adhere to the following rules<br />
when preparing it:<br />
v Provide as much information as possible in softcopy format.<br />
v Write any notes and documents in English.<br />
v If you are asked to supply any additional trace output, provide an<br />
unformatted binary version, rather than the viewable output from the<br />
formatter.<br />
v If you upload files to a mainframe system, do so in binary rather than<br />
ASCII format.<br />
APARs and fixes<br />
Once a reported problem is confirmed as being both new and valid, An<br />
authorized program analysis report (APAR) is raised from the Problem<br />
Management Record (PMR) and becomes a permanent record describing your<br />
error, and in time, its solution. An APAR is the means of reporting to the<br />
appropriate product service team any problems you find with an IBM<br />
program.<br />
The APAR process<br />
The first step in the APAR process is that a Level-2 representative from the<br />
support organization enters an APAR containing a description of your<br />
152 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Program Support<br />
problem into the RETAIN system. If you have a means of getting round the<br />
problem, details of this are entered as well. Your name is also entered, so that<br />
your support organization knows who to contact if the service team need to<br />
ask anything further about the APAR documentation.<br />
At this stage, you are given an APAR number. This number is always<br />
associated with the APAR and its resolution and, if a code change is required,<br />
is associated with the fix as well.<br />
The service team may ask for additional backup documentation, normally via<br />
the Level-2 representative. The specific documentation required will vary from<br />
problem to problem, and depends on what information has already been<br />
supplied during the PMR stage.<br />
During the investigation, you can ask your support organization at any time<br />
about how your APAR is progressing, particularly if it is a problem of high<br />
severity.<br />
Obtaining the fix<br />
When the service team has found a fix for your problem, you may be asked to<br />
test it on your system. If so, you may be sent a Program Temporary Fix (PTF)<br />
in the form of individual replacement modules. This is normally done through<br />
the Level-2 organization and feedback from your testing will be requested.<br />
Each PTF may contain several APAR fixes. If an individual APAR fix within a<br />
PTF is found to be in error, it may still be advisable to apply the PTF, to<br />
obtain the other APAR fixes.<br />
In time, formal corrective service software is made available, which you can<br />
order through your support organization. Traditionally, corrective service<br />
software has been supplied on Corrective Service Diskettes (CSD) ordered by<br />
CSD number. It may now be supplied on CD-ROM or via the Internet.<br />
Fixes for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> are available from the <strong>CICS</strong> Support web<br />
page at: www.ibm.com/software/ts/cics/support/details.<br />
Chapter 9. Problem determination 153
154 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Appendix A. Hardware and software<br />
This chapter lists hardware requirements and supported software for all<br />
operating systems on which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs.<br />
Hardware requirements<br />
This section discusses the disk space requirements on z/OS, and general<br />
hardware requirements on distributed platforms.<br />
Disk space requirements on z/OS<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is normally installed into a directory such as<br />
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,<br />
during installation, the uncompressed tar file is present in the /usr/lpp<br />
directory. The HFS data set for this directory must be large enough to take the<br />
25MB (40 cylinders) that this file occupies. You can delete the files once<br />
installation is complete. Installation also requires 25MB (40 cylinders) in the<br />
/tmp directory.<br />
Once installed, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> occupies 27MB. You need enough<br />
disk space for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and any logging and tracing files.<br />
IBM recommends that you use a separate HFS data set with a primary<br />
allocation of 40 cylinders for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software. Increase this<br />
to 50 cylinders if the logging and trace files will be stored in the same HFS<br />
data set. Increase it further if many instances of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will run, or if much logging is required. Alternatively, you can use a separate<br />
HFS data set, with a primary allocation of 5 cylinders, for each instance of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
If you use the existing /usr/lpp HFS data set, ensure it has enough space to<br />
take the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software.<br />
Table 10. Hardware requirements on UNIX systems<br />
AIX LINUX SOLARIS HP-UX<br />
Processor v IBM RISC<br />
System/6000 ®®<br />
v IBM RS/6000 ®®<br />
Scalable<br />
POWERParallel<br />
System (SP2 ® G5, G6, MP3000 or<br />
above<br />
SPARC PA-RISC 1.1 or 2.0<br />
).<br />
© Copyright IBM Corp. 1996, 2002 155
Table 10. Hardware requirements on UNIX systems (continued)<br />
AIX LINUX SOLARIS HP-UX<br />
Terminals Any type of Any standard Any type of Any standard<br />
terminal or telnet or X based terminal or telnet or X based<br />
X/Terminal that terminal that can X/Terminal that terminal that can<br />
can attach to the access Linux. can attach to the access HP-UX.<br />
processor.<br />
processor.<br />
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB<br />
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB<br />
for temporary files for temporary files for temporary files for temporary files<br />
used during used during used during used during<br />
installation. installation. installation. installation.<br />
Table 11. Hardware requirements on Windows systems<br />
Processor Any processor capable of running the appropriate<br />
operating system and other prerequisite software.<br />
Network adapters To connect workstations to the LAN, you need a<br />
suitable adapter such as an ethernet adapter.<br />
Memory At least 64 MB.<br />
Disk space You need 30 MB of free disk space for your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> (including documentation in US<br />
English only).<br />
Supported software<br />
The following products are supported.<br />
You need a further 30 MB for temporary files used<br />
during installation. At least 12 MB of this must be on<br />
your system partition.<br />
Operating systems<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported on the following operating systems:<br />
v AIX V4.3.3 with Service Pack 25<br />
v AIX 5.1<br />
v HP-UX 11.0<br />
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)<br />
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)<br />
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)<br />
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)<br />
156 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)<br />
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)<br />
v OS/390 V2.10<br />
v z/OS V1.2<br />
v Windows XP Professional<br />
v Windows 2000 Professional with a minimum of Service Pack 1<br />
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a<br />
minimum of Service Pack 1<br />
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a<br />
v Windows NT Server V4.0 with a minimum of Service Pack 6a.<br />
Notes:<br />
– Windows NT 4 Terminal Server is not supported<br />
– The setting of multiple user interface languages, under Windows<br />
2000 MultiLanguage <strong>Version</strong>, is not supported.<br />
– If you plan to run <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> under load, and<br />
using remote protocols, it is strongly recommended that you use<br />
a server version, rather than a workstation version, of Windows.<br />
Web browsers<br />
v HTML/HTTP functions: Any browser that supports HTML V1.0 should<br />
work with the product.<br />
v Java Functions: Any JDK 1.1 compliant Web browser should work with the<br />
product.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following browsers:<br />
v Microsoft Internet Explorer <strong>5.0</strong>, 5.5 and 6.0<br />
v Netscape Communicator 4.7 and 6.2<br />
v HotJava Browser V 1.1 (for Solaris)<br />
Note: Applets running within the JVM supplied with the Netscape<br />
Communicator browser fail to make successful connections with the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. Message number CCL6652E is returned to<br />
the applet. Currently there is no solution to this problem.<br />
Java applets are supported for compatibility with previous versions of<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. However, support for them might be<br />
removed in a future release. It is recommended that you use Java<br />
applications, or Java servlets, when developing new solutions.<br />
Telnet clients<br />
If you run the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> over telnet, certain telnet clients can<br />
cause problems with the display. For example, your telnet session might<br />
Appendix A. Hardware and software 157
|<br />
|<br />
|<br />
|<br />
|<br />
truncate message lines over a certain length. This is usually a problem with<br />
the telnet client that you are using, or the terminal type that you are going in<br />
as. Currently there is no solution to this problem.<br />
JDK levels<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JDK levels 1.3 and 1.3.1 at the following<br />
minimum service levels:<br />
v AIX: IBM Java SDK 1.3 (service release 6)<br />
v HP-UX: Java SDK 1.3.0.02<br />
v Solaris: Sun Java SDK SE 1.3.0_04.<br />
v z/OS: IBM Java SDK 1.3<br />
If using the IBM Persistent Reusable JVM, you are recommended to run at a<br />
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable<br />
functionality of this JVM.<br />
If using Java under DBCS code pages, especially IBM-939, install service<br />
refresh 14 or later.<br />
v Windows: IBM Java SDK 1.3 (service release 6)<br />
JSSE<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports JSSE in the the following environments:<br />
v Standard Java runtime environment (JRE).<br />
Only the IBM JSSE is supported:<br />
– AIX: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
– HP-UX: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Linux for S/390: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– Solaris: Install the JSSE package and JCE supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
– z/OS with JRE 1.3.1: includes a version of JSSE that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> supports<br />
– Windows: Install the JSSE package supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong><br />
v WebSphere Application Server:<br />
All supported levels have built in JSSE support.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support the use of JSSE with applets.<br />
<strong>CICS</strong> Servers<br />
A <strong>CICS</strong> server runs real-time multi-user applications and manages the<br />
associated resources and data. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with<br />
the following servers:<br />
158 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.2<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V2.1 (with APAR PQ30168, for signon<br />
capable terminals, applied)<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for z/OS V1.3 with APAR PQ30168, for signon<br />
capable terminals, applied. Apply z/OS APAR PQ38644, for EXCI, if you<br />
are using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
v <strong>CICS</strong> for MVS/ESA V4.1, with communication through SNA. (with APAR<br />
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for<br />
EPI emulation. APAR PN79262 is needed for DBCS support.<br />
v <strong>CICS</strong> for OS/400 ® V4.4<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for OS/2 ® V4.1 with CSD 3<br />
v <strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA 1.1.0 (with APAR PQ30170, for<br />
signon capable terminals, applied), or a minimum service level of 1.1.1<br />
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)<br />
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)<br />
v TXSeries V<strong>5.0</strong> (Windows, AIX)<br />
Web servers<br />
Any web server that is supported by your application server should work<br />
with the product.<br />
Application servers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following:<br />
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,<br />
AIX and Solaris.<br />
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.<br />
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF<br />
UQ99329 (Service Level W401030).<br />
SNA communications<br />
Customers wishing to use SNA communications should install one of the<br />
following products:<br />
Windows operating systems<br />
Any one of:<br />
v IBM eNetwork Communications Server V6.1, with a minimum of<br />
service level 1<br />
v IBM eNetwork Personal Communications V<strong>5.0</strong>, with a minimum of<br />
service level 2<br />
v IBM eNetwork Personal Communications V5.5<br />
v Microsoft SNA Server V4.0 with a minimum of SP4<br />
Appendix A. Hardware and software 159
|<br />
|<br />
AIX<br />
IBM eNetwork Communications Server V6.1, with a minimum of service<br />
level 1 (AIX).<br />
SNA is not supported on other UNIX operating systems.<br />
TCP/IP communications<br />
TCP/IP support is provided by the operating system.<br />
TCP62 communications<br />
TCP62 support is provided by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Compilers and application development tools<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with the following compilers and<br />
application development tools:<br />
AIX<br />
v IBM C for AIX V4.4<br />
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6<br />
v IBM VisualAge ® C++ Professional V4.0<br />
v IBM VisualAge C++ Professional V<strong>5.0</strong> (requires AIX version 4.2 or later)<br />
HP-UX<br />
v HP ANSI C B.11.01, with a minimum of service level 7<br />
v HP aC++ B.11.01, with a minimum of service level 6<br />
Linux for S/390<br />
v GNU compiler C runtime V2.95, with a minimum of service level 2<br />
v GNU compiler C++ runtime V2.95, with a minimum of service level 2<br />
Solaris<br />
Sun WorkShop C++ V<strong>5.0</strong><br />
Note: The C++ compiler must have all available service patches applied.<br />
Windows<br />
v IBM VisualAge COBOL V3.0<br />
v Microsoft Visual C++ V6.0<br />
v Microsoft Visual Basic V6.0<br />
v Microsoft Visual Basic Script (VBScript) V<strong>5.0</strong><br />
Note: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not support use of the COM<br />
libraries with Microsoft <strong>Transaction</strong> Server (MTS), or the MTS<br />
component of COM+.<br />
Screen readers<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is supported with JAWS.<br />
160 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
Other tools<br />
These tools are available for viewing the PDF online documents:<br />
v Adobe Acrobat Reader V<strong>5.0</strong><br />
v GhostView V4.0 on Linux<br />
GPL licence and copyright issues on Linux<br />
This product uses the following libraries from the glibc package: libnsl.so,<br />
libm.so, libdl.so, ld.so, libc.so and libpthread.so. Refer to the glibc package on<br />
your machine for the various copyright statements and licensing terms for<br />
these libraries.<br />
This product also uses libncurses.so from the ncurses package. Again, refer to<br />
this package on your machine for the copyright statement and licensing terms<br />
applicable to this library.<br />
IMPORTANT: Your use of the libstdc++ or egcs-c++ packages is subject to the<br />
GNU GPL licence terms which could require you to provide source code in<br />
certain circumstances. Note that IBM will not supply source code, for example<br />
for the <strong>CICS</strong> <strong>Gateway</strong>s C++ libraries.<br />
Appendix A. Hardware and software 161
162 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Appendix B. Supported code pages<br />
The following code pages are supported:<br />
US English<br />
v IBM-1047<br />
Simplified Chinese<br />
v IBM-935<br />
v IBM-1388<br />
Japanese<br />
v IBM-930<br />
v IBM-939<br />
v IBM-1930<br />
v IBM-1939<br />
© Copyright IBM Corp. 1996, 2002 163
164 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 166<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks” on page 167 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 167 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 168 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 1996, 2002 165
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX for IBM eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
166 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Redbooks<br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT: Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA: Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400: Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 167
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
168 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
iKeyMan<br />
Samples<br />
and follow the Library link.<br />
See this Web site for information:<br />
www.tivoli.com<br />
The samples are not accessible.<br />
Configuration tool accessibility<br />
Components<br />
Each component in the configuration tool has a name and description for<br />
screen readers.<br />
Keys<br />
You can use the following keys to operate the configuration tool:<br />
Alt, Space<br />
Press and release the Alt key, then press Space, to open the window<br />
menu. This allows you to move, size, maximize or minimize the window.<br />
Ctrl+letter<br />
Certain actions have shortcuts assigned to them. Hold down the Ctrl key<br />
and type the letter to do the action.<br />
Ctrl+letter Action<br />
C Copies the selected value.<br />
N Creates a new configuration.<br />
© Copyright IBM Corp. 1996, 2002 169
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Ctrl+letter Action<br />
O Opens an existing configuration.<br />
P Pastes.<br />
S Saves the current configuration.<br />
U Cuts the selected value.<br />
V Pastes.<br />
W Creates a new server definition.<br />
X Cuts the selected value.<br />
Arrows (left and right)<br />
1. (Applies if the menus are active.) Move to a different menu.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the tree is active.) If a node contains subnodes, the left<br />
arrow collapses the node, the right arrow expands it. If a node cannot<br />
be expanded further, pressing the right arrow moves down to the next<br />
node. If a subnode is selected, pressing the left arrow moves to the<br />
parent node.<br />
Arrows (up and down)<br />
1. (Applies if the tree is active.) Move up and down through the tree.<br />
2. (Applies if the buttons are active.) Cycle through the buttons.<br />
3. (Applies if the Authorized Hosts list box is active.) Move through the<br />
entries in the list. If only one entry is in the list, press the Home key<br />
to select it.<br />
Control+Page Up<br />
Scroll left.<br />
Control+Page Down<br />
Scroll right.<br />
Control+Tab<br />
Use this (rather than Tab) on panels that contain a table to cycle between<br />
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to<br />
move backwards.<br />
Enter<br />
Activates a button in the Task Guide.<br />
Escape<br />
Closes the menu.<br />
F2 Select and change an editable number field in a table, for example the<br />
Bias value field on the Program definition for managing workload panel.<br />
170 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
F6 (Applies if the tree or the panel is active.) Toggles between the tree and<br />
the panel.<br />
F8 (Applies if the tree or the panel is active.) Allows you to gain control of<br />
the split between the tree and panel areas. After pressing F8, use the<br />
arrow keys to move the split:<br />
v Press the left arrow key to move the split left (decrease the width of the<br />
tree, increase the width of the panel).<br />
v Press the right arrow key to move the split right (increase the width of<br />
the tree, decrease the width of the panel).<br />
F10<br />
Opens the file menu.<br />
Home<br />
Selects the first entry in the Authorized Hosts list box.<br />
Page Up<br />
Scroll up.<br />
Page Down<br />
Scroll down.<br />
Shift+Tab<br />
If the cursor is on a field in the panel other than the first field, moves<br />
backwards through the fields. Otherwise, toggles between the tree and the<br />
panel.<br />
Space<br />
1. Activates a button.<br />
2. Selects a checkbox.<br />
3. Selects a node in the tree.<br />
Tab<br />
Cycles through the tree, fields in the panel, and the buttons.<br />
Customizing colors and fonts<br />
Use the Settings option on the menu to change colors and fonts. Settings are<br />
not applied consistently on the Task Guide.<br />
To make them more noticeable, the names of items that contain errors are<br />
displayed in the original typeface, in red and underlined.<br />
Using help<br />
Screen readers read the entire page in the help window, rather than the area<br />
required by a user who has pressed F1. Also, the help window is not<br />
navigable by the keyboard. The solution is to open the help files, which are<br />
html files, in a browser outside the configuration tool. The help file index is<br />
cclhlp15.htm in directory: where represents the directory<br />
Accessibility 171
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
containing the help files in these languages:<br />
Language <br />
English html<br />
German html_de<br />
Spanish html_es<br />
French html_fr<br />
Italian html_it<br />
Japanese html_ja<br />
Korean html_ko<br />
Turkish html_tr<br />
Simplified Chinese html_zh<br />
Task Guide<br />
Screenreaders cannot read the Task Guide; do not use the Task Guide if you<br />
use a screenreader. Use the menu in the configuration tool to add servers<br />
(Tools —> New server). Use the tree structure to enable protocols that the<br />
Java gateway will use.<br />
172 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans .<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 1996, 2002 173
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX, TXSeries<br />
for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390. A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA, <strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
174 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 175
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
176 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 177
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
178 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many<br />
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
Glossary 179
Glossary<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
R<br />
RACF. Resource Access Control Facility. An IBM<br />
licensed program that provides access control by<br />
identifying users to the system; verifying users of<br />
the system; authorizing access to protected<br />
180 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
resources; logging detected, unauthorized<br />
attempts to enter the system; and logging<br />
detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.<br />
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
Glossary 181
Glossary<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
182 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for OS/2,<br />
<strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.<br />
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 183
Glossary<br />
184 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Index<br />
Special characters<br />
_BPX_SHAREAS 48, 67, 140<br />
_BPX_SPAWN_SCRIPT 140<br />
x<br />
A<br />
accessibility 169<br />
Acrobat 161<br />
adapters 156<br />
administration 128<br />
Adobe 161<br />
APAR (authorized program analysis report)<br />
authorization 152<br />
closing 153<br />
documentation needed 150<br />
process 152<br />
submitting 152<br />
API (Application Programming Interface) 3<br />
application development tools 160<br />
Application Programming Interface (API) 3<br />
application servers 21, 159<br />
application tracing 135<br />
ARM 119<br />
ASSIZEMAX parameter 123<br />
asymmetric keys 5<br />
AUTH_USERID_PASSWORD environment variable 48<br />
authentication 8<br />
Authorized Hosts configuration setting 62<br />
automatic restart management 119<br />
B<br />
books 165<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 165<br />
BPX.FILEATTR.APF 120<br />
BPX.FILEATTR.PROGCTL 65, 66<br />
BPX.SERVER 66<br />
BPX.SERVER FACILITY profile 67<br />
BPXBATCH program 123<br />
BPXPRMxx member 29, 31, 73, 123, 144<br />
browsers 20, 157<br />
C<br />
CA (certification authority) 6<br />
CCF 22<br />
certification authority (CA) 6<br />
cfwk.zip 146<br />
<strong>CICS</strong> Description configuration setting 64<br />
<strong>CICS</strong> External Call Interface (EXCI) 1, 3<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java (MVS) 23<br />
<strong>CICS</strong> resource adapters 68<br />
<strong>CICS</strong> Server configuration setting 64<br />
<strong>CICS</strong> server resource definitions 37<br />
<strong>CICS</strong> servers 21, 158<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS 24<br />
configuring 43<br />
installing 25<br />
migration 23, 24<br />
problem determination 131<br />
software requirements 20<br />
startup options 117, 127<br />
tar file 26<br />
uninstalling 34<br />
<strong>CICS</strong>CLI environment variable 49, 53<br />
cicseci resource adapter 68<br />
cicseci.rar 67<br />
cicseciRRS.rar 67<br />
CLASSPATH environment variable 49, 107, 143, 146<br />
ClientSecurity 69<br />
code pages 32, 33<br />
code sets 33<br />
Common Client Interface (CCI) 13<br />
Common Connector Framework 22<br />
communication protocols 159<br />
compilers 160<br />
configuration<br />
environment variables 48<br />
configuration file<br />
referencing 49, 53<br />
configuration settings<br />
Authorized Hosts 62<br />
<strong>CICS</strong> Description 64<br />
<strong>CICS</strong> Server 64<br />
Connection timeout (ms) 59<br />
CTG User Classpath 65<br />
CTG User Libpath 65<br />
Display TCP/IP hostnames 57<br />
Drop working connections 60<br />
Enable protocol handler 59<br />
Enable reading input from console 57<br />
EXCI Net Name 65<br />
EXCI Options 65<br />
<strong>Gateway</strong> 63<br />
<strong>Gateway</strong> trace file 64<br />
<strong>Gateway</strong> trace wrap size 64<br />
Handler wakeup timeout (ms) 59<br />
High Level Qualifier 65<br />
Idle timeout (ms) 59<br />
Initial number of Connection Manager threads 56<br />
© Copyright IBM Corp. 1996, 2002 185
configuration settings (continued)<br />
Initial number of Worker threads 56<br />
Java clients obtaining generic ECI replies 58<br />
KeyRing database 61<br />
KeyRing or Keystore name 61<br />
KeyRing or Keystore password 61<br />
Library Name 65<br />
Log client connections and disconnections 58<br />
Max dedicated connections 62<br />
Maximum number of Connection Manager<br />
threads 56<br />
Maximum number of Worker threads 57<br />
Ping time frequency (ms) 60<br />
Port 59<br />
Require clients to use security classes 60<br />
RRM Name 65<br />
SO_LINGER setting 60<br />
Timeout for in-progress requests to complete<br />
(ms) 58<br />
Use client authentication 60<br />
Use RACF Authentication 64<br />
Validate Units of Work 58<br />
Worker thread available timeout (ms) 58<br />
configuration tool 52<br />
configuration tool help 171<br />
connection definition 37<br />
Connection timeout (ms) configuration setting 59<br />
ConnectionManager threads 117<br />
ConnectionURL 68<br />
Corrective Service Diskette (CSD) 153<br />
CSD (Corrective Service Diskette) 153<br />
CTG User Classpath configuration setting 65<br />
CTG User Libpath configuration setting 65<br />
CTG_JNI_TRACE 63, 136<br />
CTG_RRMNAME environment variable 49<br />
CTG.INI 43<br />
ctgarm command 120<br />
ctgcfg command 52<br />
ctgclient.jar 143<br />
ctgenvvar script 47<br />
ctgenvvarsamp 43<br />
ctgenvvarsamp script 47<br />
ctgikey 76, 87<br />
ctginstall script 32<br />
ctgjnilog 133<br />
CTGSAMP.INI 43<br />
ctgserver.jar 143<br />
ctgstart command 117, 123<br />
ctgstart script 48, 148<br />
D<br />
DBCS 34<br />
development tools 160<br />
DFHJVPIPE environment variable 39, 49, 148<br />
DFHJVSYSTEM_ environment variables 49<br />
186 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
DFHXCOPT, EXCI options table 50, 52<br />
DFHXCURM 42<br />
diagnosing common problems 139<br />
if a process locks 145<br />
Java exceptions 142<br />
java.lang.OutOfMemory exception 143<br />
SSL exceptions 145<br />
digital certificates 5, 8<br />
externally signed 77, 87, 96<br />
maintaining 76, 87, 95<br />
self-signed 82, 91, 101<br />
digital signatures 5<br />
directory structure 33<br />
disability 169<br />
disk space required 156<br />
DISPLAY environment variable 34<br />
Display TCP/IP hostnames configuration setting 57<br />
distinguished name (DN) 6<br />
DN (distinguished name) 6<br />
documentation 165<br />
documenting problems 150<br />
Drop working connections configuration setting 60<br />
E<br />
ECI (External Call Interface) 1, 3<br />
Enable protocol handler configuration setting 59<br />
Enable reading input from console configuration<br />
setting 57<br />
encryption 5, 8<br />
Enterprise Information Systems (EIS) 13<br />
environment variables<br />
AUTH_USERID_PASSWORD 48<br />
<strong>CICS</strong>CLI 49, 53<br />
CLASSPATH 49, 107, 146<br />
CTG_JNI_TRACE 63, 136<br />
CTG_RRMNAME 49<br />
DFHJVPIPE 49, 148<br />
DFHJVSYSTEM_ 49<br />
EXCI_LOADLIB 50, 52<br />
EXCI_OPTIONS 50, 52, 148<br />
JAVA_COMPILER 22<br />
JAVA_HOME 76, 87<br />
JAVA_PROPAGATE 22, 148<br />
LD_LIBRARY_PATH 50<br />
LIBPATH 22, 50, 97, 102<br />
RRM_NAME 49<br />
STEPLIB 50, 66, 127<br />
EPI (External Presentation Interface) 1<br />
ESI (External Security Interface) 1<br />
etc/profile 22<br />
EXCI (<strong>CICS</strong> External Call Interface) 1, 3<br />
EXCI Allocate_Pipe call 141<br />
EXCI Net Name configuration setting 65<br />
EXCI Open_Pipe call 141<br />
EXCI Options configuration setting 65
EXCI options table, DFHXCOPT 50, 52<br />
EXCI pipe limitations 141<br />
EXCI pipes<br />
Resuse 42<br />
EXCI_LOADLIB environment variable 50, 52<br />
EXCI_OPTIONS environment variable 50, 52, 148<br />
extattr command 65, 147<br />
External Call Interface (ECI) 1, 3<br />
External Presentation Interface (EPI) 1<br />
External Security Interface (ESI) 1<br />
externally-signed certificates 7<br />
F<br />
firewalls 12<br />
G<br />
<strong>Gateway</strong> configuration setting 63<br />
<strong>Gateway</strong> trace file configuration setting 64<br />
<strong>Gateway</strong> trace wrap size 64<br />
<strong>Gateway</strong> tracing 134<br />
<strong>Gateway</strong>.properties file 52<br />
generic ECI replies<br />
Configuration 58<br />
GhostView 161<br />
glossary of terms and abbreviations 173<br />
gskkyman 95<br />
H<br />
Handler wakeup timeout (ms) configuration<br />
setting 59<br />
hangs 145<br />
help 171<br />
High Level Qualifier configuration setting 65<br />
HTTP (Hypertext Transfer Protocol) 2<br />
HTTP over SSL (HTTPS) 2<br />
HTTPS 10<br />
HTTPS (HTTP over SSL) 2<br />
Hypertext Transfer Protocol (HTTP) 2<br />
I<br />
Idle timeout (ms) configuration setting 59<br />
iKeyMan 76, 87<br />
distributing to client workstations 77<br />
Initial number of Connection Manager threads<br />
configuration setting 56<br />
Initial number of Worker threads configuration<br />
setting 56<br />
install_path x<br />
installation 25<br />
migration 23, 24<br />
path x<br />
installation path x<br />
installation problems 139<br />
J<br />
J2EE<br />
resource adapter files 67<br />
resource adapters 3<br />
Java<br />
applet 11<br />
application 12<br />
classes 3<br />
firewall 12<br />
Java language 11<br />
servlet 11<br />
Java development kit 21, 158<br />
Java exceptions 142<br />
Java Secure Socket Extension (JSSE) 21, 158<br />
JAVA_COMPILER environment variable 22<br />
JAVA_HOME environment variable 76, 87<br />
JAVA_PROPAGATE 67<br />
JAVA_PROPAGATE environment variable 22, 48, 148<br />
java.lang.OutOfMemory exception 143<br />
JDK levels 21, 158<br />
JNI error messages 133<br />
JNI tracing 63, 128, 135<br />
JSSE 7, 9, 21, 86, 87, 158<br />
installation 86<br />
migration from SSLight 86<br />
K<br />
keyboard 169<br />
KeyRing database configuration setting 61<br />
KeyRing or Keystore name configuration setting 61<br />
KeyRing or Keystore password configuration<br />
setting 61<br />
KeyRingClass 70<br />
KeyRingPassword 70<br />
KeyRings 7, 76<br />
KeyStores 7, 87<br />
L<br />
LD_LIBRARY_PATH environment variable 50<br />
LIBPATH environment variable 22, 50, 97, 102<br />
Library Name configuration setting 65<br />
license file 32, 33<br />
local gateway connection 12<br />
locales 32<br />
locks 145<br />
M<br />
Max dedicated connections configuration setting 62<br />
MAXASSIZE parameter 123<br />
MAXCPUTIME value 73<br />
Maximum number of Connection Manager threads<br />
configuration setting 56<br />
Maximum number of Worker threads configuration<br />
setting 57<br />
MAXTHREADS parameter 15, 144<br />
Index 187
MAXTHREADSTASK parameter 15<br />
memory leak 143<br />
messages 132<br />
migrating from <strong>CICS</strong> <strong>Gateway</strong> for Java (MVS) 24<br />
Migrating from <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong><br />
4 24<br />
migration issues 23, 24<br />
N<br />
network gateway connection 12<br />
network name 35<br />
network security<br />
AUTH_USERID_PASSWORD environment<br />
variable 48<br />
authentication 8<br />
certification authority (CA) 6<br />
concepts 4<br />
ctgikey 76, 87<br />
defining a RACF facility class 148<br />
digital certificates 5, 8<br />
externally signed 77, 87, 96<br />
maintaining 76, 87, 95<br />
self-signed 82, 91, 101<br />
digital signatures 5<br />
distinguished name (DN) 6<br />
encryption 5, 8<br />
exits 34<br />
externally-signed certificates 7<br />
gskkyman 95<br />
HTTPS 10, 107<br />
iKeyMan 76, 87<br />
distributing to client workstations 77<br />
JSSE 7, 9, 86, 87<br />
installation 86<br />
migration from SSLight 86<br />
KeyRings 7, 76<br />
keys 5<br />
KeyStores 7, 87<br />
mapping client certificates to RACF userids 105<br />
marking programs as program-controlled 147<br />
migrating old self-signed certificates 86, 95<br />
permissions to security class 67<br />
RACDCERT command 105<br />
security exits 10<br />
self-signed certificates 7<br />
setting extended attributes on HFS files 66, 147<br />
signer certificate 6<br />
SSL 8, 107<br />
SSL handshaking 8<br />
SSLight 9, 76<br />
surrogate options in DFHXCOPT 52, 147<br />
System SSL 9<br />
trusted root key 6<br />
X.509 protocol 6, 8<br />
188 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration<br />
O<br />
operating systems 20, 156<br />
P<br />
Password 69<br />
PDF library, extracting 35<br />
performance<br />
assessing 109<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration 110<br />
Java considerations 112<br />
monitoring 114<br />
other system factors 113<br />
tracing 114<br />
Ping time frequency (ms) configuration setting 60<br />
PMR (Problem Management Record) 149<br />
Port configuration setting 59<br />
port numbers 141<br />
PortNumber 69<br />
problem determination<br />
application tracing 135<br />
<strong>CICS</strong> server resources 147<br />
diagnosing common problems 139<br />
<strong>Gateway</strong> tracing 134<br />
installation 139<br />
JNI tracing 135<br />
messages 132<br />
port numbers 141<br />
preliminary checks 131<br />
tracing 133<br />
Problem Management Record (PMR) 149<br />
problem reporting<br />
documenting problems 150<br />
information needed 151<br />
support organization 149<br />
problems, diagnosing 139<br />
process locks 145<br />
program control 147<br />
program controlled 65<br />
program support 149<br />
protocols<br />
HTML 14<br />
HTTP 2<br />
HTTPS 2<br />
SSL 2, 8<br />
TCP/IP 2<br />
PTF (Program Temporary Fix) 153<br />
pthread_security_np 65<br />
public key encryption 5<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 165<br />
R<br />
RACDCERT command 105<br />
RACF<br />
AUTH_USERID_PASSWORD environment<br />
variable 48
RACF (continued)<br />
configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to use<br />
RACF 65<br />
defining a RACF facility class 148<br />
mapping client certificates to RACF userids 105<br />
marking programs as program-controlled 147<br />
problems 147, 148<br />
RACDCERT command 105<br />
setting extended attributes on HFS files 66, 147<br />
userids 105<br />
railroad diagrams x<br />
re-authentication support 70<br />
README file 19<br />
region size considerations 123, 144<br />
Require clients to use security classes configuration<br />
setting 60<br />
resource adapter files 67<br />
resource adapters 68<br />
resource adapters, J2EE 3<br />
RETAIN database 149<br />
RETAIN problem management system<br />
APARs 152<br />
Problem Management Record 149<br />
RRM Name configuration setting 65<br />
RRM_NAME environment variable 49<br />
S<br />
screen readers 160<br />
SDFHEXCI 66<br />
SDFHEXCI data set 147<br />
Secure Sockets Layer (SSL) 2, 8<br />
security exits 10, 34<br />
self-signed certificates 7<br />
ServerName 69<br />
servers<br />
application 21, 159<br />
<strong>CICS</strong> 21, 158<br />
web 21, 159<br />
ServerSecurity 70<br />
servlets 11<br />
sessions definition 37<br />
shortcut keys 169<br />
signer certificate 6<br />
SNA 159<br />
SO_LINGER setting configuration setting 60<br />
software requirements<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS 20<br />
SSL (Secure Sockets Layer) 2, 8<br />
SSL exceptions 145<br />
SSL handshaking 8<br />
SSLight 9, 76<br />
standard error (stderr) file 132, 135<br />
standard output (stdout) file 132<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 117<br />
starting <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with JCL 121<br />
starting multiple <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s 124<br />
STDENV data set 126<br />
stderr 132, 135<br />
stdout 132<br />
STEPLIB environment variable 50, 66, 127<br />
stopping <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 127<br />
support organization<br />
program support 149<br />
sending documentation to 152<br />
SURROGCHK, DFHXCOPT table option 52, 147<br />
symmetric keys 5<br />
syntax notation x<br />
SYS1.PARMLIB 73<br />
System SSL 9<br />
T<br />
TCP/IP (Transmission Control Protocol/Internet<br />
Protocol) 2, 160<br />
TCP62 160<br />
TCPAdmin protocol settings 62<br />
TCPIP.PROFILE 139<br />
Telnet 157<br />
thread limits 15<br />
Timeout for in-progress requests to complete (ms)<br />
configuration setting 58<br />
tools<br />
application development 160<br />
other 161<br />
TPNName 69<br />
trace 118, 134<br />
trace options on ctgstart command 118, 134<br />
TraceLevel 70<br />
tracing 71, 133<br />
dynamic 128<br />
<strong>Gateway</strong> daemon 128<br />
JNI 128<br />
levels 71<br />
performance considerations 135<br />
query current trace settings 128<br />
tracing, JNI 135<br />
TranName 69<br />
transaction support 70<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP) 2<br />
trusted root key 6<br />
U<br />
uninstalling 34<br />
UNIX System Services parameters<br />
MAXTHREADS 15<br />
MAXTHREADSTASK 15<br />
upgrading 23, 24<br />
Use client authentication configuration setting 60<br />
Use RACF Authentication configuration setting 64<br />
Userid 69<br />
Index 189
V<br />
Validate Units of Work 58<br />
W<br />
web browsers 20, 157<br />
web servers 21, 159<br />
Web servers 13<br />
Work load management 42<br />
Worker thread available timeout (ms) configuration<br />
setting 58<br />
Worker threads 117<br />
X<br />
X-Windows 34<br />
X.509 protocol 6, 8<br />
XAResource 70<br />
Z<br />
z/OS Environment settings<br />
CTG User Classpath 65<br />
CTG User Libpath 65<br />
EXCI Net Name 65<br />
EXCI Options 65<br />
High Level Qualifier 65<br />
Library Name 65<br />
RRM Name 65<br />
Use RACF Authentication 64<br />
z/OS Server settings<br />
<strong>CICS</strong> Description 64<br />
<strong>CICS</strong> Server 64<br />
z/OS shell environment 22<br />
190 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 1996, 2002 191
Trademarks<br />
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
AIX <strong>CICS</strong><br />
IBM MVS<br />
OS/2 z/OS<br />
System/390 TXseries<br />
WebSphere<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of<br />
Microsoft Corporation in the United States, other countries, or both.<br />
192 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Java, and all Java-based trademarks and logos are trademarks of Sun<br />
Microsystems, Inc. in the United States, or other countries, or both.<br />
UNIX is a registered trademark in the United States and other countries<br />
licensed exclusively through X/Open Company Limited.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
Notices 193
194 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 1996, 2002 195
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6191-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> z/OS Administration <strong>Version</strong> <strong>5.0</strong>
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Programming Guide<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6141-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Programming Guide<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6141-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 239.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong>, program number 5724-D12. It will also apply to all<br />
subsequent versions, releases, and modifications until otherwise indicated in new editions.<br />
This edition replaces SC34-5946, SC34-5947, SC34-5945, SC34-5938. Vertical lines at the left side of the page indicate<br />
material that is new to this edition.<br />
© Copyright International Business Machines Corporation 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
Contents<br />
About this book . . . . . . . . . . vii<br />
Who should read this book . . . . . . . vii<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . vii<br />
Installation path. . . . . . . . . . ix<br />
Directory delimiters . . . . . . . . ix<br />
Programming language specific. . . . . ix<br />
Operating system specific . . . . . . ix<br />
Summary of changes . . . . . . . . xi<br />
Part 1. Language independent<br />
information . . . . . . . . . . . 1<br />
Chapter 1. Getting started . . . . . . . 3<br />
Overview . . . . . . . . . . . . . 3<br />
External Call Interface (ECI) . . . . . . . 3<br />
External Presentation Interface (EPI) . . . . 4<br />
External Security Interface (ESI) . . . . . . 5<br />
Using the external access interfaces . . . . 6<br />
ECI and EPI exits . . . . . . . . . . 7<br />
Support for object-oriented programming . . 7<br />
Chapter 2. External Call Interface (ECI) . . 9<br />
Overview . . . . . . . . . . . . . 9<br />
ECI function . . . . . . . . . . . 9<br />
Types of ECI call . . . . . . . . . 10<br />
Program link calls . . . . . . . . . . 12<br />
Managing logical units of work . . . . 12<br />
Security in the ECI . . . . . . . . . 15<br />
Status information calls . . . . . . . . 15<br />
How status information is supplied and<br />
used . . . . . . . . . . . . . 15<br />
Reply solicitation calls . . . . . . . . 17<br />
Chapter 3. External Presentation Interface<br />
(EPI) . . . . . . . . . . . . . . 19<br />
Overview . . . . . . . . . . . . . 19<br />
How to use EPI. . . . . . . . . . . 20<br />
Initialization and termination . . . . . 20<br />
Listing the configured servers . . . . . 20<br />
Adding terminal resources . . . . . . 20<br />
Deleting terminal resources . . . . . . 23<br />
Authentication and authorization . . . . 23<br />
Starting transactions . . . . . . . . 24<br />
Events and callbacks . . . . . . . . 24<br />
Processing the events . . . . . . . . 26<br />
Sending and receiving data . . . . . . 27<br />
Managing pseudoconversations . . . . 27<br />
Security in the EPI . . . . . . . . . 27<br />
EPI versions . . . . . . . . . . . . 29<br />
3270 data streams for the EPI . . . . . . 30<br />
Inbound data streams (EPI to <strong>CICS</strong>) . . . 31<br />
Outbound data streams (<strong>CICS</strong> to EPI) . . 32<br />
3270 order codes . . . . . . . . . 33<br />
Chapter 4. External Security Interface (ESI) 35<br />
Overview . . . . . . . . . . . . . 35<br />
Benefits of APPC PEM . . . . . . . . 36<br />
Benefits of ESI . . . . . . . . . . . 36<br />
Part 2. Language Specific<br />
information. . . . . . . . . . . 37<br />
Chapter 5. Programming in C and COBOL 39<br />
Supported operating systems . . . . . . 39<br />
Writing the non-<strong>CICS</strong> applications . . . . 39<br />
Making ECI calls . . . . . . . . . . 40<br />
<strong>CICS</strong>_ExternalCall . . . . . . . . . 40<br />
Callback routines . . . . . . . . . 41<br />
<strong>CICS</strong>_EciListSystems . . . . . . . . 41<br />
Making EPI calls . . . . . . . . . . 42<br />
EPI functions. . . . . . . . . . . 42<br />
Callback routines . . . . . . . . . 42<br />
Compiling and linking applications . . . . 42<br />
Client daemon for Windows . . . . . 43<br />
Client daemon for AIX . . . . . . . 43<br />
Client daemon for Solaris . . . . . . 44<br />
Chapter 6. Programming in C++. . . . . 45<br />
Establishing the working environment . . . 45<br />
Windows environment variables . . . . 45<br />
Compiling and Linking . . . . . . . . 47<br />
Multi-Threading . . . . . . . . . . 47<br />
Handling Exceptions . . . . . . . . . 47<br />
Async Exception Handling . . . . . . 48<br />
External call interface . . . . . . . . . 49<br />
Using COMMAREAs . . . . . . . . 49<br />
© Copyright IBM Corp. 2002 iii
|<br />
|<br />
Finding potential servers . . . . . . . 50<br />
Server connection . . . . . . . . . 50<br />
Monitoring server availability . . . . . 51<br />
Passing data to a server program . . . . 52<br />
Controlling server interactions . . . . . 53<br />
Managing logical units of work . . . . 57<br />
Security Management for ECI . . . . . 58<br />
External presentation interface . . . . . . 59<br />
Support for Automatic <strong>Transaction</strong><br />
Initiation (ATI) . . . . . . . . . . 61<br />
Starting a 3270 terminal connection to<br />
<strong>CICS</strong> . . . . . . . . . . . . . 62<br />
Accessing fields on <strong>CICS</strong> 3270 screens . . 63<br />
EPI call synchronization types . . . . . 64<br />
EPI BMS conversion utility . . . . . . 67<br />
Using EPI BMS Map Classes . . . . . 70<br />
Security Management for EPI . . . . . 71<br />
Chapter 7. Programming in Java . . . . 73<br />
Overview of the programming interface for<br />
Java. . . . . . . . . . . . . . . 73<br />
Writing Java client programs . . . . . . 74<br />
Flow of program control . . . . . . . 75<br />
Java<strong>Gateway</strong> . . . . . . . . . . . 76<br />
ECIRequest . . . . . . . . . . . 78<br />
Common Connector Framework and<br />
<strong>CICS</strong>ELUW flag. . . . . . . . . . 79<br />
EPIRequest . . . . . . . . . . . 79<br />
Setting up the CLASSPATH . . . . . . 81<br />
Codepage conversion . . . . . . . . 81<br />
Using a browser and <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> on the same workstation . . . 81<br />
Performance issues. . . . . . . . . 81<br />
Tracing in Java client programs . . . . 82<br />
Making ECI calls on z/OS . . . . . . 84<br />
ECI return codes and server errors on<br />
z/OS . . . . . . . . . . . . . 86<br />
Making EPI calls on z/OS . . . . . . 86<br />
EXCI considerations on z/OS . . . . . 86<br />
EPI support classes . . . . . . . . 87<br />
EPI beans . . . . . . . . . . . 101<br />
Security . . . . . . . . . . . . . 111<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security classes 111<br />
Using a Java 2 Security Manager . . . . 113<br />
Chapter 8. Programming using J2EE . . 115<br />
The Common Client Interface . . . . . . 115<br />
CCI Framework Classes. . . . . . . 115<br />
CCI Input and Output classes . . . . . 116<br />
Connector specification API Javadoc . . 117<br />
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
J2EE Connector Specification API . . . 117<br />
ECI resource adapter CCI . . . . . . 117<br />
EPI resource adapter CCI . . . . . . 121<br />
Security credentials and the <strong>CICS</strong><br />
resource adapters . . . . . . . . . 129<br />
Compiling applications . . . . . . . 129<br />
Compiling and running Enterprise Bean<br />
clients and deploying Enterprise Beans . 129<br />
Using the J2EE <strong>CICS</strong> resource adapters in a<br />
nonmanaged environment . . . . . . . 130<br />
Creating the appropriate<br />
ConnectionFactory object . . . . . . 130<br />
Storing ConnectionFactory objects . . . 131<br />
Running the J2EE <strong>CICS</strong> resource adapters<br />
in a nonmanaged environment . . . . 131<br />
J2EE Tracing . . . . . . . . . . . 132<br />
Issues with tracing if ConnectionFactory<br />
serialized . . . . . . . . . . . 132<br />
Resource adapter samples . . . . . . . 133<br />
ECI sample . . . . . . . . . . . 133<br />
EPI sample . . . . . . . . . . . 134<br />
Chapter 9. Programming in COM . . . . 137<br />
Establishing the working environment . . . 137<br />
The COM libraries . . . . . . . . 137<br />
Using the COM classes . . . . . . . . 139<br />
Object Creation and Interfaces . . . . 139<br />
Type Libraries and Visual Basic<br />
Intellisense . . . . . . . . . . . 140<br />
Class summary . . . . . . . . . 141<br />
Exception Handling . . . . . . . . 141<br />
Making an ECI link call to <strong>CICS</strong> using<br />
Visual Basic. . . . . . . . . . . 144<br />
ECI Userid and Password Management 149<br />
Connection to <strong>CICS</strong> 3270 applications<br />
using Visual Basic. . . . . . . . . 150<br />
Connecting to <strong>CICS</strong> 3270 applications<br />
using VBScript . . . . . . . . . . 155<br />
Support for Automatic <strong>Transaction</strong><br />
Initiation (ATI) . . . . . . . . . . 155<br />
Security Management . . . . . . . 156<br />
Part 3. Appendixes . . . . . . . 159<br />
Appendix A. ECI extensions that are<br />
environment-dependent . . . . . . . 161<br />
Call type extensions . . . . . . . . . 161
|<br />
Asynchronous program link call, with<br />
notification by message<br />
(ECI_ASYNC_NOTIFY_MSG) . . . . . 161<br />
Asynchronous program link call, with<br />
notification by semaphore<br />
(ECI_ASYNC_NOTIFY_SEM) . . . . . 162<br />
Asynchronous status call, with<br />
notification by message<br />
(ECI_STATE_ASYNC_MSG) . . . . . 162<br />
Asynchronous status call, with<br />
notification by semaphore<br />
(ECI_STATE_ASYNC_SEM) . . . . . 162<br />
Fields to support ECI extensions . . . . . 163<br />
Reply message formats . . . . . . . . 164<br />
ECI return notification . . . . . . . . 164<br />
Summary of input parameter requirements 164<br />
Appendix B. Sample Programs . . . . 167<br />
Appendix C. ECI and EPI exits. . . . . 169<br />
Installing the exits . . . . . . . . . 169<br />
Writing your own user exits . . . . . . 171<br />
How the exit routines are described in the<br />
reference sections . . . . . . . . . . 171<br />
ECI exits reference . . . . . . . . . 171<br />
Identification token . . . . . . . . 172<br />
EPI exits reference . . . . . . . . . 184<br />
<strong>CICS</strong>_EpiInitializeExit . . . . . . . 186<br />
<strong>CICS</strong>_EpiTerminateExit . . . . . . . 187<br />
<strong>CICS</strong>_EpiAddTerminalExit . . . . . . 188<br />
<strong>CICS</strong>_EpiTermIdExit . . . . . . . . 191<br />
<strong>CICS</strong>_EpiTermIdInfoExit . . . . . . 192<br />
|<br />
|<br />
<strong>CICS</strong>_EpiStartTranExit . . . . . . . 193<br />
<strong>CICS</strong>_EpiReplyExit . . . . . . . . 195<br />
<strong>CICS</strong>_EpiDelTerminalExit . . . . . . 196<br />
<strong>CICS</strong>_EpiGetEventExit . . . . . . . 197<br />
<strong>CICS</strong>_EpiSystemIdExit . . . . . . . 199<br />
<strong>CICS</strong>_EpiTranFailedExit. . . . . . . 201<br />
Diagnostic information . . . . . . . . 203<br />
<strong>CICS</strong>TERM, <strong>CICS</strong>PRNT and the EPI exits 203<br />
The product library and related literature 209<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 209<br />
Sample configuration documents. . . . . 210<br />
Redbooks . . . . . . . . . . . . 211<br />
Other Useful Books . . . . . . . . . 211<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 211<br />
Microsoft ® Windows Family publications 212<br />
APPC-related publications . . . . . . 212<br />
TCP62–related publications . . . . . 213<br />
Obtaining books from IBM. . . . . . . 213<br />
Accessibility . . . . . . . . . . . 215<br />
Documentation . . . . . . . . . . 215<br />
Glossary . . . . . . . . . . . . 217<br />
Index . . . . . . . . . . . . . 229<br />
Notices . . . . . . . . . . . . . 239<br />
Trademarks . . . . . . . . . . . . 241<br />
Sending your comments to IBM . . . . 243<br />
Contents v
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
About this book<br />
This book is an introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. It provides the information that you need to allow non-<strong>CICS</strong><br />
applications to use <strong>CICS</strong> facilities in a client/server environment.<br />
The book is in two parts:<br />
Part 1, “Language independent<br />
information” on page 1<br />
Part 2, “Language Specific information”<br />
on page 37<br />
The interfaces described in this book are:<br />
v External call interface (ECI)<br />
v External presentation interface (EPI)<br />
v External security interface (ESI)<br />
Who should read this book<br />
This provides general,<br />
language-independent information about<br />
the interfaces.<br />
This provides information about the<br />
interfaces for each supported language<br />
(Java , C++, C, COM).<br />
See also <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140.<br />
This book is intended for anyone involved with programming a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
It is assumed that you are familiar with the operating system under which<br />
your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs.<br />
An understanding of Internet terminology is helpful.<br />
Conventions and terminology used in this book<br />
A number of parts, both internal and external to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, are used when creating a business solution using the product.<br />
Figure 1 on page viii shows some of the possible scenarios you will encounter,<br />
and the terminology used in each case.<br />
© Copyright IBM Corp. 2002 vii
Distributed platforms running in remote mode<br />
Java client<br />
application<br />
z/OS running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Distributed platforms running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
Client<br />
daemon<br />
Distributed platforms running non-Java applications<br />
Client<br />
application<br />
Client<br />
daemon<br />
z/OS running in remote mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Client<br />
daemon<br />
<strong>CICS</strong><br />
server<br />
<strong>CICS</strong><br />
server<br />
Figure 1. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses, with their associated terminology<br />
<strong>CICS</strong><br />
server<br />
The following explains the terms used in Figure 1:<br />
<strong>Gateway</strong> daemon<br />
Used only in remote mode, the <strong>Gateway</strong> daemon listens on protocols<br />
defined in CTG.INI for gateway requests from remote Java client<br />
applications. It issues these requests to the Client daemon on<br />
distributed platforms, and directly to <strong>CICS</strong> over the EXCI on z/OS ® .<br />
The <strong>Gateway</strong> daemon runs the protocol listener threads, the worker<br />
threads and the connection manager threads. It uses the GATEWAY<br />
section of CTG.INI (and on z/OS the ctgenvvar script) for its<br />
configuration.<br />
Client daemon<br />
The Client daemon (process cclclnt) exists only on distributed<br />
platforms. It manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending and receiving the<br />
appropriate flows from the <strong>CICS</strong> server to satisfy the application<br />
requests. It uses the CLIENT section of CTG.INI for its configuration.<br />
viii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>Gateway</strong> classes<br />
The interface for Java Client applications to connect to the <strong>Gateway</strong><br />
daemon. The <strong>Gateway</strong> classes, which are supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, must be in the classpath for Java Client<br />
applications to run.<br />
Client application<br />
A user application, written in a supported programming language<br />
other than Java, that communicates directly with the Client daemon.<br />
Java Client application<br />
A Java application, servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Installation path<br />
The term is used in file paths to represent the directory where<br />
you installed the product. See the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration<br />
book for your operating system, for the default installation locations.<br />
Directory delimiters<br />
References to directory path names in this book use the Microsoft ® Windows ®<br />
convention of a backslash (\) as delimiter, instead of the forward slash (/)<br />
delimiter used on z/OS and UNIX ® operating systems.<br />
Programming language specific<br />
The term C refers to both the C and C++ programming languages.<br />
Operating system specific<br />
Unless otherwise specified, the term Windows refers to Windows NT ® ,<br />
Windows 2000, and Windows XP.<br />
The term Windows 2000 Terminal Server means a server with the Terminal<br />
Services feature installed.<br />
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.<br />
About this book ix
x <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
Summary of changes<br />
This book contains material that previously appeared in these books:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Gateway</strong> Programming, SC34-5938<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++ Programming, SC34-5945<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> COM Automation Programming, SC35-5946<br />
v <strong>CICS</strong> Family Client/Server Programming, SC34-5947<br />
Vertical lines at the left side of the page indicate material that is new to this<br />
edition.<br />
The following functional changes have been made for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>:<br />
v The Windows XP operating system is supported.<br />
v COBOL is supported on the Windows operating system.<br />
Some beans that were previously provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product are now, instead, included with the set of sample programs.<br />
See “Beans provided in earlier versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>” on<br />
page 101 for details.<br />
© Copyright IBM Corp. 2002 xi
xii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Part 1. Language independent information<br />
© Copyright IBM Corp. 2002 1
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 1. Getting started<br />
Overview<br />
ECI, EPI, and ESI allow your non-<strong>CICS</strong> applications to access <strong>CICS</strong> facilities<br />
and data.<br />
Figure 2 illustrates the use of the external interfaces by a non-<strong>CICS</strong> application<br />
in a client system. This application is using the facilities of <strong>CICS</strong> in a server<br />
system. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> processes the application’s ECI and EPI<br />
requests, and transmits them to the server system using an appropriate<br />
communication protocol. Although the figure shows the client system and<br />
server system as separate workstations, it is possible for the whole<br />
configuration to be on a single workstation.<br />
Client system Server system<br />
Application<br />
ECI<br />
EPI<br />
<strong>CICS</strong><br />
<strong>Transaction</strong><br />
<strong>Gateway</strong><br />
Figure 2. External access interfaces in a <strong>CICS</strong> client/server configuration<br />
External Call Interface (ECI)<br />
ECI allows a non-<strong>CICS</strong> application to call a <strong>CICS</strong> program in a <strong>CICS</strong> server.<br />
The application can connect to several servers at the same time, and there can<br />
be several program calls outstanding at the same time.<br />
<strong>CICS</strong><br />
The <strong>CICS</strong> program cannot perform terminal I/O, but can access and update<br />
all other <strong>CICS</strong> resources.<br />
Figure 3 on page 4 shows that the same <strong>CICS</strong> program can be called by a<br />
non-<strong>CICS</strong> application using ECI, or by a <strong>CICS</strong> program using EXEC <strong>CICS</strong> LINK.<br />
Data passes between the two programs using a COMMAREA, in a similar<br />
way to <strong>CICS</strong> interprogram communication.<br />
© Copyright IBM Corp. 2002 3
Application<br />
Figure 3. ECI illustrated<br />
ECI<br />
<strong>CICS</strong><br />
<strong>CICS</strong><br />
<strong>CICS</strong> program<br />
EXEC <strong>CICS</strong> LINK ...<br />
<strong>CICS</strong> programs<br />
Calls can be made synchronously or asynchronously:<br />
v Synchronous calls return control when the called program completes, and<br />
the information returned is immediately available.<br />
v Asynchronous calls return control without waiting for the called program to<br />
complete, and the application can ask to be notified when the information<br />
becomes available.<br />
Calls can also be extended. That is, a single logical unit of work may cover two<br />
or more successive calls, though only one call can be active for each logical<br />
unit of work at any time. The application can manage many logical units of<br />
work concurrently if it uses asynchronous calls.<br />
The called program can update resources on its own system, and can use<br />
distributed program link (DPL) to call <strong>CICS</strong> programs on other systems. It can<br />
access resources on other <strong>CICS</strong> systems by function shipping, by distributed<br />
transaction processing (DTP), or by the front end programming interface<br />
(FEPI).<br />
External Presentation Interface (EPI)<br />
EPI allows a non-<strong>CICS</strong> application program to be viewed as a 3270 terminal<br />
by a <strong>CICS</strong> server system to which it is connected. Figure 4 on page 5 shows<br />
how both an EPI application and a <strong>CICS</strong> terminal can schedule transactions in<br />
a <strong>CICS</strong> server.<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
Data
Application<br />
EPI<br />
<strong>CICS</strong><br />
Figure 4. External presentation interface<br />
<strong>CICS</strong> transactions<br />
The application can use the facilities of several servers at the same time, and<br />
can act as if it were many different 3270 terminals.<br />
The application can schedule <strong>CICS</strong> transactions, and for these transactions it is<br />
the principal facility.<br />
With <strong>CICS</strong> servers that support access through the EPI, other <strong>CICS</strong><br />
transactions running in the server can use the <strong>CICS</strong> START command to<br />
schedule transactions that use the non-<strong>CICS</strong> application as their initiating<br />
terminal.<br />
When a non-<strong>CICS</strong> application uses the EPI to start a transaction in a <strong>CICS</strong><br />
server, 3270 data streams and events are passed between the server and the<br />
application. The application can present the contents of the terminal I/O to its<br />
user in any manner appropriate to the application’s operating environment.<br />
<strong>Transaction</strong>s can be routed to other <strong>CICS</strong> systems by standard transaction<br />
routing. Resources on other <strong>CICS</strong> systems can be accessed by function<br />
shipping.<br />
External Security Interface (ESI)<br />
ESI allows a non-<strong>CICS</strong> application to invoke services provided by advanced<br />
program-to-program communication (APPC) password expiration<br />
management (PEM).<br />
Data<br />
Chapter 1. Getting started 5
APPC PEM with <strong>CICS</strong> provides support for an APPC sign-on transaction that<br />
signs on userids to a <strong>CICS</strong> server, and processes requests for a password<br />
change by:<br />
v Identifying a user and authenticating that user’s identification<br />
v Notifying specific users during the authentication that their passwords have<br />
expired<br />
v Letting users change their passwords when, or before, the passwords expire<br />
v Telling users how long their current passwords will remain valid<br />
v Providing information about unauthorized attempts to access the server<br />
using a particular user identifier<br />
You can include ESI calls in your ECI or EPI applications.<br />
Using the external access interfaces<br />
The external interfaces allow non-<strong>CICS</strong> applications to access and update<br />
<strong>CICS</strong> resources by initiating <strong>CICS</strong> transactions or calling <strong>CICS</strong> programs.<br />
When used in conjunction with the <strong>CICS</strong> communication facilities, they enable<br />
non-<strong>CICS</strong> programs to access and update resources on any <strong>CICS</strong> system. This<br />
supports such activities as:<br />
1. Developing graphical user interface (GUI) front ends for <strong>CICS</strong><br />
applications, using Presentation Manager ® or other presentation systems<br />
2. Connecting external devices such as bar-code readers to <strong>CICS</strong> systems<br />
3. Allowing the integration of <strong>CICS</strong> systems and non-<strong>CICS</strong> systems.<br />
EPI allows you to develop GUIs, either for existing <strong>CICS</strong> systems or for new<br />
applications. It is particularly useful for developing new GUI front ends for<br />
existing <strong>CICS</strong> transactions, which need not be changed. The application can<br />
use EPI to communicate with a <strong>CICS</strong> transaction, and can exploit the<br />
presentation facilities of the client system to communicate with the user.<br />
If you attach an external device, such as a bar code reader, the application can<br />
deal with device input and output, and can use the EPI to start a transaction,<br />
perhaps one already written to deal with the kind of data that the external<br />
device produces. The application converts the input from the external device<br />
into a 3270 data stream to start the transaction and pass the data to it. Output<br />
from the transaction, in the form of a 3270 data stream, is then converted into<br />
the signals and data streams that operate the external device.<br />
You can use both EPI and ECI to pass data between a non-<strong>CICS</strong> application<br />
and a <strong>CICS</strong> program. However, the methods are different:<br />
v EPI uses 3270 data streams<br />
v ECI uses application-defined formats in a COMMAREA<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
ECI and EPI exits<br />
For <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the operation of the EPI and ECI can be<br />
customized by the user exits described in Appendix C, “ECI and EPI exits” on<br />
page 169.<br />
Support for object-oriented programming<br />
The principal communication mechanism that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides is the External Call Interface (ECI). The supplied ECI class library,<br />
modelling the full function of ECI in an object-oriented way, allows you to:<br />
v make links to servers<br />
v make calls to <strong>CICS</strong> programs on servers<br />
v check status<br />
v use units of work (UOW’s)<br />
The second interface available to application programmers on <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is the External Presentation Interface (EPI). EPI provides<br />
communication with 3270 terminal based <strong>CICS</strong> applications using classes<br />
encapsulating terminals, screens, fields and BMS maps. EPI classes make it<br />
unnecessary to work directly with the 3270 datastream, and make it easier to<br />
examine and update the contents of an output screen.<br />
Chapter 1. Getting started 7
Support for object-oriented programming<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 2. External Call Interface (ECI)<br />
Overview<br />
This chapter describes the External Call Interface (ECI).<br />
Although the interface is described in a way that is independent of<br />
programming language, the names used for elements of the interface are<br />
similar to those used in programming.<br />
Information that is specific to programming languages is in the following<br />
chapters:<br />
v Chapter 5, “Programming in C and COBOL” on page 39<br />
v Chapter 6, “Programming in C++” on page 45<br />
v Chapter 7, “Programming in Java” on page 73<br />
v Chapter 8, “Programming using J2EE” on page 115<br />
v Chapter 9, “Programming in COM” on page 137<br />
Some ECI functions are dependent on the operating system. These are<br />
described in Appendix A, “ECI extensions that are environment-dependent”<br />
on page 161.<br />
The Chapter is organized as follows:<br />
“Overview”<br />
“Program link calls” on page 12<br />
“Status information calls” on page 15<br />
“Reply solicitation calls” on page 17<br />
ECI function<br />
ECI allows a non-<strong>CICS</strong> application program to call a <strong>CICS</strong> program in a <strong>CICS</strong><br />
server. The non-<strong>CICS</strong> application does not issue any <strong>CICS</strong> commands itself;<br />
the <strong>CICS</strong> commands are issued by the called program running in the server.<br />
This means the called program appears to have been called by the EXEC <strong>CICS</strong><br />
LINK command with the COMMAREA option. An ECI application can make use of<br />
existing <strong>CICS</strong> programs, or you can write new <strong>CICS</strong> programs to be called by<br />
ECI applications. The called programs must follow the rules for <strong>CICS</strong><br />
programs called by DPL.<br />
An application can run more than one <strong>CICS</strong> program concurrently, and these<br />
programs might be distributed across several <strong>CICS</strong> servers.<br />
© Copyright IBM Corp. 2002 9
External Call Interface (ECI)<br />
The function provided by ECI is packaged in two parts:<br />
<strong>CICS</strong>_ExternalCall Provides most of the function of ECI. It has a<br />
single parameter, the ECI parameter block, in<br />
which various fields describe the function to<br />
be performed and the inputs and outputs.<br />
Most of the following sections are concerned<br />
with the use of <strong>CICS</strong>_ExternalCall.<br />
<strong>CICS</strong>_EciListSystems Used to find out about available servers to<br />
which <strong>CICS</strong>_ExternalCall requests can be<br />
directed.<br />
Types of ECI call<br />
There are three types of call to <strong>CICS</strong>_ExternalCall:<br />
v Program link calls<br />
v Status information calls<br />
v Reply solicitation calls.<br />
The type of call to <strong>CICS</strong>_ExternalCall is determined by the setting of the<br />
eci_call_type parameter in the ECI parameter block.<br />
Restrictions on call type for particular operating environments are discussed<br />
in the descriptions of each call type.<br />
Program link calls<br />
Program link calls cause a <strong>CICS</strong> program to be executed on a <strong>CICS</strong> server.<br />
These calls can be:<br />
Synchronous The application waits until the called program has finished.<br />
Returned information is immediately available.<br />
Asynchronous The application gets back control without waiting for<br />
completion of the called program. The application can ask to<br />
be notified later when the information is available. It must use<br />
a reply solicitation call to determine the outcome of the<br />
asynchronous request.<br />
Status information calls<br />
Status information calls retrieve status information about the type of system<br />
on which the application is running and its status. These calls can be:<br />
Synchronous The application waits until the information has been made<br />
available.<br />
Asynchronous The application gets back control while the information is<br />
being retrieved. The application can ask to be notified later<br />
when the information is available. It must use a reply<br />
solicitation call to determine the outcome of the asynchronous<br />
request.<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Call Interface (ECI)<br />
Reply solicitation calls<br />
Reply solicitation calls get information back after asynchronous program link<br />
or asynchronous status information calls. Reply solicitation calls can be:<br />
General Retrieving any piece of outstanding information.<br />
Specific Retrieving information for a named asynchronous request.<br />
An application that uses the asynchronous method of calling may have<br />
several program link and status information calls outstanding at any time.<br />
The eci_message_qualifier parameter in the ECI parameter block can be used<br />
on an asynchronous call to provide a user-defined identifier for the call. The<br />
use of different identifiers for different asynchronous calls within a single<br />
application is the programmer’s responsibility. When a general reply<br />
solicitation call is made, ECI uses the eci_message_qualifier field to return<br />
the name of the call to which the reply belongs. When a specific reply<br />
solicitation call is made, you must supply a value in the<br />
eci_message_qualifier field to identify the asynchronous call about which<br />
information is being sought.<br />
Time-outs<br />
The support consists of a field eci_timeout in the ECI parameter block, and<br />
two return codes: ECI_ERR_RESPONSE_TIMEOUT and<br />
ECI_ERR_REQUEST_TIMEOUT.<br />
In the processing of timeouts, there are two cases to consider.<br />
v The time-out occurs before the request has been forwarded to the server. In<br />
this case the response is ECI_ERR_REQUEST_TIMEOUT. The requested<br />
program was not called, and no server resources have been updated.<br />
– If the call was intended to start, or be the whole of, a new logical unit of<br />
work, the logical unit of work was not started, and no recoverable<br />
resources have been updated.<br />
– If the call was intended to continue an existing logical unit of work, the<br />
logical unit of work was continued, but no recoverable resources were<br />
updated, and the logical unit of work is still uncommitted.<br />
– If the call was intended to end an existing logical unit of work, the<br />
logical unit of work was continued, no recoverable resources were<br />
updated, and the logical unit of work is still uncommitted.<br />
v The time-out occurs after the request has been forwarded to the server. In<br />
this case the response is ECI_ERR_RESPONSE_TIMEOUT, and it could be<br />
returned to a synchronous call, or to an asynchronous call, or to the reply<br />
solicitation request that gets the reply to an asynchronous call.<br />
– If the call was intended to be the only call of a new logical unit of work,<br />
the logical unit of work was started, but it is not possible for the<br />
application to determine whether updates were performed, and whether<br />
they were committed or backed out.<br />
Chapter 2. External Call Interface (ECI) 11
External Call Interface (ECI)<br />
– If the call was intended to end an existing logical unit of work by using<br />
ECI_NO_EXTEND, the logical unit of work has ended, but it is not<br />
possible for the application to determine whether updates were<br />
performed, and whether they were committed or backed out.<br />
– If the call was intended to continue or to end an existing logical unit of<br />
work by using ECI_COMMIT, the logical unit of work persists, and<br />
changes to recoverable resources are still pending.<br />
Program link calls<br />
Program link calls can be either synchronous or asynchronous. For<br />
asynchronous calls, it is the responsibility of the calling application to solicit<br />
the reply using one of the reply solicitation calls. (See “Reply solicitation calls”<br />
on page 17.)<br />
Managing logical units of work<br />
An ECI application is often concerned with updating recoverable resources on<br />
the server, and the application programmer needs to understand the facilities<br />
that ECI provides for managing logical units of work. A logical unit of work is<br />
all the processing in the server that is needed to complete a set of changes to<br />
recoverable resources. When the logical unit of work ends normally, the<br />
changes will all be committed. When the logical unit of work ends<br />
abnormally, for instance because a program abends, the changes are all backed<br />
out. You can use ECI to start and end logical units of work on the server.<br />
The changes to recoverable resources in a logical unit of work might be made<br />
by:<br />
v A single program link call, or<br />
v A sequence of program link calls<br />
On successful return from the first of a sequence of calls for a logical unit of<br />
work, the eci_luw_token field in the control block contains a token that<br />
should be used for all later calls related to the same logical unit of work. All<br />
program link calls for the same logical unit of work will be sent to the same<br />
server.<br />
Note: Take care when extending a logical unit of work across multiple<br />
program link calls that may span a long period of time, for example,<br />
user thinking time. The reason is that the logical unit of work holds<br />
various locks and other <strong>CICS</strong> resources on the server, and this may<br />
cause delays to other users who are waiting for those same locks and<br />
resources.<br />
When a logical unit of work ends, the <strong>CICS</strong> server attempts to commit the<br />
changes. The last, or only, program link call of a logical unit of work is<br />
advised whether the attempt was successful.<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Only one program link call per logical unit of work can be outstanding at any<br />
time. (An asynchronous program link call is outstanding until a reply<br />
solicitation call has processed the reply.)<br />
Table 1 shows how you can use combinations of eci_extend_mode,<br />
eci_program_name, and eci_luw_token parameter values to perform tasks<br />
associated with managing logical units of work through ECI. In each case you<br />
must also store appropriate values in other fields for the call type you have<br />
chosen.<br />
Table 1. Logical units of work in ECI<br />
Task to perform Parameters to use<br />
Call a program that is to be the only program of a Set up the parameters as follows:<br />
logical unit of work.<br />
v eci_extend_mode: ECI_NO_EXTEND<br />
One request flows from client to server and a v eci_program_name: provide it<br />
reply is sent to the client only after all the changes<br />
made by the specified program have been<br />
committed.<br />
v eci_luw_token: zero<br />
Call a program that is to start a new logical unit of<br />
work that is to be extended.<br />
Call a program that is to continue an existing<br />
logical unit of work.<br />
Call a program that is to be the last program of an<br />
existing logical unit of work, and commit the<br />
changes.<br />
End an existing logical unit of work, without<br />
calling another program, and commit changes to<br />
recoverable resources.<br />
End an existing logical unit of work, without<br />
calling another program, and back out changes to<br />
recoverable resources.<br />
External Call Interface (ECI)<br />
Set up the parameters as follows:<br />
v eci_extend_mode: ECI_EXTENDED<br />
v eci_program_name: provide it<br />
v eci_luw_token: zero<br />
Afterwards, save the token from eci_luw_token.<br />
Set up the parameters as follows:<br />
v eci_extend_mode: ECI_EXTENDED<br />
v eci_program_name: provide it<br />
v eci_luw_token: provide it<br />
Set up the parameters as follows:<br />
v eci_extend_mode: ECI_NO_EXTEND<br />
v eci_program_name: provide it<br />
v eci_luw_token: provide it<br />
Set up the parameters as follows:<br />
v eci_extend_mode: ECI_COMMIT<br />
v eci_program_name: null<br />
v eci_luw_token: provide it<br />
Set up the parameters as follows:<br />
v eci_extend_mode: ECI_BACKOUT<br />
v eci_program_name: null<br />
v eci_luw_token: provide it<br />
If an error occurs in one of the calls of an extended logical unit of work, you<br />
can use the eci_luw_token field to see if the changes made so far have been<br />
backed out, or are still pending. See the description of the eci_luw_token field<br />
Chapter 2. External Call Interface (ECI) 13
External Call Interface (ECI)<br />
in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference for more information. If the<br />
changes are still pending, you should end the logical unit of work with<br />
another program link call, either committing or backing out the changes.<br />
Each logical unit of work (LUW) occupies one <strong>CICS</strong> non-facility task for the<br />
duration of its execution. This means that you must define enough free tasks<br />
in the <strong>CICS</strong> server to service the maximum expected number of concurrent<br />
calls.<br />
Figure 5 shows an application program using asynchronous program calls.<br />
The program has two calls outstanding in one server and one call in another.<br />
To keep track of its requests, the program is using message qualifiers that it<br />
has generated itself, and LUW tokens returned in the eci_luw_token field. The<br />
LUW token is unique for each call.<br />
Server 1<br />
Message qualifiers<br />
LUWtokens<br />
Application<br />
<strong>CICS</strong> programs <strong>CICS</strong> program<br />
Figure 5. Asynchronous program link calls with message qualifiers and LUW tokens<br />
Server 2<br />
For more details of the program link calls, study the descriptions of the<br />
individual call types:<br />
ECI_SYNC for a synchronous program link call<br />
ECI_ASYNC for an asynchronous program link call.<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Security in the ECI<br />
The ECI_SYNC and ECI_ASYNC calls are implemented as a set of<br />
intersystem conversations between a Client daemon and a <strong>CICS</strong> server; a<br />
conversation is allocated for each unit of work created by the client<br />
application.<br />
Status information calls<br />
External Call Interface (ECI)<br />
A userid and password might be required for each intersystem conversation;<br />
the requirement is determined by the way in which the Client daemon and<br />
<strong>CICS</strong> server have been configured.<br />
The client application can specify the userid and password in the eci_userid<br />
(or eci_userid2) and eci_password (or eci_password2) in the ECI parameter<br />
block for the first or only call in the unit of work.<br />
The client application can pass the userid and password to the<br />
<strong>CICS</strong>_SetDefaultSecurity function. The values are server-specific and are used<br />
whenever the values have been omitted from the ECI parameter block. The<br />
values can be changed at any time by the <strong>CICS</strong>_SetDefaultSecurity function.<br />
If the userid and password are required for intersystem conversations, and<br />
they are not set by the <strong>CICS</strong>_SetDefaultSecurity function, the Client daemon<br />
might use another method, for example opening a pop-up window, to request<br />
them.<br />
For more information on how to configure client/server security on UNIX or<br />
Windows, see Client Security, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration.<br />
Status information calls can be either synchronous or asynchronous. For<br />
asynchronous calls, it is the responsibility of the calling application to obtain<br />
the reply using a reply solicitation call (see “Reply solicitation calls” on<br />
page 17).<br />
How status information is supplied and used<br />
Status information is supplied in the ECI status block, which is passed across<br />
the interface in the eci_commarea parameter.<br />
The following status information is held in the ECI status block.<br />
Type of connection Whether the ECI program is locally connected<br />
to a <strong>CICS</strong> server, to a <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, or to nothing.<br />
State of the <strong>CICS</strong> server Available, unavailable, or unknown.<br />
Chapter 2. External Call Interface (ECI) 15
External Call Interface (ECI)<br />
State of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Available, not applicable, or unknown.<br />
For a more detailed description of the ECI status block, refer to <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference.<br />
The status information calls allow you to perform three tasks:<br />
Enquire on the type of system the application is running on, and its<br />
connection with a given server.<br />
For this you need to provide a COMMAREA in<br />
which the status is returned.<br />
Set up a request to be notified when the status changes from some<br />
specified value. For this you need to provide a COMMAREA in<br />
which the specified status is described. When<br />
the status is different from the status specified,<br />
you are notified of the new status. Only<br />
asynchronous calls can be used for this<br />
purpose.<br />
Cancel a request for notification of status change.<br />
For this no COMMAREA is required.<br />
Table 2 shows how you can use combinations of eci_extend_mode,<br />
eci_commarea, eci_commarea_length, and eci_luw_token parameter values to<br />
perform tasks associated with status enquiries. In each case you must also<br />
store appropriate values in other fields for the call type you have chosen.<br />
For more details of the status information calls, see the descriptions of the<br />
individual call types in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference:<br />
ECI_STATE_SYNC<br />
For a synchronous status information call<br />
ECI_STATE_ASYNC<br />
For an asynchronous status information call.<br />
Table 2. Status enquiries with <strong>CICS</strong>_ExternalCall<br />
Task to perform Parameters to use<br />
Find the current status. Set up the parameters as follows:<br />
v eci_commarea: nulls<br />
v eci_commarea_length: length of ECI_STATUS<br />
v eci_extend_mode: ECI_STATE_IMMEDIATE<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
Afterwards, consult the contents of the<br />
COMMAREA to find the status.
Table 2. Status enquiries with <strong>CICS</strong>_ExternalCall (continued)<br />
Task to perform Parameters to use<br />
Set up a request to find out about status change. Set up the parameters as follows:<br />
v eci_commarea: specified status<br />
v eci_commarea_length: length of ECI_STATUS<br />
v eci_extend_mode: ECI_STATE_CHANGED<br />
v eci_luw_token: zero<br />
Afterwards, save the token from eci_luw_token so<br />
that you can cancel the request later.<br />
Cancel a request to find out about status change. Set up the parameters as follows:<br />
v eci_commarea: none<br />
v eci_commarea_length: zero<br />
v eci_extend_mode: ECI_STATE_CANCEL<br />
v eci_luw_token: provide it<br />
Reply solicitation calls<br />
External Call Interface (ECI)<br />
After an asynchronous program link call, or asynchronous status information<br />
call, it is the responsibility of the calling application to solicit the reply. All<br />
calls return any outstanding reply that meets the selection criteria specified in<br />
the call.<br />
For more details of the reply solicitation calls, see the descriptions of the<br />
individual call types in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference:<br />
ECI_GET_REPLY For a reply solicitation call that gets any<br />
outstanding reply for any asynchronous call, if<br />
any reply is available.<br />
ECI_GET_REPLY_WAIT For a reply solicitation call that gets any<br />
outstanding reply for any asynchronous call,<br />
waiting if no replies are available.<br />
ECI_GET_SPECIFIC_REPLY For a reply solicitation call that gets any<br />
outstanding reply for a given asynchronous<br />
call, if any reply is available.<br />
ECI_GET_SPECIFIC_REPLY_WAIT<br />
For a reply solicitation call that gets any<br />
outstanding reply for a given asynchronous<br />
call, waiting if no replies are available.<br />
Chapter 2. External Call Interface (ECI) 17
External Call Interface (ECI)<br />
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 3. External Presentation Interface (EPI)<br />
Overview<br />
This chapter describes the External Presentation Interface (EPI).<br />
Although the interface is described in a way that is independent of<br />
programming language, the names used for elements of the interface are<br />
similar to those used in programming.<br />
Information that is specific to programming languages is in the following<br />
chapters:<br />
v Chapter 5, “Programming in C and COBOL” on page 39<br />
v Chapter 6, “Programming in C++” on page 45<br />
v Chapter 7, “Programming in Java” on page 73<br />
v Chapter 8, “Programming using J2EE” on page 115<br />
v Chapter 9, “Programming in COM” on page 137<br />
The chapter is organized as follows:<br />
“Overview”<br />
“How to use EPI” on page 20<br />
“3270 data streams for the EPI” on page 30<br />
EPI allows a non-<strong>CICS</strong> application program to have access to one or more<br />
<strong>CICS</strong> servers. In each <strong>CICS</strong> server, the application can establish one or more<br />
terminal resources. The application acts as the operator of these terminal<br />
resources, starting <strong>CICS</strong> transactions, and sending and receiving standard 3270<br />
data streams associated with those transactions.<br />
Consider the following when you design client/server implementations using<br />
EPI.<br />
v A <strong>CICS</strong> transaction that sends data to an EPI application must not use basic<br />
mapping support (BMS) paging.<br />
v An EPI application can use EPI to determine the default screen size of the<br />
terminal resource definition, but not the alternate screen size.<br />
v An EPI application cannot use EPI to determine whether it is to send or<br />
receive double byte character set (DBCS) data streams to or from the <strong>CICS</strong><br />
transaction.<br />
v The 3270 data streams produced by <strong>CICS</strong> transactions must not contain<br />
structured fields.<br />
© Copyright IBM Corp. 2002 19
External Presentation Interface (EPI)<br />
How to use EPI<br />
v For EPI terminals on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, the maximum screen size<br />
is 27 rows by 132 columns. This is because the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
supports the ASCII-7 subset of the 3270 data stream architecture, which<br />
only supports 12 bit addressing. For more information, see “3270 data<br />
streams for the EPI” on page 30.<br />
v If a <strong>CICS</strong> transaction uses EXEC <strong>CICS</strong> START with the DELAY option to<br />
schedule transactions to a terminal resource autoinstalled by an EPI<br />
application, the EPI application should take care when deleting the terminal<br />
resource, or delayed ATI requests might be lost. See your server<br />
documentation to determine the effects of deleting a terminal resource<br />
when delayed ATI requests are outstanding.<br />
The application is responsible for the presentation of the 3270 data received.<br />
The application may present the data in the normal way by emulating a 3270<br />
terminal, or it may present a very different view. For example:<br />
v A Windows application might use the Windows graphical user interface.<br />
v A Solaris application might use Open Look.<br />
Initialization and termination<br />
Any application that needs to use EPI must call the <strong>CICS</strong>_EpiInitialize<br />
function to initialize EPI. Until this call is made, no other EPI function is<br />
allowed. The <strong>CICS</strong>_EpiInitialize function takes a parameter indicating the<br />
version of the EPI for which the application was coded. This is to ensure that<br />
existing applications continue to run without change if the EPI is extended.<br />
See “EPI versions” on page 29 for more details.<br />
Before an EPI application ends, it should call the <strong>CICS</strong>_EpiTerminate function<br />
to terminate EPI cleanly.<br />
Listing the configured servers<br />
After calling <strong>CICS</strong>_EpiInitialize successfully, the application should call<br />
<strong>CICS</strong>_EpiListSystems to check which <strong>CICS</strong> servers are configured for use by<br />
the application.<br />
Adding terminal resources<br />
The primary purpose of EPI is to allow an application to appear to a <strong>CICS</strong><br />
server as one or more 3270 terminals.<br />
Terminal resources are added by invoking either the <strong>CICS</strong>_EpiAddTerminal<br />
or <strong>CICS</strong>_EpiAddExTerminal function.<br />
An application can specify the server in which the terminal resource is to be<br />
installed; if it does not the default server is selected.<br />
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Presentation Interface (EPI)<br />
An application can specify the terminal resource to be installed by supplying<br />
one of the following:<br />
The netname of an existing terminal resource in the server<br />
This terminal resource should be one that is<br />
not currently in use.<br />
The name of a model terminal definition<br />
In this case, the server generates a netname<br />
and autoinstalls a terminal resource with that<br />
netname, using the specified model terminal<br />
definition.<br />
Nothing In this case the server generates a netname<br />
and autoinstalls a terminal resource with that<br />
name, using a default model terminal<br />
definition.<br />
When an application has installed a terminal resource, no other application<br />
can use that terminal resource until the first application deletes it.<br />
The <strong>CICS</strong>_EpiAddTerminal and <strong>CICS</strong>_EpiAddExTerminal functions return a<br />
terminal index, which must be passed on subsequent EPI function calls to<br />
indicate the terminal resource to which the function is to apply. Each index<br />
identifies a combination of server and terminal resource. The terminal index<br />
supplied is the first available integer starting from 0. This allows the<br />
application to maintain a mapping between terminal indexes and terminal<br />
resource information, using array lookup.<br />
Terminal indexes are unique within an application, but not across<br />
applications, so each application gets terminal index zero for the first terminal<br />
it installs, and so on.<br />
Figure 6 on page 22 shows an application with three terminal resources, one in<br />
one server and two in another. The application uses the terminal indexes to<br />
operate the terminal resources, sending and receiving 3270 data streams.<br />
Chapter 3. External Presentation Interface (EPI) 21
External Presentation Interface (EPI)<br />
Server 1<br />
Terminal resources<br />
Figure 6. Using terminal indexes<br />
Application<br />
Terminal indexes<br />
0 1 2<br />
Terminal resource<br />
Server 2<br />
Terminal attributes<br />
Most attributes are determined by the server when the terminal resource is<br />
installed; some are returned to the application in the <strong>CICS</strong>_EpiDetails_t<br />
structure passed to the <strong>CICS</strong>_EpiAddTerminal and <strong>CICS</strong>_AddExTerminal<br />
functions.<br />
Some attributes might be determined by the application. These attributes are<br />
specified in the <strong>CICS</strong>_EpiAttributes_t structure passed to the<br />
<strong>CICS</strong>_EpiAddExTerminal function. For example the character set and<br />
encoding scheme to be used for 3270 data is specified in the CCSID field in the<br />
<strong>CICS</strong>_EpiAttributes_t structure. For more details on the<br />
<strong>CICS</strong>_EpiAttributes_t structure refer to its entry in the EPI constants and data<br />
structures section in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
manual.<br />
Timeout<br />
Execution of the <strong>CICS</strong>_EpiAddTerminal function is synchronous; execution of<br />
the <strong>CICS</strong>_EpiAddExTerminal function can be asynchronous. Control is not<br />
returned to the invoking application until a response, for example, that the<br />
terminal resource has been installed, is available.<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Presentation Interface (EPI)<br />
The response time depends on a number of factors; for example:<br />
v Network parameters and traffic<br />
v Server parameters and transaction load<br />
An application can limit the length of time that it will wait for a response; the<br />
limit is specified in the InstallTimeOut field in the <strong>CICS</strong>_EpiAttributes_t<br />
structure passed to the <strong>CICS</strong>_EpiAddExTerminal function.<br />
If the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> does not receive a response from the server<br />
within the specified interval, control will be returned to the invoking<br />
application with the return code set to <strong>CICS</strong>_EPI_ERR_RESPONSE_TIMEOUT.<br />
If the Client daemon is subsequently notified that the terminal resource has<br />
been installed in the server, the Client daemon will delete the terminal<br />
resource. Note that this action has the effect of increasing the network traffic<br />
and the transaction load on the server.<br />
Deleting terminal resources<br />
If a terminal resource is no longer required, it can be deleted by invoking<br />
either the <strong>CICS</strong>_EpiDelTerminal or <strong>CICS</strong>_EpiPurgeTerminal function.<br />
The <strong>CICS</strong>_EpiDelTerminal function is used when the terminal resource is to<br />
be deleted in a controlled manner. The call succeeds only if no transaction is<br />
running against the terminal resource and there are no unprocessed events for<br />
the terminal resource; if a transaction is in progress or there are unprocessed<br />
events, the call returns an error code.<br />
The <strong>CICS</strong>_EpiPurgeTerminal function is used when the terminal resource is<br />
to be deleted without regard to a transaction that may be running against the<br />
terminal or unprocessed events for the terminal resource.<br />
When the terminal resource has been deleted the terminal index value<br />
becomes free and can be reused when another terminal resource is added. The<br />
server deletes the terminal resource if it was autoinstalled.<br />
Authentication and authorization<br />
When an application has defined a terminal resource, it can start transactions<br />
from that terminal resource. The server may have to:<br />
v Authenticate the userid and password for the terminal ″operator″<br />
v Grant authority, based on the authenticated userid, to access the resources<br />
required for the execution of each transaction.<br />
Chapter 3. External Presentation Interface (EPI) 23
External Presentation Interface (EPI)<br />
The frequency with which the userid and password are authenticated by the<br />
server depends on another attribute specified in the SignOnCapability field<br />
in the <strong>CICS</strong>_EpiAttributes_t structure passed to the <strong>CICS</strong>_EpiAddExTerminal<br />
function.<br />
Signon capable terminals<br />
If the terminal resource is installed as signon capable, the application is<br />
responsible for starting a signon transaction, for example the <strong>CICS</strong> supplied<br />
CESN transaction; the userid and password being embedded in the 3270 data.<br />
<strong>Transaction</strong>s started before the signon transaction will execute with the<br />
authorities granted to a default userid. <strong>Transaction</strong>s started after the signon<br />
transaction will execute with the authorities granted to the authenticated<br />
userid.<br />
A consequence of installing a terminal as signon capable is that the<br />
application must be prepared to cope with the ″operator″ being signed off if<br />
the terminal resource remains idle for longer than a server defined limit.<br />
Signon incapable terminals<br />
If the terminal resource is installed as signon incapable, the userid and<br />
password are authenticated for each transaction started for the terminal<br />
resource. The initial userid and password for the terminal resource may be<br />
specified in the UserId and Password fields in the <strong>CICS</strong>_EpiAttributes_t<br />
structure passed to the <strong>CICS</strong>_EpiAddExTerminal function.<br />
The userid and password may be changed at any time by invoking the<br />
<strong>CICS</strong>_EpiSetSecurity function.<br />
For information on how to provide a userid and password, on UNIX or<br />
Windows, see Client Security, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration.<br />
Starting transactions<br />
When an application has defined a terminal resource, it can start a transaction<br />
from that terminal resource. To the <strong>CICS</strong> server it appears as if a terminal user<br />
had typed a transaction code on the screen and pressed an AID key. To start a<br />
transaction, the <strong>CICS</strong>_EpiStartTran function is called. There are two ways of<br />
specifying the transaction to be started and the data to be associated with it.<br />
1. Supply the transaction identifier as a parameter to the call (TransId), and<br />
supply any transaction data in the Data parameter.<br />
2. Combine a transaction identifier and transaction data into a 3270 data<br />
stream, and supply the data stream as a parameter to the call (Data).<br />
Events and callbacks<br />
When an application has defined a terminal resource, several events can<br />
happen to it because of actions in the <strong>CICS</strong> server, rather than actions of the<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Presentation Interface (EPI)<br />
application. The application cannot predict when those events may happen,<br />
but it is the responsibility of the application to collect and process the events<br />
as appropriate. Events are held by the EPI in a first-in-first-out queue until<br />
they are collected, one by one, by the application making calls to the<br />
<strong>CICS</strong>_EpiGetEvent function. During such a call, the EPI puts information in a<br />
<strong>CICS</strong>_EpiEventData_t structure to indicate the event that occurred and any<br />
associated data. It also indicates whether there are more events still waiting in<br />
the queue.<br />
The application can synchronize the processing of these events with its other<br />
activities in one of three ways:<br />
v Polling<br />
v Blocking<br />
v Callback notification.<br />
Polling<br />
The <strong>CICS</strong>_EpiGetEvent call can be made in a polling mode by specifying<br />
<strong>CICS</strong>_EPI_NOWAIT for the Wait parameter. If no event is waiting to be<br />
collected, the function returns immediately with an error code. This is the<br />
mechanism that you would have to adopt in a single-user single-threaded<br />
environment, where the application might alternately poll the keyboard for<br />
user activity and poll the EPI for event activity.<br />
Blocking<br />
The <strong>CICS</strong>_EpiGetEvent call can be made in a blocking mode by specifying<br />
<strong>CICS</strong>_EPI_WAIT for the Wait parameter. If no event is waiting to be collected,<br />
the function waits and does not return until an event becomes available. You<br />
could use this mechanism in a multithreaded environment, where a secondary<br />
thread could be dedicated to event processing. It could also be used after a<br />
notification by callback, because the event information is known to be<br />
available.<br />
Callback notification<br />
When the terminal resource is defined with the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call, the optional parameter NotifyFn may be used<br />
to provide the address of a callback routine that the EPI calls whenever an<br />
event occurs against that terminal resource.<br />
Note: Some compilers do not support the use of callback routines. Consult<br />
your compiler documentation for more information.<br />
An application should carry out the minimum of processing in its callback<br />
routine, and never block in the specified routine before returning to the EPI.<br />
The routine itself cannot make EPI calls. You decide what it should do when<br />
the notification is received. For example, in a multithreaded environment, it<br />
might post a semaphore to signal another thread that an event has occurred.<br />
Chapter 3. External Presentation Interface (EPI) 25
External Presentation Interface (EPI)<br />
In a Presentation Manager environment, it might post a message to a window<br />
to indicate to the window procedure that an event has occurred. Other actions<br />
will be appropriate for other environments.<br />
When the callback routine is called, it is passed a single parameter—the<br />
terminal index of the terminal resource against which the event occurred. This<br />
allows the same callback routine to be used for more than one terminal<br />
resource.<br />
Processing the events<br />
On return from the <strong>CICS</strong>_EpiGetEvent function, the <strong>CICS</strong>_EpiEventData_t<br />
structure contains the details of the event that occurred. The Event field in<br />
this structure indicates the event, and can take one of the following values:<br />
v <strong>CICS</strong>_EPI_EVENT_SEND<br />
v <strong>CICS</strong>_EPI_EVENT_CONVERSE<br />
v <strong>CICS</strong>_EPI_EVENT_END_TRAN<br />
v <strong>CICS</strong>_EPI_EVENT_START_ATI<br />
v <strong>CICS</strong>_EPI_EVENT_ADD_TERM<br />
v <strong>CICS</strong>_EPI_EVENT_END_TERM<br />
The application should attempt to process events as quickly as possible,<br />
because some events describe the state of the terminal resource. If these events<br />
are not processed, the application may receive unexpected error return codes<br />
when it tries to issue EPI functions, because the state maintained inside the<br />
EPI might not match the state maintained in the application. For example, an<br />
application can start a transaction only if the terminal resource is not currently<br />
running another transaction. The <strong>CICS</strong>_EPI_EVENT_END_TRAN event<br />
signals the end of a transaction, and so the application and the EPI enter a<br />
state in which new transactions can be started for that terminal resource. The<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI event indicates that an ATI transaction has<br />
started at the terminal resource, and therefore that the terminal resource has<br />
entered a state in which the starting of transactions is no longer allowed. If<br />
the application calls <strong>CICS</strong>_EpiStartTran after the<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI event has been notified, but before the event<br />
has been retrieved, the <strong>CICS</strong>_EpiStartTran call fails, even though, to the<br />
application, it may appear that it is still in a state in which it should succeed.<br />
When a client application is driven with an event or callback, it should issue a<br />
<strong>CICS</strong>_EpiGetEvent to get the associated event. In certain timing conditions,<br />
the <strong>CICS</strong>_EPI_EVENT_START_ATI may already have been notified from a<br />
previous <strong>CICS</strong>_EpiGetEvent. The <strong>CICS</strong>_EpiGetEvent issued after the callback<br />
can receive <strong>CICS</strong>_EPI_ERR_NO_EVENT (if <strong>CICS</strong>_EPI_NOWAIT is specified<br />
for the Wait parameter) or wait until a subsequent event is received (if<br />
<strong>CICS</strong>_EPI_WAIT is specified for the Wait parameter). Note that this can<br />
happen after a <strong>CICS</strong>_EPI_EVENT_START_ATI is received.<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Presentation Interface (EPI)<br />
Sending and receiving data<br />
When a transaction sends data to a terminal resource, the EPI generates either<br />
a <strong>CICS</strong>_EPI_EVENT_SEND event or a <strong>CICS</strong>_EPI_EVENT_CONVERSE event.<br />
The data sent might be data from the transaction, or it might be messages<br />
produced by the server, including error messages. You should consult your<br />
server documentation to see what messages are possible. An EPI application<br />
should analyze the data stream to see if an error has occurred.<br />
The <strong>CICS</strong>_EPI_EVENT_SEND event indicates that data was sent but that no<br />
reply is required. Typically this would result from an EXEC <strong>CICS</strong> SEND<br />
command, but in some servers it would result from an EXEC <strong>CICS</strong><br />
CONVERSE command. (In the latter case, a <strong>CICS</strong>_EPI_EVENT_CONVERSE<br />
event occurs later to tell the application to send a data stream back to the<br />
transaction in the server.)<br />
The <strong>CICS</strong>_EPI_EVENT_CONVERSE event indicates that a reply is required,<br />
and would typically result from an EXEC <strong>CICS</strong> RECEIVE or EXEC <strong>CICS</strong><br />
CONVERSE command. The application should respond to this event by<br />
issuing a <strong>CICS</strong>_EpiReply call to provide the response data. The<br />
<strong>CICS</strong>_EpiReply function should be issued only to respond to a<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE event; if it is issued at any other time, an<br />
error is returned.<br />
Managing pseudoconversations<br />
<strong>CICS</strong> transactions can operate in a pseudoconversational mode. The<br />
conversation between a terminal resource and a server is broken up into a<br />
number of segments, each of which is a separate transaction. As each<br />
transaction ends, it provides the name of the transaction to be run to process<br />
the next input from the terminal resource. (It uses EXEC <strong>CICS</strong> RETURN with<br />
the TRANSID option to do this.) The <strong>CICS</strong>_EPI_EVENT_END_TRAN event<br />
tells the application whether the transaction just ended has specified a<br />
transaction to process the next input, and which transaction has been<br />
specified. The application must not attempt to start a different transaction, but<br />
must use <strong>CICS</strong>_EpiStartTran to start the transaction specified by the<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event.<br />
Security in the EPI<br />
The EPI is implemented as a set of intersystem conversations between <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> and server; for example, a conversation is allocated for:<br />
v Each terminal resource that is installed; refer to the <strong>CICS</strong>_EpiAddTerminal<br />
and <strong>CICS</strong>_EpiAddExTerminal functions.<br />
v Each transaction that is started; refer to the <strong>CICS</strong>_EpiStartTran function.<br />
v Each terminal resource that is deleted from the server; refer to the<br />
<strong>CICS</strong>_EpiDelTerminal function.<br />
Chapter 3. External Presentation Interface (EPI) 27
External Presentation Interface (EPI)<br />
A userid and password may be required for each intersystem conversation;<br />
the requirement is determined by the way in which <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> and <strong>CICS</strong> server have been configured.<br />
The client application can specify the userid and password in the<br />
<strong>CICS</strong>_EpiAttributes_t structure passed to the <strong>CICS</strong>_EpiAddExTerminal<br />
function. The values are terminal specific and are passed to the server in the<br />
intersystem conversation allocated to install the terminal and in subsequent<br />
intersystem conversations relating to the installed terminal. The values can be<br />
changed at any time by the <strong>CICS</strong>_EpiSetSecurity function.<br />
The client application can pass the userid and password to the<br />
<strong>CICS</strong>_SetDefaultSecurity function. The values are server-specific and are<br />
used whenever the terminal-specific values are not available. The values can<br />
be changed at any time by the <strong>CICS</strong>_SetDefaultSecurity function.<br />
If the userid and password are required for intersystem conversations and<br />
have not been set by the <strong>CICS</strong>_EpiAddExTerminal or <strong>CICS</strong>_EpiSetSecurity<br />
or <strong>CICS</strong>_SetDefaultSecurity functions then the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
may use other methods to determine the values.<br />
For information on how to provide a userid and password, on UNIX or<br />
Windows, see Client Security, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration<br />
or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration.<br />
Signon incapable terminals<br />
The userid determined by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is authenticated by<br />
the server for each transaction started at a signon incapable terminal. The<br />
transaction is executed in the server with the authorities assigned to the<br />
authenticated userid.<br />
If no userid is passed by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, then the transaction<br />
is executed in the server with the authorities assigned to the default userid.<br />
Signon capable terminals<br />
The userid, if any, determined by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> may be<br />
authenticated by the <strong>CICS</strong> server for each transaction started at a signon<br />
capable terminal. Such transactions are executed in the <strong>CICS</strong> server with the<br />
authorities assigned to a userid determined by the client application or to the<br />
default userid.<br />
The first transaction(s) to be started at the terminal are executed with the<br />
authorities assigned to the default userid.<br />
Signon transactions are <strong>CICS</strong>-supplied or user-written. In both cases, the<br />
userid and password are determined by the client application and are<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
External Presentation Interface (EPI)<br />
embedded in the 3270 data stream passed to the <strong>CICS</strong>_EpiStartTran or<br />
<strong>CICS</strong>_EpiReply functions. If the userid is authenticated then subsequent<br />
transactions started at the terminal are executed in the <strong>CICS</strong> server with the<br />
authorities assigned to the authenticated userid.<br />
The client application may start a signoff transaction at the terminal. The<br />
userid may be signed off by the server following a predefined period of<br />
inactivity. In either case, subsequent transactions started at the terminal are<br />
executed with the authorities assigned to the default userid.<br />
Note: A <strong>CICS</strong> server may reject an attempt to install a signon capable<br />
terminal. This would be the case for <strong>CICS</strong> for OS/400 ® where all<br />
authentication is managed by the operating system.<br />
Security on z/OS Servers<br />
Security checking done in the server for transactions started at a signon<br />
capable terminal installed by a Client application does not depend on what is<br />
specified by the ATTACHSEC option for the connection representing the<br />
Client daemon. Instead security checking depends on whether the user signs<br />
on while using the terminal.<br />
If the user does not sign on, the Client daemon installed terminal is associated<br />
with the default user defined for the server in the SIT. When a transaction is<br />
run, the security checks are carried out against this default user. A check is<br />
also done against the userid associated with the connection to see whether the<br />
Client daemon itself has authority to access the resource.<br />
When a user does sign on, the terminal is associated with the userid just<br />
authenticated. For transactions attempting to access resources, security<br />
checking is done against the userid associated with the connection and the<br />
signed-on user’s userid.<br />
It is recommended that the Usedfltuser parameter on the server connection<br />
definition is set to Yes if using signon capable terminals and to No if using<br />
signon incapable terminals.<br />
EPI versions<br />
The following descriptions of EPI functions embrace three versions of the EPI.<br />
You should consult the documentation for your client or server environment<br />
to determine which versions of the EPI they provide. You establish the version<br />
of the EPI that you need by using the <strong>Version</strong> parameter on the<br />
<strong>CICS</strong>_EpiInitialize function. This will return one of the following:<br />
v <strong>CICS</strong>_EPI_VERSION_100<br />
v <strong>CICS</strong>_EPI_VERSION_101<br />
Chapter 3. External Presentation Interface (EPI) 29
EPI versions<br />
v <strong>CICS</strong>_EPI_VERSION_200<br />
The functions described in the following sections are the functions for<br />
versions up to <strong>CICS</strong>_EPI_VERSION_200. The following functions and data<br />
structures are only supported for <strong>CICS</strong>_EPI_VERSION_200:<br />
v <strong>CICS</strong>_EpiAddExTerminal<br />
v <strong>CICS</strong>_EpiPurgeTerminal<br />
v <strong>CICS</strong>_EpiSetSecurity<br />
v <strong>CICS</strong>_EpiAttributes_t<br />
v The MapName, MapSetName,System, TermID, and SignonCapability<br />
fields in the <strong>CICS</strong>_EpiDetails_t data structure<br />
The following are not supported for <strong>CICS</strong>_EPI_VERSION_200:<br />
v <strong>CICS</strong>_EpiGetSysError<br />
v <strong>CICS</strong>_EpiSysError_t<br />
In addition, if you initialize the EPI with <strong>CICS</strong>_EPI_VERSION_100, the<br />
following restrictions apply:<br />
v The <strong>CICS</strong>_EpiInquireSystem function is not supported.<br />
v The return codes EPI_ERR_IN_CALLBACK, EPI_ERR_NULL_PARM, and<br />
EPI_ERR_SECURITY are not supported. EPI_ERR_FAILED will be returned<br />
instead.<br />
v The System parameter of <strong>CICS</strong>_EpiAddTerminal must specify a non-null<br />
string, as the mechanism for finding a default server is not supported. (If a<br />
null string is specified, <strong>CICS</strong>_EPI_ERR_SYSTEM is returned.)<br />
3270 data streams for the EPI<br />
The data streams implemented for the EPI follow those defined in the 3270<br />
Data Stream Programmer’s Reference. All data flows for the EPI are in ASCII<br />
format, and structured fields are not supported. Data flows are defined under<br />
the following topics in the 3270 Data Stream Programmer’s Reference:<br />
v Introduction to the 3270 data stream (excluding structured fields)<br />
v 3270 data stream commands<br />
v Character sets, orders and attributes<br />
v Keyboard and printer operations.<br />
The use of 3270 data streams within the EPI, and some nonstandard orders<br />
and attributes, are defined here.<br />
The supplied C header file, cics3270.g, and the COBOL copybook cics3270.cbl,<br />
contain constants and conversion tables that you will find useful in handling<br />
3270 data streams.<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Note that if a <strong>CICS</strong> user transaction issues EXEC <strong>CICS</strong> SEND and EXEC <strong>CICS</strong><br />
RECEIVE commands, <strong>CICS</strong> does not process the data (after the initial control<br />
bytes) that is passed between the EPI application and the <strong>CICS</strong> transaction. In<br />
this case, the data buffer may be used to pass user-specified data between the<br />
programs. Be aware that the contents of the data buffer may be code-page<br />
converted if the buffer is passed between <strong>CICS</strong> systems, in which case the<br />
data should be limited to ASCII and EBCDIC characters.<br />
If a <strong>CICS</strong> transaction issues EXEC <strong>CICS</strong> SEND MAP and EXEC <strong>CICS</strong><br />
RECEIVE MAP commands, <strong>CICS</strong> converts the data from the BMS structure to<br />
a 3270 data stream. In this case, the application receives 3270 data from <strong>CICS</strong><br />
and should return valid 3270 data to be converted for the transaction.<br />
The distributed <strong>CICS</strong> products (that is, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong><br />
Universal Client) support the ASCII-7 subset of the 3270 data stream<br />
architecture. This precludes the use of 14- and 16- bit addresses, or structured<br />
fields, and means that only 12-bit SBA addressing is supported. Because of<br />
this restriction, the maximum screen size for EPI terminals is 27 rows by 132<br />
columns. The <strong>CICS</strong>/390 and <strong>CICS</strong>/400 ® products support the EBCDIC 3270<br />
data stream architecture. However transactions on these servers must avoid<br />
the use of 14- and 16- bit addresses and structured fields if these are to be<br />
started from one of the distributed <strong>CICS</strong> products.<br />
Inbound data streams (EPI to <strong>CICS</strong>)<br />
AID<br />
(1 byte)<br />
Cursor address<br />
(2 bytes)<br />
Data buffer<br />
(variable length)<br />
3270 data streams<br />
EPI applications send 3270 data to <strong>CICS</strong> on calls to the following functions:<br />
v <strong>CICS</strong>_EpiStartTran<br />
v <strong>CICS</strong>_EpiReply.<br />
The format in both cases is the same. The data stream must be a minimum of<br />
3 non-null bytes, representing the AID and cursor address; the sole exception<br />
to this is if the AID represents the CLEAR key or a PA key, when the data<br />
stream may consist of the AID only. These fields are passed to the <strong>CICS</strong><br />
transaction in the EIBAID and EIBCPOSN fields of the EIB.<br />
The contents of the data buffer consist of:<br />
v ASCII displayable characters with embedded 3270 control characters, when<br />
it is passed to an EXEC <strong>CICS</strong> RECEIVE MAP command.<br />
v User-specified data, when it is passed to an EXEC <strong>CICS</strong> RECEIVE<br />
command.<br />
Chapter 3. External Presentation Interface (EPI) 31
3270 data streams<br />
On starting a transaction, the transaction ID is extracted from the start of the<br />
data buffer as follows:<br />
v If a set buffer address (SBA) order is present at the start of the data buffer,<br />
the transaction ID is extracted from the 4th through 7th bytes of the buffer.<br />
v If an SBA is not present at the start of the data buffer, the transaction ID is<br />
extracted from the 1st through 4th bytes of the buffer.<br />
In either case, the transaction ID may be shorter than 4 bytes, being delimited<br />
by either another SBA, an ASCII space, or the end of the string.<br />
The contents of the data buffer passed on the start of a <strong>CICS</strong> transaction are<br />
available to the transaction in response to an initial EXEC <strong>CICS</strong> RECEIVE<br />
command.<br />
When the application replies, the contents of the data buffer are available in<br />
an unconverted form in response to an EXEC <strong>CICS</strong> RECEIVE command or<br />
converted to a BMS structure in response to an EXEC <strong>CICS</strong> RECEIVE MAP<br />
command.<br />
Note: It is the EPI programmer’s responsibility in the latter case to ensure that<br />
the data is formatted correctly so that the conversion succeeds.<br />
Outbound data streams (<strong>CICS</strong> to EPI)<br />
Command<br />
(1 byte)<br />
Write control<br />
character<br />
(1 byte)<br />
Data buffer<br />
(variable length)<br />
The 3270 commands are either write or read commands, instructing the EPI to<br />
process the data or to reply with data respectively.<br />
On a <strong>CICS</strong>_EPI_EVENT_SEND event, the command is one of the following<br />
3270 write commands:<br />
v Write<br />
v Erase/Write<br />
v Erase/Write Alternate<br />
v Erase All Unprotected.<br />
The first three commands are followed by a write control character (WCC)<br />
and data. An Erase All Unprotected command has neither WCC nor data. The<br />
Write Structured Field command is not generated by <strong>CICS</strong> and is therefore not<br />
supported for the EPI.<br />
The contents of the data buffer consist of:<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
3270 data streams<br />
v ASCII displayable characters with embedded 3270 control characters, when<br />
it is passed from an EXEC <strong>CICS</strong> SEND MAP command.<br />
v User-specified data, when it is passed from an EXEC <strong>CICS</strong> SEND<br />
command.<br />
A <strong>CICS</strong>_EPI_EVENT_CONVERSE event specifies a read command. The<br />
contents of the data stream vary with the source of the event, as follows:<br />
v If the event is the result of an EXEC <strong>CICS</strong> RECEIVE command, the data<br />
buffer might contain data sent by the transaction, or it might be empty. The<br />
EPI program should reply when the data to be sent is available.<br />
v If the event is the result of an EXEC <strong>CICS</strong> RECEIVE BUFFER command, the<br />
data buffer contains the 3270 Read Buffer command. This should be<br />
processed as described in the 3270 Data Stream Programmer’s Reference.<br />
3270 order codes<br />
3270 orders are included in both inbound and outbound data streams to<br />
provide additional control function. Table 3 lists the order codes that may<br />
occur in 3270 data streams, and shows whether they relate to inbound or<br />
outbound data streams, or both.<br />
Table 3. Order codes occurring in 3270 data streams<br />
Order code Inbound Outbound<br />
Start field (SF) Yes Yes<br />
Start field extended (SFE) Yes Yes<br />
Set buffer address (SBA) Yes Yes<br />
Set attribute (SA) Yes Yes<br />
Modify field (MF) No Yes<br />
Insert cursor (IC) No Yes<br />
Program tab (TB) No Yes<br />
Repeat to address (RA) No Yes<br />
Erase unprotected to address (EUA) No Yes<br />
Graphic escape (GE) No No<br />
Note: The 3270 Data Stream Programmer’s Reference states that the SFE, SA, and<br />
MF orders are not supported in ASCII. However, they do occur in 3270<br />
data streams for the EPI, where they take the following values:<br />
SFE X’10’<br />
SA X’1F’<br />
MF X’1A’<br />
Chapter 3. External Presentation Interface (EPI) 33
3270 data streams<br />
Each of these orders is followed by one or more attribute type-value<br />
pairs. The count of attribute pairs and the attribute type are both binary<br />
values, and are thus as defined in the 3270 Data Stream Programmer’s<br />
Reference. However, the contents of the attribute value field may vary<br />
from those defined in the 3270 Data Stream Programmer’s Reference as<br />
follows:<br />
v If the attribute type is less than or equal to X'C0' (for example, a<br />
color), the attribute value is defined as an EBCDIC value in the 3270<br />
Data Stream Programmer’s Reference. The EPI uses the ASCII<br />
equivalent of the EBCDIC value; for example, red is defined as X'F2'<br />
in the 3270 Data Stream Programmer’s Reference, and should be defined<br />
as X'32' in the EPI data stream.<br />
v If the attribute type is greater than X'C0' (for example, field<br />
outlining), the attribute value is a binary value. The EPI uses the<br />
values defined in the 3270 Data Stream Programmer’s Reference.<br />
Further details of 3270 orders and other control characters are supplied in the<br />
files named in the following table.<br />
COBOL copybook<br />
Supplied file<br />
cics3270.cbl<br />
C header file cics3270.h<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 4. External Security Interface (ESI)<br />
Overview<br />
This chapter describes the External Security Interface (ESI).<br />
Although the interface is described in a way that is independent of<br />
programming language, the names used for elements of the interface are<br />
similar to those used in programming.<br />
Information that is specific to programming languages is in the following<br />
chapters:<br />
v Chapter 5, “Programming in C and COBOL” on page 39<br />
v Chapter 6, “Programming in C++” on page 45<br />
v Chapter 7, “Programming in Java” on page 73<br />
v Chapter 8, “Programming using J2EE” on page 115<br />
v Chapter 9, “Programming in COM” on page 137<br />
The Chapter is organized as follows:<br />
“Overview”<br />
“Benefits of APPC PEM” on page 36<br />
“Benefits of ESI” on page 36<br />
ESI allows a non-<strong>CICS</strong> application to invoke services provided by advanced<br />
program-to-program communication (APPC) password expiration<br />
management (PEM).<br />
APPC PEM with <strong>CICS</strong> provides support for an APPC architected sign-on<br />
transaction that signs on userids to a <strong>CICS</strong> server, and processes requests for a<br />
password change by:<br />
v Identifying a user and authenticating that user’s identification<br />
v Notifying specific users during the authentication that their passwords have<br />
expired<br />
v Letting users change their passwords when (or before) the passwords expire<br />
v Telling users how long their current passwords will remain valid<br />
v Providing information about unauthorized attempts to access the server<br />
using a particular user identifier<br />
© Copyright IBM Corp. 2002 35
External Security Interface (ESI)<br />
Benefits of APPC PEM<br />
APPC PEM has the following benefits:<br />
v It enables users to update passwords on APPC links.<br />
This can be particularly useful in the case of expired passwords. On APPC<br />
links that do not support APPC PEM, when users’ passwords expire on<br />
remote systems, they are unable to update them from their own systems.<br />
The only alternative on a non-APPC PEM system is to log on directly to the<br />
remote system using a non-APPC link, such as an LU2 3270-emulation<br />
session, to update the password.<br />
v It provides users of SNA, or TCP62, with additional information regarding<br />
their sign-on status, for example, the date and time at which they last<br />
signed on. It informs users whether their userid is revoked, or the<br />
password has expired, when they provide the correct password or<br />
PassTicket.<br />
Benefits of ESI<br />
To use APPC PEM, you need a PEM client (requestor) and a PEM server<br />
linked by a SNA, or TCP62, session. An external security manager (ESM),<br />
such as resource access control facility (RACF ® ), or an equivalent ESM, must<br />
also be available to the PEM server.<br />
ESI provides the following functions:<br />
v The <strong>CICS</strong>_VerifyPassword function, which allows a client application to<br />
verify that a password matches the password recorded by an ESM for a<br />
specified userid.<br />
v The <strong>CICS</strong>_ChangePassword function, which allows a client application to<br />
change the password recorded by an ESM for a specified userid.<br />
v The <strong>CICS</strong>_SetDefaultSecurity function, which allows a client application to<br />
specify a default userid and password to be used for ECI and EPI request<br />
to the server.<br />
These functions allow a non-<strong>CICS</strong> application program to act as a PEM<br />
requestor without the application programmer having to manage an APPC<br />
conversation, which implies knowledge of the formats for PEM requests and<br />
replies, and of the interface to the local PEM server.<br />
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Part 2. Language Specific information<br />
© Copyright IBM Corp. 2002 37
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 5. Programming in C and COBOL<br />
This Chapter contains information about the external access interfaces, that is<br />
specific to C and Cobolt, and is organized as follows:<br />
“Supported operating systems”<br />
“Writing the non-<strong>CICS</strong> applications”<br />
“Making ECI calls” on page 40<br />
“Making EPI calls” on page 42<br />
“Compiling and linking applications” on page 42<br />
This chapter does not deal with testing or debugging ECI and EPI<br />
applications. You should refer to the programming documentation for the<br />
environment in which you are working.<br />
Supported operating systems<br />
v Programming applications in C for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
supported on the AIX ® , HP-UX, Linux, Solaris and Windows operating<br />
systems.<br />
v Programming applications in COBOL for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
supported only on the Windows operating system.<br />
Writing the non-<strong>CICS</strong> applications<br />
ECI and EPI applications are stand-alone programs that can be run on any<br />
programs that can be run on any of the <strong>CICS</strong> Universal Client or <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> systems except <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
Programs that do not make operating-system-specific calls are portable<br />
between these environments. The sample programs and associated build files for<br />
your environment illustrate much of what is discussed here.<br />
An application program may use the facilities of both ECI and EPI.<br />
An application must be constructed as a single process, though in<br />
environments in which a process can generate several threads, an application<br />
can be multi-threaded.<br />
This chapter explains the writing of programs in the C and Cobol<br />
programming languages.<br />
© Copyright IBM Corp. 2002 39
Creating applications<br />
The following table shows the header files for C required in your programs:<br />
Use File<br />
ECI cics_eci.h<br />
EPI cics_epi.h<br />
Type definitions cicstype.h<br />
The following table shows the copybook files for COBOL required in your<br />
programs:<br />
Use File<br />
ECI cicseci.cbl<br />
EPI cicsepi.cbl<br />
Note: Cobol is only supported on the Windows operating system.<br />
You should study the contents of the files you intend to use. Each file contains<br />
the definitions of all the entry points, types, data structures, and constants<br />
needed for writing programs for the corresponding interface.<br />
When compiling C programs, you may need to ensure that the structures<br />
passed to the <strong>CICS</strong> external facilities are packed. If this is necessary, the C<br />
header files will contain the #pragma pack directive, which should not be<br />
changed.<br />
Making ECI calls<br />
ECI functions are called in the manner described below.<br />
COBOL applications must ensure that the ECI function calls are statically<br />
linked at link time by using the system linkage convention.<br />
For Micro Focus Object COBOL, you should use call-convention 8 for every<br />
program call, or use the default call-convention 0 and compile using the<br />
LITLINK compiler directive.<br />
<strong>CICS</strong>_ExternalCall<br />
The method of calling <strong>CICS</strong>_ExternalCall is shown here for C and COBOL.<br />
The ECI parameter block (ECI_PARMS for C and ECI-PARMS for COBOL) is<br />
used for passing parameters to the ECI. The format of the call and associated<br />
declarations is as follows:<br />
For C programs:<br />
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
ECI_PARMS EciBlock;<br />
cics_sshort_t Response;<br />
.<br />
.<br />
.<br />
Response = <strong>CICS</strong>_ExternalCall(&EciBlock);<br />
For COBOL programs:<br />
CALL <strong>CICS</strong>EXTERNALCALL<br />
USING BY REFERENCE ECI-PARMS<br />
RETURNING ECI_ERROR_ID.<br />
The name _<strong>CICS</strong>_ExternalCall may also be used with the Micro Focus Object<br />
COBOL compiler, but it is not recommended.<br />
Callback routines<br />
Each callback routine has only one parameter. You should consult the sample<br />
programs for examples of writing callback routines.<br />
Callback routines can be used in C but are not available in Cobol.<br />
<strong>CICS</strong>_EciListSystems<br />
The format of the <strong>CICS</strong>_EciListSystems call for C is as follows:<br />
#define MAX_SYS 5<br />
cics_sshort_t Response;<br />
cics_ushort_t Count;<br />
<strong>CICS</strong>_EciSystem_t List[MAX_SYS];<br />
.<br />
Count = MAX_SYS;<br />
.<br />
Response = <strong>CICS</strong>_EciListSystems(NULL, &Count, List);<br />
Creating applications<br />
The COBOL name of the system information structure is <strong>CICS</strong>-ECISYSTEM<br />
The format of the <strong>CICS</strong>_EciListSystems call for COBOL is as follows:<br />
01 LIST-SIZE PIC 9(4) COMP-5.<br />
CALL <strong>CICS</strong>ECILISTSYSTEMS<br />
USING<br />
BY REFERENCE NULL-PTR<br />
BY REFERENCE LIST-SIZE<br />
BY REFERENCE <strong>CICS</strong>-ECISYSTEM<br />
RETURNING ECI-ERROR_ID.<br />
The name _<strong>CICS</strong>_EciListSystems may also be used with the Micro Focus Object<br />
COBOL compiler, but it is not recommended.<br />
Chapter 5. Programming in C and COBOL 41
Creating applications<br />
Making EPI calls<br />
EPI functions<br />
EPI functions are called in a standard manner. an example of calling the<br />
<strong>CICS</strong>_EpiListSystems function for C and COBOL follow:<br />
For C programs:<br />
#define MAX_SYS 5<br />
<strong>CICS</strong>_EpiSystem_t System;<br />
cics_ushort-t Count;<br />
cics_sshort_t Response;<br />
.<br />
Count = MAX_SYS;<br />
.<br />
Response = <strong>CICS</strong>_EpiListSystems(NULL, &Count, &System);<br />
For Cobol programs:<br />
01 COUNT PIC 9(4) COMP-5.<br />
01 NAMESPACE POINTER.<br />
.<br />
.<br />
.<br />
CALL <strong>CICS</strong>EPILISTSYSTEMS<br />
USING BY VALUE NAMESPACE<br />
BY REFERENCE COUNT<br />
BY REFERENCE <strong>CICS</strong>-EPISYSTEM<br />
RETURNING EPI-RETURN-CODE.<br />
Callback routines<br />
Each callback routine has only one parameter. You should consult the sample<br />
programs for examples of writing callback routines.<br />
Callback routines can be used in C but are not available in Cobol.<br />
Compiling and linking applications<br />
This section gives some examples showing how to compile and link typical<br />
ECI and EPI applications in the various client environments. These are<br />
examples only, and may refer to specific compilers and linkers.<br />
Refer to the samples supplied with your environment (see Appendix B,<br />
“Sample Programs” on page 167) for more information about compiling and<br />
linking programs.<br />
For details of supported compilers, see the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Administration book for your operating system.<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Client daemon for Windows<br />
For C Programs:<br />
cl /c /DWIN32 /D_WIN32 /D_X86_=1 /D<strong>CICS</strong>_W32 program.c<br />
link program.obj cclwin32.lib<br />
Figure 7. Command to issue for C compiling<br />
Notes:<br />
v The compiler options /DWIN32, /D_WIN32, and /D_X86_=1 are used to<br />
select the correct Windows function and are standard Win32 options. These<br />
options are not specific to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v The compiler option /D<strong>CICS</strong>_W32 must be used to define the symbol<br />
<strong>CICS</strong>_W32 to the compiler to ensure that the <strong>CICS</strong> header files are<br />
processed correctly.<br />
v The application must be linked with the CCLWIN32.LIB library in addition<br />
to the standard C runtime and Windows libraries.<br />
v Callback functions must be declared using the <strong>CICS</strong>EXIT calling<br />
convention—see samples for details.<br />
For COBOL Programs:<br />
cobol program;<br />
cblnames -mPROGRAM program.obj<br />
link ecicobnl.obj cbllds.obj /NOD cclwin32.lib mfrts32.lib msvcrt.lib kernel32.lib<br />
Figure 8. Command to issue for COBOL compiling<br />
Notes:<br />
1. ″program″ must be replaced by the name of the program, and<br />
″PROGRAM″ must be replaced by the name of the program in upper case<br />
2. It is important to use the correct calling convention when invoking the ECI<br />
or EPI from COBOL. The sample programs use the ″SPECIAL-NAMES.<br />
CALL CONVENTION 8 IS <strong>CICS</strong>.″ statements to achieve this<br />
3. The application must be linked with the CCLWIN32.LIB library, in<br />
addition to the standard COBOL libraries, because a 32-bit Windows<br />
application is being generated.<br />
4. ECI or EPI callback functions are not supported in COBOL applications.<br />
Client daemon for AIX<br />
cc_r -c -D<strong>CICS</strong>_AIX -I/include program.c<br />
cc_r -o program program.o -lpthreads -lc_r -lcclaix<br />
Creating applications<br />
Chapter 5. Programming in C and COBOL 43
Creating applications<br />
Notes:<br />
v The constant <strong>CICS</strong>_AIX must be defined to the compiler using the<br />
-D<strong>CICS</strong>_AIX option.<br />
v The application must be linked with the standard AIX libpthreads.a and<br />
libc_r.a libraries, as well as the libcclaix.a library.<br />
Client daemon for Solaris<br />
cc -c -D<strong>CICS</strong>_SOL -I/include program.c<br />
cc -o program program.o -lpthread -lc -lcclsol<br />
Notes:<br />
v The constant <strong>CICS</strong>_SOL must be defined to the compiler using the<br />
-D<strong>CICS</strong>_SOL option.<br />
v The application must be linked with the standard Solaris libpthread.so and<br />
libc.so libraries, as well as the libcclsol.so library.<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 6. Programming in C++<br />
Establishing the working environment<br />
You are provided with C++ (OO) support for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
AIX, HP-UX, Linux, Solaris and Windows operating systems. This includes<br />
the class library, C++ header files, the BMS map utility, and sample code.<br />
See Supported software in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration book for<br />
your operating system, for full details of <strong>CICS</strong> server platforms supported by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>s.<br />
Windows environment variables<br />
On the Windows operating system there are system specific (these apply to all<br />
users) and user specific environment variables. This is illustrated by the<br />
screenshot in Figure 9 on page 46 where the top pane is the user environment<br />
variables and the bottom one is the generic system ones. This duplication can<br />
cause problems due to the user variables taking precedence over the system<br />
ones.<br />
© Copyright IBM Corp. 2002 45
Establishing the working environment<br />
Figure 9. Duplication of environment variables on the Windows Operating System<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and <strong>CICS</strong> Universal Client append directories to<br />
the LIB and INCLUDE variables only in the system set, to ensure that these are<br />
used you should add ;%LIB% to the end of your user LIB environment variable<br />
and ;%INCLUDE% to the end of your user INCLUDE environment variable. The<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> appends ;%CLASSPATH% to your user CLASSPATH<br />
environment variable. When you select OK on the Edit user variable window<br />
to make this change, the variable is displayed with the system paths<br />
appended.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Compiling and Linking<br />
Refer to the sample programs for more information about compiling and<br />
linking programs; see Appendix B, “Sample Programs” on page 167.<br />
Your C++ program source needs #include statements to include either<br />
cicseci.hpp, for the ECI classes, or cicsepi.hpp, for the EPI classes. These<br />
files are in the \include subdirectory.<br />
On UNIX operating systems, when compiling C++ applications that use the<br />
<strong>CICS</strong> C++ libraries, define these macros instead of CC_UNIX:<br />
Operating system Macro<br />
AIX <strong>CICS</strong>_AIX<br />
HP-UX <strong>CICS</strong>_HPUX<br />
Linux <strong>CICS</strong>_LNX<br />
Solaris <strong>CICS</strong>_SOL<br />
Compiling and Linking<br />
Multi-Threading<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++ libraries are not completely thread-safe.<br />
That is, they do not have critical sections, or semaphores, to prevent two<br />
threads from updating the same instance of an object. However, the classes do<br />
not share data, so they can be used in a well designed, multi-threaded,<br />
program. The normal technique is for each thread to have its own instance of<br />
lightweight objects, such as CclConn, CclFlow, CclBuf.<br />
Handling Exceptions<br />
Most class methods could generate an exception. The default exception<br />
handler is found in the handleException method in the CclECI and CclEPI<br />
classes. It is a simple routine which does a C++ throw of a CclException<br />
object. It does not perform any action if an exception occurs within the<br />
destruction of an object. You must not do a throw within a destructor as this<br />
causes unpredictable results.<br />
This routine is suitable for most needs when using synchronisation modes of<br />
dsync and sync. For example:<br />
Chapter 6. Programming in C++ 47
Handling Exceptions<br />
#include <br />
#include <br />
void main(void) {<br />
CclECI *eci;<br />
eci = CclECI::instance();<br />
CclFlow flow(Ccl::sync);<br />
CclBuf buf;<br />
CclConn conn("<strong>CICS</strong>OS2","SYSAD","SYSAD");<br />
buf.setDataLength(80);<br />
try {<br />
conn.link(flow,"EC01",&buf);<br />
cout
Once you have subclassed the ECI Class, you still can only create one object<br />
of this class for your application, however do not use the instance method,<br />
you must create the object either explicitly e.g.<br />
MyCclECI myeci;<br />
or by using the new operator<br />
MyCclECI *pmyeci;<br />
pmyeci = new MyCclECI;<br />
Handling Exceptions<br />
External call interface<br />
The ECI is one of two interfaces through which a non-<strong>CICS</strong> client program<br />
can interact with a <strong>CICS</strong> server. The ECI object model consists of a set of<br />
classes which give access to the features of the ECI and supports an<br />
object-oriented approach to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> programming with the<br />
ECI. The following classes are included:<br />
Table 4. C++ ECI classes.<br />
Object Classname Description<br />
Global Ccl Contains global enumerations<br />
Buffer CclBuf Used for exchanging data with a server<br />
Connection CclConn Models the connection to a server<br />
ECI CclECI Controls and lists access to <strong>CICS</strong> servers<br />
Exception CclException Encapsulates exception information<br />
Flow CclFlow Handles a single client/server interaction<br />
SecAttr CclSecAttr Provides information about security<br />
attributes (passwords)<br />
SecTime CclSecTime Provides date and time information<br />
UOW CclUOW Corresponds with a Unit of Work in the<br />
server—used for managing updates to<br />
recoverable resources.<br />
Using COMMAREAs<br />
A COMMAREA is a block of storage allocated by the program. The client<br />
program uses the COMMAREA to send data to the server and the server uses<br />
the same storage to return data to the client. Therefore, you must create a<br />
COMMAREA that is large enough to contain all the information to be sent to<br />
the server and large enough to contain all the information that can be<br />
returned from the server.<br />
Chapter 6. Programming in C++ 49
External call interface<br />
For example, you need to send a 12 byte serial number to the server, but you<br />
may receive 20 Kb back from the server. You must create a COMMAREA of<br />
size 20 Kb. Your code would look like this:<br />
// serialNo is a Null terminated string<br />
CclBuf Commarea; // create extensible buffer object<br />
Commarea.assign(strlen(serialNo),serialNo); // Won’t include the Null<br />
Commarea.setDataLength(20480); // stores Nulls in the unused area<br />
In the example, the serial number is stored in the new Commarea which is then<br />
increased in size to 20480. The extra bytes are filled with nulls. This is<br />
important as it ensures that the information transmitted to the server is kept<br />
to a minimum. The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> software strips off the excess<br />
nulls and transmits 12 bytes to the server.<br />
Finding potential servers<br />
Information about the <strong>CICS</strong> servers that can be used by a client program is<br />
defined in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration file. See Configuration<br />
in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration book for your operating<br />
system, for more information. The existence of such a definition doesn’t<br />
guarantee availability of a server.<br />
The ECI object CclECI provides access to this server information through its<br />
serverCount, serverDesc, and serverName methods.<br />
Unless the ECI class has been subclassed, its unique instance is found using<br />
the class method instance as in the following example:<br />
CclECI* pECI = CclECI::instance();<br />
printf( "Server Count = %d\n", pECI-> serverCount() );<br />
printf( "Server1 Name = %s\n", pECI-> serverName( 1 ) );<br />
...<br />
Typical output produced:<br />
Server Count = 2<br />
Server1 Name = DEVTSERV<br />
Server connection<br />
A client program requires one connection object, CclConn, for each <strong>CICS</strong><br />
server with which it will interact. When a connection object is created,<br />
optional data can be specified which includes:<br />
v The name of the server to be connected. This must be one of the server<br />
names defined in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration file. If this<br />
name is omitted, the default server will be used.<br />
v A user ID. Some servers might require that a client application provides a<br />
user ID and password before they permit specific interactions.<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
v A password.<br />
In this example, a connection object is created with a server name, user ID<br />
and password:<br />
CclConn serv2( "Server2","sysad","sysad" );<br />
External call interface<br />
Creating a connection object does not, in itself, cause any interaction with the<br />
server. The information in the connection object is used when one of the<br />
following server request calls is issued:<br />
link—to request the execution of a server program.<br />
status—to request the status (availability) of the server.<br />
changed—to request the notification of any change in this status.<br />
cancel—to request the cancellation of a changed request.<br />
These are methods of the connection class. There are two other server request<br />
calls; the backout and commit methods of the unit of work class. More<br />
information on the use of all these methods can be found in following<br />
sections.<br />
Monitoring server availability<br />
The connection object CclConn has three methods which can be used to<br />
determine the availability of the server connection that it represents:<br />
status requests the status (that is, the availability) of the server.<br />
changed<br />
requests notification of any change in this status.<br />
cancel<br />
requests cancellation of a changed request.<br />
The example described below shows how server availability can be monitored<br />
in a client program that is busy doing something else.<br />
Here is a subclass of the flow class designed for use with server status calls.<br />
The reply handler implementation prints the server name and its<br />
newly-changed status; it ignores the returned communication area. Next, it<br />
issues a changed server request so that the next server status change will be<br />
received. The reply handler will be called every time the availability of the<br />
server changes.<br />
Chapter 6. Programming in C++ 51
External call interface<br />
class ChgFlow : public CclFlow {<br />
public:<br />
ChgFlow( Ccl::Sync stype ) : CclFlow( stype ) {}<br />
void handleReply( CclBuf* ) {<br />
CclConn* ccon = connection();<br />
cout serverName()
In the next example, an existing memory structure is used. This could, for<br />
example, correspond to a record used in the server program. In this case, the<br />
buffer object knows the record is fixed-length, externally-defined, and ensures<br />
it can not be extended in any subsequent processing. The link call requests<br />
execution of the program QVALUE on the <strong>CICS</strong> server defined by the serv2<br />
connection object and passes data via the structure on which the buffer object<br />
comma2 is overlaid.<br />
struct rec{<br />
short key;<br />
char name[8];<br />
char retval[70];<br />
};<br />
rec record1 = { 1234,"Hilary" };<br />
CclBuf comma2( sizeof(rec),&record1 );<br />
serv2.link( sflow,"QVALUE",&comma2 );<br />
...<br />
The communications area returned from a server is also contained in a buffer<br />
object.<br />
Controlling server interactions<br />
A flow object—CclFlow—controls each interaction between the client program<br />
and a server and determines the synchronization of reply processing;<br />
synchronous, deferred synchronous or asynchronous. This example creates a<br />
synchronous flow object:<br />
CclFlow sflow( Ccl::sync );<br />
External call interface<br />
A flow object is referenced when a server request call is first issued and<br />
remains active from that time until all client processing of the corresponding<br />
reply from the server has been completed. At that point it is set inactive and<br />
becomes available for reuse or deletion. During its active lifespan, a flow<br />
object maintains the state of the client/server interaction it is controlling.<br />
The flow class should be subclassed to provide the implementation of a reply<br />
handler which will be called when a reply is received; this happens regardless<br />
of the synchronization type. The reply handler is passed a buffer object which<br />
contains the communication area returned by the server. A default reply<br />
handler is provided; it just returns to the caller without doing anything.<br />
Separate flow subclasses could be needed to cater for different client/server<br />
communication area protocols. Many flows may be active at the same time.<br />
Many servers may be used simultaneously by the same <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or <strong>CICS</strong> Universal Client.<br />
Chapter 6. Programming in C++ 53
External call interface<br />
Synchronous reply handling<br />
In the synchronous model, the client remains blocked at the server request call<br />
until a reply is eventually received from the server.<br />
The example program in Figure 10 calls a server program using parameters<br />
supplied on the command line. It does no subclassing to handle exceptions or<br />
to handle the reply from the server.<br />
...<br />
CclECI* pECI = CclECI::instance();<br />
CclConn server1( argv[1],argv[2],argv[3] );<br />
CclBuf comma1( argv[4] );<br />
CclFlow sflow( Ccl::sync );<br />
server1.link( sflow,"ECIWTO",&comma1 );<br />
Figure 10.<br />
The program gains access to the ECI object and constructs a connection object<br />
using the supplied server name, password and user ID. Then a buffer object is<br />
constructed using text from the command line and a synchronous flow object<br />
is created.<br />
The link call requests execution of the <strong>CICS</strong> ECIWTO sample program on the<br />
server and passes text to it in the buffer. Processing is then blocked until a<br />
reply is received from the server. ECIWTO just writes the communication area<br />
to the operator console on the server and returns it, unchanged, to the client.<br />
After the reply is received, the program reports the most recent exception<br />
code and prints the returned communication area:<br />
cout
Asynchronous reply handling<br />
In the asynchronous model, the client program issues a server request call and<br />
then continues immediately with the next statement without waiting for a<br />
reply. As soon as the reply is received from the server it is immediately<br />
passed to the reply handler of the flow object controlling the interaction; in<br />
parallel with whatever else the client happens to be doing.<br />
The example program in Figure 11 calls a server program using parameters<br />
supplied on the command line. It subclasses the ECI class to handle<br />
exceptions and subclasses the flow class to handle the reply from the server.<br />
Here is a simple subclass of the flow class with a reply handler<br />
implementation which just prints the reply received:<br />
class MyCclFlow : public CclFlow {<br />
public:<br />
MyCclFlow( Ccl::Sync sync ) : CclFlow( sync ) {}<br />
void handleReply( CclBuf* pcomm ){<br />
cout
External call interface<br />
Meanwhile, when the reply does come back from the server, the reply handler<br />
is called and, assuming there are no exceptions, prints the returned<br />
communication area. Note that in the asynchronous model, the buffer object<br />
to hold the returned communication area is allocated internally within the<br />
flow object, and is deleted after the reply handler has run. The buffer object<br />
supplied on the original link call is not used for the reply, and can be deleted<br />
as soon as the link call returns.<br />
If you call the program in Figure 11 on page 55 like this:<br />
ecicpo2 DEVTSERV sysad sysad "Hello World"<br />
the following output is expected on successful completion:<br />
Server call in progress. Enter q to quit...<br />
Reply from <strong>CICS</strong> server: Hello World<br />
q<br />
If the client program decides at some point that it really can do no more until<br />
a reply is received from the server, it can use the wait method on the<br />
appropriate flow object. This effectively makes the interaction synchronous,<br />
blocking the client:<br />
asflow.wait();<br />
Deferred synchronous reply handling<br />
In the deferred synchronous model, the client program issues a server request<br />
call and then continues immediately with the next statement without waiting<br />
for a reply. Unlike the asynchronous case, where a server reply is handled<br />
immediately it arrives, the client decides when it wants to poll for a reply.<br />
When a poll is issued, the flow object checks whether there is, in fact, a reply<br />
from the original server request. If there is, the flow object’s reply handler is<br />
called synchronously and is passed the returned communication area in a<br />
buffer object. Poll returns a value to its caller indicating whether the reply<br />
was received or not; if not it can try again later.<br />
The same simple subclass of the flow class described above is used. There are<br />
some small changes to the main program to indicate deferred synchronous<br />
reply handling:<br />
...<br />
MyCclECI myeci;<br />
CclConn server1( argv[1],argv[2],argv[3] );<br />
CclBuf comma1( argv[4] );<br />
MyCclFlow dsflow( Ccl::dsync );<br />
server1.link( dsflow,"ECIWTO",&comma1 );<br />
...<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
For demonstration purposes, the program is now made to loop with a delay<br />
until poll indicates the reply has been received from the server. Note that in<br />
the deferred synchronous model, a buffer object to hold the returned<br />
communication area can be supplied as a parameter to the poll method. If, as<br />
in the example below, no buffer object is supplied on the poll method, one is<br />
allocated internally within the flow object, and is deleted after the reply<br />
handler has run.<br />
...<br />
Ccl::Bool reply = Ccl::no;<br />
while ( reply == Ccl::no ) {<br />
cout
External call interface<br />
of work have successfully completed, the unit of work can be committed by<br />
the commit method of the unit of work object or backed out by backout:<br />
serv1.link( sflow, "ECITSQ", &( comma1="1st link in UOW" ), &uow );<br />
serv1.link( sflow, "ECITSQ", &( comma1="2nd link in UOW" ), &uow );<br />
...<br />
uow.backout( sflow );<br />
If no UOW object is used, each link call becomes a complete unit of work<br />
(equivalent to LINK SYNCONRETURN in the <strong>CICS</strong> server).<br />
Whenever using logical units of work, you must ensure that you backout or<br />
commit active units of work, especially at program termination. You can check<br />
to see if a logical unit of work is still active by checking the uowId method of<br />
the CclUOW class for a non zero value.<br />
Security Management for ECI<br />
You can perform security management on servers that support Password<br />
Expiry Management (PEM). See Supported software in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Administration book for your operating system, for more information<br />
on supported servers and protocols.<br />
To use these features you first must have constructed a Connection object. The<br />
two methods available are verifyPassword which checks the userid and<br />
password within the connection object with the Server Security System, and<br />
changePassword which allows you to change the password at the server. If<br />
successful the connection object password is updated accordingly.<br />
If either call is successful, you are returned a pointer to an internal object<br />
which provides information about the security, a CclSecAttr object. This object<br />
provides access to information such as last verified Date and Time, Expiry<br />
Date and Time and Last access Date and Time. If you query for example last<br />
verified Date, you get back a pointer to an object which allows you to get the<br />
information in various formats. The following is a sample of code to show the<br />
use of these various objects:<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Connection object already created called conn<br />
CclSecAttr *pAttrblock; // pointer to security attributes<br />
CclSecTime *pDTinfo; // pointer to Date/Time information<br />
try {<br />
pAttrblock = conn->verifyPassword();<br />
pDTinfo = pAttrblock->lastVerifiedTime();<br />
cout
|<br />
|<br />
C++ External presentation interface<br />
1. General purpose C++ classes for handling 3270 datastream, such as fields<br />
and attributes, and <strong>CICS</strong> transaction routing data, such as transaction ID.<br />
2. Generation of C++ classes for specific <strong>CICS</strong> applications from BMS map<br />
source files. These classes allow client applications to access data on 3270<br />
panels, using the same field names as used in the <strong>CICS</strong> server BMS<br />
application.<br />
Note: These classes do not contain any specific support for 3270 datastreams<br />
that contain DBCS fields. However they do not support 3270<br />
datastreams that contain mixed SBCS and DBCS fields.<br />
The BMS utility is a tool for statically producing C++ class source code<br />
definitions and implementations from a <strong>CICS</strong> BMS mapset.<br />
The following table describes the supplied classes. For full details of the<br />
methods each class provides, refer to the C++ chapter, in <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Reference.<br />
Table 5. C++ EPI classes.<br />
Object Classname Description<br />
Global Ccl Contains global enumerations.<br />
EPI CclEPI Initializes the EPI. This class also has<br />
methods that obtain information on <strong>CICS</strong><br />
servers accessible to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Exception CclException Encapsulates error information.<br />
Field CclField Supports a single field on a virtual screen<br />
and provides access to field text and<br />
attributes.<br />
Map CclMap This class provides access to CclField<br />
objects, using BMS map information. The<br />
<strong>CICS</strong>BMSC utility generates classes derived<br />
from CclMap.<br />
Screen CclScreen<br />
See note on page 61 for BMS support on<br />
Linux.<br />
Each terminal (CclTerminal object) has a<br />
virtual screen associated with it. The<br />
CclScreen class contains a collection of<br />
CclField objects and methods to access these<br />
objects. It also has methods for general<br />
screen handling.<br />
SecAttr CclSecAttr Provides information about security<br />
attributes (passwords)<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
C++ External presentation interface<br />
Table 5. C++ EPI classes. (continued)<br />
Object Classname Description<br />
SecTime CclSecTime Provides date and time information<br />
Session CclSession Controls communication with the server in<br />
synchronous, asynchronous and deferred<br />
synchronous modes.<br />
Terminal CclTerminal<br />
Applications can use CclSession to derive<br />
their own classes to encapsulate specific<br />
<strong>CICS</strong> transactions.<br />
Controls a 3270 terminal connection to <strong>CICS</strong>.<br />
The CclTerminal class handles <strong>CICS</strong><br />
conversational, pseudo-conversational, and<br />
ATI transactions. One application can create<br />
many CclTerminal objects.<br />
Linux<br />
Note: <strong>CICS</strong>BMSC is not provided with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for the<br />
Linux operating system.<br />
End of Linux<br />
Support for Automatic <strong>Transaction</strong> Initiation (ATI)<br />
The <strong>CICS</strong> server API call EXEC <strong>CICS</strong> START allows a server program to start<br />
a transaction on a particular terminal. This mechanism, called Automatic<br />
<strong>Transaction</strong> Initiation (ATI), requires additional programming at the client side<br />
to handle the interaction between these transactions and normal<br />
client-initiated transactions.<br />
Firstly, client applications can control whether ATI transactions are allowed by<br />
using the setATI() and queryATI() methods on the CclTerminal class.The<br />
default setting is for ATIs to be disabled. The following code fragment shows<br />
how to enabled ATIs for a particular terminal:<br />
// Create terminal connection to <strong>CICS</strong> server<br />
CclTerminal terminal( "myserver" );<br />
// Enable ATIs<br />
terminal.setATI(CclTerminal::enabled);<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> queues ATIs for a terminal while a transaction<br />
is in progress. The CclTerminal class will perform one of more of the<br />
following<br />
v run any outstanding ATIs as soon as a transaction ends<br />
v call Additional programming needed to handle the ATI replies<br />
Chapter 6. Programming in C++ 61
C++ External presentation interface<br />
v run ATIs before or between client-initiated transactions<br />
depending on whether the call synchronisation type is Synchronous,<br />
Asynchronous or Deferred synchronous.<br />
Synchronous When you call the CclTerminal send() method, any<br />
outstanding ATIs will be run after the client-initiated<br />
transaction has completed. The CclTerminal class will wait for<br />
the ATI replies then update the CclScreen contents as part of<br />
the synchronous send() call. If you expect an ATI to occur<br />
before or between client-initiated transactions, you can call the<br />
CclTerminal receiveATI() method to wait synchronously for<br />
the ATI.<br />
Asynchronous When the client application calls the CclTerminal send()<br />
method for an async session, the CclTerminal class starts a<br />
separate thread to handle replies. If ATIs are disabled, this<br />
thread finishes when the <strong>CICS</strong> transaction is complete. If ATIs<br />
are enabled, the reply thread continues to run between<br />
transactions. When the CclTerminal state becomes idle, any<br />
outstanding ATIs are run and ATIs received subsequently are<br />
run immediately. The reply thread is not started until the first<br />
CclTerminal::send() call, so if you expect ATIs to occur<br />
before any client-initiated transactions, you can call the<br />
receiveATI() method to start the reply thread.<br />
Deferred synchronous<br />
After the CclTerminal send() method is called for a dsync<br />
session, the poll() method is used to receive the replies.<br />
Outstanding ATIs are started when the last reply has been<br />
received (i.e. on the final poll() call). You can also call the<br />
poll() method to start and receive replies for ATIs between<br />
client-initiated transactions. As the poll() method can be called<br />
before or between client-initiated transactions, the receiveATI()<br />
method is not needed (and is invalid) for deferred<br />
synchronous sessions. For any of the synchronisation types<br />
you can provide a handleReply() method by subclassing the<br />
CclSession class. As for client-initiated transactions, this<br />
method will be called when the ATI 3270 data has been<br />
received and the CclScreen object updated. The transID()<br />
method on the CclTerminal or CclSession can be called to<br />
identify the ATI.<br />
Starting a 3270 terminal connection to <strong>CICS</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI must be initialized, by creating a CclEPI<br />
object, before a terminal connection can be made to <strong>CICS</strong>. The CclEPI object,<br />
like the CclECI object, also provides access to information about <strong>CICS</strong> servers<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
C++ External presentation interface<br />
which have been configured in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> configuration<br />
file. The following C++ sample shows the use of the CclEPI object:<br />
#include // <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI headers<br />
...<br />
CclEPI epi; // Initialize <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI<br />
// List all <strong>CICS</strong> servers in <strong>Gateway</strong> initialization file<br />
for ( int i=1; i
C++ External presentation interface<br />
// Get access to the CclScreen object<br />
CclScreen* screen = terminal.screen();<br />
for ( int i=1; i ≤ screen->fieldCount(); i++ ) {<br />
CclField* field = screen->field(i); // get field by index<br />
if ( field->textLength > 0 )<br />
cout field(i); // get field by index<br />
// Find unprotected (i.e. input) fields<br />
if ( field->inputProt() == CclField::unprotect )<br />
...<br />
// Find fields containing a specific text string<br />
if ( strstr(field->text(), "<strong>CICS</strong> Sign-on") )<br />
...<br />
// Find red fields<br />
if ( field->foregroundColor() == CclField::red )<br />
...<br />
}<br />
Note that the string “Sign-on” in the above sample may need to be changed<br />
to meet local conventions. For example, an AIX server may use the string<br />
“SIGNON”.<br />
EPI call synchronization types<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI C++ classes support synchronous<br />
(“blocking”), and deferred synchronous (“polling”) and asynchronous<br />
(“callback”) protocols.<br />
In the example above the CclSession object is created with the synchronization<br />
type of Ccl::sync. When this CclSession object is passed as the first parameter<br />
on a CclTerminal send method, a synchronous call is made to <strong>CICS</strong>. The C++<br />
program is then blocked until the reply was received from <strong>CICS</strong>. When the<br />
reply is received, updates are made to the CclScreen object according to the<br />
3270 datastream received, then control is returned to the C++ program.<br />
To make asynchronous calls the CclSession object used on the CclTerminal<br />
send method is created with a synchronization type of Ccl::async. The call is<br />
made to <strong>CICS</strong> using the CclTerminal send method, but control returns<br />
immediately to the client application without waiting for a reply from <strong>CICS</strong>.<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
C++ External presentation interface<br />
The CclTerminal object starts a separate thread which waits for the reply from<br />
<strong>CICS</strong>. When a reply is received, the handleReply method on the CclSession<br />
object is invoked. To process the reply, the handleReply method should be<br />
overridden in a CclSession subclass:<br />
class MySession : public CclSession {<br />
public:<br />
MySession(Ccl::Sync protocol) : CclSession( protocol ) {}<br />
// Override reply handler method<br />
void handleReply( State state, CclScreen* screen );<br />
};<br />
The implementation of the handleReply method can process the screen data<br />
available in the CclScreen object, which will have been updated in line with<br />
the 3270 datastream sent from <strong>CICS</strong>:<br />
void MySession::handleReply( State state, CclScreen* screen ) {<br />
// Check the state of the session<br />
switch( state ) {<br />
case CclSession::client:<br />
case CclSession::idle:<br />
// Output data from the screen<br />
for ( int i=1; i < screen->fieldCount(); i++ ) {<br />
cout
C++ External presentation interface<br />
Most client applications will want to wait until the <strong>CICS</strong> server program has<br />
finished sending data (that is, the CclSession/CclTerminal state is client or<br />
idle) before processing the screen. However, some long-running server<br />
programs may send intermediate results or progress information that can<br />
usefully be accessed while the state is still server.<br />
The implementation of the handleReply method can read and process data<br />
from the CclScreen object, update fields as required, and set the cursor<br />
position and AID key in preparation for the return transmission to <strong>CICS</strong>. The<br />
application main program should invoke further methods (send or<br />
disconnect) ontheCclTerminal object to drive the server application:<br />
try {<br />
// Connect to <strong>CICS</strong> server<br />
CclTerminal terminal( "<strong>CICS</strong>1234" );<br />
// Create asynchronous session<br />
MySession session(Ccl::async);<br />
// Start CESN transaction on <strong>CICS</strong> server<br />
terminal.send( &session, "CESN" );<br />
// Replies processed asynchronously in overridden<br />
// handleReply method<br />
...<br />
} catch ( CclException &exception ) {<br />
cout
C++ External presentation interface<br />
try {<br />
// Connect to <strong>CICS</strong> server<br />
CclTerminal terminal( "<strong>CICS</strong>1234" );<br />
// Create deferred synchronous session<br />
MySession session(Ccl::dsync);<br />
// Start CESN transaction on <strong>CICS</strong> server<br />
terminal.send( &session, "CESN" );<br />
...<br />
if ( terminal.poll())<br />
// reply processed in handleReply method<br />
else<br />
// no reply received yet<br />
} catch ( CclException &exception ) {<br />
cout
|<br />
|<br />
C++ External presentation interface<br />
Client Application BMS Mapsets<br />
<strong>CICS</strong> Map Classes<br />
<strong>CICS</strong> EPI Classes<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Figure 12. Use of BMS map classes<br />
BMS Conversion Utility<br />
The utility generates C++ class definitions and implementations that<br />
applications can use to access the map data as named fields within a map<br />
object. A class is defined for each map, allowing field names and lengths to be<br />
known at compile time. The C++ classes use the <strong>CICS</strong> EPI base classes to<br />
handle the inbound and outbound 3270 datastreams. The generated classes<br />
inherit a base class CclMap that provides general functions required by all<br />
map classes.<br />
Run the <strong>CICS</strong>BMSC utility on the BMS source as follows:<br />
<strong>CICS</strong>BMSC .BMS<br />
Linux<br />
See note on page 61 for BMS support on Linux.<br />
End of Linux<br />
Server BMS Application<br />
<strong>CICS</strong> Server<br />
The utility generates .HPP and .CPP files containing the definition and<br />
implementation of the map classes.<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Having used the EPI BMS utility to generate the map class, use the base EPI<br />
classes to reach the required 3270 screens in the usual way. Then use the map<br />
classes to access fields by their names in the BMS map. The map classes are<br />
validated against the data in the current CclScreen object.<br />
Mapset containing a single map<br />
The mapset listed in Figure 13 contains a simple map, MAPINQ1.<br />
***************************************************************<br />
* cicssda MAPINQ1 -- Wed 2 Aug 14:14:02 1995<br />
***************************************************************<br />
MAPINQ1 DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=C,STORAGE=AUTO,TIOAPFX=YES<br />
MAPINQ1 DFHMDI SIZE=(24,80),MAPATTS=(COLOR,HILIGHT,VALIDN),LINE=1, X<br />
COLUMN=1,COLOR=NEUTRAL,HILIGHT=OFF<br />
DTITLE DFHMDF POS=(2,2),LENGTH=5,ATTRB=(PROT,NORM),COLOR=TURQUOISE, X<br />
CASE=MIXED,INITIAL=’Date:’<br />
DATE DFHMDF POS=(2,9),LENGTH=8,ATTRB=(PROT,BRT),CASE=MIXED<br />
...<br />
PRODNAM DFHMDF POS=(5,24),LENGTH=40,ATTRB=(PROT,BRT),CASE=MIXED<br />
...<br />
APPLID DFHMDF POS=(15,15),LENGTH=8,ATTRB=(PROT,BRT),CASE=MIXED<br />
...<br />
MAPINQ1 DFHMSD TYPE=FINAL<br />
Figure 13. Sample Map Class—BMS Source<br />
C++ External presentation interface<br />
The BMS Conversion Utility generates the C++ class definition (shown in<br />
Figure 14 on page 70) from this mapset. The class name “MAPINQ1Map” is<br />
derived from the map name in the BMS source. The class inherits the CclMap<br />
class.<br />
The class provides these main operations:<br />
1. The constructor MAPINQ1Map invokes the parent constructor, that<br />
validates the map object against the current screen.<br />
2. The method field provides access to fields in the map, using the BMS<br />
source field names (provided as an enumeration within the class).<br />
Chapter 6. Programming in C++ 69
C++ External presentation interface<br />
//************* <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Classes *************************************<br />
//<br />
// FILE NAME: epiinq.hpp<br />
//<br />
// DESCRIPTION: C++ header for epiinq.bms<br />
// Generated by <strong>CICS</strong> BMS Conversion Utility - <strong>Version</strong> 1.0<br />
//<br />
//***********************************************************************<br />
#include // <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI classes<br />
//-----------------------------------------------------------------------<br />
// MAPINQ1Map class declaration<br />
//----------------------------------------------------------------------class<br />
MAPINQ1Map : public CclMap {<br />
public:<br />
enum FieldName {<br />
DTITLE,<br />
DATE,<br />
...<br />
PRODNAM,<br />
...<br />
APPLID,<br />
...<br />
};<br />
//-------------- Constructors/Destructors -------------------------------<br />
MAPINQ1Map( CclScreen* screen );<br />
~MAPINQ1Map();<br />
//-------------- Actions ------------------------------------------------<br />
CclField* field( FieldName name ); // access field by name<br />
...<br />
}; // end class<br />
Figure 14. Sample Map Class—Generated C++ Header<br />
Using EPI BMS Map Classes<br />
The map classes generated using <strong>CICS</strong>BMSC can be compiled and built into a<br />
client application. Note that when building Windows applications using<br />
pre-compiled headers, add #include stdafx.h to the .cpp file generated by<br />
<strong>CICS</strong>BMSC.<br />
CclEPI, CclTerminal and CclSession objects are used in the normal way to<br />
start a <strong>CICS</strong> transaction:<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
try {<br />
// Initialize <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI<br />
CclEPI epi;<br />
// Connect to <strong>CICS</strong> server<br />
CclTerminal terminal( "<strong>CICS</strong>1234" );<br />
// Start transaction on <strong>CICS</strong> server<br />
CclSession session( Ccl::sync );<br />
terminal.send( &session, "EPIC" );<br />
C++ External presentation interface<br />
In this example the server program uses a BMS map for its first panel, for<br />
which a map class “MAPINQ1Map” has been generated. When the map<br />
object is created, the constructor validates the screen contents with the fields<br />
defined in the map. If validation is successful, fields can then be accessed<br />
using their BMS field names instead of by index or position from the<br />
CclScreen object:<br />
MAPINQ1Map map( terminal.screen() );<br />
CclField* field;<br />
// Output text from "PRODNAM" field<br />
field = map.field(MAPINQ1Map::PRODNAM);<br />
cout
C++ External presentation interface<br />
If either call is successful, you are returned a pointer to an internal object<br />
which provides information about the security, a CclSecAttr object. This object<br />
provides access to information such as last verified Date and Time, Expiry<br />
Date and Time and Last access Date and Time. If you query for example last<br />
verified Date, you get back a pointer to an object which allows you to get the<br />
information in various formats. The following is sample code to show the use<br />
of these various objects.<br />
// Terminal object already created called term<br />
CclSecAttr *pAttrblock; // pointer to security attributes<br />
CclSecTime *pDTinfo; // pointer to Date/Time information<br />
try {<br />
pAttrblock = term->verifyPassword();<br />
pDTinfo = pAttrblock->lastVerifiedTime();<br />
cout
|<br />
|<br />
|<br />
Chapter 7. Programming in Java<br />
Overview of the programming interface for Java<br />
This chapter introduces the classes, interfaces, and beans, that make up the<br />
public programming interface of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v Classes for writing Java client programs<br />
– com.ibm.ctg.client.Java<strong>Gateway</strong><br />
– com.ibm.ctg.client.ECIRequest<br />
– com.ibm.ctg.client.EPIRequest<br />
– com.ibm.ctg.client.ESIRequest<br />
– com.ibm.ctg.client.CicsCpRequest<br />
– com.ibm.ctg.client.Callbackable (interface)<br />
For more information, see “Writing Java client programs” on page 74.<br />
v Classes for implementing security, using SSL, JSSE, and RACF ®<br />
– com.ibm.ctg.security.SSLightServerSecurity<br />
– com.ibm.ctg.security.JSSEServerSecurity<br />
– com.ibm.ctg.security.SystemSSLServerSecurity (z/OS only)<br />
– com.ibm.ctg.security.ServerSecurity<br />
– com.ibm.ctg.security.ClientSecurity<br />
– com.ibm.ctg.util.RACFUserid (z/OS only)<br />
For more information, see “<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security classes” on<br />
page 111.<br />
v EPI support classes<br />
– com.ibm.ctg.epi.AID<br />
– com.ibm.ctg.epi.EPI<strong>Gateway</strong><br />
– com.ibm.ctg.epi.Field<br />
– com.ibm.ctg.epi.FieldData<br />
– com.ibm.ctg.epi.Map<br />
– com.ibm.ctg.epi.MapData<br />
– com.ibm.ctg.epi.Screen<br />
– com.ibm.ctg.eoi.EPISecurityAttrs<br />
– com.ibm.ctg.epi.Terminal<br />
– com.ibm.ctg.epi.TerminalSession (interface)<br />
– com.ibm.ctg.epi.TerminalInterface<br />
– com.ibm.ctg.epi.Session (interface)<br />
– com.ibm.ctg.epi.EPIException, with the following subclasses:<br />
- com.ibm.ctg.epi.EPI<strong>Gateway</strong>Exception<br />
- com.ibm.ctg.epi.EPIRequestException<br />
- com.ibm.ctg.epi.EPISecurityException<br />
- com.ibm.ctg.epi.EPITxnFailedException<br />
© Copyright IBM Corp. 2002 73
Overview<br />
- com.ibm.ctg.epi.TerminalException<br />
- com.ibm.ctg.epi.EPIMapException<br />
- com.ibm.ctg.epi.EPI3270Exception<br />
- com.ibm.ctg.epi.EPIFieldException<br />
- com.ibm.ctg.epi.EPIScreenException<br />
These classes are not available for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
For more information, see “EPI support classes” on page 87.<br />
v EPI bean classes<br />
– com.ibm.ctg.epi.EPITerminal Class<br />
– com.ibm.ctg.epi.ScreenEvent Class<br />
– com.ibm.ctg.epi.ScreenEventListener interface<br />
– com.ibm.ctg.epi.ScreenHandler Class<br />
– com.ibm.ctg.epi.TerminalEvent Class<br />
– com.ibm.ctg.epi.TerminalEventListener interface<br />
These classes are not available for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
For more information, see “EPI beans” on page 101.<br />
Note: It may appear that there is a greater emphasis on EPI programming<br />
(support classes, beans) compared to ECI programming in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. This is a consequence of the nature of these<br />
interfaces. For more information on the ECI and EPI interfaces, see<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference.<br />
Online information on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> classes and interfaces is<br />
provided in the Javadoc (in HTML format).<br />
Writing Java client programs<br />
This section provides an introduction to writing Java client programs for the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides the following basic classes for<br />
writing Java client programs:<br />
com.ibm.ctg.client.Java<strong>Gateway</strong><br />
This class represents the logical connection between a program and a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. You need a Java<strong>Gateway</strong> object for each<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> that you want to talk to.<br />
com.ibm.ctg.client.ECIRequest<br />
This class contains the details of an ECI request to the <strong>Gateway</strong>. This<br />
class takes strings for various parameters. If you specify a string that<br />
is too long, the string is truncated to the maximum length.<br />
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Writing Java client programs<br />
com.ibm.ctg.client.EPIRequest<br />
This class contains the details of an EPI request to the <strong>Gateway</strong>. This<br />
class takes strings for various parameters. If you specify a string that<br />
is too long, the string is truncated to the maximum length.<br />
com.ibm.ctg.client.ESIRequest<br />
This class contains the details of an ESI request to the <strong>Gateway</strong>.<br />
com.ibm.ctg.client.CicsCpRequest<br />
This class contains the details of the codepage used by the Client<br />
daemon.<br />
com.ibm.ctg.client.Callbackable<br />
The asynchronous model supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
allows the use of callback objects. This interface defines the methods<br />
that a Callbackable object must provide.<br />
Flow of program control<br />
At the simplest level, the flow of program control needed to write a simple<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Java client program is as follows:<br />
1. The Java program creates and opens an instance of a<br />
com.ibm.ctg.client.Java<strong>Gateway</strong> object.<br />
v The default Java<strong>Gateway</strong> constructor creates a blank Java<strong>Gateway</strong><br />
object. You must then set the correct properties in this object using the<br />
relevant set methods. The Java<strong>Gateway</strong> is then opened by calling the<br />
open method.<br />
v Two other Java<strong>Gateway</strong> constructors, basic and extended, simplify the<br />
creation of a Java<strong>Gateway</strong> by setting the relevant properties. On return<br />
from a successful call to the basic constructor, the resultant Java<strong>Gateway</strong><br />
is open and connected to the requested <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
2. The Java program creates an instance of one of the <strong>Gateway</strong> request<br />
classes containing the request that it wants to make, that is:<br />
v A com.ibm.ctg.client.ECIRequest is created for an ECI request<br />
v A com.ibm.ctg.client.EPIRequest is created for an EPI request<br />
v A com.ibm.ctg.client.ESIRequest is created for an ESI request<br />
v A com.ibm.ctg.client.CicsCpRequest is created for querying the codepage<br />
of the Client daemon it is connected through.<br />
3. The Java program then flows the request to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
using the flow method of the Java<strong>Gateway</strong> object.<br />
4. The Java program checks the return code of the flow operation to see<br />
whether the request was successful.<br />
5. The program continues to create request objects and flow them through<br />
the Java<strong>Gateway</strong> object, as appropriate.<br />
6. The Java program then closes the Java<strong>Gateway</strong> object.<br />
Chapter 7. Programming in Java 75
Writing Java client programs<br />
Java<strong>Gateway</strong><br />
The Java<strong>Gateway</strong> represents a logical connection between your program and<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> when you specify a remote protocol. If you<br />
specify a local connection, you connect directly to the <strong>CICS</strong> server, bypassing<br />
any <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> servers.<br />
For example you may specify a remote <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> server by<br />
suppling a URL such as tcp://acmectg.acme.com:2006. To use the local<br />
protocol, specify a URL of local:.<br />
Protocols<br />
The Java<strong>Gateway</strong> supports the following protocols :<br />
v TCP/IP<br />
v SSL<br />
v HTTP<br />
v HTTPS (using an applet, or if your Java environment supports HTTPS. For<br />
example, JSSE provides this support.)<br />
v Local<br />
When you create a Java<strong>Gateway</strong> you determine the protocol to use, and if<br />
required, the connection details of the remote <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
server (network address and port number). With the Java<strong>Gateway</strong> class you<br />
can either specify this information using the setAddress, setProtocol and<br />
setPort methods, or you can provide all the information in URL form of<br />
Protocol://Address:Port. You can use the setURL method or pass the URL into<br />
one of the Java<strong>Gateway</strong> constructors.<br />
Java<strong>Gateway</strong> security<br />
When you connect to a remote <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, resources allocated<br />
to a particular connection, and identifiers specified on the request objects on a<br />
particular connection, are available only to that connection:<br />
ECI Requests<br />
Logical unit of work (LUW) ids and message qualifiers can only be used<br />
on the same Java<strong>Gateway</strong> that created or assigned them. This is a security<br />
feature. It stops programs that are connected to the same <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> server from manipulating the LUW ids of another application, or<br />
from using the message qualifier to request its messages. For example,<br />
attempts to get a specific reply to a message from a different Java<strong>Gateway</strong><br />
will result in an ECI_ERR_NO_REPLY return code.<br />
EPI Requests<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Writing Java client programs<br />
Terminal ids can only be used on the same Java<strong>Gateway</strong> that created the<br />
terminal. Again, this is a security feature to stop other programs that<br />
connect to the same <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> from manipulating that<br />
terminal.<br />
If you specify the local: protocol, the behavior is different. All Java<strong>Gateway</strong>s<br />
that are created in the same JVM (that is, the same process) have access to<br />
each other’s allocated resources or specified indentifiers.<br />
SSL Java<strong>Gateway</strong><br />
There are two ways to define the KeyRing or KeyStore, and password, to be<br />
used by a SSL Java<strong>Gateway</strong>:<br />
Single KeyRing or KeyStore for all SSL Java<strong>Gateway</strong>s in same JVM<br />
Invoke the static method setKeyRing(String key, String password). This<br />
defines a JVM wide KeyRing class, or KeyStore, with associated password,<br />
to use for all SSL Java<strong>Gateway</strong>s created. For example:<br />
SslJava<strong>Gateway</strong>.setKeyRing(″../keys/mykeystore.jks″, ″passphrase″);<br />
Invoke the static method getKeyRing() to determine the name of the<br />
KeyRing or KeyStore. For example<br />
String JVMWideKeyStore = SslJava<strong>Gateway</strong>.getKeyRing();<br />
Different KeyRing or KeyStore for each SSL Java<strong>Gateway</strong><br />
For each Java<strong>Gateway</strong>, for which you want a different KeyRing or<br />
KeyStore, specify a properties object that defines properties specific to the<br />
protocol used. Currently, SSL is the only protocol that has any properties<br />
defined. These properties are:<br />
Java<strong>Gateway</strong>.SSL_PROP_KEYRING_CLASS<br />
Defines the KeyRing class, or KeyStore to be used.<br />
Java<strong>Gateway</strong>.SSL_PROP_KEYRING_PW<br />
Defines the password to use for the KeyRing, or KeyStore.<br />
For an SSL Java<strong>Gateway</strong> you must specify both of these properties. If<br />
specified, these properties override the JVM wide definitions of the<br />
KeyRing or KeyStore, and password, for that SSL Java<strong>Gateway</strong>.<br />
The following example creates an SSL Java<strong>Gateway</strong> with a specific<br />
KeyStore and password:<br />
Properties sslProps = new Properties();<br />
sslProps.setProperty(Java<strong>Gateway</strong>.SSL_PROP_KEYRING_CLASS, "../keys/mykeystore.jks");<br />
sslProps.setProperty(Java<strong>Gateway</strong>.SSL_PROP_KEYRING_PW, "passphrase");<br />
Java<strong>Gateway</strong> mySslGW = new Java<strong>Gateway</strong>("ssl://mysystem.com", 8050, sslProps);<br />
Chapter 7. Programming in Java 77
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Writing Java client programs<br />
You can also use the setProtocolProperties method before invoking open<br />
on a Java<strong>Gateway</strong>. You cannot change the protocol properties when the<br />
Java<strong>Gateway</strong> is open; any attempt to do so causes an IOException to be<br />
thrown.<br />
Note: The getKeyRing() method does not return the name of the specific<br />
KeyRing or KeyStore created this way. It still returns the JVM wide<br />
settings, which could be null if the setKeyRing() method has not<br />
been called.<br />
Flowing Requests<br />
Once you have created and opened a Java<strong>Gateway</strong>, you flow requests through<br />
it. Create the appropriate request (for example, an ECIRequest) and pass it<br />
into the flow method. The request is then sent as follows:<br />
v To the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> server to be executed if you have a<br />
remote Java<strong>Gateway</strong><br />
v Direct to <strong>CICS</strong> if you are using a local Java<strong>Gateway</strong><br />
ECIRequest<br />
To make ECI type calls to <strong>CICS</strong> you need to create ECIRequest objects. For<br />
more information on these objects refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference guide.<br />
Callbacks<br />
ECIRequest supports callback objects. A callback object, which must<br />
implement the Callbackable interface, receives the results of the flow via the<br />
setResults method. Once the results have been applied, a new thread is<br />
started to execute the run method.<br />
You can specify a callback object for all ECIRequest call types (not just<br />
asynchronous call types). In the case of synchronous calls the results are<br />
passed to your Callbackable object as well as to your ECIRequest object in the<br />
flow request.<br />
Message qualifiers<br />
Message qualifiers provide a way to make an asynchronous ECI Request call,<br />
and retrieve the results later. (In an asynchronous call, the flow can continue<br />
without waiting for the results of the request.) In order to be able to retrieve<br />
those results you must tag your request call with a number. The number<br />
(known as the message qualifier) is then used to identify the results for that call.<br />
For remote <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> connections, the message qualifier must<br />
be unique within the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> server. If you attempt to<br />
make a request and provide a message qualifier value which is already in use,<br />
you will get an error message telling you that you cannot use that message<br />
qualifier. The automatic message qualifier generator feature of ECIRequest<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Writing Java client programs<br />
avoids this problem. Turn it on by invoking the method<br />
setAutoMsgQual(true) on your ECIRequest object. This will assign a message<br />
qualifier that is unique on all asynchronous requests (ECI_ASYNC,<br />
ECI_ASYNC_TPN, ECI_STATE_ASYNC, ECI_STATE_ASYNC_JAVA), when<br />
the request is flowed. The value contained in the ECIRequest after the flow<br />
can be used to retrieve the results when a call type of<br />
ECI_GET_SPECIFIC_REPLY and ECI_GET_SPECIFIC_REPLY_WAIT are used.<br />
For remote connections you cannot get replies on a different connection to the<br />
one that flowed the original request with a message qualifier; see<br />
“Java<strong>Gateway</strong>” on page 76.<br />
If you use ASYNC calls with message qualifiers, you might have to pass a<br />
userid and password when you retrieve the reply using one of the various<br />
GET_REPLY type calls. The userid and password are not used to validate<br />
whether the reply can be retrieved; they are passed to the gateway to hold in<br />
case security is required to clean up (BACKOUT) an LUW if the connection is<br />
closed or broken before the application can finish its work.<br />
For a local connection, the message qualifier should be unique for each<br />
request, although this is not enforced. Also, any connection can get a message<br />
using a message qualifier, even if the request was flowed down a different<br />
connection, provided the Java<strong>Gateway</strong>s are within the same JVM. However, it<br />
is recommended that you use the automatic message qualifier generation:<br />
v To avoid problems resulting from reusing the same message qualifier<br />
v To allow you to switch your application between local and remote<br />
connection<br />
Message qualifiers are not supported on <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS.<br />
Common Connector Framework and <strong>CICS</strong>ELUW flag<br />
If you use the ECI CCF Connector with a real Coordinator, you must set the<br />
<strong>CICS</strong>ELUW flag on the ECIInteractionSpec to TRUE. The default is TRUE. If<br />
<strong>CICS</strong>ELUW is FALSE, the ECI Resource is not registered with the Coordinator,<br />
and you cannot extend logical units of work as expected.<br />
EPIRequest<br />
To make EPI type calls to <strong>CICS</strong> you need to create EPIRequest objects. For<br />
more information on these objects, refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference. Note that <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS does not<br />
support EPIRequest objects.<br />
Using the EPIRequest class<br />
It is recommended that you use EPI beans or the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
EPI support classes if you are writing programs using the EPI. However, read<br />
this section if you intend to use the EPIRequest class.<br />
Chapter 7. Programming in Java 79
Writing Java client programs<br />
When connecting to <strong>CICS</strong> using EPI, a Java application is acting as a terminal<br />
to <strong>CICS</strong>. It is, therefore, important to be aware of the 3270 data streams that<br />
might flow from <strong>CICS</strong>, and the 3270 data streams that might be expected in<br />
reply. After an event has been returned to a Java application, the size field of<br />
the EPIRequest object indicates the size of the data array returned.<br />
It is also important to be aware of the principles and restrictions governing<br />
EPI programming, and to be aware that there might be minor differences in<br />
the working of the EPI code on different operating systems. For example, if<br />
you are running a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on Windows, you will probably<br />
need to send <strong>Transaction</strong> identifiers in the data array of the EPIRequest object,<br />
rather than in the EPIRequest object’s Transid field.<br />
When getting events from <strong>CICS</strong> it is recommended that you use the<br />
EPI_WAIT option, and ensure that the size field of the EPIRequest object is set<br />
to the maximum size of the 3270 data stream that <strong>CICS</strong> might return.<br />
Parameter lengths: When using the EPIRequest class it is important to note<br />
that the various parameters have maximum lengths. Any<br />
parameters passed exceeding these lengths will be<br />
truncated.<br />
Generally, EPI programs written using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> should:<br />
1. Open a connection to the <strong>Gateway</strong>.<br />
2. Add a terminal.<br />
3. Start a transaction.<br />
4. Get an event until either:<br />
v the event received is an end transaction or a converse<br />
v or the error received is severe<br />
5. If the event received is a converse, send the reply and return to the get<br />
event loop.<br />
6. If the event received is an end transaction, delete the terminal and do a<br />
last get event to obtain the end terminal event.<br />
7. Close the connection to the <strong>Gateway</strong>.<br />
Terminal Indexes<br />
For remote connections, terminal indexes can only be used on the connection<br />
to which they were assigned. See “Java<strong>Gateway</strong>” on page 76 for more<br />
information. For local connections, all local Java<strong>Gateway</strong>s can access terminal<br />
indexes on other local Java<strong>Gateway</strong>s, provided they are in the same JVM.<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Writing Java client programs<br />
Setting up the CLASSPATH<br />
Before you write any Java client programs, update the CLASSPATH<br />
environment variable to include the jar files supplied with <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. For example, on Windows:<br />
CLASSPATH = \classes\ctgclient.jar;<br />
\classes\ctgserver.jar<br />
The ctgserver.jar file is required in CLASSPATH only for Java<strong>Gateway</strong>s using<br />
the local URL.<br />
For more information on setting CLASSPATH, see the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Administration book for your operating system.<br />
Codepage conversion<br />
If the code page of the application is different from the code page of the<br />
server, conversion must be performed on the data in the COMMAREA. To do<br />
this, you need to make use of <strong>CICS</strong>-supplied resource conversion capabilities<br />
on the server, such as the DFHCNV macro definitions.<br />
Using a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same workstation<br />
If you intend to use a browser and <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on the same<br />
workstation, remove ctgclient.jar and ctgserver.jar from the CLASSPATH<br />
setting. If you do not remove them, you are likely to receive the following<br />
error when running applications:<br />
ERROR: java.io.IOException:<br />
CCL6664E: Unable to load relevant class to support the tcp protocol<br />
The reason for the error is that Java searches the CLASSPATH environment<br />
variable before downloading classes across the network. If the required class<br />
is local, Java attempts to use it. However, using class files from the local file<br />
system breaks Java application security rules; therefore an exception is raised.<br />
Performance issues<br />
There are several performance issues to consider when you run Java client<br />
applications. The Java Virtual Machine (JVM) allocates a fixed size of stack<br />
space for each running thread in an application. You can usually control the<br />
amount of space that Java allocates by setting limits on the following sizes:<br />
v The native stack size, allocated when running native JIT (Just-In-Time)<br />
compiled code.<br />
v The Java stack size, allocated when running Java Bytecode.<br />
v The initial Java heap size.<br />
v The maximum Java heap size.<br />
How you set these limits depends on your JVM. Refer to your Java<br />
documentation for more information.<br />
Chapter 7. Programming in Java 81
Writing Java client programs<br />
Tracing in Java client programs<br />
You can control tracing in Java client programs using:<br />
v calls to the com.ibm.ctg.client.T class<br />
For example, from within a user application:<br />
if (getParameter("trace") != null)<br />
{<br />
T.setOn(true);<br />
}<br />
where trace is a startup parameter that can be set on the user program.<br />
v <strong>Gateway</strong>.T system properties<br />
For example:<br />
java -Dgateway.T=on com.usr.smp.test.testprog1<br />
which specifies full debug for testprog1.<br />
For more information on the use of system properties, refer to your Java<br />
documentation.<br />
The following is an explanation of the various trace levels available. The<br />
names of calls and properties are case sensitive.<br />
Trace level Standard<br />
com.ibm.ctg.client.T call<br />
T.setOn (true/false)<br />
System property<br />
gateway.T.trace=on<br />
Definition The standard option for application tracing.<br />
By default, it displays only the first 128 bytes<br />
of any data blocks (for example the commarea,<br />
or network flows).<br />
This trace level is equivalent to the <strong>Gateway</strong><br />
trace set by the ctgstart –trace option.<br />
Trace level Full Debug<br />
com.ibm.ctg.client.T call<br />
T.setDebugOn (true/false)<br />
System property<br />
gateway.T=on<br />
Definition The debugging option for application tracing.<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Writing Java client programs<br />
By default, it traces out the whole of any data<br />
blocks. The trace contains more information<br />
about the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> than the<br />
standard trace level.<br />
This trace level is equivalent to the <strong>Gateway</strong><br />
debug trace set by the ctgstart –x option.<br />
Trace level Exception Stacks<br />
com.ibm.ctg.client.T call<br />
T.setStackOn (true/false)<br />
System property<br />
gateway.T.stack=on<br />
Definition The exception stack option for application<br />
tracing.<br />
It traces most Java exceptions, including<br />
exceptions which are expected during normal<br />
operation of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
No other tracing is written.<br />
This trace level is equivalent to the <strong>Gateway</strong><br />
stack trace set by the ctgstart –stack option.<br />
You can further configure the tracing by using the following options:<br />
com.ibm.ctg.client.T call<br />
T.setTFile(true,filename)<br />
System property<br />
gateway.T.setTFile=filename<br />
Option usage The value filename specifies a file location for<br />
writing of trace output. This is as an<br />
alternative to the default output on stderr.<br />
Long filenames must be surrounded by<br />
quotation marks, for example: ″trace output<br />
file.log″<br />
com.ibm.ctg.client.T call<br />
T.setTruncationSize(number)<br />
System property<br />
gateway.T.setTruncationSize=number<br />
Option usage The value number specifies the maximum size<br />
of any data blocks that will be written in the<br />
trace. Any positive integer is valid. If you<br />
specify a value of 0, then no data blocks will<br />
Chapter 7. Programming in Java 83
Writing Java client programs<br />
be written in the trace. If a negative value is<br />
assigned to this option the exception<br />
java.lang.IllegalArgumentException will be<br />
raised.<br />
com.ibm.ctg.client.T call<br />
T.setDumpOffset(number)<br />
System property<br />
gateway.T.setDumpOffset=number<br />
Option usage The value number specifies the offset from<br />
which displays of any data blocks will start. If<br />
the offset is greater than the total length of<br />
data to be displayed, an offset of 0 will be<br />
used. If a negative value is assigned to this<br />
option the exception<br />
java.lang.IllegalArgumentException will be<br />
raised.<br />
com.ibm.ctg.client.T call<br />
T.setTimingOn (true/false)<br />
System property<br />
gateway.T.timing=on<br />
Option usage Specifies whether or not to display<br />
time-stamps in the trace.<br />
Use the options in addition to one of the directives to switch tracing on.<br />
For example, the following switches standard tracing on, and sets the<br />
maximum size of any data blocks to be dumped to 20 000 bytes:<br />
java -Dgateway.T.trace=on -Dgateway.T.setTruncationSize=20000<br />
Making ECI calls on z/OS<br />
The <strong>CICS</strong> Java classes allow you to create ECIRequest objects that represent<br />
calls to the ECI.<br />
Program link calls<br />
You can create ECIRequest objects that represent requests for synchronous and<br />
asynchronous program link calls (ECI_SYNC and ECI_ASYNC call types).<br />
The following restrictions apply:<br />
v The length of the communication area (COMMAREA) passed to ECI must not<br />
exceed 32 659 bytes.<br />
v You cannot use message qualifiers, such as the variable Message_Qualifier,<br />
or the methods isAutoMsgQual(), setAutoMsgQual(),<br />
setMessageQualifier(), orsetMessageQualifier()<br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Writing Java client programs<br />
v You cannot use reply solicitation call types such as GET_REPLY,<br />
GET_REPLY_WAIT, GET_SPECIFIC_REPLY, orGET_SPECIFIC_REPLY_WAIT<br />
v If you use the ECI_ASYNC call type, you must use the callbackable<br />
interface<br />
v You cannot use the methods getECITimeout(), orsetECITimeout(). Asan<br />
alternative, set the TIMEOUT parameter in the EXCI options table<br />
DFHXCOPT. For details, see the <strong>CICS</strong> External Interfaces Guide, SC34-6006.<br />
Status information calls<br />
The ECI status information calls (ECI_STATE_SYNC and ECI_STATE_ASYNC<br />
call types) return their results in a <strong>CICS</strong> communication area. Because the<br />
contents of the communication area are platform dependent, the ECIRequest<br />
class provides help with interpreting the results of a status information call:<br />
v Public variables to hold the results of a status information call in a<br />
platform-independent manner<br />
v Two call types (ECI_STATE_SYNC_JAVA and ECI_STATE_ASYNC_JAVA)<br />
that return the results of a status information call in the public variables<br />
rather than in a communication area<br />
v Methods to interpret the contents of the public variables as strings for<br />
display<br />
Only the ECI_STATE_IMMEDIATE value for the extend mode in status<br />
information calls is supported.<br />
<strong>CICS</strong> security considerations<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS region is an EXCI user, so the<br />
following security considerations apply:<br />
v If the user ID of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS address space is<br />
the same as the user ID of the <strong>CICS</strong> address space:<br />
– LINK security checking is not performed.<br />
– Surrogate user checking is performed, so the user ID of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for z/OS address space must be authorized to use<br />
the user ID passed on the ECI call.<br />
v If the user ID of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for z/OS address space is<br />
different from the user ID of the <strong>CICS</strong> address space, LINK security checking<br />
is performed according to the setting of ATTACHSEC for the connection.<br />
The user ID passed on the ECI call is validated.<br />
v The userid and password coded on the ECIRequest object is validated with<br />
RACF ® for every EXCI call.<br />
v Userid and password authentication can be disabled for each EXCI call.<br />
This is done using the AUTH_USERID_PASSWORD environment variable<br />
in the ctgstart script. See Setting environment variables, in<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: z/OS Administration, for more information.<br />
Chapter 7. Programming in Java 85
Writing Java client programs<br />
ECI return codes and server errors on z/OS<br />
This section describes how the return codes from the EXCI are returned to the<br />
user of the ECIRequest object.<br />
Table 6 shows how EXCI return codes map to ECI return codes. The EXCI<br />
return codes are documented in the <strong>CICS</strong> External Interfaces Guide.<br />
Table 6. EXCI return codes and ECI return codes<br />
EXCI return codes ECI symbolic names/return codes rc<br />
201, 203 ECI_ERR_NO_<strong>CICS</strong> –3<br />
202 ECI_ERR_RESOURCE_SHORTAGE –16<br />
401, 402, 403, 404, 410, 411,<br />
412, 413, 418, 419, 421<br />
ECI_ERR_SYSTEM_ERROR –9<br />
422 ECI_ERR_TRANSACTION_ABEND –7<br />
423 ECI_ERR_SECURITY_ERROR –27<br />
601, 602, 603, 604, 605, 606,<br />
607, 608, 621, 622, 623, 627,<br />
628<br />
ECI_ERR_SYSTEM_ERROR –9<br />
609 ECI_ERR_SECURITY_ERROR –27<br />
624 ECI_ERR_REQUEST_TIMEOUT –5<br />
Making EPI calls on z/OS<br />
The <strong>CICS</strong> Java classes allow you to create EPIRequest objects that represent<br />
calls to the EPI. You set the public variable Call_Type in an EPIRequest object<br />
to specify which EPI call you wish to make. The results of the EPI call are<br />
returned in the object after you use the flow method of the Java<strong>Gateway</strong><br />
object.<br />
However, as you might expect, attempts to flow an EPIRequest object are<br />
rejected. The return code EPI_ERR_FAILED is returned. You should not use<br />
EPI_GetSysError to attempt to get more information. If you want to run<br />
transactions in the manner of the EPI, you should use the ECI and set up a<br />
request for DFHWBTTA. This is described in the <strong>CICS</strong> Internet guide.<br />
EXCI considerations on z/OS<br />
<strong>Version</strong> 2 of the EXCI is supported, and it provides support for eci_transid<br />
and resolves previous problems with ASCII/EBCDIC conversion.<br />
If you use EXCI <strong>Version</strong> 2 and eci_tpn is specified on the ECI request, then<br />
the definition of the user mirror transaction should now specify<br />
PROGRAM(DFHMIRS), regardless of whether the transacton is defined as<br />
local or remote.<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI support classes<br />
This chapter:<br />
v Gives an overview of the EPI support classes<br />
v Explains how to use the EPI support classes<br />
v Describes how to handle exceptions<br />
v Describes how to disconnect terminals<br />
v Describes the encoding of 3270 datastreams<br />
v Explains how to convert BMS maps and use the Map class<br />
v Describes how to use the EPIRequest class<br />
EPI support classes<br />
Overview of EPI support classes<br />
Many existing <strong>CICS</strong> server applications are written for 3270 terminal<br />
interfaces, and <strong>CICS</strong> has some powerful capabilities for dealing with these<br />
data streams, including Basic Mapping Support (BMS).<br />
The External Presentation Interface (EPI) provides a mechanism for client<br />
applications to communicate with transactions on a server and to handle 3270<br />
data streams. A client application using EPI connects to <strong>CICS</strong> as if it were a<br />
3270 terminal, and must send and receive 3270 data streams.<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI support classes make it simpler for a Java<br />
programmer to access the facilities that the EPI provides:<br />
v Connecting 3270 sessions to <strong>CICS</strong> servers<br />
v Starting <strong>CICS</strong> transactions<br />
v Sending and receiving 3270 data streams<br />
You do not need a detailed knowledge of 3270 data streams. The classes<br />
provide higher-level constructs for handling 3270 data streams as follows:<br />
v General purpose Java classes for handling 3270 data streams, such as fields<br />
and attributes, and <strong>CICS</strong> transaction routing data, such as transaction ID.<br />
v Generation of Java classes for specific <strong>CICS</strong> applications from BMS map<br />
source files. These classes allow client applications to access data on 3270<br />
panels, using the same field names as used in the <strong>CICS</strong> server BMS<br />
application.<br />
Note: These classes do not contain any specific support for 3270 datastreams<br />
that contain DBCS fields. However they do not support 3270<br />
datastreams that contain mixed SBCS and DBCS fields.<br />
The BMS conversion utility is a tool for statically producing Java class source<br />
code from a <strong>CICS</strong> BMS mapset. See “Converting BMS maps and using the<br />
Map class” on page 100.<br />
Chapter 7. Programming in Java 87
EPI support classes<br />
The EPI support classes are similar to the C++ EPI classes (the objects<br />
required and the methods to manipulate them are similar).<br />
In the examples in this chapter, statements similar to the following are<br />
assumed:<br />
import com.ibm.ctg.epi.*;<br />
import java.io.*;<br />
The EPI support classes are as explained in the following, see the HTML<br />
Javadoc for a more comprehensive explanation.<br />
com.ibm.ctg.epi.AID<br />
Represents an AID (attention identifier) character to be sent to <strong>CICS</strong>.<br />
com.ibm.ctg.epi.EPI<strong>Gateway</strong><br />
Connects to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. This class also has<br />
methods that obtain information on <strong>CICS</strong> servers accessible to the<br />
client.<br />
com.ibm.ctg.epi.Field<br />
Supports a single field on a virtual screen and provides access to field<br />
text and attributes.<br />
com.ibm.ctg.epi.FieldData<br />
Contains information about a single field, that is, its row and column<br />
position and length.<br />
com.ibm.ctg.epi.Map<br />
Provides access to Field objects using BMS map information. The<br />
BMSMapConvert utility generates classes derived from Map.<br />
com.ibm.ctg.epi.MapData<br />
Contains information about a BMS map, that is, its size, number of<br />
fields, and so on.<br />
com.ibm.ctg.epi.Screen<br />
The Terminal object for a terminal has a virtual screen associated with<br />
it. The Screen class contains a collection of Field objects and methods<br />
to access these objects. It also has methods for general screen<br />
handling.<br />
com.ibm.ctg.epi.Terminal<br />
Controls a 3270 terminal connection to <strong>CICS</strong>. The Terminal class<br />
handles <strong>CICS</strong> conversational, pseudo-conversational, and ATI<br />
transactions. One application can create many Terminal objects.<br />
com.ibm.ctg.epi.TerminalInterface (interface)<br />
The Terminal class implements this interface.<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI support classes<br />
com.ibm.ctg.epi.TerminalSession (interface)<br />
Defines the behavior of a terminal in session, that is, a terminal with<br />
an associated Session object. TerminalInterface extends this with<br />
functions that allow the Session object to be changed.<br />
com.ibm.ctg.epi.Session (interface)<br />
Controls communication with the server in synchronous and<br />
asynchronous modes. Application classes can implement the Session<br />
interface to handle replies from the server.<br />
com.ibm.ctg.epi.EPIException<br />
This is the superclass to exceptions that can be thrown by the EPI<br />
support classes.<br />
com.ibm.ctg.epi.EPI<strong>Gateway</strong>Exception<br />
This exception is thrown when general problems relating to<br />
the gateway occur.<br />
com.ibm.ctg.epi.EPIRequestException<br />
This exception is thrown when problems relating to EPI<br />
Requests occur.<br />
com.ibm.ctg.epi.EPISecurityException<br />
This exception is thrown when problems relating to security<br />
requests occur.<br />
com.ibm.ctg.epi.EPITxnFailedException<br />
This exception is thrown when problems running a<br />
transaction occur.<br />
com.ibm.ctg.epi.TerminalException<br />
This exception is thrown when the Terminal class detects<br />
problems.<br />
com.ibm.ctg.epi.EPIMapException<br />
This exception is thrown by the autogenerated map classes if<br />
a map is not valid.<br />
com.ibm.ctg.epi.EPI3270Exception<br />
This exception is thrown when problems occur trying to<br />
process a 3270 datastream.<br />
com.ibm.ctg.epi.EPIFieldException<br />
This exception is thrown if problems occur interacting with<br />
field objects.<br />
com.ibm.ctg.epi.EPIScreenException<br />
This exception is thrown if problems occur interacting with<br />
screen objects.<br />
Chapter 7. Programming in Java 89
EPI support classes<br />
Using the EPI support classes<br />
This section describes how to use the EPI support classes. Examples of code<br />
are included.<br />
Establishing a terminal to <strong>CICS</strong>: The following describes how to establish a<br />
terminal to a <strong>CICS</strong> Server. For more information about EPI and terminal<br />
properties, such as Signon Capability and Read Timeouts, see <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Reference.<br />
EPI<strong>Gateway</strong>: Create a Java<strong>Gateway</strong> object (to start a connection to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>) before attempting to connect a terminal to <strong>CICS</strong>. The<br />
EPI<strong>Gateway</strong> class provides methods to access information about <strong>CICS</strong> servers<br />
that are accessible from the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and it can be used<br />
instead of the Java<strong>Gateway</strong> class.<br />
try {<br />
EPI<strong>Gateway</strong> eGate = new EPI<strong>Gateway</strong>("local:" ,0);<br />
int numSystems = eGate.serverCount();<br />
System.out.println("Number of servers:" + numSystems);<br />
for (int sysCount = 1; sysCount
EPI support classes<br />
To create a terminal using the default constructor, first instantiate a<br />
terminal, and then use the appropriate setter methods to set the required<br />
properties. Use only the setters that apply to a basic terminal. These<br />
methods are:<br />
v set<strong>Gateway</strong><br />
v setServerName<br />
v setDeviceType<br />
v setNetName<br />
v setSession<br />
All properties, with the exception of set<strong>Gateway</strong>, are optional and have a<br />
default setting of null. After you have defined your terminal, connect it to<br />
the <strong>CICS</strong> server using the connect() method. Use only this version of the<br />
connect() method. The other versions of the connect method are allowed<br />
only for an extended terminal. See “Connecting an extended terminal to<br />
<strong>CICS</strong>” on page 93 and “Synchronization and sessions” on page 94 for<br />
further information.<br />
try {<br />
EPI<strong>Gateway</strong> eGate = new EPI<strong>Gateway</strong>("tcp://My<strong>Gateway</strong>",2006);<br />
Terminal term = new Terminal();<br />
term.set<strong>Gateway</strong>(eGate);<br />
term.setServerName("<strong>CICS</strong>1");<br />
term.connect();<br />
}<br />
catch (IOException ioEx) {<br />
ioEx.printStackTrace();<br />
}<br />
catch (EPIException epiEx) {<br />
epiEx.printStackTrace();<br />
}<br />
Basic terminal constructor<br />
The second way is to use the basic terminal constructor. This sets all the<br />
required properties and automatically connects you to the <strong>CICS</strong> Server.<br />
try {<br />
EPI<strong>Gateway</strong> eGate = new EPI<strong>Gateway</strong>("tcp://My<strong>Gateway</strong>",2006);<br />
Terminal term = new Terminal(eGate, "<strong>CICS</strong>1", null, null);<br />
}<br />
catch (IOException ioEx) {<br />
ioEx.printStackTrace();<br />
}<br />
catch (EPIException epiEx) {<br />
epiEx.printStackTrace();<br />
}<br />
Exceptions: As the examples show, exceptions must be caught irrespective<br />
of which method is used to construct a basic terminal.<br />
Chapter 7. Programming in Java 91
EPI support classes<br />
The other optional setter is setSession. Sessions are discussed in<br />
“Synchronization and sessions” on page 94.<br />
Extended terminal: There are two ways to construct an extended terminal:<br />
v Using the default constructor<br />
v Using the extended terminal constructor<br />
Default terminal constructor<br />
To create a terminal using the default constructor, you first instantiate a<br />
terminal, and then use the appropriate setter methods on that object. As<br />
for the basic terminal, set<strong>Gateway</strong> is mandatory, with setDeviceType,<br />
setNetName and setServer being optional. The following setters define the<br />
properties for the extended terminal. Using any of these setters implies<br />
that you are creating an extended terminal:<br />
v setSignonCapability (Default = signon capablez)<br />
v setUserid (Default = null)<br />
v setPassword (Default = null)<br />
v setReadTimeout (Default = 0)<br />
v setEncoding (Default = null)<br />
v setInstallTimeout (Default = 0)<br />
try {<br />
EPI<strong>Gateway</strong> eGate = new EPI<strong>Gateway</strong>("tcp://My<strong>Gateway</strong>",2006);<br />
Terminal term = new Terminal();<br />
term.set<strong>Gateway</strong>(eGate);<br />
term.setServerName("<strong>CICS</strong>1");<br />
term.setSignonCapability(Terminal.EPI_SIGNON_INCAPABLE);<br />
term.setUserid(userid);<br />
term.setPassword(password);<br />
term.connect();<br />
}<br />
catch (IOException ioEx) {<br />
ioEx.printStackTrace();<br />
}<br />
catch (EPIException epiEx) {<br />
epiEx.printStackTrace();<br />
}<br />
Once you have defined your terminal, you can connect it to <strong>CICS</strong><br />
(see“Connecting an extended terminal to <strong>CICS</strong>” on page 93).<br />
Extended terminal constructor<br />
The extended terminal constructor sets all required properties at<br />
construction time:<br />
try {<br />
EPI<strong>Gateway</strong> eGate = new EPI<strong>Gateway</strong>("tcp://My<strong>Gateway</strong>",2006);<br />
Terminal term = new Terminal(eGate, "<strong>CICS</strong>1", null, null,<br />
Terminal.EPI_SIGNON_INCAPABLE, userid,<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
term.connect();<br />
}<br />
catch (IOException ioEx) {<br />
ioEx.printStackTrace();<br />
}<br />
catch (EPIException epiEx) {<br />
epiEx.printStackTrace();<br />
}<br />
password,0, null);<br />
EPI support classes<br />
Unlike the basic terminal constructor the extended terminal constructor<br />
does not automatically connect to <strong>CICS</strong>. This must be done explicitly<br />
using one of the following methods:<br />
Connecting an extended terminal to <strong>CICS</strong>: The connect methods that can be<br />
used are as follows:<br />
Connect()<br />
This method connects the terminal to <strong>CICS</strong> using the session property<br />
and install timeout property.<br />
Connect(installTimeout)<br />
This method connects the terminal to <strong>CICS</strong> using the session property,<br />
but updates the install timeout property to that supplied.<br />
Connection(Session, installTimeout)<br />
This method connects the terminal to <strong>CICS</strong>, updating the current<br />
session property with the supplied session object, and updating the<br />
install timeout property with that supplied. Sessions are discussed in<br />
“Synchronization and sessions” on page 94.<br />
Using send to start and interact with transactions: Once you have<br />
established a terminal to <strong>CICS</strong>, you use send methods to start a new<br />
transaction or to send a screen to <strong>CICS</strong>:<br />
try {<br />
term.send("EP01",null);<br />
}<br />
catch (EPIException ex) {<br />
ex.printStackTrace();<br />
}<br />
You can also build your own screen to start a transaction. Screen manipulation<br />
and fields are discussed in “Accessing fields on <strong>CICS</strong> 3270 screens” on<br />
page 94. The following shows an alternative way of starting a transaction<br />
using the Screen and Field objects:<br />
try {<br />
Screen scr = term.getScreen();<br />
Field fld = scr.field(1);<br />
fld.setText("EP01");<br />
term.send();<br />
Chapter 7. Programming in Java 93
EPI support classes<br />
}<br />
catch (EPIException ex) {<br />
ex.printStackTrace();<br />
}<br />
Accessing fields on <strong>CICS</strong> 3270 screens: When a terminal connection to <strong>CICS</strong><br />
has been established, the Terminal, Screen and Field objects are used to<br />
navigate through the screens presented by the <strong>CICS</strong> server application,<br />
reading and updating screen data as required.<br />
The Screen object is created by the Terminal object and is obtained via the<br />
getScreen method on the Terminal object. It provides methods for obtaining<br />
general information about the 3270 screen (for example, cursor position) and<br />
for accessing individual fields (by row/column, screen position or by index).<br />
The following example prints out field contents, ends the <strong>CICS</strong> transaction (by<br />
returning PF3) and disconnects the terminal:<br />
// Get access to the Screen object<br />
Screen screen = terminal.getScreen();<br />
for ( int i=1; i 0 )<br />
System.out.println( "Field " + i + ": " + field.getText() );<br />
}<br />
// Return PF3 to <strong>CICS</strong><br />
screen.setAID( AID.PF3 );<br />
terminal.send();<br />
// Disconnect the terminal from <strong>CICS</strong><br />
terminal.disconnect();<br />
The Field class provides access to the text and attributes of an individual 3270<br />
field. You can use these in a variety of ways to locate and manipulate<br />
information on a 3270 screen:<br />
for ( int i=1; i
EPI support classes<br />
blocks until all the information has been received back from the server; an<br />
asynchronous send exits from the method immediately, but still processes the<br />
replies in the background. While information is being received from the<br />
server, the Screen object is updated.<br />
To select synchronous mode, you can either specify null for the session using<br />
the setSession method, or specify a null session when invoking send.<br />
Alternatively, you can implement the session interface and specify that it is a<br />
synchronous session.<br />
To select asynchronous mode, implement the session interface and specify that<br />
it is an asynchronous session.<br />
Implementing the session interface: The session interface defines two methods<br />
that must be implemented: getSyncType and . The following code shows a<br />
sample implementation:<br />
import com.ibm.ctg.epi.*;<br />
public class myASession implements Session {<br />
public int getSyncType() {<br />
return Session.async;<br />
}<br />
public void handleReply(TerminalInterface term) {<br />
System.out.println(<br />
"Reply received Terminal state = " + term.getState());<br />
}<br />
public void handleException(TerminalInterface a, Exception e) {<br />
System.out.println("Exception received:" + e.getMessage());<br />
}<br />
}<br />
This example defines the session as an asynchronous session, because it<br />
returns Session.async on the getSyncType call. To make the session a<br />
synchronous session, you return Session.sync.<br />
The example shows two methods:<br />
handleReply<br />
You must implement the handleReply method. It is called for each<br />
transmission received from <strong>CICS</strong>. Depending on the design of the<br />
<strong>CICS</strong> server program, a Terminal send call can result in one or more<br />
replies. The Terminal state property indicates whether the server has<br />
finished sending replies:<br />
Terminal.server<br />
Indicates that the <strong>CICS</strong> server program is still running and<br />
has further data to send. The client application can process the<br />
current screen contents immediately, or simply wait for<br />
Chapter 7. Programming in Java 95
EPI support classes<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
further replies. The application cannot disconnect the terminal,<br />
or send the screen to <strong>CICS</strong>, or start a new transaction.<br />
Terminal.client<br />
Indicates that the <strong>CICS</strong> server program is now waiting for a<br />
response. The client application should process the screen<br />
contents and send a reply. The application cannot disconnect<br />
the terminal or start a new transaction.<br />
Terminal.idle<br />
Indicates that the <strong>CICS</strong> server program has completed. The<br />
client application should process the screen contents and<br />
either disconnect the terminal or start a further transaction.<br />
Terminal.failed<br />
Indicates that the transaction has failed to start or complete<br />
for some reason, for example, a conversion transaction has<br />
timed-out waiting for a response from the application. Invoke<br />
the endReason and endReasonString methods for more<br />
information.<br />
Terminal.discon<br />
Indicates that the terminal has been disconnected. Invoke the<br />
endReason and endReasonString methods for more<br />
information.<br />
Terminal.error<br />
Indicates that the terminal is in error state and cannot be<br />
used. Try to disconnect the terminal to ensure that all<br />
resources are cleaned up.<br />
Most client applications will want to wait until the <strong>CICS</strong> server<br />
program has finished sending data (that is, the Terminal state is client<br />
or idle) before processing the screen. However, some long-running<br />
server programs might send intermediate results or progress<br />
information that can usefully be accessed while the state property is<br />
still server.<br />
The implementation of the handleReply method can read and process<br />
data from the Screen object, update fields as required, set the cursor<br />
position and AID key in preparation for the return transmission to<br />
<strong>CICS</strong>, and then use the Terminal send method to drive the server<br />
application.<br />
In synchronous mode, handleReply executes on the same thread that<br />
invoked the send. In asynchronous mode, handleReply executes on a<br />
separate thread.
EPI support classes<br />
Note: The handleReply method should never attempt to disconnect a<br />
terminal. The disconnect call might make the application hang<br />
if called from handleReply.<br />
handleException<br />
The handleException method is not specified as part of the session<br />
interface and is optional. The compiler does not force implementation<br />
of the method. The Terminal class invokes this method if it is present<br />
in the Session object.<br />
You must implement the handleException method for asynchronous<br />
mode sends.<br />
It is recommended that you also implement the handleException<br />
method for synchronous mode sends with Automatic <strong>Transaction</strong><br />
Initiation (ATI) enabled.<br />
As for the method, the Terminal state property shows information<br />
about the terminal connection.<br />
Exceptions are passed in the Exception object. See “Exception<br />
handling”, for a list of the exceptions that can occur.<br />
Using your session: You can set the session on a terminal by either using the<br />
setSession method, or by passing the session object as part of a send or<br />
connect method. “null” is also accepted as a session, meaning that you have<br />
no listening object in place for replies and exceptions, and that all calls are<br />
synchronous.<br />
ATIs and Read Timeouts: ATI events and Read Timeout events are<br />
asynchronous and can occur at any time during the execution of an<br />
application, providing ATIs are enabled and a Read Timeout value was<br />
specified when creating an extended terminal. If you plan to use these<br />
features, it is recommended that you use an asynchronous session. However,<br />
these features can be used on a synchronous session; in this case, if any events<br />
occur while blocked, will run on the thread that invoked send or disconnect.<br />
If your application is not within a send or disconnect invocation, executes on<br />
a separate thread.<br />
Exception handling<br />
Exceptions can occur when interacting with a terminal. The following is the<br />
exception hierarchy.<br />
Chapter 7. Programming in Java 97
EPI support classes<br />
EPIException<br />
Figure 15. Exception hierarchy<br />
EPI3270Exception<br />
EPIRequestException<br />
EPISecurityException<br />
TerminalException<br />
EPI<strong>Gateway</strong>Exception<br />
EPITxnFailedException<br />
EPIFieldException<br />
EPIScreenException<br />
EPIMapException<br />
A description of each exception is given in “Overview of EPI support classes”<br />
on page 87.<br />
The other type of exception that can occur is IOException.<br />
The exceptions provide a field to retrieve an exception-specific error code<br />
which distinguishes the exceptions. The method is getErrorCode().<br />
If you are using either a null session or a synchronous session, and you have<br />
not enabled ATIs and are not using Read Timeouts, all exceptions are thrown<br />
on the application thread. When trying to invoke methods such as connect,<br />
send, or disconnect, wrap the call in a try/catch/finally type block.<br />
When using asynchronous sessions, a problem arises if you have ATIs, or<br />
Read Timeouts, or both, enabled. In this case, exceptions can occur while<br />
within connect/send/disconnect method invocations but also outside of these<br />
calls.<br />
If you use asynchronous sessions, exceptions cannot be thrown on any of the<br />
application threads. If you enable ATIs, or Read Timeouts, or both, it is<br />
recommended that you use asynchronous sessions.<br />
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
To know when an exception has occurred while not invoking a terminal<br />
method, you can implement the handleException method on the session (see<br />
“Synchronization and sessions” on page 94, for an example). You can<br />
implement it for both synchronous and asynchronous sessions. If the terminal<br />
is unable to throw the exception on the application thread (that is, it is not<br />
blocked on a synchronous call or it is an asynchronous session), this method<br />
is invoked on a separate thread and the exception is passed to it.<br />
Disconnecting terminals<br />
Always make sure that a terminal disconnects without any problems, and that<br />
you disconnect all terminals before your application ends. This ensures that<br />
all resources are cleaned up. There are two types of disconnect:<br />
v PurgeOnDisconnect property is set to false (the default)<br />
v PurgeOnDisconnect property is set to true<br />
Purge attempts to disconnect the terminal even if events are still outstanding<br />
or a transaction is still running. To disconnect with purge, set the property to<br />
true:<br />
term.setPurgeOnDisconnect(true);<br />
term.disconnect();<br />
After successful disconnection, you can reconnect the terminal object by<br />
issuing one of the connect() methods:<br />
term.disconnect();<br />
.....<br />
term.connect();<br />
EPI support classes<br />
Session does not apply to a disconnect call. All disconnects are considered<br />
synchronous.<br />
Extended terminal encoding property<br />
You can specify the encoding in which the resulting 3270 datastream is to be<br />
constructed. When the terminal is connected, the <strong>CICS</strong> server (providing it<br />
supports EPI <strong>Version</strong> 2) is informed of the encoding applied to the 3270<br />
datastream. If you specify null, the encoding used by the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> server is used (or the default encoding of the application if the local<br />
gateway is being used).<br />
Basic terminals always work in the encoding used by the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> server (or the default encoding of the application if the local<br />
gateway is being used).<br />
Refer to your <strong>CICS</strong> Server document for more information on supported<br />
codepages.<br />
Chapter 7. Programming in Java 99
EPI support classes<br />
Converting BMS maps and using the Map class<br />
A large proportion of existing <strong>CICS</strong> applications use BMS maps for 3270<br />
screen output. This means that the server application can use data structures<br />
corresponding to named fields in the BMS map rather than handling 3270<br />
data streams directly. The EPI BMS conversion utility uses the information in<br />
the BMS map source to generate classes specific to individual maps, which<br />
allow fields to be accessed by their names.<br />
The utility generates Java classes that applications can use to access the map<br />
data as named fields within a map object. A class is defined for each map,<br />
allowing field names and lengths to be known at compile time. The generated<br />
classes extend the class Map, which provides general functions required by all<br />
map classes.<br />
Run the BMS map converter utility on the BMS source as follows:<br />
java com.ibm.ctg.epi.BMSMapConvert -p package -name filename.BMS<br />
The utility generates .java files containing the source for the map classes. Use<br />
the -p parameter to specify the package to put the new files into. This saves<br />
you having to edit the files to add the ″package″ statement.<br />
After you have used the EPI BMS utility to generate the map class, use the<br />
base EPI classes to reach the required 3270 screens in the usual way. Then use<br />
the map classes to access fields by their names in the BMS map. The map<br />
classes are validated against the data in the current Screen object.<br />
Using Map classes: The classes generated by the BMS Conversion Utility<br />
have the following features:<br />
v The class name is derived from the map name in the BMS source.<br />
v The class extends Map.<br />
v Two constructors are provided. One constructor takes a Screen parameter<br />
and throws an EPIException, if the screen has not been produced by the<br />
relevant BMS map. The no argument constructor creates a Map that can be<br />
validated against a screen later by using the setScreen method.<br />
v The method field provides access to fields in the map, using the BMS<br />
source field names (provided as constants within the class).<br />
To use the generated Map class, create a Terminal and start a transaction as<br />
usual:<br />
try {<br />
EPI<strong>Gateway</strong> epi = new EPI<strong>Gateway</strong>("jgate", 2006 );<br />
// Connect to <strong>CICS</strong> server<br />
Terminal terminal = new Terminal( epi, "<strong>CICS</strong>1234", null, null );<br />
// Start transaction on <strong>CICS</strong> server<br />
terminal.send( null, "EPIC", null );<br />
MAPINQ1Map map = new MAPINQ1Map( terminal.getScreen() );<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
EPI support classes<br />
Field field;<br />
// Output text from "PRODNAM" field<br />
field = map.field(MAPINQ1Map.PRODNAM);<br />
System.out.println( "Product Name: " + field.getText() );<br />
// Output text from "APPLID" field<br />
field = map.field(MAPINQ1Map.APPLID);<br />
System.out.println( "Applid : " + field.getText() );<br />
} catch (Exception exception) {<br />
exception.printStackTrace();<br />
}<br />
In this example the server program uses a BMS map for its first panel, for<br />
which a map class ″MAPINQ1Map″ has been generated. When the map object<br />
is created, the constructor validates the screen contents with the fields defined<br />
in the map. If validation is successful, fields can then be accessed using their<br />
BMS field names instead of by index or position from the Screen object:<br />
BMS Map objects can also be used within the Session handleReply method.<br />
For validation to succeed, the entire BMS map must be available on the<br />
current screen. A map class cannot therefore be used when some or all of the<br />
BMS map has been overlaid by another map or by individual 3270 fields.<br />
EPI beans<br />
This section describes the beans that you can use for EPI functions.<br />
Beans provided in earlier versions of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
These beans, which previously were provided as part of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> product, are now included with the set of sample programs:<br />
v EPIMonitor<br />
v EPIScreenButtons<br />
v EPIBasicScreenHandler<br />
Include the archive \classes\ctgsamples.jar in the classpath<br />
of any programs that use these beans. The EPIBasicScreenHandler bean<br />
includes new functions, such as font and color selection, and an improved<br />
layout.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI beans Overview<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> includes high-level EPI classes to allow you to<br />
easily write Java programs that access data from existing <strong>CICS</strong> 3270<br />
applications.<br />
However, the EPI beans, based on this function, go one step further — you<br />
can create applications that access your existing <strong>CICS</strong> 3270 screens without any<br />
programming at all. Using any of the large number of new visual application<br />
builder tools, you can quickly and easily create new Java front-ends that can<br />
connect to <strong>CICS</strong>, run transactions, display data from 3270 screens, and send<br />
Chapter 7. Programming in Java 101
EPI beans<br />
user input back to the server. Note that the EPI beans do not support<br />
double-byte character set (DBCS) fields in 3270 data streams.<br />
Several visual development tools, that allow you to build Java applications<br />
with Java beans, are now available.<br />
To use the beans with a visual development tool, you may need to import or<br />
load the ctgclient.jar file into the tool. Refer to the tool’s documentation to<br />
find out how to do this. Alternatively, you may need to include this file in the<br />
CLASSPATH setting.<br />
Using the beans: Once you have loaded the beans into a suitable visual<br />
development tool, you are ready to start creating an application that uses<br />
them.<br />
Connecting to <strong>CICS</strong>: Before your application can do anything else, it must<br />
connect to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. To do this, you need an<br />
EPITerminal bean. Set the properties of the bean and specify the URL of the<br />
gateway you wish to connect to. In Figure 16 on page 103 you can see an<br />
example of what a property sheet for the bean might look like.<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Figure 16. A property sheet for the Terminal Bean<br />
EPI beans<br />
Define the terminal specific properties you require including the <strong>CICS</strong> to<br />
which you wish to connect. See Figure 17 on page 104 for an example of the<br />
terminal settings property sheet. Refer to the beans reference section for more<br />
information on the various properties. To connect to <strong>CICS</strong>, call the<br />
EPITerminal’s connect method.<br />
Chapter 7. Programming in Java 103
EPI beans<br />
Figure 17. A Terminal settings property sheet<br />
Starting a transaction: To start a transaction, you can call the EPITerminal’s<br />
startTran method, having previously set the transaction property to the<br />
transaction ID you want to start. Some tools allow you to call the<br />
set<strong>Transaction</strong> method with a defined parameter when an event occurs.<br />
Alternatively, send an ActionEvent to EPITerminal with the action command<br />
set to the transaction ID that you want to start. The transaction property is set<br />
to that value and the transaction is started as soon as possible. ActionEvents<br />
are generated by buttons, menu items and entry fields (when you select Enter<br />
- the action command is the text).<br />
Handling screens: Once you have started a transaction on the <strong>CICS</strong> server,<br />
<strong>CICS</strong> begins sending data back to the EPITerminal bean. When EPITerminal<br />
receives data from <strong>CICS</strong>, it sends a handleScreen event to all its registered<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI beans<br />
event listeners. To handle the data sent by <strong>CICS</strong>, you create beans called<br />
screen handlers and connect them to the EPITerminal’s handleScreen event.<br />
You can use one of the tools provided to generate screen handler beans<br />
automatically. The automatically-generated screen handler beans give you<br />
access to some of the data in the screen in the form of bound properties. You<br />
then create your own user interface (from other beans) to allow those<br />
properties to be displayed and changed.<br />
Sending data back to <strong>CICS</strong>: Once you have received a screen from <strong>CICS</strong> and<br />
viewed and edited it as required, you must send it back to <strong>CICS</strong> to continue<br />
processing. If you are using an automatically generated bean, then this means:<br />
v Setting the screen handlers AID property to the required AID value<br />
v Calling the send method of the screen handler or EPITerminal<br />
Another way to achieve the same result is to send an ActionEvent to the<br />
screen handler with the action command set to an AID value (for example:<br />
enter or PF3). The AID is then set to that value and the screen is sent to <strong>CICS</strong>.<br />
ActionEvents are generated by buttons, menu items, and entry fields.<br />
Disconnecting from <strong>CICS</strong>: When your application is finished, ensure that the<br />
EPITerminal’s disconnect method is called to disconnect the terminal from<br />
<strong>CICS</strong>. When disconnect is invoked, if the terminal is not in the idle state (i.e.<br />
no transactions running) EPITerminal sends the handleScreen event to its<br />
registered event listeners, requesting that they exit any running transactions.<br />
The default behaviour of the generated screen handlers is to send the AID PF3<br />
to the <strong>CICS</strong> server. If you know that this will not work for a particular<br />
transaction you are using, generate a screen handler for the relevant screen,<br />
and customise it to ensure it can exit that screen. If you have not specified<br />
purge on disconnect, then the disconnect will only occur if the transaction is<br />
ended.<br />
Example: This example demonstrates the basic principles involved in using<br />
the beans.<br />
1. Add the ctgsamples.jar file to your CLASSPATH environment variable. This<br />
provides access to the EPIBasicScreenHandler and the EPIScreenButtons<br />
beans used in this example.<br />
2. Using your preferred bean composer tool, create an EPITerminal, and look<br />
at its properties. Set the URL property to the address of the <strong>Gateway</strong>, for<br />
example: tcp://jbloggs.hursley.ibm.com:2006. The terminal settings<br />
property allows you to set further terminal settings, such as the name of<br />
your <strong>CICS</strong> server.<br />
3. Create two buttons labelled Connect and Disconnect. Connect the<br />
Connect button’s actionPerformed event to the connect method on<br />
Chapter 7. Programming in Java 105
EPI beans<br />
EPITerminal. Similarly, connect the Disconnect button to the EPITerminal’s<br />
disconnect method. You can now connect to the <strong>CICS</strong> server and<br />
disconnect again.<br />
4. Create an EPIBasicScreenHandler. This is a visual part that is able to<br />
display data sent from <strong>CICS</strong>. Connect the EPITerminal’s handleScreen<br />
event to the EPIBasicScreenHandler’s handleScreen method. Check that<br />
the event data is passed to EPIBasicScreenHandler.<br />
5. Connect the Connect button’s actionPerformed event to the startTran<br />
method on EPITerminal. Look at EPITerminal’s properties and check that<br />
the transaction property is set to a transaction that you can run on the<br />
<strong>CICS</strong> server.<br />
6. Create an EPIScreenButtons object. This is a simple set of buttons that you<br />
can use to drive the terminal. Connect the EPIScreenButtons’<br />
actionPerformed event to the EPIBasicScreenHandler’s actionPerformed<br />
method. Depending on the tool you are using, check that the event data is<br />
passed to EPIBasicScreenHandler.<br />
7. You should now be able to connect to <strong>CICS</strong> and run a transaction. The<br />
EPIBasicScreenHandler displays data sent from <strong>CICS</strong> and accepts user<br />
input. When you select one of the buttons, the screen is sent back to <strong>CICS</strong>.<br />
The screen is also sent if you select Enter while a text field has the input<br />
focus. Make sure you disconnect the terminal when you have finished<br />
with it.<br />
Generating screen handler beans: You can automatically generate screen handler<br />
beans, from BMS definition files. See “Screen Handler beans”. These screen<br />
handler beans define bound properties for each labelled field in the<br />
corresponding BMS map so that you can easily map between data from <strong>CICS</strong><br />
and user interface components.<br />
To use the generated screen handlers you connect them to the EPITerminal’s<br />
handleScreen event as above. Any number of screen handlers can be<br />
connected to an EPITerminal. When the screen handler receives a new screen<br />
from <strong>CICS</strong>, it decides whether the screen is displaying the corresponding BMS<br />
map. If it recognizes the screen, it sends the screenHandled event. It also<br />
updates its bound properties with the new data from <strong>CICS</strong>.<br />
Screen Handler beans<br />
A screen handler bean is a Java class that can:<br />
v Recognize a <strong>CICS</strong> screen<br />
v Make information from the screen available as bean properties<br />
v Exit the screen<br />
Screen handlers can be used with the EPI beans to create Java front-ends to<br />
existing <strong>CICS</strong> 3270 applications. They are also used by the <strong>CICS</strong> <strong>Transaction</strong><br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>Gateway</strong> Terminal Servlet both to exit transactions and to allow fields on the<br />
screen to be accessed by symbolic names.<br />
You do not have to write screen handler classes—they can be generated<br />
automatically from BMS map definitions.<br />
Generating screen handler beans: To generate screen handler classes, you<br />
use the BMS Map Conversion utility supplied with the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. For example, to generate beans for the screens defined by the BMS<br />
map file called test1.bms, you use the command:<br />
java com.ibm.ctg.epi.BMSMapConvert -b test1.bms<br />
The parameters you can supply to the BMS Map Conversion tool are (in any<br />
order):<br />
-b to generate screen handler beans. The default is not to generate beans.<br />
-k exit to set the key that the screen handler will use to exit the screen, for<br />
example, -k clear. The default is PF3.<br />
-p package name<br />
to generate the Java source code with the statement package package<br />
name, for example -p testing.beans. The default is not to add a<br />
package statement.<br />
BMS map definition filenames<br />
Use your platform’s standard filename conventions. Files are assumed<br />
to have the filetype .BMS if you do not give the full filename.<br />
The BMS Map Conversion tool generates two Java source files for<br />
each map defined in a BMS file:<br />
v A Map class<br />
v A ScreenHandler class<br />
The names of the source files are derived from the map name, for<br />
example, if a map called MAP1 is defined in the BMS file, then Java<br />
source files called MAP1Map.java and MAP1ScreenHandler.java<br />
would be produced.<br />
The ScreenHandler class uses the Map class, so keep these files together.<br />
EPI beans<br />
Customizing and writing Screen Handlers: Customize the generated<br />
ScreenHandler classes if:<br />
v The screen handler cannot exit the screen it is associated with simply by<br />
sending an AID, such as PF3, to <strong>CICS</strong>. In this case, you will need to change<br />
the exitScreen method to do whatever is appropriate.<br />
Chapter 7. Programming in Java 107
EPI beans<br />
v You want to change the way the screen handler recognizes the screen it is<br />
associated with. Normally, it checks that the screen contains the same fields<br />
that were defined by the BMS map.<br />
If you want to write your own screen handlers, consider the following points:<br />
v They must be Java beans. In general, this means they should have a<br />
constructor that takes no arguments, and they should implement the<br />
java.io.Serializable interface.<br />
v Generated screen handlers extend the class ScreenHandler. This is not<br />
necessary; in fact for use with the EPI beans, screen handlers need only<br />
provide a method that accepts a TerminalEvent parameter.<br />
For use with the Terminal Servlet, screen handlers should implement the<br />
TerminalEventListener interface and should use the TerminalEvent<br />
isHandled method to signal that they have recognized a screen.<br />
EPITerminal bean reference<br />
This bean acts as a 3270 terminal connected to the <strong>CICS</strong> server through the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
To use this bean:<br />
v Set the bean properties to appropriate values—you need at least to set the<br />
URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
v Connect screen handler beans to the terminal handleScreen event.<br />
v Call the connect method to make the terminal connect to <strong>CICS</strong>.<br />
v Start a transaction by setting the transaction property to the transaction ID<br />
then calling startTran.<br />
v Make sure that the terminal is disconnected before your application ends,<br />
by calling disconnect or terminate.<br />
Properties:<br />
<strong>Gateway</strong> URL<br />
The URL of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to connect to, for example:<br />
setting the URL to: tcp://buster:2006 would result in the terminal<br />
trying to connect to a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> at the TCP/IP<br />
address buster and the port number 2006.<br />
<strong>Gateway</strong> Server Security class<br />
The server security class that is used by the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. Only advanced users should modify this property.<br />
Standard terminal properties<br />
Changing any of these values while the terminal is connected to the<br />
server has no effect. You must disconnect and reconnect the terminal<br />
to use different settings.<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI beans<br />
These are the standard terminal properties:<br />
v <strong>CICS</strong> Server Name—the <strong>CICS</strong> server to connect to<br />
v Terminal Model Definition<br />
v Terminal Netname<br />
v Purge on Disconnect—set to true to force a purge rather than a<br />
standard disconnect.<br />
Extended terminal properties<br />
Changing any of these values (apart from userid and password) while<br />
the terminal is connected to the server has no effect. You must<br />
disconnect and reconnect the terminal to use different settings.<br />
These are the extended terminal properties:<br />
v Signon Capability — choose either a signon capable or signon<br />
incapable terminal. The <strong>CICS</strong> server must support the chosen<br />
option.<br />
v Read Timeout—Valid range 0—3600<br />
v Install Timeout—Vaild range 0—3600<br />
v Java encoding—The encoding to use for 3270 datastreams<br />
v Userid—A Userid to be associated with the terminal<br />
v Password—A Password to be associated with the terminal<br />
ATI enabled<br />
Set this property to true if you want to allow the <strong>CICS</strong> server to start<br />
transactions on the terminal.<br />
transaction<br />
A transaction ID. This is the transaction that is started when the<br />
method startTran is called.<br />
transactionData<br />
<strong>Transaction</strong> parameters. When startTran is called this string is passed<br />
as a parameter to the transaction, for example: if the transaction ID is<br />
CESN and the transaction data is set to USERID=fred PS=pswd then the<br />
effect of calling startTran would be the same as typing CESN<br />
USERID=fred PS=pswd at a <strong>CICS</strong> terminal.<br />
AutoDisconnectTimeout<br />
The terminal timeout interval in milliseconds. If the terminal is idle<br />
(no data received from <strong>CICS</strong>) for longer than this period, the terminal<br />
attempts to disconnect from <strong>CICS</strong>. You can set this value to 0 if you<br />
do not want the terminal to time out. You should ensure that this<br />
timeout value is less than the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> connection<br />
timeout value, otherwise the terminal may lose its connection to the<br />
<strong>Gateway</strong> without being able to disconnect from <strong>CICS</strong>.<br />
Chapter 7. Programming in Java 109
EPI beans<br />
connected<br />
This boolean value is set to true if the terminal is connected to <strong>CICS</strong>.<br />
Events:<br />
TerminalEvent<br />
terminalConnected<br />
when the terminal has connected to <strong>CICS</strong>.<br />
terminalDisconnected<br />
when the terminal has disconnected from <strong>CICS</strong>.<br />
handleScreen<br />
when the terminal receives a screen from <strong>CICS</strong>.<br />
exceptionOccurred<br />
if an exception occurs.<br />
Methods:<br />
connect()<br />
Connects the terminal to the server, if not already connected.<br />
startTran()<br />
Starts a transaction on the terminal using the transaction ID and<br />
transaction data already set.<br />
send() Sends the current screen to <strong>CICS</strong>.<br />
disconnect()<br />
Disconnects the terminal from the server. The terminal cannot<br />
disconnect from the server while a transaction is running. If a<br />
transaction is running the terminal attempts to end it before<br />
disconnecting. The terminal remains connected to the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> until the terminate method is called or the<br />
application ends.<br />
terminate()<br />
Waits for the terminal to finish disconnecting, then closes the<br />
connection to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
actionPerformed( ActionEvent e )<br />
Sets the transaction ID to the event’s action command, then calls the<br />
startTran method. Can be used to make a button push (or other<br />
ActionEvent) trigger the starting of a transaction.<br />
connect(int installTimeout)<br />
Connects the terminal to <strong>CICS</strong> if not already connected. If the terminal<br />
does not connect within the specified timeout, an exceptionOccurred<br />
event is raised.<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
Security<br />
EPI beans<br />
getTermid()<br />
Returns the current termId for a connected terminal<br />
getUserid()<br />
Returns the userid associated with the terminal<br />
getPassword()<br />
Returns the password associated with the terminal<br />
setUserid()<br />
Sets the Userid for the terminal. If it is a signon capable terminal then<br />
this userid is used for the next transaction started.<br />
setPassword()<br />
Sets the Password for the terminal. If it is a signon capable terminal<br />
then this password is used for the next transaction started.<br />
verifyPassword()<br />
If your <strong>CICS</strong> Server supports Password Expiry Management, this<br />
verifies the current userid and password associated with the terminal.<br />
It returns an EPISecurityAttrs Instance.<br />
changePassword(String newPassword)<br />
If your <strong>CICS</strong> Server supports Password Expiry Management, this<br />
changes the password associated with the terminal and at the <strong>CICS</strong><br />
Server. It returns an EPISecurityAttrs Instance.<br />
Send(String tranid, String tranData)<br />
Starts the provided transaction on the <strong>CICS</strong> Server, passing up the<br />
optional tranData.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> security classes<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> provides the following classes for implementing<br />
security:<br />
com.ibm.ctg.security.JSSEServerSecurity<br />
Use this interface to allow the exposure of of X.509 Client Certificates<br />
when using the JSSE protocol.<br />
Refer to your JSSE, or Java, documentation for information on using<br />
X.509 certificates.<br />
com.ibm.ctg.security.SSLightServerSecurity<br />
Use this interface to allow the exposure of of SSL Client Certificates<br />
when using the SSLight protocol.<br />
com.ibm.ctg.security.SystemSSLServerSecurity<br />
Use this interface to allow the exposure of of SSL Client Certificates<br />
when using the System SSL protocol.<br />
Chapter 7. Programming in Java 111
|<br />
|<br />
|<br />
|<br />
Security<br />
com.ibm.ctg.security.ServerSecurity<br />
Use this interface for server-side security classes that do not require<br />
the exposure of SSL Client Certificates.<br />
com.ibm.ctg.security.ClientSecurity<br />
Use this interface for all client-side-side security classes.<br />
com.ibm.ctg.util.RACFUserid<br />
This class tries to map an X.509 Client Certificate to a RACF userid.<br />
The certificate must already be associated with a valid RACF userid.<br />
The SSLightServerSecurity, SystemSSLServerSecurity, JSSEServerSecurity,<br />
or ServerSecurity interfaces and partner ClientSecurity interface define a<br />
simple yet flexible model for providing security when using <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>. Implementations of the interfaces can be as simple, or as robust, as<br />
necessary; from simple XOR (eXclusive-OR) scrambling to use of the Java<br />
Cryptography Architecture.<br />
The SSLightServerSecurity, SystemSSLServerSecurity, and JSSEServerSecurity<br />
interfaces have been designed to work in conjunction with the Secure Sockets<br />
Layer (SSL) protocol. The interfaces allow server-side security objects access to<br />
a Client Certificate passed during the initial SSL handshake. The exposure of<br />
the Client Certificate depends on the the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> being<br />
configured to support Client Authentication.<br />
An individual Java<strong>Gateway</strong> instance has an instance of a ClientSecurity class<br />
associated with it, until the Java<strong>Gateway</strong> is closed. Similarly, an instance of<br />
the partner SSLightServerSecurity, SystemSSLServerSecurity,<br />
JSSEServerSecurity, or ServerSecurity class is associated with the connected<br />
Java client, until the connection is closed.<br />
The basic model consists of:<br />
v An initial handshake to exchange pertinent information. For example, this<br />
handshake could involve the exchange of public keys. However, at the<br />
interface level, the flow consists of a simple byte-array, therefore an<br />
implementation has complete control over the contents of its handshake<br />
flows.<br />
v The relevant ClientSecurity instance being called to encode outbound<br />
requests, and decode inbound replies.<br />
v The partner SSLightServerSecurity, SystemSSLServerSecurity,<br />
JSSEServerSecurity, or ServerSecurity instance, being called to decode<br />
inbound requests and to encode outbound replies.<br />
The inbound request, and Client Certificate, is exposed via the<br />
afterDecode() method:<br />
– For SSLight, the afterDecode() method exposes the <strong>Gateway</strong>Request<br />
object, along with the com.ibm.sslight.SSLCert[] certificate chain object.<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
– For System SSL, the afterDecode() method exposes the <strong>Gateway</strong>Request<br />
object, along with the com.ibm.gskssl.SSLCertificate certificate object.<br />
– For JSSE, the afterDecode() method exposes the <strong>Gateway</strong>Request object,<br />
along with the javax.security.cert.X509Certificate[] certificate chain<br />
object.<br />
ClientSecurity and SSLLightServerSecurity, SystemSSLServerSecurity,<br />
JSSEServerSecurity, or ServerSecurity class instances should maintain as data<br />
members sufficient information from the initial handshake to correctly encode<br />
and decode the flows. At the server, each connected client has its own<br />
instance of the ServerSecurity implementation class.<br />
Using a Java 2 Security Manager<br />
Java 2 provides a Security Manager system that controls access to Java<br />
resources. It restricts access to Java resources by using a security policy.<br />
Examples of protected resources are: reading a file, and opening a network<br />
socket. When a program tries to access a protected resource, the Java Security<br />
Manager verifies that both the code trying to access the resource, and,<br />
possibly, the caller of that code, have appropriate permissions. Without these<br />
permissions, the program cannot run.<br />
If you are using any of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Java APIs under a Java<br />
2 security environment (such as a J2EE server), your application needs Java<br />
permissions to execute correctly. The only exception to this is if you are using<br />
the J2EE APIs in a managed environment.<br />
Figure 18 shows the minimum permissions that your application needs to use<br />
<strong>Gateway</strong> Java APIs. It might need additional permissions to execute correctly.<br />
permission java.net.SocketPermission "*", "resolve, connect";<br />
permission java.util.PropertyPermission "*", "read, write";<br />
permission java.io.FilePermission "${user.home}${file.separator}ibm${file.separator}ctg${file.separator}-",<br />
"read,write,delete";<br />
permission java.lang.RuntimePermission "loadLibrary.*";<br />
permission java.lang.RuntimePermission "shutdownHooks";<br />
permission java.lang.RuntimePermission "modifyThread";<br />
permission java.lang.RuntimePermission "modifyThreadGroup";<br />
permission java.lang.RuntimePermission "readFileDescriptor";<br />
permission java.lang.RuntimePermission "writeFileDescriptor";<br />
permission java.security.SecurityPermission "putProviderProperty.IBMJSSE";<br />
permission java.security.SecurityPermission "insertProvider.IBMJSSE";<br />
Figure 18. Required Java 2 Security Manager permissions<br />
Security<br />
Permissions to access to the file system<br />
Depending on the functions performed by your program, the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Java APIs might require access to the file system. The<br />
following permission<br />
Chapter 7. Programming in Java 113
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Security<br />
permission java.io.FilePermission "${user.home}${file.separator}ibm<br />
${file.separator}ctg${file.separator}-","read,write,delete";<br />
gives a general location for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> classes to access the file<br />
system.<br />
The format is of the permission not mandatory, and you can specify<br />
alternative locations or none at all. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> classes require<br />
access to the file system in the following cases:<br />
v For writing trace information to a file<br />
v For accessing KeyStores, if you are using JSSE for your SSL protocol<br />
implementation<br />
See Network security, inthe<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration book<br />
for your operating system, for information on how JSSE is selected as the<br />
implementation.<br />
|<br />
For example, on Windows, you can specify the permission:<br />
permission java.io.FilePermission "c:${file.separator}ibm${file.separator}ctg${file.separator}-",<br />
"read,write,delete";<br />
to allow access to the directory c:\ibm\ctg and all subdirectories.<br />
Or, for example, on UNIX, you can specify the permission:<br />
permission java.io.FilePermission "${file.separator}tmp${file.separator}ibm${file.separator}ctg${file.separator}-",<br />
"read,write,delete";<br />
to allow access to the directory /tmp/ibm/ctg and all subdirectories.<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 8. Programming using J2EE<br />
The Common Client Interface<br />
One of the main advantages of the J2EE resource adapter architecture is the<br />
Common Client Interface (CCI). The CCI provides a standard interface that<br />
allows developers to communicate with any number of Enterprise Information<br />
Systems (EISs) through their specific resource adapters, using a generic<br />
programming style. The CCI is closely modeled on the client interface used by<br />
Java Database Connectivity (JDBC ), and is similar in its idea of Connections<br />
and Interactions.<br />
Within the CCI there are two distinct types of class: framework, and<br />
input/output.<br />
Framework classes<br />
The framework is used to request a connection to an EIS such as<br />
<strong>CICS</strong>, and execute commands upon that EIS passing input and<br />
retrieving output. Examples include Connection and<br />
ConnectionFactory.<br />
Input/output classes<br />
The input/output classes are used to pass any J2EE component<br />
specific information both to the framework and the EIS. Examples are<br />
InteractionSpec and ConnectionSpec.<br />
CCI Framework Classes<br />
The aim of the framework classes is to provide a connection to an EIS for<br />
J2EE components to send and receive data. The first class you will use in<br />
developing a J2EE Component is the ConnectionFactory object, which is used<br />
to get a Connection object for the particular EIS you want to access. The<br />
Connection object is then used to create one or more Interaction objects. You<br />
execute commands on the EIS through these Interaction objects. Figure 19<br />
shows an example of executing a command on an EIS using the J2EE CCI<br />
interfaces.<br />
ConnectionFactory cf = <br />
Connection conn = cf.getConnection();<br />
Interaction int = conn.createInteraction();<br />
int.execute();<br />
int.close();<br />
conn.close();<br />
Figure 19. A run through the Framework connector classes<br />
© Copyright IBM Corp. 2002 115
CCI Framework Classes<br />
Figure 20 shows how closely this matches up to the JDBC programming<br />
model where database connections are used to create statement objects that<br />
are in turn used to execute SQL queries on a database.<br />
Connection conn = <br />
Statement stmt = conn.createStatement();<br />
String query = "SELECT * FROM A;";<br />
stmt.executeQuery(query);<br />
stmt.close();<br />
conn.close();<br />
Figure 20. The JDBC Connection model<br />
CCI Input and Output classes<br />
Using the framework classes discussed above gives a generic way of accessing<br />
an EIS via a J2EE resource adapter. Because every EIS has different input and<br />
output needs, the CCI interfaces provide a way for J2EE Components to pass<br />
EIS-specific information to a J2EE resource adapter. The following types of<br />
object are used for this purpose within a J2EE resource adapter:<br />
v InteractionSpec objects<br />
v ConnectionSpec objects<br />
v Record objects<br />
Spec objects define the action that a resource adapter will carry out, for<br />
example the name of the program to execute on <strong>CICS</strong>. Record objects simply<br />
store the input/output data to be used during the interaction, for example a<br />
byte array representing an ECI COMMAREA.<br />
Figure 21 on page 117 shows a complete run through of an interaction with an<br />
EIS including input and output Record objects and Spec objects being used to<br />
define the specific attributes of both the interaction and connection. As you<br />
can see, setters are used to define any component-specific properties on the<br />
Spec objects before they are used, thus allowing a developer to customize the<br />
behavior of a resource adapter. The following sections cover the ECI and EPI<br />
implementations of these classes in detail, including properties that can be set<br />
on the Spec objects, and supported Record types.<br />
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
ConnectionFactory cf = <br />
ECIConnectionSpec cs = new ECIConnectionSpec();<br />
cs.setXXX(); //Set any connection specific properties<br />
Connection conn = cf.getConnection( cs );<br />
Interaction int = conn.createInteraction();<br />
ECIInteractionSpec is = new ECIInteractionSpec();<br />
is.setXXX(); //Set any interaction specific properties<br />
RecordImpl in = new RecordImpl();<br />
RecordImpl out = new RecordImpl();<br />
int.execute( is, in, out );<br />
int.close();<br />
conn.close();<br />
Figure 21. Complete CCI run through.<br />
CCI Input and Output classes<br />
Connector specification API Javadoc<br />
You can obtain the connector architecture API Javadoc from the Sun Web site,<br />
this will assist in the coding of your CCI applications and provides<br />
information such as the exceptions used by CCI implementations.<br />
J2EE Connector Specification API<br />
IBM recommends that you get the J2EE Connector Specification document from<br />
Sun’s Web site at java.sun.com/j2ee/download.html, to help in coding your<br />
CCI applications. It contains information such as the exceptions used in CCI<br />
apllications.<br />
ECI resource adapter CCI<br />
The ECI resource adapter allows a J2EE developer to access <strong>CICS</strong> programs,<br />
using data areas known as COMMAREAs to pass information to and from the<br />
server. This means that you can now use the large installed base of proven<br />
applications on <strong>CICS</strong> within your J2EE Components. The CCI interfaces for<br />
<strong>CICS</strong> are in the com.ibm.connector2.cics package.<br />
ECI connection interfaces<br />
The ECI resource adapter provides implementations of the connection<br />
interfaces. Use the ECIConnectionSpec class implementation directly. Use the<br />
ConnectionFactory and Connection interfaces, rather than the ECI-specific<br />
implementations. These classes allow connections to a <strong>CICS</strong> Server using ECI.<br />
ECIConnectionSpec: This class allows the J2EE component to pass security<br />
credentials different from those defined at deployment time. You can set the<br />
credentials using the ECIConnectionSpec constructor, or with setters on a<br />
newly constructed ECIConnectionSpec. See “Security credentials and the <strong>CICS</strong><br />
Chapter 8. Programming using J2EE 117
ECI resource adapter CCI<br />
resource adapters” on page 129 for information on the precedence of security<br />
credentials. Properties supported include:<br />
UserName The userid to be used to access <strong>CICS</strong>.<br />
Password The password for the userid.<br />
So to obtain a connection you code something like this:<br />
ConnectionFactory cf = <br />
ECIConnectionSpec cs = new ECIConnectionSpec();<br />
cs.setUserName("myuser");<br />
cs.setPassword("mypass");<br />
Connection conn = cf.getConnection(cs);<br />
ECI interaction interfaces<br />
The ECI resource adapter also provides implementations of the interaction<br />
interfaces. Use the ECIInteractionSpec class implementation directly. Use the<br />
Interaction interface, rather than the ECI-specific implementation.<br />
ECIInteractionSpec: This class defines the specific properties of a call to<br />
<strong>CICS</strong> and is required as a parameter to each call to ECIInteraction.execute().<br />
The properties defined on ECIInteractionSpec are:<br />
InteractionVerb<br />
The ECI resource adapter supports both synchronous and<br />
asynchronous calls to <strong>CICS</strong>. Use this property to specify which is to<br />
be used for this interaction. Available choices are:<br />
v SYNC_SEND - An asynchronous call.<br />
v SYNC_RECEIVE - A synchronous receive. This is used to retrieve a<br />
reply from a SYNC_SEND call.<br />
v SYNC_SEND_RECEIVE - A synchronous call.<br />
Notes:<br />
1. When a SYNC_SEND call has been issued with the execute()<br />
method of a particular ECIInteraction object, that instance of<br />
ECIInteraction cannot execute another SYNC_SEND, or<br />
SYNC_SEND_RECEIVE, until a SYNC_RECEIVE has been<br />
executed.<br />
2. Simultaneous asynchronous calls to the same managed connection<br />
are permitted, provided this does not result in two asynchronous<br />
calls being outstanding within the same transaction. An exception<br />
is thrown if this happens.<br />
FunctionName<br />
When SYNC_SEND or SYNC_SEND_RECEIVE is specified in the<br />
InteractionVerb property, FunctionName needs to contain the name of<br />
the program to execute on <strong>CICS</strong>.<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
ECI resource adapter CCI<br />
ExecuteTimeout<br />
This property holds the timeout value for interactions with <strong>CICS</strong>.<br />
Possible values include:<br />
0 No timeout. This is the default value.<br />
A positive integer<br />
Time in milliseconds.<br />
ExecuteTimeout is not used on the z/OS operating system.<br />
CommareaLength<br />
The length of the COMMAREA being passed to <strong>CICS</strong> inside your<br />
input record. If this is not supplied a default is used:<br />
SYNC_SEND, SYNC_SEND_RECEIVE<br />
Length of input record data<br />
SYNC_RECEIVE<br />
The value of ReplyLength<br />
ReplyLength<br />
The amount of data you want back from <strong>CICS</strong>. This can reduce<br />
network bandwidth if the data returned by <strong>CICS</strong> is less than the<br />
entire COMMAREA, and you know the size of the data in advance.<br />
You are recommended not to set ReplyLength, so that the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> can automatically strip trailing zeros from the<br />
incoming COMMAREA, without needing to know its size in advance.<br />
Your program will still receive a full COMMAREA of the size<br />
specified in commareaLength; only the amount of data sent over the<br />
network is reduced.<br />
Automatic stripping of trailing zeros is not performed if you set<br />
ReplyLength. For more information on COMMAREA stripping, see<br />
the ECIRequest class in JavaDoc.<br />
As with ECIConnectionSpec, you can set properties on the ECIInteractionSpec<br />
class at either construction time or using setters. Unlike ECIConnectionSpec,<br />
the ECIInteractionSpec class has been designed as a Java bean. So in a<br />
managed environment, your server may provide tools to allow you to define<br />
these properties using a GUI without writing any code.<br />
ECI resource adapter input/output records using the streamable interface<br />
For input and output the ECI resource adapter supports only records that<br />
implement the javax.resource.cci.Streamable interface. This allows the ECI<br />
resource adapter to read and write streams of bytes that make up the <strong>CICS</strong><br />
COMMAREAs directly to and from the Record objects supplied to the<br />
execute() method of ECIInteraction. Figure 22 on page 120 shows how to build<br />
Chapter 8. Programming using J2EE 119
ECI resource adapter CCI<br />
a record for use as input by the ECI resource adapter using the method<br />
supplied in the javax.resource.cci.Streamable interface.<br />
Byte commarea[] = new byte[10];<br />
ByteArrayInputStream stream = new ByteArrayInputStream(commarea);<br />
Record in = new RecordImpl();<br />
in.read(stream);<br />
int.execute(..., in, ...);<br />
Figure 22. Using the streamable interface to build an input record<br />
To retrieve a byte array from the output record the reverse of the process<br />
shown in Figure 22 can be achieved by using the output records write()<br />
method using a ByteArrayOutputStream object as the parameter. The streams<br />
toByteArray() method will then provide the <strong>CICS</strong> COMMAREA output in the<br />
form of a byte array. In Figure 22 a class called RecordImpl is used as the<br />
concrete implementation class of the javax.resource.cci.Record interface. To<br />
provide more functionality for your specific J2EE components, you can write<br />
implementations of the Record interface that allow you to set the contents of<br />
the record using the constructor. This avoids the use of the<br />
ByteArrayInputStream in Figure 22. A managed environment may provide<br />
tools that allow you to build implementations of the Record interface that are<br />
customized for your J2EE components needs without writing any code.<br />
Application transaction demarcation<br />
In a managed environment transactions can be controlled by the server, or by<br />
the application itself. In a nonmanaged environment transactions have to be<br />
controlled by the application. This section discusses how to achieve this for<br />
local transactions.<br />
When carrying out multiple interactions with <strong>CICS</strong> using a deployed resource<br />
adapter you may wish to group all actions together to ensure that they either<br />
all succeed or all fail. You can use the Local<strong>Transaction</strong> interface to do this.<br />
The ECI resource adapter provides an implementation of this interface. You<br />
do not work directly with this implementation; instead you use the interface.<br />
For example:<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Connection conn = null;<br />
Interaction int = null;<br />
try {<br />
conn =(Connection)cf.getConnection();<br />
int = conn.createInteraction();<br />
ECIInteractionSpec spec = new ECIInteractionSpec(SYNC_SEND_RECEIVE, "EC01");<br />
Local<strong>Transaction</strong> tran = conn.getLocal<strong>Transaction</strong>();<br />
tran.begin();<br />
int.execute(spec, in, out);<br />
...<br />
int.execute(spec, in, out);<br />
tran.commit();<br />
}<br />
catch( ResourceException re ) {<br />
tran.rollback();<br />
}<br />
try {<br />
int.close();<br />
conn.close();<br />
}<br />
catch( ResourceException re ) {<br />
...<br />
}<br />
Figure 23. Determining whether to commit or rollback<br />
Once you have completed all the work in your transaction your J2EE<br />
component can commit the transaction if it was successful, or roll back if an<br />
error occurred and the final result is undesired. Figure 23 shows a possible<br />
method for determining whether to call commit() or rollback(). If an error<br />
occurs during a commit() call, the ECI resource adapter automatically tries to<br />
rollback the transaction on <strong>CICS</strong>, as no other action is valid once a transaction<br />
has failed to commit.<br />
Samples<br />
J2EE ECI sample programs are provided in the \samples<br />
subdirectory. Refer to the samples.txt file, in that subdirectory, for more<br />
information.<br />
EPI resource adapter CCI<br />
The <strong>CICS</strong> EPI resource adapter allows a J2EE component to communicate<br />
with <strong>CICS</strong> EPI transactions that use 3270 datastreams for input and output.<br />
The way the resource adapter achieves this is to represent a 3270 terminal<br />
with each EPIConnection object, thus providing access to the <strong>CICS</strong> 3270<br />
interface. The CCI interfaces for <strong>CICS</strong> are in the com.ibm.connector2.cics<br />
package.<br />
Note: ATIs are not supported.<br />
ECI resource adapter CCI<br />
Chapter 8. Programming using J2EE 121
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
EPI resource adapter CCI<br />
EPI connection interfaces<br />
The EPI resource adapter provides implementations of the connection<br />
interfaces. Use the EPIConnectionSpec class implementation directly. Use the<br />
ConnectionFactory and Connection interfaces, rather than the EPI-specific<br />
implementations. These classes allow connections to a <strong>CICS</strong> Server using EPI.<br />
EPIConnectionSpec: This allows the J2EE component to pass security<br />
credentials different to those defined at deployment time. You can set the<br />
credentials using the EPIConnectionSpec constructor, or with setters on a<br />
newly constructed EPIConnectionSpec. See “Security credentials and the <strong>CICS</strong><br />
resource adapters” on page 129 for information on the precedence of security<br />
credentials. Properties supported include:<br />
UserName The userid to be used to access <strong>CICS</strong>.<br />
Password The password for the userid.<br />
NetName The netname for the terminal to be used by<br />
this connection as defined within <strong>CICS</strong>.<br />
DeviceType The device type of the terminal that the<br />
EPIConnection will use.<br />
Using this class allows different components to use the same resource adapter<br />
while still using different terminals and user accounts on the <strong>CICS</strong> server.<br />
EPI interaction interfaces<br />
The EPI resource adapter also provides implementations of the interaction<br />
interfaces. Use the EPIInteractionSpec class implementation directly. Use the<br />
Interaction interface, rather than the EPI-specific implementation.<br />
EPIInteractionSpec: The EPIInteractionSpec class allows a J2EE component<br />
to define the properties of a particular interaction. Like the ECI resource<br />
adapter, an EPIInteractionSpec instance must be supplied to each call of<br />
EPIInteraction.execute(). The properties defined on EPIInteractionSpec are:<br />
InteractionVerb<br />
The EPI resource adapter supports synchronous calls to <strong>CICS</strong>.<br />
Available choices are:<br />
v SYNC_SEND - A synchronous call. It does not unblock until the EPI<br />
transaction has sent all the information that would appear on a<br />
screen.<br />
v SYNC_RECEIVE - A synchronous receive. Used to retrieve the<br />
current contents of the screen.<br />
v SYNC_SEND_RECEIVE - A synchronous call.<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI resource adapter CCI<br />
FunctionName<br />
When SYNC_SEND or SYNC_SEND_RECEIVE is specified in the<br />
InteractionVerb property, FunctionName needs to contain the name of<br />
the program to execute on <strong>CICS</strong>.<br />
AID This value holds the AID key that will be sent to <strong>CICS</strong>. The default<br />
value is enter.<br />
CursorRow<br />
The row on which the cursor will be positioned on the terminal<br />
screen.<br />
CursorColumn<br />
The column in which the cursor will be positioned on the terminal<br />
screen.<br />
OutputAttributeType<br />
This allows you to control what will be held in the attribute byte for<br />
the field on a returned screen. It applies only to the streamable<br />
interface (see “Writing input and output records” on page 124).<br />
Available options are:<br />
ATTRIBUTE_NONE<br />
The value 0x20 is stored in the byte which represents the<br />
attribute byte on the screen<br />
ATTRIBUTE_BASE<br />
(Default) Stores the base attribute in the byte which represents<br />
the attribute byte on the screen<br />
ATTRIBUTE_FOREGROUNDCOLOR<br />
Stores the foreground color value in the byte which represents<br />
the attribute byte on the screen<br />
ATTRIBUTE_BACKGROUNDCOLOR<br />
Stores the background color value in the byte which<br />
represents the attribute byte on the screen<br />
ATTRIBUTE_HIGHLIGHT<br />
Stores the highlight attribute value in the byte which<br />
represents the attribute byte on the screen<br />
ATTRIBUTE_TRANSPARENCY<br />
Stores the transparency attribute value in the byte which<br />
represents the attribute byte on the screen<br />
ATTRIBUTE_MARKER<br />
Stores the byte defined by the enumeration MARKER_BYTE<br />
value in the byte which represents the attribute byte on the<br />
screen. This can be used to locate fields easily within an<br />
output record using the streamable interface.<br />
Chapter 8. Programming using J2EE 123
|<br />
|<br />
|<br />
EPI resource adapter CCI<br />
So for example if you want to know the foreground color of a field<br />
you set the OutputAttributeType to<br />
ATTRIBUTE_FOREGROUNDCOLOR and then read the attribute file<br />
out of the byte stream contained in your output record. To see<br />
whether the same field has the highlight attribute set you execute<br />
another SYNC_RECEIVE interaction with the OutputAttributeType<br />
property set to ATTRIBUTE_HIGHLIGHT.<br />
In addition to these input properties the EPIInteractionSpec also has a set of<br />
output properties for use by the J2EE component:<br />
CursorRow<br />
The current row on which the cursor is positioned.<br />
CursorColumn<br />
The current column in which the cursor is positioned.<br />
ScreenWidth<br />
The width of the current screen.<br />
ScreenDepth<br />
The depth of the current screen.<br />
TermId<br />
The ID of the terminal being used for the interaction, as defined in<br />
<strong>CICS</strong>.<br />
MapName<br />
The name of the BMS map being used on the current screen.<br />
MapSetName<br />
The name of the mapset that the current map belongs to.<br />
Closing an EPIInteraction<br />
Closing an EPIInteraction does not affect the state of the connection; the<br />
terminal remains connected.<br />
Writing input and output records<br />
Records are needed to supply information to the EPI resource adapter and to<br />
retrieve information from the resource adapter. Although the EPI resource<br />
adapter supports the Streamable interface as defined in the Connector<br />
Architecture, if you wish to use it you must write your own records, parsing<br />
the input stream and generating the output stream correctly. For information<br />
about the Stream format see “Stream Format” on page 127.<br />
The EPI resource adapter provides a more efficient way to access information<br />
in the form of a record that is ready to use. This is the recommended way to<br />
access and send information to a resource adapter.<br />
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI Screen Record: The EPI resource adapter provides a record that you can<br />
use with the EPI resource adapter to retrieve and send information to <strong>CICS</strong><br />
through EPI. Like the EPI Support classes, it represents information by<br />
containing field objects within a screen object. Use the Screen container to get<br />
a reference to a field, and then use methods on the field to query and<br />
manipulate the field text.<br />
The record is found in the com.ibm.connector2.cics package. It is an<br />
implementation of the screenable interface, which is the contact between the<br />
EPI resource adapter and the record on how to transfer information.<br />
EPIScreenRecord: To create an EPIScreenRecord:<br />
EPIScreenRecord screen = new EPIScreenRecordImpl();<br />
Note that you actually instantiate an instance of EPIScreenRecordImpl.<br />
You then pass this as an output record initially and start a new transaction,<br />
for example:<br />
EPIInteractionSpec epiSpec = new EPIInteractionSpec();<br />
epiSpec.setFunctionName(“CESN”);<br />
epiSpec.setAID(AIDKey.enter);<br />
epiSpec.setInteractionVerb(EPIInteractionSpec.SYNC_SEND_RECEIVE);<br />
// epiInter is an interaction created elsewhere<br />
epiInter.execute(epiSpec, null, screen);<br />
Note the use of null as the input record.<br />
The screen information is in the screen object. Other screen information such<br />
as cursor position is returned to your defined EPIInteractionSpec object. You<br />
can then request a specific field by index number, which has a range from 1 to<br />
the total number of fields on the screen, or you can request an iterator over all<br />
the fields. The fields are indexed in order starting from the top left of the<br />
screen going from left to right to the bottom right of the screen. The iterator<br />
returns each field in incrementing index order.<br />
So for example you can obtain a field using the index number by coding:<br />
EPIFieldRecord field = screen.getField(7);<br />
To use the iterator, code the following:<br />
java.util.Iterator it = screen.getFields();<br />
while (it.hasNext()) {<br />
EPIFieldRecord field = (EPIFieldRecord)it.next();<br />
....<br />
....<br />
}<br />
EPI resource adapter CCI<br />
Chapter 8. Programming using J2EE 125
EPI resource adapter CCI<br />
The following is a code example of a function that takes a screen record and<br />
prints out the screen in a layout suitable for a terminal:<br />
public void printScreen(EPIScreenRecord inscr) {<br />
int col = 1;<br />
int row = 1;<br />
}<br />
System.out.println(“——————————————————————————————————————”);<br />
for (int i = 1; i row) {<br />
System.out.print(“\n”);<br />
row++;<br />
col = 1;<br />
}<br />
while (f.getTextCol() > col) {<br />
System.out.print(“ ”);<br />
col++;<br />
}<br />
if (f.isDisplay()) {<br />
System.out.print(f.getText());<br />
col += f.getText().length();<br />
}<br />
}<br />
catch (ScreenException se) {<br />
}<br />
}<br />
System.out.print(“\n”);<br />
System.out.println(“——————————————————————————————————————”);<br />
After you have accessed and updated the fields, pass the record back as the<br />
input record. If you wish, you can use it again as the output record. For<br />
example:<br />
epiSpec.setAID(AIDKey.enter);<br />
epiInter.execute(epiSpec, screen, screen);<br />
EPIFieldRecord: You always access EPIFieldRecords from an<br />
EPIScreenRecord instance (rather than creating them direct). The<br />
EPIFieldRecord has many methods to access the various attributes of a field<br />
(for example, whether it is protected or not, which colors are applicable). You<br />
can also retrieve and modify text. See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Reference, for more information on these interfaces in the<br />
com.ibm.connector2.cics package. EPIFieldRecord contains various static final<br />
variables that define names for color attributes, highlighting and transparency.<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
EPI resource adapter CCI<br />
ScreenException: An EPIScreenRecord and EPIFieldRecord can throw<br />
exceptions. They are checked exceptions, and all inherit from the base class<br />
ScreenException. See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, for<br />
more information on these exceptions.<br />
Stream Format: The stream is a byte representation of the screen. The<br />
number of bytes that are sent to the application, and received from the<br />
application, should be the same as the number of bytes on the screen. That is,<br />
the number of bytes should equal the product of screen depth and screen width.<br />
For example, if the terminal to which you are connected has a 24 by 80<br />
character screen the number of bytes that should be flowed to and from the<br />
resource adapter is: 24x80 = 1920 bytes.<br />
When providing an input record, you must flow the exact number of bytes on<br />
the stream otherwise the record will be rejected. Also, the byte stream must<br />
represent exactly what the screen looks like as seen by the resource adapter. If<br />
it does not the record will be rejected.<br />
For each field on the screen, there is a byte preceeding the field that<br />
represents the attribute byte on a 3270 terminal. On a 3270 screen this byte is<br />
displayed as a blank. However, in the byte stream it can be controlled to<br />
contain information about the field. You can select what is placed in this field<br />
by specifying an appropriate value in the EPIInteractionSpec<br />
setOutputAttributeType method. For example, this byte could contain a<br />
blank, which is the base attribute, or it could contain a value which represents<br />
the color attribute for that field. See“EPIInteractionSpec” on page 122 for more<br />
details.<br />
A special option is EPIInteractionSpec.ATTRIBUTE_MARKER. This will store the<br />
value EPIInteractionSpec.MARKER_BYTE in that location. This enables a record<br />
to dynamically locate a field, without needing prior knowledge of the screen<br />
format, for example a BMS map.<br />
Writing LogonLogoff classes<br />
LogonLogoff classes are specified at deployment and used to logon to signon<br />
capable terminals, or to terminals that install as signon unknown.<br />
It is recommended that you use signon incapable terminals, in which case you<br />
do not need the LogonLogoff classes.<br />
If you choose to use the classes, implement the<br />
com.ibm.connector2.cci.LogonLogoff interface which has the following<br />
interface definition:<br />
Chapter 8. Programming using J2EE 127
EPI resource adapter CCI<br />
public interface LogonLogoff {<br />
public void logoff(javax.resource.cci.Connection conn);<br />
public void logon(javax.resource.cci.Connection conn,<br />
javax.security.auth.Subject security);<br />
}<br />
This class is only required for the EPI resource adapter. Also, you do not need<br />
to implement the logoff method because this is never called. However, you<br />
must provide a dummy implementation so that the class can be compiled. As<br />
you can see with the logon method signature, you are passed a connection<br />
and a security subject. The logon is driven in the same way as for applications<br />
that communicate with <strong>CICS</strong> using the EPI resource adapter. You create<br />
interactions using this connection and, when finished, you close the<br />
interaction. For example:<br />
Interaction epiInt = (Interaction)(conn.createInteraction());<br />
EPIInteractionSpec spec = new EPIInteractionSpec();<br />
//------------------------------------------------------------------<br />
// configure the spec to perform a CESN, and execute the call<br />
//-----------------------------------------------------------------spec.setAID(AIDKey.enter);<br />
spec.setFunctionName("CESN");<br />
spec.setInteractionVerb(EPIInteractionSpec.SYNC_SEND_RECEIVE);<br />
EPIScreenRecord screen = new EPIScreenRecordImpl();<br />
epiInt.execute(spec,null,screen);<br />
Close the interaction when you have finished with it. For example:<br />
epiInt.close();<br />
Note: Do not close the connection within the LogonLogoff class.<br />
The credentials with which you logon are held as Subject object. To retrieve<br />
this information you need to get an iterator from the private credentials. There<br />
is a single entry within the private credentials of type PasswordCredential. You<br />
can obtain the userid and password from this entry as follows:<br />
Iterator it = security.getPrivateCredentials().iterator();<br />
PasswordCredential pc = null;<br />
if (it.hasNext()) {<br />
pc = (PasswordCredential)it.next();<br />
}<br />
if (pc == null) {<br />
throw new javax.resource.spi.SecurityException("<br />
Unable to logon, No Security Information Provided");<br />
}<br />
String user = pc.getUserName();<br />
String pass = new String(pc.getPassword());<br />
If there are any problems, throw an appropriate<br />
javax.resource.spi.SecurityException.<br />
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Java security: You might need to grant your LogonLogoff class the Java<br />
security permission, to enable it to retrieve the credential information from the<br />
subject passed to it:<br />
Samples<br />
J2EE EPI sample programs are provided in the samples subdirectory of your<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> installation. These are documented in the<br />
samples.txt file, which is also found at that location.<br />
Security credentials and the <strong>CICS</strong> resource adapters<br />
EPI resource adapter CCI<br />
permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\"", "read";<br />
Security Credentials for accessing <strong>CICS</strong> can come from three different places.<br />
These are the ConnectionSpec properties, the deployed security credentials, or<br />
the server itself (for nonmanaged environments, the third option does not<br />
apply). The precedence for these credentials is:<br />
1. The Server Supplied Credentials (highest precedence)<br />
2. The ConnectionSpec Supplied Credentials<br />
3. The Deployed Security Credentials.<br />
Compiling applications<br />
To compile supplied applications in both managed and nonmanaged<br />
environments, include the following in the CLASSPATH:<br />
v cicsj2ee.jar (required for access to Connection and Interaction Specs)<br />
v ctgclient.jar (required for AIDkey objects)<br />
v ccf2.jar (required for creating LogonLogoff classes)<br />
v connector.jar (required for all resource adapter applications)<br />
v screenable.jar (required if using the EPI Screen Record)<br />
Compiling and running Enterprise Bean clients and deploying Enterprise<br />
Beans<br />
If you develop an Enterprise Bean that passes back the EPI Screen Record as a<br />
return parameter, your deployment tool needs the following jar files:<br />
v cicsj2ee.jar<br />
v screenable.jar<br />
An Enterprise Bean client that receives an EPI Screen Record also needs these<br />
jar files on the classpath.<br />
Chapter 8. Programming using J2EE 129
Using the J2EE <strong>CICS</strong> resource adapters in a nonmanaged environment<br />
Using the J2EE <strong>CICS</strong> resource adapters in a nonmanaged environment<br />
You can use the resource adapters in a nonmanaged environment. In this<br />
environment, you are responsible for:<br />
v Defining the EIS connection<br />
v Creating the ConnectionFactory object<br />
v Providing your own connection pooling<br />
v Supplying your log writer<br />
v Managing transactions<br />
Your nonmanaged environment can be either inside, or outside, a J2EE server<br />
environment. The resource adapters provide a default connection manager to<br />
support execution within the nonmanaged environment.<br />
<strong>Transaction</strong> management applies only to the ECI resource adapter. See<br />
“Application transaction demarcation” on page 120 for information on<br />
managing transactions in a nonmanaged environment.<br />
Creating the appropriate ConnectionFactory object<br />
Your application needs to get an appropriate ConnectionFactory object. In the<br />
managed environment, the server or application does this for you, and you<br />
can reference it using JNDI (see “Storing ConnectionFactory objects” on<br />
page 131). In the nonmanaged environment, unless you have previously<br />
registered one that you can access, you must create a ConnectionFactory<br />
object with the appropriate EIS connection information.<br />
Creating an ECI ConnectionFactory<br />
You must first create an ECIManagedConnectionFactory and set the<br />
appropriate properties on this object. The properties are the same as the<br />
deployment parameters described in J2EE setup and configuration, inthe<strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Administration book for your operating system. These are<br />
accessible using setter and getter methods. The J2EE Programming Reference<br />
documentation lists the setter and getter methods for the<br />
ECIManagedConnectionFactory and shows the relationship between<br />
deployment parameters and properties. The following example shows how to<br />
create a ConnectionFactory for ECI:<br />
ECIManagedConnectionFactory eciMgdCf = new ECIManagedConnectionFactory();<br />
eciMgdCf.setConnectionURL("local:");<br />
eciMgdCf.setPortNumber(new Integer(0));<br />
eciMgdCf.setServerName("tp600");<br />
eciMgdCf.setLogWriter(new java.io.PrintWriter(System.err));<br />
eciMgdCf.setUserName("myUser");<br />
eciMgdCf.setPassword("myPass");<br />
eciMgdCf.setTraceLevel(new<br />
Integer(ECIManagedConnectionFactory.RAS_TRACE_ENTRY_EXIT));<br />
ConnectionFactory cxf = (ConnectionFactory)eciMgdCf.createConnectionFactory();<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Creating the appropriate ConnectionFactory object<br />
Creating an EPI ConnectionFactory<br />
You must first create an EPIManagedConnectionFactory and set the<br />
appopriate properties on this object. The properties are the same as the<br />
deployment parameters described in J2EE setup and configuration, inthe<strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Administration book for your operating system. This<br />
process is similar to that for creating an ECI ConnectionFactory. The following<br />
example shows how to create a ConnectionFactory for EPI:<br />
EPIManagedConnectionFactory epiMgdCf = new EPIManagedConnectionFactory();<br />
epiMgdCf.setConnectionURL("local:");<br />
epiMgdCf.setPortNumber(new Integer(0));<br />
epiMgdCf.setServerName("tp600");<br />
epiMgdCf.setLogWriter(new java.io.PrintWriter(System.err));<br />
epiMgdCf.setUserName("myUser");<br />
epiMgdCf.setPassword("myPass");<br />
epiMgdCf.setSignonType(new Integer(0)); // signon capable terminal<br />
epiMgdCf.setLogonLogoffClass("com.acme.companyApp.our<strong>CICS</strong>Logon");<br />
epiMgdCf.setTraceLevel(new<br />
Integer(EPIManagedConnectionFactory.RAS_TRACE_ERROR_EXCEPTION));<br />
ConnectionFactory cxf = (ConnectionFactory)epiMgdCf.createConnectionFactory();<br />
Storing ConnectionFactory objects<br />
You can store ConnectionFactory objects for later reuse, so that your<br />
application doesn’t need to rebuild them. Inside a J2EE server environment,<br />
IBM recommends that you register your ConnectionFactory object, which has<br />
links to your EIS connection information, in the J2EE Java Naming and<br />
Directory Interface (JNDI ) service. This makes migration from nonmanaged<br />
to managed Java environments easier because applications can get<br />
ConnectionFactory objects in the same manner. However, this may not be<br />
possible outside a JNDI environment unless either an LDAP server, or an<br />
appropriate JNDI Service Provider, is available within your environment.<br />
The resource adapter ConnectionFactory objects support both the serializable<br />
and referenceable Java interfaces. This means that you can choose how to<br />
register them in the JNDI. For more information, refer to the J2EE Connector<br />
Architecture Specification.<br />
If you plan to use serializable interfaces, refer to J2EE Tracing, inthe<strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Administration book for your operating system. This gives<br />
information on how serialization and deserialization of ConnectionFactory<br />
objects affects the setting of the LogWriter property.<br />
Running the J2EE <strong>CICS</strong> resource adapters in a nonmanaged environment<br />
In a J2EE environment, all of the required Java libraries should be available.<br />
You might need to ensure that your J2EE server adds the following delivered<br />
jar files to your CLASSPATH. These files are in the \classes<br />
subdirectory:<br />
v cicsj2ee.jar<br />
v ctgclient.jar<br />
Chapter 8. Programming using J2EE 131
Running the J2EE <strong>CICS</strong> resource adapters in a nonmanaged environment<br />
v ctgserver.jar (required only for local: protocol)<br />
v ccf2.jar<br />
v connector.jar<br />
v screenable.jar (required for the EPIScreenRecord)<br />
Outside a J2EE enviroment, you must ensure that, as well as the above<br />
libraries being listed in the CLASSPATH, the following Java extensions are<br />
also available:<br />
v JAAS (required for EPI resource adapter)<br />
v JTA (required for the ECI resource adapter)<br />
JAAS is included with IBM JREs and JDKs by default. The JTA library is<br />
available from the Sun Java website.<br />
All of the above libraries and extensions should be available from the J2EE<br />
server libraries.<br />
J2EE Tracing<br />
In a nonmanaged environment where the DefaultConnectionManager is used<br />
the application can set the LogWriter property on the class to define where<br />
trace messages are sent. It is important to note however that in a nonmanaged<br />
environment, if the ConnectionFactory is serialized for storage the LogWriter<br />
must be set after deserialization in order for it to be used, as it is not restored<br />
automatically after deserialization. Figure 24 shows an example of this<br />
process.<br />
ECIManagedConnectionFactory MCF = new ECIManagedConnectionFactory();<br />
MCF.setLogWriter(myLogWriter);<br />
ECIConnectionFactory cf = MCF.createConnectionFactory();<br />
objOutStream.write(cf);<br />
ECIConnectionFactory cf2 = (ECIConnectionFactory) objInStream.read();<br />
DefaultConnectionManager.setLogWriter(myLogWriter);<br />
Figure 24. An example of resetting the LogWriter after ConnectionFactory deserialization.<br />
Issues with tracing if ConnectionFactory serialized<br />
As described above, if you use the serializable interface to store your<br />
ConnectionFactory then you lose the reference to your LogWriter. This is<br />
because LogWriters are not serializable and cannot be stored. When you<br />
deserialize your ConnectionFactory it will not contain a reference to the<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Running the J2EE <strong>CICS</strong> resource adapters in a nonmanaged environment<br />
LogWriter. To ensure that your LogWriters are stored on any connections<br />
created from this ConnectionFactory you must do the following. This only<br />
applies in a nonmanaged environment.<br />
DefaultConnectionManager.setLogWriter(new java.io.PrintWriter(System.err));<br />
Connection Conn = (Connection)cxf.getConnection();<br />
The setLogWriter method on the DefaultConnectionManager, which is<br />
supplied with the resource adapters, is a static method. The example above<br />
shows how to set the log to output the System.err. The trace level applied to<br />
the ManagedConnectionFactory remains.<br />
Resource adapter samples<br />
The samples consist of one ECI and one EPI Sample. They show how to use<br />
the <strong>CICS</strong> resource adapters as well as demonstrating how to write custom<br />
records that implement the javax.resource.cci.Streamable interface. For<br />
information on how to deploy the ECI and EPI resource adapters, see J2EE<br />
setup and configuration, inthe<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration book for<br />
your operating system.<br />
ECI sample<br />
The ECI Sample consists of a stateless Enterprise Bean, a client application,<br />
and a custom record that demonstrates using the Streamable interface. The<br />
following files are part of the ECI Sample:<br />
ECIDateTime.java Enterprise Bean Remote Interface<br />
ECIDateTimeHome.java Enterprise Bean Home Interface<br />
ECIDateTimeBean.java Enterprise Bean Implementation<br />
ECIDateTimeClient.java Enterprise Bean client program<br />
JavaStringRecord.java Custom Record<br />
Ejb-jar-eci-1.1.xml Example of a deployment descriptor<br />
The deployment descriptor is an example of an EJB 1.1–compliant deployment<br />
descriptor for this Enterprise Bean. If you wish to package it up into a jar file,<br />
rename it to Ejb-jar.xml and store it in the META-INF directory of the jar<br />
file. It may require further entries if it is to be deployed into an EJB<br />
2.0–compliant environment.<br />
See your J2EE Server documentation for information on how to compile and<br />
deploy the bean. The Enterprise Bean looks for an ECI connection factory<br />
named java:comp/env/ECI. The bean must refer to this resource when<br />
deployed. Refer to your J2EE Server documentation on how to deploy the<br />
resource adapter with an entry in the JNDI with this name. The client<br />
Chapter 8. Programming using J2EE 133
ECI sample<br />
program looks for the ECIDateTime bean with a name of ECIDateTimeBean1.<br />
See your J2EE Server document for details of how to setup the bean with this<br />
JNDI name.<br />
You will need to install the sever sample program EC01 on your <strong>CICS</strong> Server.<br />
This file can be found in the samples\server subdirectory of your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> installation. Further details of this sample can be found<br />
in thesamples.txt file in the samples folder.<br />
The bean is a simple bean that outputs the date and time as known to the<br />
<strong>CICS</strong> Server, and can be deployed as Bean Managed <strong>Transaction</strong>. The Custom<br />
record takes a COMMAREA and converts it to a string. Ensure that the EC01<br />
sample program, which you installed on your <strong>CICS</strong> server, sends its results in<br />
ASCII, as the COMMAREA is expected in ASCII. The JavaStringRecord does<br />
however allow for the selection of other encodings, and is commented using<br />
JavaDoc. The Client program takes no parameters.<br />
EPI sample<br />
The EPI Sample consists of<br />
v A Stateful Enterprise Bean<br />
v An Enterprise Bean Client<br />
v A custom record which demonstrates using the Streamable interface<br />
v A sample LogonLogoff class<br />
The following files are part of the EPI Sample:<br />
EPIPlayScript.java Enterprise Bean Remote Interface<br />
EPIPlayScriptHome.java Enterprise Bean Home Interface<br />
EPIPlayScriptBean.java Enterprise Bean Implementation<br />
EPIPlayScriptClient.java Enterprise Bean client program<br />
<strong>CICS</strong>CESNLogon.java A LogonLogoff Class<br />
Ejb-jar-epi-1.1.xml Example of a deployment descriptor<br />
The deployment descriptor is an example of an EJB 1.1-compliant deployment<br />
descriptor for this Enterprise Bean. If you wish to package it up into a jar file,<br />
rename it to Ejb-jar.xml and store it in the META-INF directory of the jar<br />
file. It may require further entries if it is to be deployed into an EJB<br />
2.0-compliant environment.<br />
Your J2EE Server documentation describes how to compile and deploy the<br />
bean within your environment. However, you need to ensure that he<br />
following jar files are also available on the CLASSPATH:<br />
v cicsj2ee.jar<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
v connector.jar<br />
v ctgclient.jar<br />
v ccf2.jar<br />
The Enterprise Bean looks for an EPI connection factory named<br />
java:comp/env/EPI. See your J2EE Server’s documentation for details of how<br />
deploy the resource adapter under this reference in the JNDI. When deploying<br />
the bean into your environment you need to supply this reference for the bean<br />
to find the resource. The client program looks for the EPIPlayScript bean with<br />
a name of EPIPlayScript1. Refer to your J2EE Server documentation for<br />
details of how to setup the bean with this name in the JNDI namespace. The<br />
bean can be deployed as a Bean Managed <strong>Transaction</strong>.<br />
The bean is designed to take a series of commands and drive a 3270<br />
interaction. Once the commands are complete, the field text is returned as a<br />
string array based on fields requested to be returned by the script. The client<br />
can then look at these field texts and send more commands to drive that<br />
interaction if necessary. The commands that drive the 3270 screen are as<br />
follows:<br />
S(txn) Start transaction “txn”<br />
F(x)=“Text” Set field number x to “Text”. Field numbers<br />
start at 1.<br />
P(aid) Press key ’aid’<br />
C(row, col) place cursor at row, col (row and col start at 1)<br />
R(x) Adds the text of the field at the given field<br />
number to the string array that will be<br />
returned. Field numbers start at 1.<br />
So an example of a script might be:<br />
S(CESN)F(7)="myuser"F(10)="mypass"P(enter)R(1)<br />
EPI sample<br />
The EPIPlayScriptClient program takes no parameters; it has a default<br />
command sequence coded into it. Experiment by changing this command<br />
sequence or enhancing the sample.<br />
The <strong>CICS</strong>CESNLogon.java sample contains example code on how to logon to a<br />
<strong>CICS</strong> 390 system. There are also examples showing how to logon to <strong>CICS</strong> for<br />
NT 3.1 and <strong>CICS</strong> for OS/2 in comments. They are designed to work for<br />
English systems and may have to be tailored for other versions of <strong>CICS</strong> and<br />
languages. In order to use this class, deploy it as part of the sample bean and<br />
reference it when you deploy the EPI resource adapter. For more information<br />
Chapter 8. Programming using J2EE 135
EPI sample<br />
about how to deploy the EPI resource adapter see J2EE setup and configuration,<br />
in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration book for your operating<br />
system.<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Chapter 9. Programming in COM<br />
Establishing the working environment<br />
You are provided with Component Object Model (COM) Object Oriented (OO)<br />
support for the Client daemon in the Windows environment. This includes the<br />
COM runtimes, type libraries, the BMS map utility, and sample code.<br />
The COM libraries<br />
The COM libraries are automation compatible. Automation compatible means<br />
that they can be used easily from programming languages such as Visual<br />
Basic, VBScript and Delphi. However, these libraries are only supported with<br />
Visual Basic and VBScript and full support is not provided for other<br />
development environments.<br />
Servers<br />
The libraries are provided as in-process servers (cclieci.dll and<br />
ccliepi.dll) and out-of-process or local servers (ccloeci.exe and<br />
ccloepi.exe). Although local servers are provided they are not supported and<br />
have not been tested in a DCOM environment.<br />
It is recommended that you use in-process servers as they provide better<br />
performance than the out-of-process servers.<br />
Registration<br />
The COM libraries are registered at installation time. This registers the COM<br />
classes, associated ProgIDs and the type libraries for each of the libraries. At<br />
this time you must choose whether you require in or out of process servers.<br />
Visual Basic will only use the type libraries if you register them to each Visual<br />
Basic Project. It is recommended that you do this to make full use of the the<br />
features and performance enhancements of these type libraries. See “Enabling<br />
the use of the COM libraries” on page 138 for details about project<br />
enablement.<br />
VBScript does not use type libraries.<br />
All the COM libraries support automatic registration and de-registration . If<br />
you have de-registered the COM libraries the sections “Registering in-process<br />
servers” and “Registering out-of-process servers” on page 138 describe how to<br />
reregister them.<br />
Registering in-process servers: To register in-process servers use the<br />
Microsoft supplied program REGSVR32.<br />
© Copyright IBM Corp. 2002 137
Establishing the working environment<br />
For example to register the ECI COM libraries issue the command<br />
REGSVR32 CCLIECI.DLL<br />
to de-register issue the command<br />
REGSVR32 /U CCLIECI.DLL<br />
Registering out-of-process servers: To register the out-of-process servers, run<br />
the executable and, when a window appears indicating that registration has<br />
been done, close it. For example to register the EPI libraries run the program<br />
CCLOEPI.<br />
To unregister the out-of-process servers, run the executable with the<br />
/unregister parameter. For example to unregister the EPI libraries run the<br />
program<br />
CCLOEPI /unregister<br />
Enabling the use of the COM libraries<br />
To set up Visual Basic to use the type libraries, go to the Visual Basic<br />
Project/References... dialog and select either<br />
Client daemon EPI<br />
or<br />
Client daemon ECI<br />
depending on your application needs. Press OK.<br />
If the type libraries are not listed then the COM libraries probably have not<br />
been registered. Refer to the previous section for information on registering<br />
the COM libraries.<br />
COM Libraries: Objects and Apartments<br />
The design of the Client daemon COM Libraries requires the passing of a<br />
COM object to another COM object. For this to work the relevant COM<br />
objects need to be created in the same apartment. For example, in ECI, to<br />
make a link method call on the Connect COM object a Flow, Buffer and UOW<br />
object need to be passed. These must all be created in the same apartment in<br />
order to function properly.<br />
Again with EPI it is important to ensure that the Terminal Session and Map<br />
COM Objects are created in the same apartment. The Terminal is responsible<br />
for creating the Screen object and it will create it in the same apartment as<br />
itself. This Screen object is then responsible for creating field objects and also<br />
creates them in the same apartment as itself. The out-of-process servers<br />
guarantees that all objects are created in the same apartment. However, the<br />
programmer has control of the apartment where COM objects are created<br />
when they use the in-process servers.<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Establishing the working environment<br />
In most cases in Visual Basic you do not need to worry about apartments as<br />
you will be creating single threaded applications.<br />
Using the COM classes<br />
The Client daemon provides COM classes for the <strong>CICS</strong> ECI and EPI on<br />
Windows. The interfaces could be used from any application development<br />
environment that supports COM automation. However, this book refers only<br />
to Visual Basic and VBScript. Only these environments are supported.<br />
These COM classes can be accessed from Microsoft Visual Basic, from Visual<br />
Basic for Applications (which is provided built-in to applications such as<br />
Microsoft Excel version <strong>5.0</strong>.), and from VBScript.<br />
COM sample programs are provided in the \samples<br />
subdirectory. Refer to the samples.txt file, in that subdirectory, for more<br />
information.<br />
Object Creation and Interfaces<br />
To talk to COM objects you have to use interfaces. The ECI and EPI COM<br />
libraries provide two interfaces per COM class.<br />
The first interface is called IDispatch and is provided to support old Visual<br />
Basic applications and VBScript. A second interface, a Custom interface, is also<br />
provided for use by Visual Basic. This interface is faster than the IDispatch<br />
interface and it is recommended that you use this interface with Visual Basic.<br />
Each COM class provides an IDispatch interface and a Custom interface.<br />
Visual Basic provides more than one way to create a COM object and select<br />
the interface to talk to that object. To create an object there are the<br />
CreateObject function and the New function. It is recommended that you use<br />
the New function to create objects in Visual Basic.<br />
VBScript is simpler. It provides only one way to create an object, the<br />
CreateObject function, and you must use the IDispatch interface.<br />
The following are some examples of creating COM objects<br />
Set eci = CreateObject("Ccl.ECI")<br />
Set eci = New CcloECI<br />
Set connection = CreateObject("Ccl.Connect")<br />
Set connection = New CcloConn<br />
Note the two ways you can request the object class. When using CreateObject<br />
you specify a string called the Programmatic ID or ProgID for short. When<br />
using the New function you specify the Class name that is registered in the<br />
type library.<br />
Chapter 9. Programming in COM 139
COM classes<br />
When using Visual Basic you have the choice of which interface you want to<br />
use. If you DIM your variable as Object, then you select the IDispatch<br />
interface. If you DIM your variable as the Class name then you will select the<br />
custom interface. To create a terminal object in Visual Basic you would use the<br />
code:<br />
Dim Terminal as CclOTerminal<br />
Set Terminal = New CclOTerminal<br />
Figure 25. Creating a terminal object in Visual Basic<br />
or you can combine the above into a single statement if you wish<br />
Dim Terminal as New CclOTerminal<br />
When using VBScript, VBScript will automatically select the IDispatch<br />
interface for you. For example to create a terminal Object in VBScript you<br />
would use the code<br />
Dim Terminal<br />
Set Terminal = CreateObject("Ccl.Terminal")<br />
Figure 26. Creating a terminal Object in VBScript<br />
It is recommended that you:<br />
v choose one interface type or the other.<br />
v do not mix the object interface types in your program. This type of<br />
environment is not supported.<br />
v select the custom interface because it should provide performance<br />
improvements.<br />
No matter which interface you select or how the object is created, you use the<br />
objects identically in your program.<br />
Type Libraries and Visual Basic Intellisense<br />
Type libraries add many useful features to the COM libraries. One of these is<br />
Visual Basic Intellisense. The type libraries provide Visual Basic with<br />
information so that it can help you with code completion. It prompts you<br />
with the format of the method and, where applicable, constants which might<br />
be relevant to method parameters or return values you can test for. For<br />
example if you create a terminal object for Visual Basic as shown in Figure 25,<br />
when you want to select a method on the terminal object, press the ’.’ key and<br />
you are presented with a list of available methods. Select the method and<br />
press space or open bracket and you are shown the required parameters. You<br />
can also browse the type libraries for reference information on the ECI and<br />
EPI classes by using the Visual Basic Object Browser. Select either CclECILib<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
COM classes<br />
for ECI classes reference or CclEPILib for EPI classes reference information.<br />
The type libraries are embedded within the in-process library files<br />
cclieci.dll and ccliepi.dll.<br />
Class summary<br />
The following table lists the COM classes that the <strong>CICS</strong> COM servers provide.<br />
Details of the methods these provide are in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference.<br />
Table 7. ECI COM classes<br />
COM class Description<br />
Buffer Buffer used for passing data to and from a <strong>CICS</strong> server<br />
Connection Controls a connection to a <strong>CICS</strong> server<br />
ECI Provides access to a list of <strong>CICS</strong> servers configured in the<br />
Client daemon<br />
Flow Controls a single interaction with <strong>CICS</strong> server program<br />
SecAttr Provides information about security attributes (passwords)<br />
SecTime Provides date and time information<br />
UOW Coordinates a recoverable set of calls to a <strong>CICS</strong> server<br />
Table 8. EPI COM classes<br />
COM class Description<br />
EPI Initializes and terminates the <strong>CICS</strong> EPI and provides access to<br />
a list of <strong>CICS</strong> servers configured in the Client daemon<br />
Field Provides access to a single 3270 field on a screen.<br />
Map Provides access to 3270 fields defined by a <strong>CICS</strong> server BMS<br />
map<br />
Screen Provides access to a 3270 terminal screen<br />
Session Controls a sequence of 3270 terminal interactions with a <strong>CICS</strong><br />
server<br />
Terminal Controls a 3270 terminal connection<br />
Samples illustrating the use of the ECI and EPI COM classes from Visual Basic<br />
are supplied in the \samples\vb subdirectory. The following<br />
sections show extracts from the samples.<br />
Exception Handling<br />
With the ECI and EPI classes there appear to be two ways to check for<br />
problems when invoking methods.<br />
Chapter 9. Programming in COM 141
COM classes<br />
One way could be to use the ErrorWindow method and set it to false, then<br />
check the ExCode and ExCodeText methods after a call to see what the return<br />
codes are. This is not the recommended way to do it and only exists now to<br />
support backward compatibility for old applications.<br />
The recommended way is to use the Err objects which Visual Basic and<br />
VBScript provide. An Err object contains the information about an error.<br />
Visual Basic supports On Error Goto and On Error Resume features to detect<br />
that an error has occurred. VBScript only supports the On Error Resume Next<br />
feature. If you use On Error Resume Next either in Visual Basic or VBScript,<br />
you must always enter this line before any COM object call that you expect<br />
could return an error. Visual Basic/VBScript might not reset the Err variable<br />
unless you do this.<br />
The type of interface you have selected (you DIM’ed a variable as either<br />
Object or classname) will affect the value contained in the Err.number<br />
property. It is possible to write a generic routine that handles all values in<br />
Err.Number and converts them to the documented ExCode error codes<br />
available. The example code following shows how to achieve this.<br />
To get full advantage of this technique, ensure that you get full information in<br />
the Err object. Issue the following call after creating the ECI or EPI object:<br />
ECI.SetErrorFormat 1<br />
or, for EPI:<br />
EPI.SetErrorFormat 1<br />
Figure 27 on page 143 shows how to handle errors in Visual Basic.<br />
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Private Sub Command1_Click()<br />
’<br />
’ The following code assumes you have created the<br />
’ required objects first, ECI, Connect, Flow, UOW,<br />
’ Buffer<br />
’<br />
On Error GoTo ErrorHandler<br />
conn.Link flow, "EC01", buf, uow<br />
Exit Sub<br />
ErrorHandler:<br />
’<br />
’ Ok, the Connect call failed<br />
’ Parse the Error Number, this will work regardless of<br />
’ how the ECI objects were Dimmed<br />
’<br />
Dim RealError As CclECIExceptionCodes<br />
RealError = (Err.Number And 65535) - eci.ErrorOffset<br />
If RealError = ccl<strong>Transaction</strong> Then<br />
’<br />
’ <strong>Transaction</strong> abend, so query the Abend code<br />
’<br />
AbendCode = flow.AbendCode<br />
If AbendCode = "AEY7" Then<br />
MsgBox "Invalid Userid/Password to execute <strong>CICS</strong> Program", , "<strong>CICS</strong> ECI Error"<br />
Else<br />
MsgBox "Unable to execute EC01, transaction abend:" + AbendCode, , "<strong>CICS</strong> ECI Error"<br />
End If<br />
Else<br />
MsgBox Err.Description, , "<strong>CICS</strong> ECI Error"<br />
End If<br />
End Sub<br />
Figure 27. Visual Basic exception handling sample<br />
Figure 28 on page 144 shows error handling code for VBScript.<br />
COM classes<br />
Chapter 9. Programming in COM 143
COM classes<br />
On Error Resume Next<br />
con.Link flow, "EC01", buf, uow<br />
if Err.Number 0 then<br />
’<br />
’ Ok, the Connect call failed<br />
’ Parse the Error Number, this will work regardless of<br />
’ how the ECI objects were Dimmed<br />
’<br />
RealError = Err.Number And 65535 - eci.ErrorOffset<br />
’<br />
’ 13 = Ccl<strong>Transaction</strong>, a transaction abend.<br />
’<br />
If RealError = 13 Then<br />
’<br />
’ <strong>Transaction</strong> abend, so query the Abend code<br />
’<br />
AbendCode = flow.AbendCode<br />
If AbendCode = "AEY7" Then<br />
Wscript.Echo "Invalid Userid/Password to execute <strong>CICS</strong> Program"<br />
Else<br />
Wscript.Echo "Unable to execute EC01, transaction abend:", AbendCode<br />
End If<br />
Else<br />
Wscript.Echo Err.Description<br />
End If<br />
End If<br />
Figure 28. VBScript exception handling sample<br />
Known Issues with Migration<br />
As discussed in Exception Handling, the values in the Err.Number will vary<br />
depending on which interface and Error Format you selected. If an old<br />
application used DIM to define the variables as their class name, and checked<br />
Err.Number for the value of 8600 (other values were not available in previous<br />
releases), this check will fail.<br />
Making an ECI link call to <strong>CICS</strong> using Visual Basic<br />
The first step is to declare object variables for the ECI interfaces to be used.<br />
See the COM chapter of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference for<br />
details of the available interfaces. Declarations are usually made in the<br />
General Declarations section of a Visual Basic program:<br />
Dim ECI As CclOECI<br />
Dim Connect As CclOConn<br />
Dim Flow As CclOFlow<br />
Dim Buffer As CclOBuf<br />
Dim UOW As CclOUOW<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
The required ECI objects are then instantiated using the Visual Basic New<br />
function. This can be done in the Form_Load subroutine or at some later stage<br />
in response to some user action. Note that a CclOECI object must be created<br />
first.<br />
Sub ECILink_Click()<br />
Set ECI = New CclOECI<br />
Set Connect = New CclOConn<br />
Set Flow = New CclOFlow<br />
Set Buffer = New CclOBuf<br />
Details of the <strong>CICS</strong> server to be used – server name (as configured in the<br />
<strong>Gateway</strong> initialization file) , userid and password – are supplied via the<br />
Details method on the Connect object. The Buffer object is initialized with<br />
some data to be sent to <strong>CICS</strong>:<br />
Connect.Details "<strong>CICS</strong>NAME", "sysad", "sysad"<br />
Buffer.SetString "Hello"<br />
Now we are ready to make the call to <strong>CICS</strong>. The Link method takes as<br />
parameters the Flow object, the name of the <strong>CICS</strong> server program to be<br />
invoked, the Buffer object and a UOW object. In this example a null variable<br />
is supplied for the UOW parameter, so this call will not be part of a<br />
recoverable Unit Of Work. The contents of the Buffer returned from <strong>CICS</strong> are<br />
output to a Visual Basic text box “Text1”:<br />
Connect.Link Flow, "ECIWTO", Buffer, UOW<br />
Text1.Text = Buffer.String<br />
Finally the <strong>CICS</strong> COM objects are deleted:<br />
Set Connect = Nothing<br />
Set Flow = Nothing<br />
Set Buffer = Nothing<br />
End Sub<br />
Guide to COM <strong>CICS</strong> ECI<br />
This example sends and receives a simple text string. In practice, the Buffer<br />
object would contain more complex data (for example C data structure). For<br />
binary data the Buffer.SetData and Buffer.Data methods are provided to<br />
allow the contents to be accessed as a Byte array.<br />
A typical client application could access <strong>CICS</strong> through one or more<br />
Connect.Link calls and construct a ’business object’ for use in end-user Basic<br />
programs. One approach to this would be to implement the ’business object’<br />
as a separate COM automation server containing the logic to process the<br />
contents of the CclOBuffer objects.<br />
Chapter 9. Programming in COM 145
Guide to COM <strong>CICS</strong> ECI<br />
Making an ECI link call to <strong>CICS</strong> using VBScript<br />
This is similar to the previous section visual basic but the creating of the<br />
objects is different.<br />
It is not necessary to DIM any variables with VBScript but it would be good<br />
programming practice to do so.<br />
Dim ECI, Connect, Flow, Buffer, UOW<br />
To create the objects you use the code:<br />
Set ECI = CreateObject("Ccl.ECI")<br />
Set Connect = CreateObject("Ccl.Connect")<br />
Set Flow = CreateObject("Ccl.Flow")<br />
Set Buffer = CreateObject("Ccl.Buffer")<br />
Set UOW = Nothing<br />
If you are not going to use a UOW, you must explicitly set it to ’Nothing’ in<br />
VBScript.<br />
ECI Call Synchronization Types<br />
The Client daemon ECI COM classes support synchronous (“blocking”) and<br />
deferred synchronous (“polling”) protocols. These classes do not support the<br />
asynchronous calls that are available in the C++ classes.<br />
In the previous example a Flow object was used with the default<br />
synchronization type of cclSync. When this Flow object was used as the first<br />
parameter on Connect.Link, a synchronous link call was made to <strong>CICS</strong>. The<br />
Visual Basic program was then blocked until the reply was received from<br />
<strong>CICS</strong>. When the link call returned the reply from <strong>CICS</strong> was immediately<br />
available in the Buffer object.<br />
To make a deferred synchronous call you use the SetSyncType method on the<br />
Flow object to set the Flow to cclDSync. When this Flow object is used on a<br />
Connect.Link call, the ECI call is made to <strong>CICS</strong>, but control returns<br />
immediately to the Visual Basic Program, and the reply from <strong>CICS</strong> must be<br />
retrieved later using the Poll method on the Flow object:<br />
Sub ECIDsync_Click()<br />
Set Connect = New CclOConn<br />
Set Flow = New CclOFlow<br />
Set Buffer = New CclOBuf<br />
Connect.Details "<strong>CICS</strong>NAME", "sysad", "sysad"<br />
Flow.SetSyncType cclDSync<br />
Buffer.SetString "Hello"<br />
Connect.Link Flow, "ECIWTO", Buffer, UOW<br />
End Sub<br />
146 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
The call to <strong>CICS</strong> is now in progress. At a later stage (in response to a user<br />
action, or perhaps when the Visual Basic program has completed some other<br />
task) the Poll method is used on the Flow object to collect the reply from<br />
<strong>CICS</strong>. Note that the Poll method requires a Buffer object as parameter if reply<br />
data is expected from <strong>CICS</strong><br />
Sub ECIReply_Click()<br />
If Flow.Poll(Buffer) Then<br />
Text1.Text = Buffer.String<br />
Else<br />
Text1.Text = "No reply from <strong>CICS</strong> yet"<br />
End If<br />
End Sub<br />
<strong>CICS</strong> Server Information and Connection Status<br />
The ECI COM class provides the names and descriptions of <strong>CICS</strong> servers<br />
configured in the <strong>Gateway</strong> initialization file. The Connect COM class provides<br />
methods for querying the availability of a particular <strong>CICS</strong> server.<br />
Object variables are declared as before, this time we use ECI, Connect and<br />
Flow COM classes:<br />
’Declare object variables<br />
Dim ECI As CclOECI<br />
Dim Connect As CclOConn<br />
Dim Flow As CclOFlow<br />
On user request, the objects are created, and a list of <strong>CICS</strong> server names and<br />
their descriptions is constructed:<br />
Sub ECIServers_Click()<br />
Dim I as Integer<br />
’Instantiate <strong>CICS</strong> ECI objects<br />
Set ECI = New CclOECI<br />
Set Connect = New CclOConn<br />
Set Flow = New CclOFlow<br />
’List <strong>CICS</strong> server information<br />
For I = 1 To ECI.ServerCount<br />
List1.AddItem ECI.ServerName(I)<br />
List1.AddItem ECI.ServerDesc(I)<br />
Next<br />
End Sub<br />
Guide to COM <strong>CICS</strong> ECI<br />
A synchronous status call to the first server is made, and the results of the call<br />
displayed in a text field:<br />
Chapter 9. Programming in COM 147
Guide to COM <strong>CICS</strong> ECI<br />
Connect.Details ECI.ServerName(1)<br />
Connect.Status Flow<br />
Text1.Text = Connect.ServerStatusText<br />
ECI Link Calls within a Unit Of Work<br />
Using the UOW COM class, a number of link calls can be made to a <strong>CICS</strong><br />
server within a single Unit of Work. Updates to recoverable resources in the<br />
<strong>CICS</strong> server can then be committed or backed out by the client program as<br />
necessary.<br />
In this example a UOW object is created, and is used as a parameter to the<br />
Connect.Link calls:<br />
Sub ECIStartUOW_Click()<br />
’Instantiate <strong>CICS</strong> ECI objects<br />
Set Connect = New CclOConn<br />
Set Flow = New CclOFlow<br />
Set UOW = New CclOUOW<br />
Set Buffer = New CclOBuf<br />
Connect.Details "<strong>CICS</strong>NAME", "sysad", "sysad"<br />
End Sub<br />
Sub ECILink_Click()<br />
’Set up the commarea buffer<br />
Buffer.SetString Text1.Text<br />
Buffer.SetLength 80<br />
’Make the link call as part of a Unit of Work<br />
Connect.link Flow, "ECITSQ", Buffer, UOW<br />
End Sub<br />
After a number of link calls have been made, the Commit or Backout<br />
methods on the Ccl UOW interface can be used:<br />
Sub Commit_Click()<br />
’Commit the <strong>CICS</strong> updates<br />
UOW.Commit Flow<br />
End Sub<br />
Sub Backout_Click()<br />
’Backout the <strong>CICS</strong> updates<br />
UOW.Backout Flow<br />
End Sub<br />
If no UOW object is used (a NULL value is supplied on the Connect.Link<br />
call), each link call becomes a complete unit of work (equivalent to LINK<br />
SYNCONRETURN in the <strong>CICS</strong> server).<br />
148 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
When you use Logical units of work, you must ensure that you backout or<br />
commit active units of work, this is particularly important at program<br />
termination. You can check if a logical unit of work is still active by checking<br />
the uowId method for a non-zero value.<br />
In Visual Basic, if you Dim a UOW variable but never create the object, it is<br />
assumed to a be of value Nothing and the Link call will therefore not<br />
associate a unit of work with the call. In VBScript, however, it is necessary to<br />
ensure explicitly that the variable is set to nothing. To do this code<br />
Set UOW=Nothing<br />
before making your link call.<br />
Handling COMAREAS in VB<br />
A CommArea is a block of storage that contains all the information you send<br />
to and receive from the server. Because of this, you must create a CommArea<br />
that is big enough for this information. For example, you might need to send<br />
a 12 byte serial number to the server, but receive a maximum of 20 Kb back<br />
from the server; this means you must create a Commarea of size 20 Kb. To do<br />
this you could code<br />
Set Buf = new CclOBuf ’ create extensible buffer object<br />
Buf.SetString(serialNo)<br />
Buf.setLength(20480) ’ stores Nulls in the unused area<br />
Guide to COM <strong>CICS</strong> ECI<br />
In the above example, Commarea is given the serial number and the buffer is<br />
increased to the required amount, but the extra area is filled with nulls. This<br />
is important as it ensures that the information transmitted to the server is<br />
kept to a minimum. The Client daemon strips off the excess nulls and only<br />
transmits the 12 bytes to the server.<br />
ECI Userid and Password Management<br />
You can perform security management on servers that support Password<br />
Expiry Management. Refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration<br />
book for your operating system, for more information on supported servers<br />
and protocols.<br />
To use these features you must first create a connection object and invoke the<br />
Details method to associate a userid and password with the object. The two<br />
methods available are VerifyPassword that checks the userid and password<br />
within the connection object with the Server Security System, and<br />
ChangePassword that allows you to change the password at the server. If<br />
successful the connection object password is updated accordingly.<br />
If either call is successful, you are returned a CclOSecAttr object. This object<br />
provides access to information such as last verified time, expiry time and last<br />
access time. If, for example, you query the last verified time, you are returned<br />
Chapter 9. Programming in COM 149
Guide to COM <strong>CICS</strong> ECI<br />
a CclOSecTime object and you may use the SecTime COM class methods to<br />
obtain the information in various formats. The following code shows the use<br />
of these various objects.<br />
’ Connection object already created called conn<br />
on error goto pemhandler<br />
Dim SecAttr as CclOSecAttr<br />
Dim LastVerified as CclOSecTime<br />
Dim lvdate as Date<br />
Set SecAttr = conn.VerifySecurity<br />
Set LastVerified = SecAttr.LastVerifiedTime<br />
lvdate = LastVerified.GetDate<br />
strout = Format(lvdate, "hh:mm:ss, dddd, mmm d yyyy")<br />
Text1.Text = strout<br />
exit sub<br />
pemhandler:<br />
’ handle a expired password here maybe<br />
end sub<br />
Connection to <strong>CICS</strong> 3270 applications using Visual Basic<br />
Note: The COM classes do not contain any specific support for 3270<br />
datastreams that contain DBCS fields. However they do not support<br />
3270 datastreams that contain mixed SBCS and DBCS fields.<br />
The first step is to declare object variables for the EPI interfaces to be used,<br />
usually in the General Declarations section of a Visual Basic program:<br />
Dim EPI As CclOEPI<br />
Dim Terminal As CclOTerminal<br />
Dim Session As CclOSession<br />
Dim Screen As CclOScreen<br />
Dim Field As CclOField<br />
The required EPI objects are then instantiated using the Visual Basic New<br />
function. This can be done in the Form_Load subroutine or at a later stage in<br />
response to a user action.<br />
The CclOEPI object must be created first to initialize the Client daemon EPI. A<br />
CclOTerminal object can then be created, and a connection established to a<br />
specific <strong>CICS</strong> server using the Terminal.Connect method. The first parameter<br />
to this method is the <strong>CICS</strong> server name (as configured in the <strong>Gateway</strong><br />
initialization file), the other parameters specify additional connection details.<br />
150 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
See <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference for additional<br />
information.<br />
Sub EPIConnect_Click()<br />
’Create Ccl.EPI first to initialize EPI<br />
Set EPI = New CclOEPI<br />
’Create a terminal object and connect to <strong>CICS</strong><br />
Set Terminal = New CclOTerminal<br />
Terminal.Connect "<strong>CICS</strong>NAME","",""<br />
’Create a session object (defaults to synchronous)<br />
Set Session = New CclOSession<br />
End Sub<br />
Running a <strong>CICS</strong> 3270 session<br />
Having connected a CclOTerminal object to the required <strong>CICS</strong> server the<br />
Terminal, Session, Screen and Field COM classes are used to start a<br />
transaction on <strong>CICS</strong> and navigate through 3270 panels, accessing 3270 fields<br />
as required by the application.<br />
The required <strong>CICS</strong> transaction is started using its four character transaction<br />
code. Initial transaction data can also be supplied on the Terminal.Start<br />
method, in this example no data is required. To access the 3270 data returned<br />
by <strong>CICS</strong>, a screen object is obtained from the terminal object, and a variety of<br />
methods can be used to obtain fields from the screen and read and update<br />
text and attributes in the fields:<br />
Sub EPIStart_Click()<br />
’Start CESN transaction<br />
Terminal.Start Session, "CESN", ""<br />
’Get the screen object<br />
Set Screen = Terminal.Screen<br />
’Output the text from some 3270 fields<br />
Set Field = Screen.FieldByIndex(5)<br />
List1.AddItem Field.Text<br />
Set Field = Screen.FieldByIndex(6)<br />
List1.AddItem Field.Text<br />
Guide to COM <strong>CICS</strong> EPI<br />
The CESN transaction is waiting for input from the user, the program could<br />
enter text into some fields and continue the transaction, in this example we<br />
simply end the transaction by sending PF3 to <strong>CICS</strong>.<br />
’Send PF3 back to <strong>CICS</strong> to end CESN<br />
Screen.SetAID cclPF3<br />
Terminal.Send Session<br />
’Output the text from a 3270 field<br />
Set Field = Screen.FieldByIndex(1)<br />
List1.AddItem Field.Text<br />
End Sub<br />
Chapter 9. Programming in COM 151
Guide to COM <strong>CICS</strong> EPI<br />
Lastly the terminal should be disconnected, and the EPI terminated. The order<br />
in which this is done is very important.<br />
Sub EPIDone_Click()<br />
Term.Disconnect<br />
’Delete the EPI COM objects<br />
Set Field = Nothing<br />
Set Screen = Nothing<br />
Set Session = Nothing<br />
Set Terminal = Nothing<br />
Set EPI = Nothing<br />
End Sub<br />
EPI call synchronization types<br />
The Client daemon EPI COM classes support synchronous (“blocking”) and<br />
deferred synchronous (“polling”) protocols. The Visual Basic environment<br />
does not support the asynchronous calls that are available in the C++ classes.<br />
In the previous example a Session object was used with the default<br />
synchronization type of cclSync. When this Session object was used as the first<br />
parameter on Terminal.Start or Terminal.Send, a synchronous link call was<br />
made to <strong>CICS</strong>. The Visual Basic program was then blocked until the reply was<br />
received from <strong>CICS</strong>. When the call returned updated screen data from <strong>CICS</strong><br />
was immediately available in the Screen object.<br />
To make a deferred synchronous call you use the Session.SetSyncType<br />
method to set the Session to cclDSync. When this Session object is used on a<br />
Terminal.Start or Terminal.Send call, the screen contents are transmitted to<br />
<strong>CICS</strong> as 3270 datastream, but the method returns immediately. This allows the<br />
Visual Basic program to continue other tasks, including user interactions,<br />
while the <strong>CICS</strong> server transaction is running. Further 3270 screen updates<br />
from <strong>CICS</strong> must be retrieved later using the Poll method on the Terminal<br />
object:<br />
Sub EPIDSync_Click()<br />
’Create a session object (deferred synchronous)<br />
Set Session = New CclOSession<br />
Session.SetSyncType cclDSync<br />
Terminal.Start Session, "CESN", ""<br />
End Sub<br />
The transaction is now in progress in the <strong>CICS</strong> server. At a later stage (in<br />
response to a user action, or when the Visual Basic program has completed<br />
some other task) the Terminal.PollForReply method is used to collect the<br />
reply from <strong>CICS</strong>:<br />
152 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Sub EPIReply_Click()<br />
If terminal.State cclDiscon And terminal.State cclError Then<br />
If terminal.PollForReply Then<br />
’Screen has been updated, output some fields<br />
Set Screen = Terminal.Screen<br />
Set Field = Screen.FieldByIndex(1)<br />
List1.AddItem Field.Text<br />
Else<br />
List1.AddItem "No Reply from <strong>CICS</strong> yet"<br />
End If<br />
End If<br />
End Sub<br />
A <strong>CICS</strong> server transaction may send more than one reply in response to a<br />
Terminal.Start or Terminal.Send call. More than one Terminal.PollForReply<br />
call may therefore be needed to collect all the replies. Use the Terminal.State<br />
method to find out if further replies are expected. If there are, the value<br />
returned will be cclServer.<br />
<strong>CICS</strong> Server Information<br />
The EPI COM class provides the names and descriptions of <strong>CICS</strong> servers<br />
configured in the <strong>Gateway</strong> initialization file.<br />
An EPI object is created as in the previous examples, and a list of <strong>CICS</strong> server<br />
names and their descriptions is output to a listbox “List1”:<br />
Sub EPIServers_Click()<br />
Dim I<br />
’Instantiate <strong>CICS</strong> EPI object<br />
Set EPI = New CclOEPI<br />
’List <strong>CICS</strong> server information<br />
For I = 1 To EPI.ServerCount<br />
List1.AddItem EPI.ServerName(I)<br />
List1.AddItem EPI.ServerDesc(I)<br />
Next<br />
Guide to COM <strong>CICS</strong> EPI<br />
Using BMS Map data with EPI COM classes<br />
Many <strong>CICS</strong> server programs use Basic Mapping Support (BMS) to implement<br />
their 3270 screen designs. The server programs can then use symbolic names<br />
for the individual screen maps and for the 3270 fields on those maps. If the<br />
BMS source files are available, they can be copied to the Client daemon<br />
development environment and used in the implementation of a Visual Basic<br />
EPI program.<br />
The <strong>CICS</strong> BMS Conversion Utility (<strong>CICS</strong>BMSC.EXE) provided with the Client<br />
daemon produces a Visual Basic definitions file (a .BAS file) from the source<br />
BMS file (.BMS file). This definitions file can then be included in a Visual Basic<br />
program, and the same symbolic names used to identify maps and their fields<br />
in the server program can be used in the client program with the EPI Map<br />
COM class.<br />
Chapter 9. Programming in COM 153
Guide to COM <strong>CICS</strong> EPI<br />
The /B option should be specified when running the conversion utility to<br />
produce Visual Basic definitions:<br />
<strong>CICS</strong>BMSC /B .BMS<br />
Running the conversion utility on the BMS file for the supplied sample server<br />
program EPIINQ (contained in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> samples<br />
subdirectory) produces the following Visual Basic definitions:<br />
Public Const MAPINQ = xx.xx.xx.xx.xx.xx.xx<br />
Public Const MAPINQ1_PRODNAM = xx<br />
Public Const MAPINQ1_APPLID = xx<br />
Public Const MAPINQ1_TIME = xx<br />
The first constant MAPINQ1 identifies the map and provides information<br />
describing the position, size and layout of the map, remaining constants<br />
define the named fields within the map.<br />
The following example shows how to use the Map COM class to access fields<br />
by their BMS symbolic names:<br />
Dim EPI As CclOEPI<br />
Dim Terminal As CclOTerminal<br />
Dim Session As CclOSession<br />
Dim Screen As CclOScreen<br />
Dim Map as CclOMap<br />
Dim Field As CclOField<br />
First the EPI is initialized and a 3270 terminal connection to <strong>CICS</strong> is started as<br />
in the earlier example:<br />
Sub EPIConnect_Click()<br />
’Create Ccl.EPI first to initialize EPI<br />
Set EPI = New CclOEPI<br />
’Create a terminal object and connect to <strong>CICS</strong><br />
Set Terminal = New CclOTerminal<br />
Terminal.Connect "<strong>CICS</strong>NAME","",""<br />
’Create a session object (defaults to synchronous)<br />
Set Session = New CclOSession<br />
End Sub<br />
Then the BMS application is started. This example uses a transaction code<br />
“EPIC” which runs the <strong>CICS</strong> supplied server program EPIINQ:<br />
Sub EPIRunBMS_Click()<br />
Terminal.Start Session, "EPIC", ""<br />
Set Screen = Terminal.Screen<br />
At this point the <strong>CICS</strong> server program has returned the first screen to the<br />
client. This is expected to be a known map “MAPINQ1” so we create a Map<br />
object, and use the Map.Validate method to initialize it and to verify that we<br />
154 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
eceived the expected 3270 screen. Fields can then be accessed using the<br />
Map.FieldByName method:<br />
Set Map = New CclOMap<br />
If (Map.Validate(Screen,MAPINQ1)) Then<br />
Set Field = Map.FieldByName(MAPINQ1_PRODNAM)<br />
List1.AddItem Field.Text<br />
Set Field = Map.FieldByName(MAPINQ1_TIME)<br />
List1.AddItem Field.Text<br />
Else<br />
List1.Text= "Unexpected screen data"<br />
End If<br />
A more complex application would then enter data into selected fields, set the<br />
required AID key (Enter, Clear, PF or PA key) and navigate through further<br />
screens as required. The client application can mix the use of the Screen COM<br />
class (and its FieldByIndex and FieldByPosition methods) with the use of the<br />
Map COM class.<br />
Connecting to <strong>CICS</strong> 3270 applications using VBScript<br />
This is again very similar to Visual Basic but differs in how you create the<br />
objects. You do not need to have to Dim your variables but it is good coding<br />
practice to do so. As with Visual basic COM objects do not support DBCS<br />
fields in the 3270 datastreams. To create objects you must use the<br />
CreateObject function, for example:<br />
Sub EPIConnect_Click()<br />
’ Create Ccl.EPI first to initialise EPI<br />
Set EPI = CreateObject("Ccl.EPI")<br />
’ Create a terminal object and connect to <strong>CICS</strong><br />
Set Terminal = CreateObject("Ccl.Terminal")<br />
Terminal.Connect "<strong>CICS</strong>NAME","",""<br />
’ Create a session object (defaults to synchronous)<br />
Set Session = CreateObject("Ccl.Session")<br />
End Sub<br />
In a similar manner, to create a Map object you issue<br />
Set Map = CreateObject("Ccl.MAP")<br />
Screen objects and Fields Objects are created for you.<br />
Guide to COM <strong>CICS</strong> EPI<br />
Support for Automatic <strong>Transaction</strong> Initiation (ATI)<br />
The <strong>CICS</strong> server API call EXEC <strong>CICS</strong> START allows a server program to start<br />
a transaction on a particular terminal. This mechanism, called Automatic<br />
<strong>Transaction</strong> Initiation (ATI), requires additional programming at the client side<br />
to handle the interaction between these transactions and normal<br />
client-initiated transactions.<br />
Chapter 9. Programming in COM 155
Guide to COM <strong>CICS</strong> EPI<br />
Client applications can control whether ATI transactions are allowed by using<br />
the setATI and queryATI methods on the Terminal COM class. The default<br />
setting is for ATIs to be disabled. The following code fragment shows how to<br />
enable ATIs for a particular terminal:<br />
// Create terminal connection to <strong>CICS</strong> server<br />
Dim terminal as CclOTerminal<br />
Set terminal = new CclOTerminal<br />
terminal.details "MYSERVER","",""<br />
terminal.setATI CclATIEnabled<br />
The Client daemon queues ATIs for a terminal while a transaction is in<br />
progress. The Ccl Terminal class runs any outstanding ATIs as soon as a<br />
transaction ends, and calls Additional programming needed to handle the ATI<br />
replies, and to run ATIs before or between client-initiated transactions,<br />
depending on the call synchronization type used:<br />
Synchronous<br />
When you call the Terminal send method, any outstanding ATIs are<br />
run after the client-initiated transaction has completed. The Terminal<br />
class waits for the ATI replies then updates the CclOScreen object<br />
contents as part of the synchronous send call. If you expect an ATI to<br />
occur before or between client-initiated transactions, call the Ccl<br />
Terminal receiveATI method to wait synchronously for the ATI.<br />
Deferred synchronous<br />
After the CclTerminal Start or Send method is called for a deferred<br />
synchronous session, the Poll or PollForReply method is used to<br />
receive the replies. Outstanding ATIs are started when the last reply is<br />
received (that is on the final Poll or PollForReply method). You can<br />
also call the Poll or PollForReply method to start and receive replies<br />
for ATIs between client-initiated transactions.<br />
As the Poll or PollForReply methods can be called before or between<br />
client-initiated transactions, the receiveATI method is not needed (and<br />
is invalid) for deferred synchronous sessions.<br />
Security Management<br />
You can perform security management on servers that support Password<br />
Expiry Management. Refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration<br />
book for your operating system, for more information on supported servers<br />
and protocols.<br />
To use these features you first must have created a Terminal object and<br />
invoked the SetTerminalDefinition method to associate a userid and<br />
password with the object. The two methods available are VerifyPassword<br />
which checks the userid and password within the terminal object with the<br />
156 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Server Security System, and ChangePassword which allows you to change the<br />
password at the server. If successful, the terminal object password is updated<br />
accordingly.<br />
If either call is successful, you are returned a CclOSecAttr object. This object<br />
provides access to information such as last verified Date and Time, Expiry<br />
Date and Time and Last access Date and Time. If you query for example last<br />
verified Date, you are returned a CclOSecTime object which allows you to get<br />
the information in various formats. The following shows the use of these<br />
various objects.<br />
’ Terminal object already created called term<br />
on error goto pemhandler<br />
dim SecAttr as CclOSecAttr<br />
dim LastVerified as CclOSecTime<br />
dim lvdate as Date<br />
set SecAttr = term.VerifyPassword<br />
set LastVerified = SecAttr.LastVerifiedTime<br />
lvdate = LastVerified.GetDate<br />
strout = Format(lvdate, "hh:mm:ss, dddd, mmm d yyyy")<br />
Text1.Text = strout<br />
exit sub<br />
pemhandler:<br />
’ handle a expired password here maybe<br />
end sub<br />
Guide to COM <strong>CICS</strong> EPI<br />
Chapter 9. Programming in COM 157
Guide to COM <strong>CICS</strong> EPI<br />
158 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Part 3. Appendixes<br />
© Copyright IBM Corp. 2002 159
160 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Appendix A. ECI extensions that are environmentdependent<br />
This Appendix describes extensions to the ECI that are supported in certain<br />
environments.<br />
The Appendix is organized as follows:<br />
“Call type extensions”<br />
“Time-outs” on page 11<br />
“Fields to support ECI extensions” on page 163<br />
“Reply message formats” on page 164<br />
“ECI return notification” on page 164<br />
“Summary of input parameter requirements” on page 164.<br />
Call type extensions<br />
The following call types are for asynchronous calls.<br />
For more information about the program link calls, see Table 9 on page 164,<br />
and ECI_ASYNC call type in the C and Cobol chapter of <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Reference.<br />
For more information about the status information calls, see Table 9 on<br />
page 164, and ECI_STATE_ASYNC call type in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Reference.<br />
Asynchronous program link call, with notification by message<br />
(ECI_ASYNC_NOTIFY_MSG)<br />
This call type is available only for programs running on Windows.<br />
The calling application gets control back when the ECI accepts the request.<br />
Note that this does not indicate that the program has started to run, merely<br />
that the parameters have been validated. The request might be queued for<br />
later processing.<br />
The ECI sends a notification message to the specified window when the<br />
response is available. (For details of the message format, see “Reply message<br />
formats” on page 164.) On receipt of this notification, the calling application<br />
should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the<br />
actual response.<br />
The following fields are required parameters for notification by message:<br />
© Copyright IBM Corp. 2002 161
Environment-dependent extensions<br />
v eci_async_notify.window_handle<br />
v eci_message_id indicates the message type to be used in the notification<br />
process.<br />
eci_message_qualifier can be used as an input to provide a user-defined<br />
name for the call. It is returned as part of the notification message for the<br />
Windows environment.<br />
Asynchronous program link call, with notification by semaphore<br />
(ECI_ASYNC_NOTIFY_SEM)<br />
This call type is available only for programs running on Windows.<br />
The calling application gets control back when the ECI accepts the request.<br />
Note that this does not indicate that the program has started to run, merely<br />
that the parameters have been validated. The request might be queued for<br />
later processing.<br />
The ECI posts the specified semaphore when the response is available. On<br />
receipt of this notification, the calling application should use ECI_GET_REPLY<br />
or ECI_GET_SPECIFIC_REPLY to receive the actual response.<br />
eci_message_qualifier can be used as an input to provide a user-defined<br />
name for the call.<br />
The following field is a required parameter for notification by semaphore:<br />
v eci_async_notify.sem_handle refers to the semaphore.<br />
Asynchronous status call, with notification by message<br />
(ECI_STATE_ASYNC_MSG)<br />
This call type is available only for programs running on Windows.<br />
eci_message_qualifier can be used as an input to provide a user-defined<br />
name for the call.<br />
The ECI sends a notification message to the specified window when the<br />
response is available. (For details of the message format, see “Reply message<br />
formats” on page 164.) On receipt of this notification, the calling application<br />
should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the<br />
actual response.<br />
For details of the additional parameters relating to notification by message,<br />
see the description of the ECI_ASYNC_NOTIFY_MSG call type.<br />
Asynchronous status call, with notification by semaphore<br />
(ECI_STATE_ASYNC_SEM)<br />
This call type is available only for programs running on Windows.<br />
162 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
eci_message_qualifier can be used as an input to provide a user-defined<br />
name for the call.<br />
The ECI posts the specified semaphore when the response is available. On<br />
receipt of this notification, the calling application should use ECI_GET_REPLY<br />
or ECI_GET_SPECIFIC_REPLY to receive the actual response.<br />
The following field is a required parameter for notification by semaphore:<br />
v eci_async_notify.sem_handle refers to the semaphore.<br />
Fields to support ECI extensions<br />
Environment-dependent extensions<br />
The following fields in the ECI parameter block are to support<br />
environment-dependent extensions.<br />
eci_async_notify.window_handle<br />
(Windows environment, ECI_ASYNC_NOTIFY_MSG and<br />
ECI_STATE_ASYNC_MSG call types)<br />
The handle of the window to which the reply message will be posted.<br />
The ECI uses this field as input only.<br />
Note: eci_window_handle is a synonym for this parameter.<br />
eci_async_notify.sem_handle<br />
(Windows environment, ECI_ASYNC_NOTIFY_SEM and<br />
ECI_STATE_ASYNC_SEM call types)<br />
Windows applications should pass an event object handle.<br />
The ECI uses this field as input only.<br />
eci_async_notify.win_fields.hwnd<br />
The handle of the Windows window to which the reply message will<br />
be posted.<br />
The ECI uses this field as input only.<br />
eci_async_notify.win_fields.hinstance<br />
The Windows hInstance of the calling program as supplied during<br />
program initialization.<br />
The ECI uses this field as input only.<br />
eci_sync_wait.hwnd<br />
The handle of the window that is to be disabled during the<br />
synchronous call.<br />
The ECI uses this field as input only.<br />
Appendix A. ECI extensions that are environment-dependent 163
Environment-dependent extensions<br />
eci_message_id<br />
(Windows environment, ECI_ASYNC_NOTIFY_MSG and<br />
ECI_STATE_ASYNC_MSG call types)<br />
The message identifier to be used for posting the reply message to the<br />
window specified in the relevant window handle.<br />
The ECI uses this field as input only.<br />
Reply message formats<br />
When an application makes an asynchronous call requesting notification by<br />
message, the ECI returns the result in a message to a window using the<br />
specified window handle and message identifier.<br />
ECI return notification<br />
For Windows, the message is divided into two parameters, as follows:<br />
wParam<br />
High-order 16 bits<br />
Specified message qualifier<br />
Low-order 16 bits<br />
Return code<br />
lParam<br />
4-character abend code, if applicable<br />
Table 9. <strong>CICS</strong>_ExternalCall return codes — environment-dependent extensions<br />
Return code Meaning<br />
ECI_ERR_NULL_WIN_HANDLE An asynchronous call was specified with<br />
the window handle set to 0.<br />
ECI_ERR_NULL_MESSAGE_ID An asynchronous call was specified with<br />
the message identifier set to 0.<br />
ECI_ERR_NULL_SEM_HANDLE A null semaphore handle was passed<br />
when a valid handle was required.<br />
Summary of input parameter requirements<br />
Table 10 on page 166 shows the input parameters for an ECI call, and, for each<br />
call type, whether the parameters are required (R), optional (O), or not<br />
applicable (-). Where a parameter is shown as optional or not-applicable an<br />
initial field setting of nulls is recommended. An asterisk (*) immediately<br />
following an R means that further details regarding applicability are given<br />
under the description of the parameter.<br />
164 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Environment-dependent extensions<br />
The following abbreviations are used in the Parameter column:<br />
AN async_notify<br />
WF win_fields<br />
SW sync_wait<br />
Also, all named parameters have an eci_ prefix. Thus AN.WF.hwnd represents<br />
the eci_async_notify.win_fields.hwnd parameter.<br />
The following 3-character abbreviations are used for the call types in the<br />
column headings of the table:<br />
ANM ECI_ASYNC_NOTIFY_MSG<br />
ANS ECI_ASYNC_NOTIFY_SEM<br />
SAM ECI_STATE_ASYNC_MSG<br />
SAS ECI_STATE_ASYNC_SEM<br />
SYN ECI_SYNC<br />
SSN ECI_STATE_SYNC<br />
Appendix A. ECI extensions that are environment-dependent 165
Environment-dependent extensions<br />
Table 10. Input parameters for <strong>CICS</strong>_ExternalCall — environment-dependent<br />
extensions<br />
Parameter, eci_ ANM ANS SAM SAS SYN SSN<br />
call_type R R R R R R<br />
program_name R* R* - - R* -<br />
userid R R - - R -<br />
password R R - - R -<br />
transid O O - - O -<br />
commarea O O R* R* O R*<br />
commarea_length O O R* R* O R*<br />
timeout O O O O O O<br />
extend_mode R R R R R R<br />
AN.window_handle R* - R* - - -<br />
AN.sem_handle - R - R - -<br />
AN.WF.hwnd R* - R* - - -<br />
AN.WF.hinstance R* - R* - - -<br />
SW.hwnd - - - - R* R*<br />
message_id R - R - - -<br />
message_qualifier O O O O O O<br />
luw_token R R R* R* R R*<br />
version O O O O O O<br />
system_name O O O O O O<br />
166 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
Appendix B. Sample Programs<br />
Samples are supplied in subdirectories of the \samples<br />
directory. See file samples.txt, inthe\samples directory, for<br />
details, including compilation instructions and information on compiler<br />
considerations.<br />
For each language, different levels of sample are provided. These include<br />
v A simple sample to allow you to test that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is<br />
functioning and to give you a feel for the basic requirements of a Client<br />
application.<br />
v More complex samples that demonstrate advanced API features, and<br />
provide a more realistic example of a Client application.<br />
As far as possible the sample code adheres to the language standards, for<br />
example, ANSI C. The samples are all driven from the command line to avoid<br />
any dependence on platform-specific GUI code.<br />
For information on the languages and compilers supported on each <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> platform, refer to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Administration book for your operating system.<br />
© Copyright IBM Corp. 2002 167
168 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
Appendix C. ECI and EPI exits<br />
This Appendix describes exits you can add to the EPI and ECI when using<br />
Client daemon. The exits allow you to influence the processing of ECI and EPI<br />
calls for certain application requests.<br />
The Appendixt is organized as follows:<br />
“Installing the exits”<br />
“Writing your own user exits” on page 171<br />
“How the exit routines are described in the reference sections” on page 171<br />
“ECI exits reference” on page 171<br />
“Diagnostic information” on page 203<br />
“<strong>CICS</strong>TERM, <strong>CICS</strong>PRNT and the EPI exits” on page 203<br />
Installing the exits<br />
During ECI and EPI initialization, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> attempts to load<br />
the objects described in Table 11 from the \bin subdirectory,<br />
and to call the corresponding entry points.<br />
Table 11. ECI and EPI exits<br />
Object name Entry point name<br />
ECI <strong>CICS</strong>ECIX <strong>CICS</strong>_EciExitInit<br />
EPI <strong>CICS</strong>EPIX <strong>CICS</strong>_EpiExitInit<br />
Each entry point is passed a single parameter, a pointer to a structure that<br />
contains a list of addresses. The initialization code of the program puts the<br />
addresses of all the exits into the structure, and then the exits are called at<br />
appropriate points in ECI and EPI processing. Because the exits are entered by<br />
using the addresses supplied, you may give the exits any valid names. In this<br />
book, conventional names are used for the exits.<br />
If the objects are not found, no exit processing occurs.<br />
Four sample user exit files are supplied: ecix1.c, ecix2.c, epix1.c, and<br />
epix2.c in:<br />
v \samples\c\exits on Windows<br />
v /samples/c on UNIX operating systems<br />
© Copyright IBM Corp. 2002 169
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
ECI and EPI exits<br />
These exits allow server aliases to be used. They redirect requests to a server<br />
other than that specified by the Client application. See file<br />
\samples\samples.txt for more details about the samples, and<br />
how to edit them for your system. To install the samples:<br />
1. make any required changes to the details of servers and aliases<br />
2. to make files <strong>CICS</strong>ECIX and <strong>CICS</strong>EPIX:<br />
v on Windows, run ecix1mak.cmd and epix1mak.cmd<br />
v on UNIX operating systems, run csamp.mak<br />
3. copy <strong>CICS</strong>ECIX and <strong>CICS</strong>EPIX to the \bin subdirectory<br />
The following files are also supplied with your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to<br />
help with programming the exits. Unless otherwise specified, the path to the<br />
files is \samples\c\exits on Windows systems,<br />
/samples/c on UNIX systems.<br />
cicsecix.h<br />
A header file in the \include directory that defines:<br />
v inputs and outputs for each ECI exit<br />
v the format of the list of addresses for calling ECI exits<br />
v data structures used by ECI exits<br />
v return code values for ECI exits.<br />
cicsepix.h<br />
A header file in the \include directory that defines:<br />
v inputs and outputs for each EPI exit<br />
v the format of the list of addresses for calling EPI exits<br />
v data structures used by EPI exits<br />
v return code values for EPI exits.<br />
ecix1.c A template that you can use to write your own ECI user exits. It does<br />
not perform any actions if you compile it.<br />
epix1.c<br />
A template that you can use to write your own EPI user exits. It does<br />
not perform any actions if you compile it.<br />
Note: If you write a user-exit DLL, you must include all exits, apart from the<br />
following:<br />
v <strong>CICS</strong>_EciSetProgramAlias is optional.<br />
v Include either <strong>CICS</strong>_EpiTermIdExit or <strong>CICS</strong>_EpiTermIdInfoExit.<br />
New DLLs should use <strong>CICS</strong>_EpiTermIdInfoExit.<br />
170 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Writing your own user exits<br />
Follow these rules:<br />
v Do not make EPI or ECI calls from the exit.<br />
v To minimize the impact on performance, keep executable code to a<br />
minimum.<br />
v Ensure that all your exit code is re-entrant and thread-safe.<br />
v Name the primary entry points as follows:<br />
ECI <strong>CICS</strong>_ECIEXITINIT<br />
EPI <strong>CICS</strong>_EPIEXITINIT<br />
You may change the names of the actual exits; do not change the parameter<br />
lists.<br />
v Ensure that your user exit programs contain valid entry points for all of the<br />
user exit functions, with the exception of <strong>CICS</strong>_EciSetProgramAliasExit,<br />
which is optional.<br />
How the exit routines are described in the reference sections<br />
The exit routines are described under the following headings:<br />
v Purpose—describes the kind of processing that the exit is intended to<br />
perform.<br />
v When called—describes where in ECI or EPI processing the exit is called.<br />
v Parameters—describes the parameters supplied to the exit. Parameters are<br />
classified as follows:<br />
– Input—the exit may look at it, but must not change it.<br />
– Output—the exit must not look at it, but must store a value in it.<br />
– Input-output—the exit may look at it, and may store a value in it.<br />
v Return codes—describes the possible values the exit can return to the ECI<br />
or EPI. In each case the subsequent behavior of the ECI or EPI is described.<br />
ECI exits reference<br />
In this section the following exits are discussed:<br />
v <strong>CICS</strong>_EciInitializeExit<br />
v <strong>CICS</strong>_EciTerminateExit<br />
v <strong>CICS</strong>_EciExternalCallExit1<br />
v <strong>CICS</strong>_EciExternalCallExit2<br />
v <strong>CICS</strong>_EciSystemIdExit<br />
v <strong>CICS</strong>_EciDataSendExit<br />
v <strong>CICS</strong>_EciDataReturnExit<br />
v <strong>CICS</strong>_EciSetProgramAliasExit<br />
ECI and EPI exits<br />
Appendix C. ECI and EPI exits 171
ECI exits<br />
Table 12 summarizes the exit names, the parameters passed to each exit, and<br />
the possible return codes.<br />
Table 12. Summary of ECI exits<br />
Function name Parameters Return codes:<br />
<strong>CICS</strong>_EciInitializeExit <strong>Version</strong> <strong>CICS</strong>_EXIT_OK<br />
Anchor <strong>CICS</strong>_EXIT_NO_EXIT<br />
<strong>CICS</strong>_EXIT_CANT_INIT_EXITS<br />
user-defined<br />
<strong>CICS</strong>_EciTerminateExit Anchor <strong>CICS</strong>_EXIT_OK<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong>_EXIT_BAD_STORAGE<br />
user-defined<br />
<strong>CICS</strong>_EciExternalCallExit1 Anchor <strong>CICS</strong>_EXIT_OK<br />
Token<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
ParmPtr <strong>CICS</strong>_EXIT_BAD_PARM<br />
user-defined<br />
<strong>CICS</strong>_EciExternalCallExit2 Anchor <strong>CICS</strong>_EXIT_OK<br />
Token<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
ParmPtr <strong>CICS</strong>_EXIT_BAD_PARM<br />
user-defined<br />
<strong>CICS</strong>_EciSystemIdExit Anchor <strong>CICS</strong>_EXIT_OK<br />
Token<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
ParmPtr <strong>CICS</strong>_EXIT_BAD_PARM<br />
Reason <strong>CICS</strong>_EXIT_GIVE_UP<br />
user_defined<br />
<strong>CICS</strong>_EciDataSendExit Anchor <strong>CICS</strong>_EXIT_OK<br />
Token<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
user_defined<br />
<strong>CICS</strong>_EciDataReturnExit Anchor <strong>CICS</strong>_EXIT_OK<br />
Token<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
ParmPtr <strong>CICS</strong>_EXIT_BAD_PARM<br />
user_defined<br />
<strong>CICS</strong>_EciSetProgramAliasExit Anchor <strong>CICS</strong>_EXIT_OK<br />
EciParms <strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
Program <strong>CICS</strong>_EXIT_BAD_PARM<br />
user_defined<br />
Identification token<br />
In order for the exits to be able to relate calls for the same ECI request, an<br />
identification token is passed in as a parameter to all exits except<br />
<strong>CICS</strong>_EciInitializeExit and <strong>CICS</strong>_EciTerminateExit. The token is the same for<br />
<strong>CICS</strong>_EciExternalCallExit1 and <strong>CICS</strong>_EciExternalCallExit2 that relate to the<br />
same call, and on intervening <strong>CICS</strong>_EciDataSendExit,<br />
172 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
ECI exits<br />
<strong>CICS</strong>_EciDataReturnExit, and <strong>CICS</strong>_EciSystemIdExit exits. (Note that<br />
<strong>CICS</strong>_EciExternalCallExit1 and <strong>CICS</strong>_EciExternalCallExit2 are not called for<br />
a reply solicitation request.)<br />
The token is unique within the operating system that initiated the request, for<br />
the duration of the request. It may be reused once the last exit for the request<br />
has been called.<br />
In the case of an extended logical unit of work, the token may be different on<br />
different requests within the logical unit of work. (Since we allow reuse of the<br />
token, and a new program link call may not be made until the<br />
ECI_GET_REPLY request for the previous asynchronous request has<br />
completed, it may also be the same.)<br />
The token is 8 bytes long. 8 null bytes is not a valid value for the token and is<br />
not supplied to the exits.<br />
Process model implementation<br />
All exits that relate to a particular request (i.e. have the same identification<br />
token) are called in the context of the application process.<br />
Appendix C. ECI and EPI exits 173
ECI exits<br />
<strong>CICS</strong>_EciInitializeExit<br />
Function name:<br />
<strong>CICS</strong>_EciInitializeExit<br />
Parameters<br />
<strong>Version</strong><br />
Anchor<br />
Purpose: To allow the user to set up an exit environment.<br />
When called: On the first invocation of <strong>CICS</strong>_ExternalCall, for each process,<br />
after parameter validation has occurred.<br />
Parameters:<br />
<strong>Version</strong> Input parameter. The version of the ECI under which the exit<br />
is running.<br />
Anchor Output parameter. A pointer to a pointer that will be passed<br />
to the ECI exits. The second pointer is not used by the ECI; it<br />
is passed to the exits as supplied. You can acquire storage in<br />
this exit and pass its address to the other exits.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI continues processing this request, calling the exits where<br />
appropriate.<br />
<strong>CICS</strong>_EXIT_NO_EXIT<br />
The ECI continues processing this request, but does not call any more<br />
exits.<br />
<strong>CICS</strong>_EXIT_CANT_INIT_EXITS<br />
The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace record, and then<br />
continues processing this request, but does not call any more exits.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues processing this request, but does not<br />
call any more exits.<br />
174 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EciTerminateExit<br />
Function name:<br />
<strong>CICS</strong>_EciTerminateExit<br />
Parameters<br />
Anchor<br />
Purpose: To allow the user to clean up the exit environment. Any storage<br />
acquired by <strong>CICS</strong>_EciInitializeExit must be released in this exit.<br />
<strong>CICS</strong>_EciTerminateExit is not called by the Client daemon.<br />
When called: On termination of the process that issued the<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Parameters:<br />
Anchor<br />
Input parameter. The pointer set up by <strong>CICS</strong>_EciInitializeExit.<br />
ECI exits<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
Termination continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues with<br />
termination.<br />
<strong>CICS</strong>_EXIT_BAD_STORAGE<br />
<strong>CICS</strong> detected a storage error. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> trace record, and then continues with termination.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues with termination.<br />
Appendix C. ECI and EPI exits 175
ECI exits<br />
<strong>CICS</strong>_EciExternalCallExit1<br />
Function name:<br />
<strong>CICS</strong>_EciExternalCallExit1<br />
Parameters:<br />
Anchor<br />
Token<br />
ParmPtr<br />
Purpose: To allow the user to pick the best system to run the program. This<br />
exit is called exactly once on each program link and each status information<br />
call. It is not called on a reply solicitation call. Although the exit is called<br />
when eci_luw_token is not zero, any change it makes to eci_system_name is<br />
ignored, as the server was selected when the logical unit of work was started.<br />
When called: On invocation of <strong>CICS</strong>_ExternalCall, for each program link<br />
call and each status information call, after the ECI has validated the<br />
parameters.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Token Input parameter. The identification token established by the<br />
ECI for this request.<br />
ParmPtr Input parameter. A pointer to the ECI parameter block. The<br />
exit must treat all fields in the ECI parameter block as inputs,<br />
except the eci_system_name field, which it may change.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI continues to process the request with the eci_system_name<br />
now specified in the ECI parameter block.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues to process the<br />
request with the eci_system_name now specified in the ECI parameter<br />
block.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues to process the<br />
request with the eci_system_name now specified in the ECI parameter<br />
block.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
176 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
trace record, and then continues to process the request with the<br />
eci_system_name now specified in the ECI parameter block.<br />
ECI exits<br />
Notes: There is a limited set of conditions under which the exit may select a<br />
new system. The exit may select a system if the call is a program link or<br />
status information call, and if a new logical unit of work is being started. In<br />
other cases, the exit should return <strong>CICS</strong>_EXIT_OK.<br />
If the calling application has put binary zeros as the system name in the<br />
parameter block, then the application is expecting that the system will be<br />
dynamically selected, and the exit may safely select the system.<br />
If however the calling application has placed a system name in the parameter<br />
block, or if the application is a version 0 application, then it may not be<br />
expecting the target system to change, and application errors could result. In<br />
this case the exit would generally return without specifying a replacement<br />
system, with the result that the specified or default system name is to be used.<br />
If the exit chooses to change the selected system in this situation, then it may<br />
do so, but the following should be borne in mind.<br />
v The exit routine must be sensitive to whether or not the modification of the<br />
target system will cause errors in the ECI application running on the client.<br />
v The exit routine must maintain a knowledge base, keyed on appropriate<br />
data available to it, to enable it to determine whether this modification is<br />
acceptable to the client application.<br />
Appendix C. ECI and EPI exits 177
ECI exits<br />
<strong>CICS</strong>_EciExternalCallExit2<br />
Function name:<br />
<strong>CICS</strong>_EciExternalCallExit2<br />
Parameters:<br />
Anchor<br />
Token<br />
ParmPtr<br />
Purpose: To allow the user to see the results of synchronous ECI calls for<br />
information gathering purposes only. This exit is called exactly once on every<br />
application program link or status information call. It is not called on reply<br />
solicitation calls.<br />
When called: Before the ECI call returns to the application, and after the<br />
return data is filled into the ECI parameter block.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Token Input parameter. The identification token established by the<br />
ECI for this request.<br />
ParmPtr Input parameter. A pointer to the ECI parameter block. The<br />
exit must treat all fields in the ECI parameter block as inputs.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI returns control to the application that issued the<br />
<strong>CICS</strong>_ExternalCall request.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then returns control to the<br />
application that issued the <strong>CICS</strong>_ExternalCall request.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then returns control to the<br />
application that issued the <strong>CICS</strong>_ExternalCall request.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then returns control to the application that issued<br />
the <strong>CICS</strong>_ExternalCall request.<br />
178 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EciSystemIdExit<br />
Function name:<br />
<strong>CICS</strong>_EciSystemIdExit<br />
Parameters:<br />
Anchor<br />
Token<br />
ParmPtr<br />
Reason<br />
ECI exits<br />
Purpose: To allow the user to supply a new system name when the name<br />
supplied in the ECI parameter block is not valid.<br />
When called: This exit is called when an error occurs that may be corrected<br />
by selection of a new system, userid, or password. This would be when the<br />
ECI has returned one of the following codes:<br />
v ECI_ERR_NO_<strong>CICS</strong><br />
v ECI_ERR_UNKNOWN_SERVER<br />
v ECI_ERR_SECURITY_ERROR<br />
v ECI_ERR_SYSTEM_ERROR<br />
v ECI_ERR_RESOURCE_SHORTAGE<br />
v ECI_ERR_MAX_SYSTEMS.<br />
It may be called when either when the Client daemon detects an error before<br />
data is sent to the server, or after data returns from the server.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Token Input parameter. The identification token established by the<br />
ECI for this request.<br />
ParmPtr Input parameter. A pointer to the ECI parameter block. The<br />
exit must treat all fields in the ECI parameter block as inputs,<br />
except the following, which it may set:<br />
v eci_system_name<br />
v eci_userid<br />
v eci_password.<br />
Reason Input parameter. The reason code that explains why the<br />
application request has not so far succeeded.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI retries the application call using the new parameters in the<br />
ECI parameter block. (The <strong>CICS</strong> program communication area<br />
Appendix C. ECI and EPI exits 179
ECI exits<br />
supplied by the application to the <strong>CICS</strong>_ExternalCall is preserved.)<br />
The application callback routine will not be called, nor will<br />
<strong>CICS</strong>_EciExternalCallExit2.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then returns to the application<br />
that issued the <strong>CICS</strong>_ExternalCall request.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then returns to the application<br />
that issued the <strong>CICS</strong>_ExternalCall request.<br />
<strong>CICS</strong>_EXIT_GIVE_UP<br />
The ECI returns to the application that issued the <strong>CICS</strong>_ExternalCall<br />
request.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then retries the application call as described for<br />
<strong>CICS</strong>_EXIT_OK.<br />
180 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EciDataSendExit<br />
Function name:<br />
<strong>CICS</strong>_EciDataSendExit<br />
Parameters:<br />
Anchor<br />
Token<br />
Purpose: To allow the user to time calls for performance analysis.<br />
ECI exits<br />
When called: As close as possible to the time that the request will be sent to<br />
the server.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Token Input parameter. The identification token established by the<br />
ECI for this request.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI continues processing the request.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues processing the request.<br />
Appendix C. ECI and EPI exits 181
ECI exits<br />
<strong>CICS</strong>_EciDataReturnExit<br />
Function name:<br />
<strong>CICS</strong>_EciDataReturnExit<br />
Parameters:<br />
Anchor<br />
Token<br />
ParmPtr<br />
Purpose: To allow the user to time calls for performance analysis.<br />
When called: As close as possible to the time that the response from the<br />
server has been received, and the ECI block and commarea data for eventual<br />
return to the application has been built. It is also called if there is a timeout<br />
because of a lack of response from the server.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
Token Input parameter. The identification token established by the<br />
ECI for this request.<br />
ParmPtr Input parameter. A pointer to the ECI parameter block. The<br />
exit must treat all fields in the ECI parameter block as inputs.<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI continues processing the request.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues processing the request.<br />
182 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EciSetProgramAliasExit<br />
Function name:<br />
<strong>CICS</strong>_EciSetProgramAliasExit<br />
Parameters:<br />
Anchor<br />
EciParms<br />
Program<br />
Purpose: To allow the user to change the program name that the WorkLoad<br />
Manager of <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows uses for load balancing<br />
This exit is only available when the WorkLoad Manager is enabled.<br />
When called: Immediately before the WorkLoad Manager tries to select a<br />
server for an ECI program to connect to.<br />
Parameters:<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EciInitializeExit.<br />
ECIParms ECI parameter block.<br />
Program The alias name of the ECI program that the WorkLoad<br />
Manager will use for load balancing.<br />
ECI exits<br />
Return codes:<br />
<strong>CICS</strong>_EXIT_OK<br />
The ECI continues processing the request.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The ECI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues processing the<br />
request.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The ECI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues processing the request.<br />
Appendix C. ECI and EPI exits 183
EPI exits<br />
EPI exits reference<br />
In this section the following exits are discussed:<br />
v <strong>CICS</strong>_EpiInitializeExit<br />
v <strong>CICS</strong>_EpiTerminateExit<br />
v <strong>CICS</strong>_EpiAddTerminalExit<br />
v <strong>CICS</strong>_EpiTermIdExit<br />
v <strong>CICS</strong>_EpiTermIdInfoExit<br />
v <strong>CICS</strong>_EpiStartTranExit<br />
v <strong>CICS</strong>_EpiReplyExit<br />
v <strong>CICS</strong>_EpiDelTerminalExit<br />
v <strong>CICS</strong>_EpiGetEventExit<br />
v <strong>CICS</strong>_EpiSystemIdExit<br />
v <strong>CICS</strong>_EpiTranFailedExit<br />
Table 13 summarizes the exit names, the parameters passed to each exit, and<br />
the possible return codes.<br />
Table 13. Summary of EPI exits<br />
Function name Parameters Return codes:<br />
<strong>CICS</strong>_EpiInitializeExit <strong>Version</strong><br />
<strong>CICS</strong>_EXIT_OK<br />
Anchor<br />
<strong>CICS</strong>_EXIT_NO_EXIT<br />
<strong>CICS</strong>_EXIT_CANT_INIT_EXITS<br />
user-defined<br />
<strong>CICS</strong>_EpiTerminateExit Anchor <strong>CICS</strong>_EXIT_OK<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong>_EXIT_BAD_STORAGE<br />
user-defined<br />
<strong>CICS</strong>_EpiAddTerminalExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
NameSpace <strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL<br />
System<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
NetName<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
DevType<br />
user-defined<br />
<strong>CICS</strong>_EpiTermIdExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
TermIndex<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
System<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
user-defined<br />
<strong>CICS</strong>_EpiTermIdInfoExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
<strong>Version</strong><br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
TermIndex<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
EpiDetails<br />
user-defined<br />
<strong>CICS</strong>_EpiStartTranExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
TransId<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
Data<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
Size<br />
user-defined<br />
184 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Table 13. Summary of EPI exits (continued)<br />
Function name Parameters Return codes:<br />
<strong>CICS</strong>_EpiReplyExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
TermIndex<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
Data<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
Size<br />
user_defined<br />
<strong>CICS</strong>_EpiDelTerminalExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
TermIndex<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
user_defined<br />
<strong>CICS</strong>_EpiGetEventExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
TermIndex<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
Wait<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
Event<br />
user_defined<br />
<strong>CICS</strong>_EpiSystemIdExit Anchor<br />
<strong>CICS</strong>_EXIT_OK<br />
NameSpace <strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL<br />
System<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
NetName<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
DevType<br />
FailedSystem<br />
Reason<br />
SubReason<br />
UserId<br />
PassWord<br />
user_defined<br />
<strong>CICS</strong>_EpiTranFailedExit Anchor<br />
TermIndex<br />
Wait<br />
Event<br />
<strong>CICS</strong>_EXIT_OK<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
user_defined<br />
EPI exits<br />
Appendix C. ECI and EPI exits 185
EPI exits<br />
<strong>CICS</strong>_EpiInitializeExit<br />
Function name:<br />
<strong>CICS</strong>_EpiInitializeExit<br />
Parameters:<br />
<strong>Version</strong><br />
Anchor<br />
Purpose<br />
To allow the user to set up an exit environment.<br />
When called<br />
On each invocation of <strong>CICS</strong>_EpiInitialize, after the EPI has validated the<br />
parameters.<br />
Parameters<br />
<strong>Version</strong> Input parameter. The version of the EPI under which the exit<br />
is running.<br />
Anchor Output parameter. A pointer to a pointer that will be passed<br />
to the EPI exits. The second pointer is not used by the EPI; it<br />
is passed to the exits as supplied. You can acquire storage in<br />
this exit and pass its address to the other exits.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
The EPI continues processing this request, calling the exits where<br />
appropriate.<br />
<strong>CICS</strong>_EXIT_NO_EXIT<br />
The EPI continues processing this request, but does not call any more<br />
exits.<br />
<strong>CICS</strong>_EXIT_CANT_INIT_EXITS<br />
The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> trace record, and then<br />
continues processing this request, but does not call any more exits.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues processing this request, but does not<br />
call any more exits.<br />
186 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EpiTerminateExit<br />
Function name:<br />
<strong>CICS</strong>_EpiTerminateExit<br />
Parameters:<br />
Anchor<br />
Purpose<br />
To allow the user to clean up the exit environment. Any storage acquired by<br />
<strong>CICS</strong>_EpiInitializeExit must be released in this exit.<br />
When called<br />
On each invocation of <strong>CICS</strong>_EpiTerminate, after the EPI has validated the<br />
parameters.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
EPI exits<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Termination continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues with<br />
termination.<br />
<strong>CICS</strong>_EXIT_BAD_STORAGE<br />
<strong>CICS</strong> detected a storage error. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> trace record, and then continues with termination.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues with termination.<br />
Appendix C. ECI and EPI exits 187
EPI exits<br />
<strong>CICS</strong>_EpiAddTerminalExit<br />
Function name:<br />
<strong>CICS</strong>_EpiAddTerminalExit<br />
Parameters:<br />
Anchor<br />
NameSpace<br />
System<br />
NetName<br />
DevType<br />
Purpose<br />
To allow the user to select a server, or override the one passed to<br />
<strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal in the System parameter.<br />
When called<br />
On each invocation of <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal,<br />
after the EPI has validated the parameters.<br />
Parameters<br />
Anchor Input parameter. The pointer storage set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
NameSpace Input-output parameter. On input, its value depends on the<br />
value supplied for the NameSpace parameter of the<br />
<strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal call to<br />
which this exit relates:<br />
v If a null pointer was supplied, this input is a pointer to a<br />
null string.<br />
v If a non-null pointer was supplied, the Namespace input<br />
parameter points to a copy of this data.<br />
On output, it will be used by the EPI in the same way as the<br />
value specified on the call would have been used.<br />
System Input-output parameter. On input, it is the value supplied for<br />
the System parameter of the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call to which this exit relates. On<br />
output, it will be used by the EPI in the same way as the<br />
value specified on the call would have been used.<br />
NetName Input-output parameter. On input, it is the value supplied for<br />
the NetName parameter of the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call to which this exit relates. On<br />
output, it will be used by the EPI in the same way as the<br />
value specified on the call would have been used.<br />
DevType Input-output parameter. On input, it is the value supplied for<br />
the DevType parameter of the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call to which this exit relates. On<br />
188 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
output, it will be used by the EPI in the same way as the<br />
value specified on the call would have been used.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing continues with the output values of NameSpace, System,<br />
NetName, and DevType.<br />
<strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL<br />
The <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal is ended<br />
with a return code of <strong>CICS</strong>_EPI_ERR_FAILED. If the application uses<br />
<strong>CICS</strong>_EpiGetSysError, the value 109 is returned in the Cause field of<br />
the <strong>CICS</strong>_EpiSysError_t structure.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues as for <strong>CICS</strong>_EXIT_OK.<br />
Notes<br />
Note on selection of systems:<br />
EPI exits<br />
If the calling application does not specify system name in its parameter list,<br />
then it is expecting that the system will be dynamically selected, and the exit<br />
may safely select the system.<br />
If however the calling application specifies a system name, then it may not be<br />
expecting the target system to change and application errors could result. In<br />
this case the exit would generally not specify a replacement system, with the<br />
result that the specified or default system name, device type, etc. is to be<br />
used. If the exit chooses to change the selected system in this situation, then it<br />
may do so, but the following should be borne in mind.<br />
v The exit routine must be sensitive to whether or not the modification of the<br />
target system will cause errors in the EPI application running on the client.<br />
v The exit routine must maintain a knowledge base, keyed on appropriate<br />
data available to it, to enable it to determine whether this modification is<br />
acceptable to the client application.<br />
Appendix C. ECI and EPI exits 189
EPI exits<br />
<strong>CICS</strong>_EpiAddTerminalExit and <strong>CICS</strong>_EpiSystemIdExit:<br />
The relationship between these exits is as follows. The exits will get multiple<br />
chances to make a selection of the system. The first chance will always occur<br />
on the <strong>CICS</strong>_EpiAddTerminalExit. This exit will only receive the parameters<br />
passed by the application to <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal. If an error occurs when <strong>CICS</strong> tries to add the<br />
terminal (whether or not the exit has made a selection) then<br />
<strong>CICS</strong>_EpiSystemIdExit will be called. <strong>CICS</strong>_EpiSystemIdExit will<br />
additionally be passed the error that occurred on the attempt to add the<br />
terminal, and will get a chance to correct the error. This continues to occur<br />
until either a terminal is successfully added, or until <strong>CICS</strong>_EpiSystemIdExit<br />
signals to give up.<br />
If no error occurs on the attempt to add the terminal, then<br />
<strong>CICS</strong>_EpiSystemIdExit will not be called.<br />
190 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EpiTermIdExit<br />
Function name:<br />
<strong>CICS</strong>_EpiTermIdExit<br />
Parameters:<br />
Anchor<br />
TermIndex<br />
System<br />
EPI exits<br />
Purpose<br />
To allow the user to know the terminal index allocated after a successfull call<br />
to <strong>CICS</strong>_EpiAddTerminal.<br />
<strong>CICS</strong>_EpiTermIdExit is provided for compatibility with older applications<br />
only. All new applications that use the EPI exits should use<br />
<strong>CICS</strong>_EpiTermIdInfoExit instead.<br />
When called<br />
On each invocation of <strong>CICS</strong>_EpiAddTerminal, after the server has allocated<br />
the terminal.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TermIndex Input parameter. This is the terminal index for the terminal<br />
resource just reserved or installed.<br />
System Input parameter. A pointer to a null-terminated string that<br />
specifies the name of the server in which the terminal resource<br />
has been reserved or installed.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues as for <strong>CICS</strong>_EXIT_OK.<br />
Appendix C. ECI and EPI exits 191
EPI exits<br />
<strong>CICS</strong>_EpiTermIdInfoExit<br />
Function name:<br />
<strong>CICS</strong>_EpiTermIdInfoExit<br />
Parameters:<br />
Anchor<br />
<strong>Version</strong><br />
TermIndex<br />
EpiDetails<br />
Purpose<br />
To allow the user to retrieve information about the current terminal.<br />
When called<br />
Immediately after a <strong>CICS</strong> terminal has been installed<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
<strong>Version</strong> Input parameter. The EPI version.<br />
TermIndex Input parameter. The index of the terminal being installed.<br />
EpiDetails Input parameter. A pointer to the <strong>CICS</strong>_EpiDetails_t<br />
structure, containing details about the terminal being installed.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then continues as for<br />
<strong>CICS</strong>_EXIT_OK.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then continues as for <strong>CICS</strong>_EXIT_OK.<br />
192 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EpiStartTranExit<br />
Function name:<br />
<strong>CICS</strong>_EpiStartTranExit<br />
Parameters:<br />
Anchor<br />
TransId<br />
Data<br />
Size<br />
Purpose<br />
To allow the user to see when a transaction is started, for information<br />
gathering purposes. This exit will not select a system, and has no return data.<br />
When called<br />
On invocation of <strong>CICS</strong>_EpiStartTran, after the EPI has validated the<br />
parameters.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TransId Input parameter. The value supplied for the TransId<br />
parameter of the <strong>CICS</strong>_EpiStartTran call to which this exit<br />
relates.<br />
Data Input parameter. The value supplied for the Data parameter<br />
of the <strong>CICS</strong>_EpiStartTran call to which this exit relates.<br />
Size Input parameter. The value supplied for the Size parameter of<br />
the <strong>CICS</strong>_EpiStartTran call to which this exit relates.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing of the <strong>CICS</strong>_EpiStartTran call continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiStartTran call continues.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiStartTran call continues.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
EPI exits<br />
Appendix C. ECI and EPI exits 193
EPI exits<br />
194 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then processing of the <strong>CICS</strong>_EpiStartTran call<br />
continues.
<strong>CICS</strong>_EpiReplyExit<br />
Function name:<br />
<strong>CICS</strong>_EpiReplyExit<br />
Parameters:<br />
Anchor<br />
TermIndex<br />
Data<br />
Size<br />
Purpose<br />
To allow the user to see when a transaction is replied to, for information<br />
gathering purposes.<br />
EPI exits<br />
When called<br />
On invocation of <strong>CICS</strong>_EpiReply, after the EPI has validated the parameters.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TermIndex Input parameter. The value supplied for the TermIndex<br />
parameter of the <strong>CICS</strong>_EpiReply call to which this exit<br />
relates.<br />
Data Input parameter. The value supplied for the Data parameter<br />
of the <strong>CICS</strong>_EpiReply call to which this exit relates.<br />
Size Input parameter. The value supplied for the Size parameter of<br />
the <strong>CICS</strong>_EpiReply call to which this exit relates.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing of the <strong>CICS</strong>_EpiReply call continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiReply call continues.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiReply call continues.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then processing of the <strong>CICS</strong>_EpiReply call<br />
continues.<br />
Appendix C. ECI and EPI exits 195
EPI exits<br />
<strong>CICS</strong>_EpiDelTerminalExit<br />
Function Name:<br />
<strong>CICS</strong>_EpiDelTerminalExit<br />
Parameters:<br />
Anchor<br />
TermIndex<br />
Purpose<br />
To allow the user to clean up any terminal-related data structures.<br />
When called<br />
On invocation of <strong>CICS</strong>_EpiDelTerminal or <strong>CICS</strong>_EpiPurgeTerminal, after the<br />
EPI has validated the parameters. To allow the user to clean up any<br />
terminal-related data structures.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TermIndex Input parameter. The value supplied for the TermIndex<br />
parameter of the <strong>CICS</strong>_EpiDelTerminal or<br />
<strong>CICS</strong>_EpiPurgeTerminal call to which this exit relates.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing of the <strong>CICS</strong>_EpiDelTerminalor <strong>CICS</strong>_EpiPurgeTerminal<br />
call continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiDelTerminal or <strong>CICS</strong>_EpiPurgeTerminal call continues.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiDelTerminal or <strong>CICS</strong>_EpiPurgeTerminal call continues.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then processing of the <strong>CICS</strong>_EpiDelTerminal or<br />
<strong>CICS</strong>_EpiPurgeTerminal call continues.<br />
196 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EpiGetEventExit<br />
Function name:<br />
<strong>CICS</strong>_EpiGetEventExit<br />
Parameters:<br />
Anchor<br />
TermIndex<br />
Wait<br />
Event<br />
Purpose<br />
To allow the user to collect data relating to the event that has arrived.<br />
When called<br />
Immediately before <strong>CICS</strong>_EpiGetEvent returns to the caller. The exit can then<br />
examine the data returned, time the response from the system, etc.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TermIndex Input parameter. The value to be returned to the application<br />
in the TermIndex parameter of the <strong>CICS</strong>_EpiGetEvent call to<br />
which this exit relates.<br />
Wait Input parameter. The value supplied for the Wait parameter of<br />
the <strong>CICS</strong>_EpiGetEvent call to which this exit relates.<br />
Event Input parameter. The value to be returned to the application<br />
in the Event parameter of the <strong>CICS</strong>_EpiGetEvent call to<br />
which this exit relates.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing of the <strong>CICS</strong>_EpiGetEvent call continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiGetEvent call continues.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiGetEvent call continues.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
EPI exits<br />
Appendix C. ECI and EPI exits 197
EPI exits<br />
198 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then processing of the <strong>CICS</strong>_EpiGetEvent call<br />
continues.
<strong>CICS</strong>_EpiSystemIdExit<br />
Function name:<br />
<strong>CICS</strong>_EpiSystemIdExit<br />
Parameters:<br />
Anchor<br />
NameSpace<br />
System<br />
NetName<br />
DevType<br />
FailedSystem<br />
Reason<br />
SubReason<br />
UserId<br />
PassWord<br />
EPI exits<br />
Purpose<br />
To allow the user to supply a new system name when the value supplied for<br />
<strong>CICS</strong>_Epi_AddTerminal or <strong>CICS</strong>_EpiAddExTerminal was invalid.<br />
When called<br />
Immediately before <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal<br />
returns to the application when an error occurred while trying to add the<br />
terminal. The error can be <strong>CICS</strong>_EPI_ERR_SYSTEM, <strong>CICS</strong>_EPI_ERR_FAILED,<br />
or <strong>CICS</strong>_EPI_ERR_SERVER_DOWN. It occurs whether or not<br />
<strong>CICS</strong>_EpiAddTerminalExit or <strong>CICS</strong>_EpiAddExTerminal has been called<br />
previously.<br />
Note: On some systems the completion of <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal is returned to the application<br />
asynchronously, and in this case this exit will be called asynchronously.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
NameSpace Input-output parameter. The NameSpace parameter used in<br />
the failed <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal.<br />
System Input-output parameter. The System parameter used in the<br />
failed <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal.<br />
NetName Input-output parameter. The NetName parameter used in the<br />
failed <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal.<br />
DevType Input-output parameter. The DevType parameter used in the<br />
failed <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal.<br />
FailedSystem Input parameter. The identifier of the system on which the<br />
failure occurred.<br />
Appendix C. ECI and EPI exits 199
EPI exits<br />
Reason Input parameter. The reason for the failure:.<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM or <strong>CICS</strong>_EPI_ERR_FAILED.<br />
SubReason Input parameter. More about the failure. If the reason is<br />
<strong>CICS</strong>_EPI_ERR_FAILED, this is the value that appears in the<br />
Cause field of the <strong>CICS</strong>_EpiSysError_t structure.<br />
UserId Output parameter. Not used.<br />
PassWord Output parameter. Not used.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
The EPI will retry the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call using the values specified as output of<br />
this exit. Note that in this case the considerations described in<br />
“<strong>CICS</strong>_EpiAddTerminalExit” on page 188 apply.<br />
<strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL<br />
The <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal is ended<br />
with a return code of <strong>CICS</strong>_EPI_ERR_FAILED. If the application uses<br />
<strong>CICS</strong>_EpiGetSysError, the value 109 is returned in the Cause field of<br />
the <strong>CICS</strong>_EpiSysError_t structure.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then the error that caused the<br />
exit to be called is returned to the application.<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then the error that caused the<br />
exit to be called is returned to the application.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then the error that caused the exit to be called is<br />
returned to the application.<br />
200 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
<strong>CICS</strong>_EpiTranFailedExit<br />
Function Name:<br />
<strong>CICS</strong>_EpiTranFailedExit<br />
Parameters:Anchor<br />
TermIndex<br />
Wait<br />
Event<br />
Purpose<br />
To allow the user to collect data when a transaction abends or a terminal fails.<br />
When called<br />
Immediately before <strong>CICS</strong>_EpiGetEvent returns to the caller, with or without<br />
GetEventExit, when the event is <strong>CICS</strong>_EPI_EVENT_END_TRAN, and the<br />
AbendCode field is not blank.<br />
Note that there are some failures on remote systems that can occur and will<br />
simply cause the presentation of a 3270 data stream with an error message<br />
and no abend code in the <strong>CICS</strong>_EPI_EVENT_END_TRAN. This error message<br />
may not even occur on the same event as the <strong>CICS</strong>_EPI_EVENT_END_TRAN.<br />
If the exit requires to handle this situation, it may monitor it through<br />
<strong>CICS</strong>_EpiGetEventExit and scan the appropriate 3270 data streams.<br />
Parameters<br />
Anchor Input parameter. The pointer set up by<br />
<strong>CICS</strong>_EpiInitializeExit.<br />
TermIndex Input parameter. The value to be returned to the application<br />
in the TermIndex parameter of the <strong>CICS</strong>_EpiGetEvent call to<br />
which this exit relates.<br />
Wait Input parameter. The value supplied for the Wait parameter of<br />
the <strong>CICS</strong>_EpiGetEvent call to which this exit relates.<br />
Event Input parameter. The value to be returned to the application<br />
in the Event parameter of the <strong>CICS</strong>_EpiGetEvent call to<br />
which this exit relates.<br />
Return codes<br />
<strong>CICS</strong>_EXIT_OK<br />
Processing of the <strong>CICS</strong>_EpiGetEvent call continues.<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR<br />
<strong>CICS</strong> detected an invalid anchor field. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiGetEvent call continues.<br />
EPI exits<br />
Appendix C. ECI and EPI exits 201
EPI exits<br />
<strong>CICS</strong>_EXIT_BAD_PARM<br />
<strong>CICS</strong> detected an invalid parameter. The EPI writes a <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> trace record, and then processing of the<br />
<strong>CICS</strong>_EpiGetEvent call continues.<br />
user-defined<br />
User-defined return codes must have a value not less than<br />
<strong>CICS</strong>_EXIT_USER_BASE. The EPI writes a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
trace record, and then processing of the <strong>CICS</strong>_EpiGetEvent call<br />
continues.<br />
202 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Diagnostic information<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> traces the input parameters to the exits<br />
immediately before they are called, and the output of the exit when the exit<br />
returns. <strong>CICS</strong> tracing is not available for use within the exit.<br />
<strong>CICS</strong>TERM, <strong>CICS</strong>PRNT and the EPI exits<br />
You can use the <strong>CICS</strong>TERM and <strong>CICS</strong>PRNT commands to drive the EPI user<br />
exits. This gives similar load balancing functionality to the Workload Manager<br />
supplied with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows. See <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Windows Administration for more information.<br />
To use the EPI exits, you supply a <strong>CICS</strong>_EPIEXITINIT function in a DLL<br />
called cicsepix.dll (cicsepix.a on UNIX operating systems). When a<br />
<strong>CICS</strong>TERM or <strong>CICS</strong>PRNT session is started, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> looks<br />
for a cicsepix.dll (cicsepix.a) inthe\bin subdirectory. If no<br />
DLL is found, no exit processing occurs.<br />
The <strong>CICS</strong>_EPIEXITINIT function sets an ExitList structure to point to the<br />
addresses of all the exit functions, which are also contained in cicsepix.dll.<br />
The sample <strong>CICS</strong>_EPIEXITINIT is as follows:<br />
void <strong>CICS</strong>EXIT <strong>CICS</strong>_EPIEXITINIT(<strong>CICS</strong>_EpiExitList_t *ExitList)<br />
{<br />
}<br />
ExitList->InitializeExit = &<strong>CICS</strong>_EpiInitializeExit;<br />
ExitList->TerminateExit = &<strong>CICS</strong>_EpiTerminateExit;<br />
ExitList->AddTerminalExit = &<strong>CICS</strong>_EpiAddTerminalExit;<br />
ExitList->StartTranExit = &<strong>CICS</strong>_EpiStartTranExit;<br />
ExitList->ReplyExit = &<strong>CICS</strong>_EpiReplyExit;<br />
ExitList->DelTerminalExit = &<strong>CICS</strong>_EpiDelTerminalExit;<br />
ExitList->GetEventExit = &<strong>CICS</strong>_EpiGetEventExit;<br />
ExitList->TranFailedExit = &<strong>CICS</strong>_EpiTranFailedExit;<br />
ExitList->SystemIdExit = &<strong>CICS</strong>_EpiSystemIdExit;<br />
ExitList->TermIdExit = &<strong>CICS</strong>_EpiTermIdExit;<br />
ExitList->TermIdInfoExit = &<strong>CICS</strong>_EpiTermIdInfoExit;<br />
EPI exits<br />
As the exits are entered by using the addresses supplied, you can give them<br />
any name you want, as long as their function signature is exactly the same as<br />
the <strong>CICS</strong>_Epi* functions. Therefore, the ExitList-> exits could be considered as<br />
generic terminal control exits.<br />
InitializeExit is passed a version number of X'FF000000' when driven by<br />
<strong>CICS</strong>TERM or <strong>CICS</strong>PRNT. This enables user programs to be able to<br />
differentiate between <strong>CICS</strong>TERM and <strong>CICS</strong>PRNT user exits, and EPI user<br />
exits if they wish to do so.<br />
Appendix C. ECI and EPI exits 203
EPI exits<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRNT also drive the EPI tracepoints.<br />
The following describes the subset of the EPI exits that are available for<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRNT and how they are implemented. How they affect<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> terminal emulator behavior is described.<br />
EPI: <strong>CICS</strong>_EpiInitializeExit<br />
This EPI exit does not affect the running of the calling EPI program,<br />
but it does allow the user to switch the user exits on or off for the<br />
process that calls it. It is called once per process that uses the EPI. It is<br />
called before any other EPI calls take place, and is called at the end of<br />
a successful <strong>CICS</strong>_EpiInitialize.<br />
<strong>CICS</strong>TERM: InitializeExit<br />
It is important that this exit is called once only for each <strong>CICS</strong>TERM<br />
session that is created, because each <strong>CICS</strong>TERM runs in a separate<br />
process. The version number passed is X'FF000000'.<br />
EPI: <strong>CICS</strong>_EpiTerminateExit<br />
Called by <strong>CICS</strong>_EpiTerminate, this is always the last EPI call in a<br />
particular process. It does not affect the running of the calling EPI<br />
program. It is called after checking that the EPI was initialized, and<br />
that there is not an active notify thread, but just before EPI is actually<br />
terminated. The EPI exit DLL is unloaded immediately following the<br />
user exit call.<br />
<strong>CICS</strong>TERM: TerminateExit<br />
Only called once during <strong>CICS</strong>TERM termination.<br />
EPI: <strong>CICS</strong>_EpiAddTerminalExit<br />
Allows the user to select a server, change the server parameters<br />
passed to the EPI call, and refuse to add a terminal to a server. This<br />
all happens from within the EPI call. The EPI program subsequently<br />
refers to the server by an index number, therefore the program does<br />
not need to know what server it is actually connected to. If the user<br />
exit refuses to connect a server, then <strong>CICS</strong>_EpiSystemIDExit is not<br />
called (see below for further details). <strong>CICS</strong>_EpiAddTerminalExit is<br />
called after <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal has<br />
verified that the EPI has been successfully initialized, and that there is<br />
a free session. It is called before the <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal call actually sends the terminal definition to<br />
the server.<br />
<strong>CICS</strong>TERM: AddTerminalExit<br />
The /s or /r parameters of <strong>CICS</strong>TERM allow the user to specify that<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can connect to:<br />
v The first server defined in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
configuration file.<br />
v A server chosen by the user from a list of available servers<br />
204 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
v A server specified by the /s or /r parameter.<br />
EPI exits<br />
AddTerminalExit receives the system name as a parameter, and can<br />
specify a different server if required, or reject the server and cause the<br />
terminal emulator to terminate. If AddTerminalExit rejects the install,<br />
<strong>CICS</strong>TERM displays an error to the effect that the server is<br />
unavailable.<br />
EPI: <strong>CICS</strong>_EpiSystemIdExit<br />
Allows the user to re-select a server if a <strong>CICS</strong>_EpiAddTerminal or<br />
<strong>CICS</strong>_EpiAddExTerminal fails. This user exit is called if a<br />
<strong>CICS</strong>_EpiAddTerminal fails (but not if the<br />
<strong>CICS</strong>_EpiAddTerminalExit causes the failure). If it returns<br />
<strong>CICS</strong>_EXIT_OK, <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal<br />
tries to add the terminal again. The server parameters can be changed<br />
by this exit between retries.<br />
<strong>CICS</strong>_EpiSystemIdExit can be called asynchronously or<br />
synchronously by EPI programs. <strong>CICS</strong>_EpiSystemIdExit can be<br />
presented with:<br />
v A <strong>CICS</strong>_EPI_ERR_SYSTEM error, meaning the server is unknown,<br />
or,<br />
v A <strong>CICS</strong>_EPI_ERR_SERVER_DOWN error, meaning the server has<br />
failed, or,<br />
v A <strong>CICS</strong>_EPI_ERR_SECURITY error, for a security failure, or,<br />
v A <strong>CICS</strong>_EPI_ERR_FAILED error for any other type of failure.<br />
It is also passed a parameter that is the same as the cics_syserr_t data<br />
structure cause field. This value further specifies the error and is a<br />
value specific to the operating environment<br />
<strong>CICS</strong>TERM: SystemIdExit<br />
If a <strong>CICS</strong>TERM <strong>CICS</strong>_EpiAddTerminal or <strong>CICS</strong>_EpiAddExTerminal<br />
call fails due to the client requester not having enough sessions free<br />
(governed by the Maximum Requsts parameter in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> configuration file ) then SystemIdExit is called<br />
with <strong>CICS</strong>_EPI_ERR_FAILED as the primary reason code and 7046 as<br />
the secondary reason code. The secondary reason code number is the<br />
same as the client trace number for a resource shortage (CCL7046E).<br />
In all other cases of <strong>CICS</strong>_EPI_ERR_FAILED, <strong>CICS</strong>TERM passes a<br />
secondary reason code of 0.<br />
If no user exits are active, then <strong>CICS</strong>TERM retries a terminal install if<br />
it fails due to there not being enough available sessions. (This allows<br />
terminals to wait for free sessions before being installed.) If there are<br />
user exits available, then any retry behavior is controlled completely<br />
by the exit.<br />
Appendix C. ECI and EPI exits 205
EPI exits<br />
<strong>CICS</strong>_EpiSystemId is always called synchronously from the terminal<br />
thread, that is, the terminal install response is sent, it waits for a reply,<br />
and then drives SystemIdExit if the response is bad.<br />
EPI: <strong>CICS</strong>_EpiTermIdExit<br />
Allows the user to know what EPI Termid an added terminal is given.<br />
This is only called after a terminal has been successfully installed on a<br />
server. It does not affect the running of the EPI program. EPI Termid<br />
numbers are local to each process the EPI program runs under.<br />
<strong>CICS</strong>TERM: TermIdExit<br />
As only one <strong>CICS</strong>TERM runs per process, the Termid number is<br />
hardcoded to 1.<br />
EPI: <strong>CICS</strong>_EpiTermIdInfoExit<br />
Allows the user to know details about a terminal. This is called after a<br />
terminal has been successfully installed on a server.<br />
<strong>CICS</strong>TERM: TermIdInfoExit<br />
As only one <strong>CICS</strong>TERM runs per process, the Termid number is<br />
hardcoded to 1.<br />
EPI: <strong>CICS</strong>_EpiDelTerminalExit<br />
Allows the user to clean up terminal code. It is called when<br />
<strong>CICS</strong>_EpiDelTerminal is issued. It does not affect the running of the<br />
EPI program.<br />
<strong>CICS</strong>TERM: DelTerminalExit<br />
As only one <strong>CICS</strong>TERM runs per process, the Termid number is<br />
hardcoded to 1. It is called just before TerminateExit when the<br />
terminal is ended. When the server fails the AddTerminalExit is<br />
called again when it is restarted. However the DelTerminalExit is not<br />
called when the server fails.<br />
EPI: <strong>CICS</strong>_EpiStartTranExit<br />
Allows a user to see that a transaction has been started, and to see the<br />
Transid & 3270 data sent to it. It does not affect the running of the EPI<br />
program. <strong>CICS</strong>_EpiStartTranExit is called after the EPI state has been<br />
verified, and just before the <strong>CICS</strong>_EpiStartTran is called.<br />
Note that a pseudo-conversational transaction causes the<br />
<strong>CICS</strong>_EpiStartTranExit to be called because in this case an EPI<br />
program would have to start a transaction again.<br />
<strong>CICS</strong>TERM: StartTranExit:<br />
If a a non-ATI transaction is being started, then StartTranExit is called,<br />
sending a blank in the Transid field and the TIOA (terminal input<br />
output area) for the Data field. The Transid is either the first four<br />
characters of the TIOA data, or it will follow a 3270 Set Buffer<br />
206 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Address (SBA) command (which begins X'11'). In the latter case, it will<br />
start on the 4th byte of the TIOA (as a SBA command takes up a total<br />
of three bytes).<br />
StartTranExit is not driven for ATI transactions. This is because the<br />
exit is normally driven by the <strong>CICS</strong>_EpiStartTran API call, and this<br />
call is not made to start ATI transactions. However<br />
pseudo-conversational transactions will drive StartTranExit. This is<br />
because in an EPI program, the user would have to call<br />
<strong>CICS</strong>_EpiStartTran to start the pseudo-conversational transaction. In<br />
the case of pseudo-conversational transactions, the transaction id is<br />
put in the transid parameter block and the TIOA passed in the data<br />
block does not contain the transaction id.<br />
StartTranExit is not called as a result of an EXEC <strong>CICS</strong> RETURN<br />
TRANSIDname IMMEDIATE command issued by an application from<br />
a <strong>CICS</strong>TERM session.<br />
EPI: <strong>CICS</strong>_EpiReplyExit<br />
Allows the user to see when an application is replied to. It does not<br />
affect the running of the EPI program.<br />
<strong>CICS</strong>TERM ReplyExit<br />
Activated when the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is sending data and a<br />
transaction is currently active. The Termid number is hard coded to 1.<br />
The terminal TIOA is passed to ReplyExit<br />
ReplyExit is not called as a result of an EXEC <strong>CICS</strong> RETURN<br />
TRANSIDname IMMEDIATE command issued by an application from<br />
a <strong>CICS</strong>TERM session.<br />
The GetEventExit and TranFailedExit exits are not implemented for<br />
<strong>CICS</strong>TERM and <strong>CICS</strong>PRNT<br />
EPI exits<br />
Appendix C. ECI and EPI exits 207
208 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 210<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks ” on page 211 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 211 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 213 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 2002 209
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX for IBM eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere ® Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
210 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Redbooks <br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT: Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA : Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400 ® : Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 211
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
Microsoft ® Windows Family publications<br />
The following book provides introductory material about the Windows Family<br />
of operating systems:<br />
v Windows NT System Guide<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for Windows NT and Windows 2000:<br />
Communications Server for Windows: Quick Beginnings, GC31-8424<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
IBM eNetwork Personal Communications:<br />
IBM Personal Communications for Windows NT: Quick Beginnings,<br />
GC31-8679-02<br />
IBM Personal Communications: Administrator’s Reference, SC31-8840<br />
Microsoft products<br />
Microsoft SNA Server Installation Guide<br />
Microsoft SNA Server Administration Guide<br />
Microsoft SNA Server Reference<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
212 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
Other publications<br />
The product library and related literature 213
214 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
© Copyright IBM Corp. 2002 215
216 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans .<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 2002 217
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX,<br />
TXSeries for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390 ® . A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA ,<strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
218 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 219
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
220 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 221
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
222 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed. The default keyboard mapping file for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is <strong>CICS</strong>KEY.INI.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.<br />
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
Glossary 223
Glossary<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
224 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
R<br />
RACF. Resource Access Control Facility. An IBM<br />
licensed program that provides access control by<br />
identifying users to the system; verifying users of<br />
the system; authorizing access to protected<br />
resources; logging detected, unauthorized<br />
attempts to enter the system; and logging<br />
detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.<br />
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
Glossary 225
Glossary<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
226 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for<br />
OS/2 ® , <strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.<br />
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 227
Glossary<br />
228 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Index<br />
Special characters<br />
ix<br />
Numerics<br />
3270 datastreams 60, 150<br />
A<br />
accessibility 215<br />
accessing fields on 3270 screens 94<br />
Accessing fields on <strong>CICS</strong> 3270 screens<br />
in C++ External presentation interface 63<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 63<br />
AID 123<br />
Apartments<br />
Creating COM Objects 138<br />
application transaction demarcation 120<br />
Async Exception Handling 48<br />
Asynchronous call synchronisation<br />
in ATI 62<br />
asynchronous calls 4<br />
Asynchronous reply handling<br />
in C++ External call interface 55<br />
in Controlling server interactions 55<br />
asynchronous sends 94<br />
ATI 61, 155<br />
ATTRIBUTE_BACKGROUNDCOLOR 123<br />
ATTRIBUTE_BASE 123<br />
ATTRIBUTE_FOREGROUNDCOLOR 123<br />
ATTRIBUTE_HIGHLIGHT 123<br />
ATTRIBUTE_MARKER 123<br />
ATTRIBUTE_NONE 123<br />
ATTRIBUTE_TRANSPARENCY 123<br />
autoinstall 21<br />
Automatic <strong>Transaction</strong> Initiation 61, 155<br />
automation compatible 137<br />
B<br />
backout<br />
in Managing logical units of work 58<br />
in Server connection 51<br />
Backout<br />
in ECI Link Calls within a Unit Of Work 148<br />
Basic Mapping Support<br />
in C++ External presentation interface 59<br />
BMS<br />
map source files 60<br />
utility 60<br />
BMS Map Conversion utility 100, 107<br />
BMS paging 19<br />
BMSMapConvert 107<br />
books 209<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 209<br />
business object 145<br />
C<br />
C++ External call interface<br />
Asynchronous reply handling 55<br />
Controlling server interactions 53<br />
Deferred synchronous reply handling 56<br />
Finding potential servers 50<br />
Managing logical units of work 57<br />
Monitoring server availability 51<br />
Passing data to a server program 52<br />
Server connection 50<br />
Synchronous reply handling 54<br />
C++ External presentation interface<br />
Accessing fields on <strong>CICS</strong> 3270 screens 63<br />
EPI BMS conversion utility 67<br />
EPI call synchronization types 64<br />
Mapset containing a single map 69<br />
Starting a 3270 terminal connection to <strong>CICS</strong> 62<br />
Using EPI BMS Map Classes 70<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 59<br />
callback routine<br />
EPI 25, 26<br />
cancel<br />
in Monitoring server availability 51<br />
in Server connection 51<br />
CCF 79<br />
ccf2.jar 129<br />
CCI<br />
framework classes 115<br />
input and output classes 116<br />
Ccl Field<br />
in Running a <strong>CICS</strong> 3270 session 151<br />
Ccl Map<br />
Using BMS Map data with EPI COM classes 155<br />
Ccl::async<br />
in EPI call synchronization types 65<br />
Ccl::dsync<br />
in EPI call synchronization types 66<br />
Ccl::sync<br />
in EPI call synchronization types 64<br />
CclBuf<br />
in Passing data to a server program 52<br />
CclConn<br />
in Monitoring server availability 51<br />
© Copyright IBM Corp. 2002 229
CclConn (continued)<br />
in Server connection 50<br />
cclDSync<br />
in ECI Call Synchronization Types 146<br />
in EPI call synchronization types 152<br />
CclECI<br />
Finding potential servers 50<br />
CclField<br />
in Accessing fields on <strong>CICS</strong> 3270 screens 64<br />
in C++ External presentation interface 61<br />
CclFlow<br />
in Controlling server interactions 53<br />
CclMap<br />
in C++ External presentation interface 61<br />
in EPI BMS conversion utility 68<br />
in Mapset containing a single map 69<br />
CCLOECI.EXE<br />
in Using the COM classes 139<br />
CCLOEPI.EXE<br />
in Using the COM classes 139<br />
CclScreen 62<br />
in C++ External presentation interface 61<br />
in EPI BMS conversion utility 69<br />
CclSecAttr 58, 72<br />
CclSession 62<br />
in C++ External presentation interface 61<br />
in EPI call synchronization types 65<br />
CclSession::client<br />
in EPI call synchronization types 65<br />
CclSession::idle<br />
in EPI call synchronization types 65<br />
CclSession::server<br />
in EPI call synchronization types 65<br />
cclSync<br />
in ECI Call Synchronization Types 146<br />
in EPI call synchronization types 152<br />
CclTerminal 61, 62<br />
in C++ External presentation interface 61<br />
CclUOW<br />
in Managing logical units of work 57<br />
changed<br />
in Monitoring server availability 51<br />
in Server connection 51<br />
changePassword 58, 71<br />
<strong>CICS</strong> Server Information<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI<br />
in Using the COM classes 153<br />
<strong>CICS</strong> Server Information and Connection Status<br />
in Making an ECI link call to <strong>CICS</strong><br />
in Using the COM classes 147<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialisation file<br />
in Finding potential servers 50<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file<br />
in Starting a 3270 terminal connection to <strong>CICS</strong> 63<br />
230 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
<strong>CICS</strong>_EciDataReturnExit 182<br />
<strong>CICS</strong>_EciDataSendExit 181<br />
<strong>CICS</strong>_EciExitInit entry point 169<br />
<strong>CICS</strong>_EciExternalCallExit1 176<br />
<strong>CICS</strong>_EciExternalCallExit2 178<br />
<strong>CICS</strong>_EciInitializeExit 174<br />
<strong>CICS</strong>_EciListSystems function 10<br />
<strong>CICS</strong>_EciSetProgramAliasExit 183<br />
<strong>CICS</strong>_EciSystemIdExit 179<br />
<strong>CICS</strong>_EciTerminateExit 175<br />
<strong>CICS</strong>_EPI_EVENT_ADD_TERM event<br />
use 26<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE event<br />
use 26, 27, 33<br />
<strong>CICS</strong>_EPI_EVENT_END_TERM event<br />
use 26<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event<br />
use 26<br />
<strong>CICS</strong>_EPI_EVENT_SEND event<br />
use 26, 27, 32<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI event<br />
use 26<br />
<strong>CICS</strong>_EPI_NOWAIT 25<br />
<strong>CICS</strong>_EPI_WAIT 25<br />
<strong>CICS</strong>_EpiAddExTerminal function<br />
use 20, 25<br />
<strong>CICS</strong>_EpiAddTerminal function<br />
use 20, 25<br />
<strong>CICS</strong>_EpiAddTerminalExit 188<br />
<strong>CICS</strong>_EpiDelTerminal function<br />
use 23<br />
<strong>CICS</strong>_EpiDelTerminalExit 196<br />
<strong>CICS</strong>_EpiEventData_t data structure<br />
use 25, 26<br />
<strong>CICS</strong>_EpiExitInit entry point 169<br />
<strong>CICS</strong>_EpiGetEvent function<br />
use 25, 26<br />
<strong>CICS</strong>_EpiGetEventExit 197<br />
<strong>CICS</strong>_EpiInitialize function<br />
use 20<br />
<strong>CICS</strong>_EpiInitializeExit 186<br />
<strong>CICS</strong>_EpiListSystems function<br />
use 20, 42<br />
<strong>CICS</strong>_EpiPurgeTerminal function<br />
use 23<br />
<strong>CICS</strong>_EpiReply function<br />
use 27, 31<br />
<strong>CICS</strong>_EpiReplyExit 195<br />
<strong>CICS</strong>_EpiStartTran function<br />
use 24, 26, 27, 31<br />
<strong>CICS</strong>_EpiStartTranExit 193<br />
<strong>CICS</strong>_EpiSystem_t data structure<br />
use 42<br />
<strong>CICS</strong>_EpiSystemIdExit 199<br />
<strong>CICS</strong>_EpiTermIdExit 191
<strong>CICS</strong>_EpiTermIdInfoExit 192<br />
<strong>CICS</strong>_EpiTerminate function<br />
use 20<br />
<strong>CICS</strong>_EpiTerminateExit 187<br />
<strong>CICS</strong>_EpiTranFailedExit 201<br />
<strong>CICS</strong>_EXIT_BAD_ANCHOR return code<br />
<strong>CICS</strong>_EciDataReturnExit 182<br />
<strong>CICS</strong>_EciDataSendExit 181<br />
<strong>CICS</strong>_EciExternalCallExit1 176<br />
<strong>CICS</strong>_EciExternalCallExit2 178<br />
<strong>CICS</strong>_EciSetProgramAliasExit 183<br />
<strong>CICS</strong>_EciSystemIdExit 180<br />
<strong>CICS</strong>_EciTerminateExit 175<br />
<strong>CICS</strong>_EpiAddTerminalExit 189<br />
<strong>CICS</strong>_EpiDelTerminalExit 196<br />
<strong>CICS</strong>_EpiGetEventExit 197<br />
<strong>CICS</strong>_EpiReplyExit 195<br />
<strong>CICS</strong>_EpiStartTranExit 193<br />
<strong>CICS</strong>_EpiSystemIdExit 200<br />
<strong>CICS</strong>_EpiTermIdExit 191<br />
<strong>CICS</strong>_EpiTermIdInfoExit 192<br />
<strong>CICS</strong>_EpiTerminateExit 187<br />
<strong>CICS</strong>_EpiTranFailedExit 201<br />
<strong>CICS</strong>_EXIT_BAD_PARM return code<br />
<strong>CICS</strong>_EciDataReturnExit 182<br />
<strong>CICS</strong>_EciDataSendExit 181<br />
<strong>CICS</strong>_EciExternalCallExit1 176<br />
<strong>CICS</strong>_EciExternalCallExit2 178<br />
<strong>CICS</strong>_EciSetProgramAliasExit 183<br />
<strong>CICS</strong>_EciSystemIdExit 180<br />
<strong>CICS</strong>_EpiAddTerminalExit 189<br />
<strong>CICS</strong>_EpiDelTerminalExit 196<br />
<strong>CICS</strong>_EpiGetEventExit 197<br />
<strong>CICS</strong>_EpiReplyExit 195<br />
<strong>CICS</strong>_EpiStartTranExit 193<br />
<strong>CICS</strong>_EpiSystemIdExit 200<br />
<strong>CICS</strong>_EpiTermIdExit 191<br />
<strong>CICS</strong>_EpiTermIdInfoExit 192<br />
<strong>CICS</strong>_EpiTranFailedExit 202<br />
<strong>CICS</strong>_EXIT_BAD_STORAGE return code<br />
<strong>CICS</strong>_EciTerminateExit 175<br />
<strong>CICS</strong>_EpiTerminateExit 187<br />
<strong>CICS</strong>_EXIT_CANT_INIT_EXITS return code<br />
<strong>CICS</strong>_EciInitializeExit 174<br />
<strong>CICS</strong>_EpiInitializeExit 186<br />
<strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL return code<br />
<strong>CICS</strong>_EpiAddTerminalExit 189<br />
<strong>CICS</strong>_EpiSystemIdExit 200<br />
<strong>CICS</strong>_EXIT_GIVE_UP return code<br />
<strong>CICS</strong>_EciSystemIdExit 180<br />
<strong>CICS</strong>_EXIT_NO_EXIT return code<br />
<strong>CICS</strong>_EciInitializeExit 174<br />
<strong>CICS</strong>_EpiInitializeExit 186<br />
<strong>CICS</strong>_EXIT_OK return code<br />
<strong>CICS</strong>_EciDataReturnExit 182<br />
<strong>CICS</strong>_EXIT_OK return code (continued)<br />
<strong>CICS</strong>_EciDataSendExit 181<br />
<strong>CICS</strong>_EciExternalCallExit1 176<br />
<strong>CICS</strong>_EciExternalCallExit2 178<br />
<strong>CICS</strong>_EciInitializeExit 174<br />
<strong>CICS</strong>_EciSetProgramAliasExit 183<br />
<strong>CICS</strong>_EciSystemIdExit 179<br />
<strong>CICS</strong>_EciTerminateExit 175<br />
<strong>CICS</strong>_EpiAddTerminalExit 189<br />
<strong>CICS</strong>_EpiDelTerminalExit 196<br />
<strong>CICS</strong>_EpiGetEventExit 197<br />
<strong>CICS</strong>_EpiInitializeExit 186<br />
<strong>CICS</strong>_EpiReplyExit 195<br />
<strong>CICS</strong>_EpiStartTranExit 193<br />
<strong>CICS</strong>_EpiSystemIdExit 200<br />
<strong>CICS</strong>_EpiTermIdExit 191<br />
<strong>CICS</strong>_EpiTermIdInfoExit 192<br />
<strong>CICS</strong>_EpiTerminateExit 187<br />
<strong>CICS</strong>_EpiTranFailedExit 201<br />
<strong>CICS</strong>_ExternalCall 10<br />
<strong>CICS</strong>3270.INC include file 30<br />
<strong>CICS</strong>CLI<br />
in Starting a 3270 terminal connection to <strong>CICS</strong> 63<br />
cicseci.hpp<br />
Using the C++ classes 47<br />
<strong>CICS</strong>ECIX 169<br />
<strong>CICS</strong>ELUW flag 79<br />
cicsepi.hpp<br />
Using the C++ classes 47<br />
<strong>CICS</strong>EPIEXITINIT function 203<br />
<strong>CICS</strong>EPIX 169<br />
cicsepix.dll 203<br />
cicsj2ee.jar 129<br />
<strong>CICS</strong>PRNT 203<br />
<strong>CICS</strong>TERM 203<br />
CLASSPATH 101<br />
CLASSPATH environment variable 81<br />
client<br />
in EPI call synchronization types 66<br />
closing an EPIInteraction 124<br />
com.ibm.ctg.client.T class 82<br />
COMMAREA 49<br />
CommareaLength 119<br />
commit<br />
in Managing logical units of work 58<br />
in Server connection 51<br />
Commit<br />
in ECI Link Calls within a Unit Of Work 148<br />
Common Client Interface 115<br />
Common Client Interface (CCI) 115<br />
Common Connector Framework 79<br />
communication, synchronous 54<br />
compiling applications 129<br />
Component Object Model<br />
in Establishing the working environment 137<br />
Index 231
Connect<br />
in <strong>CICS</strong> Server Information and Connection<br />
Status 147<br />
Connect.Link<br />
in ECI Call Synchronization Types 146<br />
in ECI Link Calls within a Unit Of Work 148<br />
Connecting to <strong>CICS</strong> 3270 applications using the EPI<br />
<strong>CICS</strong> Server Information 153<br />
EPI call synchronization types 152<br />
in Using the COM classes 150<br />
Running a <strong>CICS</strong> 3270 session 151<br />
Using BMS Map data with EPI COM classes 153<br />
Connection object 58<br />
ConnectionFactory object<br />
creating 130<br />
storing 131<br />
connector.jar 129<br />
Controlling server interactions<br />
Asynchronous reply handling 55<br />
Deferred synchronous reply handling 56<br />
in C++ External call interface 53<br />
Synchronous reply handling 54<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 53<br />
CreateObject<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI 151<br />
in Making an ECI link call to <strong>CICS</strong> using<br />
VBScript 146<br />
ctgclient.jar 81, 102, 129<br />
ctgsamples.jar 101<br />
ctgserver.jar 81<br />
ctgstart script 85<br />
CursorColumn 123, 124<br />
CursorRow 123, 124<br />
D<br />
Data parameter<br />
<strong>CICS</strong>_EpiStartTran function 24<br />
DBCS 19, 60, 150<br />
default exception handler 48<br />
Deferred synchronous<br />
in ATI support 156<br />
Deferred synchronous call synchronisation<br />
in ATI 62<br />
Deferred synchronous reply handling<br />
in C++ External call interface 56<br />
in Controlling server interactions 56<br />
Delphi 137<br />
Details<br />
in Making an ECI link call to <strong>CICS</strong> 145<br />
DeviceType 122<br />
disability 215<br />
disconnect<br />
in EPI call synchronization types 66<br />
232 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
disconnecting terminals 99<br />
distributed program link 4<br />
distributed program link (DPL) 9<br />
distributed transaction processing 4<br />
documentation 209<br />
DPL 9<br />
E<br />
ECI 9<br />
in <strong>CICS</strong> Server Information and Connection<br />
Status 147<br />
ECI (External Call Interface) 3<br />
ECI Call Synchronization Types<br />
in Making an ECI link call to <strong>CICS</strong><br />
in Using the COM interfaces 146<br />
ECI connection interfaces 117<br />
ECI exits 171<br />
ECI interaction interfaces 118<br />
ECI Link Calls within a Unit Of Work<br />
in Making an ECI link call to <strong>CICS</strong><br />
in Using the COM interfaces 148<br />
ECI parameter block 10, 40, 163<br />
ECI resource adapter<br />
CCI 117<br />
ECI status block 15<br />
ECI_ASYNC_NOTIFY_MSG call type<br />
definition 161<br />
use 163, 164<br />
ECI_ASYNC_NOTIFY_SEM call type<br />
definition 162<br />
use 163<br />
eci_async_notify.sem_handle 162, 163<br />
eci_async_notify.window_handle 162<br />
eci_call_type 10<br />
ECI_ERR_NULL_MESSAGE_ID 164<br />
ECI_ERR_NULL_SEM_HANDLE 164<br />
ECI_ERR_NULL_WIN_HANDLE 164<br />
eci_extend_mode 13, 16<br />
ECI_GET_REPLY call type<br />
use 161, 162, 163<br />
ECI_GET_SPECIFIC_REPLY call type<br />
use 161, 162, 163<br />
eci_luw_token 12, 13, 14, 16<br />
eci_message_id 162, 164<br />
eci_message_qualifier 11<br />
with ECI_ASYNC_NOTIFY_MSG call type 162<br />
with ECI_ASYNC_NOTIFY_SEM call type 162<br />
with ECI_STATE_ASYNC_MSG call type 162<br />
with ECI_STATE_ASYNC_SEM call type 163<br />
eci_program_name 13<br />
ECI_STATE_ASYNC_MSG call type<br />
definition 162<br />
use 163, 164<br />
ECI_STATE_ASYNC_SEM call type<br />
definition 162
ECI_STATE_ASYNC_SEM call type (continued)<br />
use 163<br />
eci_window_handle 163<br />
ECIConnectionSpec 117<br />
ECIInteractionSpec 118<br />
ECIRequest 78<br />
environment variables 45<br />
EPI 19<br />
3270 data streams 30<br />
3270 order codes 33<br />
in <strong>CICS</strong> Server Information 153<br />
EPI (External Call Interface) 4<br />
EPI beans 101<br />
EPI BMS conversion utility<br />
in C++ External presentation interface 67<br />
Mapset containing a single map 69<br />
using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 67<br />
EPI call synchronization types<br />
in C++ External presentation interface 64<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI<br />
in Using the COM classes 152<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 64<br />
EPI connection interfaces 122<br />
EPI exits 184<br />
EPI interaction interfaces 122<br />
EPI Java Beans<br />
EPITerminal 102, 108<br />
screen handler beans 106<br />
using 102<br />
EPI resource adapter<br />
CCI 121<br />
EPI Screen Record 125<br />
EPI support classes 87<br />
accessing fields 94<br />
asynchronous sends 94<br />
disconnecting terminals 99<br />
establishing terminals 90<br />
exception handling 97<br />
handleException method 97<br />
handleReply method 95<br />
overview 87<br />
sessions 94<br />
synchronous sends 94<br />
terminal encoding 99<br />
using 90<br />
using send 93<br />
EPIBasicScreenHandler 101<br />
EPIConnectionSpec 122<br />
EPIFieldRecord 126<br />
EPI<strong>Gateway</strong> class 90<br />
EPIInteraction, closing 124<br />
EPIInteractionSpec 122<br />
EPIMonitor 101<br />
EPIRequest class 79<br />
EPIScreenButtons 101<br />
Err objects 142<br />
ErrorWindow 142<br />
ESI<br />
benefits 36<br />
overview 35<br />
ESI (External Security Interface) 5, 35<br />
exception handler, default 48<br />
exception handling 141<br />
Exception Handling, Async 48<br />
exceptions 97<br />
exceptions, handling 47<br />
EXCI programming considerations 86<br />
ExCode 142<br />
ExCodeText 142<br />
EXEC <strong>CICS</strong> CONVERSE 27<br />
EXEC <strong>CICS</strong> LINK 9<br />
EXEC <strong>CICS</strong> RECEIVE 27, 31, 32, 33<br />
EXEC <strong>CICS</strong> RECEIVE BUFFER 33<br />
EXEC <strong>CICS</strong> RECEIVE MAP 31, 32<br />
EXEC <strong>CICS</strong> RETURN<br />
TRANSID option 27<br />
EXEC <strong>CICS</strong> SEND 27, 31<br />
EXEC <strong>CICS</strong> SEND MAP 31<br />
EXEC <strong>CICS</strong> START<br />
DELAY option 20<br />
ExecuteTimeout 119<br />
extended calls 4<br />
External call interface<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 49<br />
External Call Interface (ECI) 3<br />
External Call Interface (EPI) 4<br />
External Security Interface (ESI) 5, 35<br />
F<br />
field<br />
in Mapset containing a single map 69<br />
field()<br />
in Mapset containing a single map 69<br />
FieldByIndex<br />
Using BMS Map data with EPI COM classes 155<br />
FieldByPosition<br />
Using BMS Map data with EPI COM classes 155<br />
Finding potential servers<br />
in C++ External call interface 50<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 50<br />
Flow<br />
in <strong>CICS</strong> Server Information and Connection<br />
Status 147<br />
Index 233
Form_Load<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI 151<br />
in Making an ECI link call to <strong>CICS</strong> 145<br />
framework classes 115<br />
front end programming interface 4<br />
FunctionName 118, 123<br />
G<br />
glossary of terms and abbreviations 217<br />
H<br />
handleException 48<br />
handleException method 97<br />
handleReply 62<br />
in EPI call synchronization types 65, 66, 67<br />
using EPI BMS Map Classes 71<br />
handleReply method 95<br />
handling exceptions 47<br />
handling screens 104<br />
handling, exception 141<br />
heap size 81<br />
I<br />
idle<br />
in EPI call synchronization types 66<br />
Initiation, Automatic <strong>Transaction</strong> 61<br />
input records 124<br />
input/output classes 115, 116<br />
input/output records 119<br />
install_path ix<br />
installation<br />
path ix<br />
installation path ix<br />
instance<br />
in Finding potential servers 50<br />
InteractionVerb 118, 122<br />
J<br />
J2EE Tracing 132<br />
Java<br />
beans, EPI 101<br />
client programs 74<br />
heap size 81<br />
samples 101<br />
stack size 81<br />
Java 2 Security Manager 113<br />
Java permissions 113<br />
Java<strong>Gateway</strong> 76<br />
flowing requests 78<br />
protocols 76<br />
security 76<br />
SSL 77<br />
JNDI 131<br />
JSSE 73, 111, 113<br />
234 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
L<br />
link<br />
in Server connection 51<br />
Link<br />
in Making an ECI link call to <strong>CICS</strong> 145<br />
load balancing 203<br />
logical unit of work 12<br />
LogonLogoff classes 127<br />
M<br />
Making an ECI link call to <strong>CICS</strong><br />
<strong>CICS</strong> Server Information and Connection<br />
Status 147<br />
ECI Call Synchronization Types 146<br />
ECI Link Calls within a Unit Of Work 148<br />
in Using the COM classes 144<br />
making ECI calls on z/OS 84<br />
<strong>CICS</strong> security considerations 85<br />
program link calls 84<br />
status information calls 85<br />
making EPI calls on z/OS 86<br />
managed environment 120<br />
Managing logical units of work<br />
in C++ External call interface 57<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 57<br />
Map<br />
in Using BMS Map data with EPI COM<br />
classes 153, 154<br />
Map.FieldByName<br />
in Using BMS Map data with EPI COM classes 155<br />
Map.Validate<br />
in Using BMS Map data with EPI COM classes 155<br />
MAPINQ1Map<br />
in Mapset containing a single map 69<br />
MapName 124<br />
Mapset containing a single map<br />
in C++ External presentation interface 69<br />
in EPI BMS conversion utility 69<br />
MapSetName 124<br />
Monitoring server availability<br />
in C++ External call interface 51<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 51<br />
multi-threading 47<br />
N<br />
NetName 122<br />
New<br />
in Making an ECI link call to <strong>CICS</strong> 145<br />
nonmanaged environment 120<br />
running the J2EE <strong>CICS</strong> resource adapters 131<br />
using J2EE <strong>CICS</strong> resource adapters in 130<br />
NotifyFn parameter<br />
<strong>CICS</strong>_EpiAddTerminal function 25
O<br />
On Error Goto 142<br />
On Error Resume 142<br />
OO support 7<br />
output records 124<br />
OutputAttributeType 123<br />
P<br />
Passing data to a server program<br />
in C++ External call interface 52<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 52<br />
password 58<br />
Password 118, 122<br />
password expiration management (PEM) 5, 35<br />
Password Expiry Management 149, 156<br />
Password Expiry Management (PEM) 71<br />
PEM (password expiration management) 5, 35<br />
PF3<br />
Accessing fields on <strong>CICS</strong> 3270 screens 63<br />
poll<br />
in Deferred synchronous reply handling 56, 57<br />
in EPI call synchronization types 67<br />
Poll<br />
in ECI Call Synchronization Types 146, 147<br />
in EPI call synchronization types 152<br />
poll method 62<br />
in ATI support 156<br />
pollForReply method<br />
in ATI support 156<br />
program link calls 12<br />
programming<br />
EPI programming 87<br />
EPI support classes 88<br />
Java classes 73<br />
Java client programs 74<br />
programming interface 73<br />
Programming Overview<br />
in Using the COM interfaces 141<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 209<br />
Q<br />
queryATI 61, 156<br />
R<br />
receiveATI 62<br />
receiveATI method<br />
in ATI support 156<br />
Registration 137<br />
reply handling, asynchronous 55<br />
ReplyLength 119<br />
resource adapter samples 133<br />
ECI 133<br />
EPI 134<br />
Running a <strong>CICS</strong> 3270 session<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI<br />
in Using the COM classes 151<br />
S<br />
sample programs 167<br />
samples, Java 101<br />
Samples.txt 167<br />
screen<br />
Accessing fields on <strong>CICS</strong> 3270 screens 63<br />
Screen<br />
in Running a <strong>CICS</strong> 3270 session 151<br />
Using BMS Map data with EPI COM classes 155<br />
screen handlers 104<br />
screen size 19<br />
screenable.jar 129<br />
ScreenDepth 124<br />
ScreenWidth 124<br />
Security<br />
Java security permissions 113<br />
security classes 111<br />
security considerations<br />
ECI 15<br />
EPI 27<br />
security credentials 129<br />
security exits 111<br />
Security Management<br />
ECI 58<br />
EPI 71<br />
semaphore 162<br />
send<br />
in EPI call synchronization types 64, 65, 66, 67<br />
in Starting a 3270 terminal connection to <strong>CICS</strong> 63<br />
send method<br />
in ATI 62<br />
in ATI support 156<br />
server<br />
in EPI call synchronization types 66, 67<br />
Server connection<br />
in C++ External call interface 50<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 50<br />
serverCount<br />
Finding potential servers 50<br />
serverDesc<br />
Finding potential servers 50<br />
serverName<br />
Finding potential servers 50<br />
Servers 137<br />
Session<br />
in Running a <strong>CICS</strong> 3270 session 151<br />
Session.SetSyncType<br />
in EPI call synchronization types 152<br />
setATI 61, 156<br />
Index 235
SetErrorFormat 142<br />
SetSyncType<br />
in ECI Call Synchronization Types 146<br />
signon capable 28<br />
signon incapable 28<br />
SSL 77<br />
stack size 81<br />
start method<br />
in ATI support 156<br />
Starting a 3270 terminal connection to <strong>CICS</strong><br />
in C++ External presentation interface 62<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 62<br />
state<br />
in EPI call synchronization types 67<br />
state (parameter)<br />
in EPI call synchronization types 65<br />
status<br />
in Monitoring server availability 51<br />
in Server connection 51<br />
stream format 127<br />
streamable interface 119<br />
structured fields 19<br />
Synchronous<br />
in ATI support 156<br />
Synchronous call synchronisation<br />
in ATI 62<br />
synchronous calls 4<br />
Synchronous reply handling<br />
in C++ External call interface 54<br />
in Controlling server interactions 54<br />
synchronous sends 94<br />
synchronous, Deferred 62<br />
system properties, Java 82<br />
T<br />
TermId 124<br />
Terminal<br />
in Running a <strong>CICS</strong> 3270 session 151<br />
Terminal class 156<br />
terminal index 21, 80<br />
terminal, signon capable 28<br />
terminal, signon incapable 28<br />
Terminal.Poll<br />
in EPI call synchronization types 152<br />
Terminal.Send<br />
in EPI call synchronization types 152<br />
Terminal.Start<br />
in EPI call synchronization types 152<br />
in Running a <strong>CICS</strong> 3270 session 151<br />
terminals<br />
basic 90<br />
disconnecting 99<br />
encoding 99<br />
establishing to <strong>CICS</strong> 90<br />
236 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide<br />
terminals (continued)<br />
extended 92<br />
threads, multiple 47<br />
time-out 11<br />
tracing 82<br />
Tracing<br />
J2EE 132<br />
<strong>Transaction</strong> Initiation, Automatic 61, 155<br />
transID 62<br />
TransId parameter<br />
<strong>CICS</strong>_EpiStartTran function 24<br />
U<br />
UOW<br />
in ECI Link Calls within a Unit Of Work 148<br />
uowId 58<br />
user-defined<br />
<strong>CICS</strong>_EpiSystemIdExit 200<br />
<strong>CICS</strong>_EpiTerminateExit 187<br />
user-defined return code<br />
<strong>CICS</strong>_EciDataReturnExit 182<br />
<strong>CICS</strong>_EciDataSendExit 181<br />
<strong>CICS</strong>_EciExternalCallExit1 176<br />
<strong>CICS</strong>_EciExternalCallExit2 178<br />
<strong>CICS</strong>_EciInitializeExit 174<br />
<strong>CICS</strong>_EciSetProgramAliasExit 183<br />
<strong>CICS</strong>_EciSystemIdExit 180<br />
<strong>CICS</strong>_EciTerminateExit 175<br />
<strong>CICS</strong>_EpiAddTerminalExit 189<br />
<strong>CICS</strong>_EpiDelTerminalExit 196<br />
<strong>CICS</strong>_EpiGetEventExit 197<br />
<strong>CICS</strong>_EpiInitializeExit 186<br />
<strong>CICS</strong>_EpiReplyExit 195<br />
<strong>CICS</strong>_EpiStartTranExit 193<br />
<strong>CICS</strong>_EpiTermIdExit 191<br />
<strong>CICS</strong>_EpiTermIdInfoExit 192<br />
<strong>CICS</strong>_EpiTranFailedExit 202<br />
UserName 118, 122<br />
Using BMS Map data with EPI COM classes<br />
in Connecting to <strong>CICS</strong> 3270 applications using the<br />
EPI<br />
in Using the COM classes 153<br />
Using EPI BMS Map Classes<br />
in C++ External presentation interface 70<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++<br />
classes 70<br />
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++ classes<br />
Accessing fields on <strong>CICS</strong> 3270 screens 63<br />
Controlling server interactions 53<br />
EPI BMS conversion utility 67<br />
EPI call synchronization types 64<br />
Finding potential servers 50<br />
Managing logical units of work 57<br />
Monitoring server availability 51<br />
Passing data to a server program 52
Using the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++ classes<br />
(continued)<br />
Server connection 50<br />
Starting a 3270 terminal connection to <strong>CICS</strong> 62<br />
Using EPI BMS Map Classes 70<br />
Using the COM classes<br />
Connecting to <strong>CICS</strong> 3270 applications using the EPI<br />
<strong>CICS</strong> Server Information 153<br />
EPI call synchronization types 152<br />
Running a <strong>CICS</strong> 3270 session 151<br />
Using BMS Map data with EPI COM<br />
classes 153<br />
Making an ECI link call to <strong>CICS</strong><br />
<strong>CICS</strong> Server Information and Connection<br />
Status 147<br />
ECI Call Synchronization Types 146<br />
ECI Link Calls within a Unit Of Work 148<br />
V<br />
VBScript 137<br />
verifyPassword 58, 71<br />
<strong>Version</strong> parameter<br />
<strong>CICS</strong>_EpiInitialize function 29<br />
Visual Basic 137<br />
W<br />
wait<br />
in Asynchronous reply handling 56<br />
in Deferred synchronous reply handling 57<br />
Wait parameter<br />
<strong>CICS</strong>_EpiGetEvent 25<br />
Windows<br />
environment variables 45<br />
WorkLoad Manager 183<br />
writing input and output records 124<br />
Z<br />
z/OS<br />
ECI return codes and server errors 86<br />
EXCI considerations 86<br />
making ECI calls 84<br />
making EPI calls 86<br />
Index 237
238 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 2002 239
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
COPYRIGHT LICENSE:<br />
This information contains sample application programs in source language,<br />
which illustrate programming techniques on various operating platforms. You<br />
may copy, modify, and distribute these sample programs in any form without<br />
payment to IBM for the purposes of developing, using, marketing, or<br />
distributing application programs conforming to IBM’s application<br />
programming interfaces for the operating platform for which the sample<br />
programs are written. These examples have not been thoroughly tested under<br />
all conditions. IBM, therefore, cannot guarantee or imply reliability,<br />
serviceability, or function of these programs.<br />
240 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Trademarks<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
AIX <strong>CICS</strong><br />
IBM OS/390<br />
VisualAge<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of<br />
Microsoft Corporation in the United States, other countries, or both.<br />
Java, and all Java-based trademarks and logos are trademarks of Sun<br />
Microsystems, Inc. in the United States, or other countries, or both.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
Notices 241
242 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 2002 243
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6141-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Programming Guide <strong>Version</strong> <strong>5.0</strong>
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Programming Reference<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6140-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Programming Reference<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6140-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 251.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of the <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong>, program number 5724-D12. It will also apply to<br />
all subsequent versions, releases, and modifications until otherwise indicated in new editions.<br />
This edition replaces SC34-5946, SC34-5947, SC34-5945, SC34-5938. Vertical lines at the left side of the page indicate<br />
material that is new to this edition.<br />
© Copyright International Business Machines Corporation 1989, 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
Contents<br />
About this book. . . . . . . . . . . v<br />
Who should read this book . . . . . . . v<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . . v<br />
Installation path . . . . . . . . . vii<br />
Directory delimiters . . . . . . . . vii<br />
Programming language specific . . . . vii<br />
Operating system specific . . . . . . vii<br />
Summary of changes . . . . . . . . ix<br />
Chapter 1. COM . . . . . . . . . . . 1<br />
Buffer COM class . . . . . . . . . . 1<br />
Interface Selection . . . . . . . . . 1<br />
Object Creation . . . . . . . . . . 1<br />
Methods . . . . . . . . . . . . 2<br />
Connect COM class . . . . . . . . . . 4<br />
Interface Selection . . . . . . . . . 4<br />
Object Creation . . . . . . . . . . 4<br />
Methods . . . . . . . . . . . . 4<br />
ECI COM class . . . . . . . . . . . 10<br />
Interface Selection . . . . . . . . . 10<br />
Object Creation . . . . . . . . . . 10<br />
Methods . . . . . . . . . . . . 11<br />
EPI COM class . . . . . . . . . . . 13<br />
Interface Selection . . . . . . . . . 13<br />
Object Creation . . . . . . . . . . 13<br />
Methods . . . . . . . . . . . . 13<br />
Field COM class . . . . . . . . . . 17<br />
Interface Selection . . . . . . . . . 17<br />
Methods . . . . . . . . . . . . 17<br />
Flow COM class . . . . . . . . . . 22<br />
Interface Selection . . . . . . . . . 22<br />
Object Creation . . . . . . . . . . 23<br />
Methods . . . . . . . . . . . . 23<br />
Map COM class. . . . . . . . . . . 26<br />
Interface Selection . . . . . . . . . 26<br />
Object Creation . . . . . . . . . . 26<br />
Methods . . . . . . . . . . . . 26<br />
Screen COM class . . . . . . . . . . 28<br />
Interface Selection . . . . . . . . . 28<br />
Methods . . . . . . . . . . . . 28<br />
SecAttr COM class. . . . . . . . . . 30<br />
Interface Selection . . . . . . . . . 30<br />
Methods . . . . . . . . . . . . 31<br />
SecTime COM class . . . . . . . . . 32<br />
Interface Selection . . . . . . . . . 32<br />
Methods . . . . . . . . . . . . 32<br />
Session COM class . . . . . . . . . . 33<br />
Interface Selection . . . . . . . . . 33<br />
Object Creation . . . . . . . . . . 33<br />
Methods . . . . . . . . . . . . 34<br />
Terminal COM class . . . . . . . . . 35<br />
Interface Selection . . . . . . . . . 35<br />
Object Creation . . . . . . . . . . 35<br />
Methods . . . . . . . . . . . . 36<br />
UOW COM class . . . . . . . . . . 45<br />
Interface Selection . . . . . . . . . 45<br />
Object Creation . . . . . . . . . . 45<br />
Methods . . . . . . . . . . . . 45<br />
Chapter 2. Java . . . . . . . . . . 47<br />
Class/interface page . . . . . . . . . 47<br />
Use page . . . . . . . . . . . . . 48<br />
Tree (Class Hierarchy). . . . . . . . . 48<br />
Deprecated API . . . . . . . . . . . 48<br />
Index page . . . . . . . . . . . . 48<br />
Chapter 3. C++. . . . . . . . . . . 49<br />
Ccl class . . . . . . . . . . . . . 49<br />
Enumerations . . . . . . . . . . 49<br />
CclBuf class . . . . . . . . . . . . 49<br />
CclBuf constructors . . . . . . . . 50<br />
Public methods . . . . . . . . . . 51<br />
Enumerations . . . . . . . . . . 55<br />
CclConn class . . . . . . . . . . . 55<br />
CclConn constructor . . . . . . . . 56<br />
Public methods . . . . . . . . . . 56<br />
Enumerations . . . . . . . . . . 60<br />
CclECI class . . . . . . . . . . . . 61<br />
CclECI constructor (protected) . . . . . 61<br />
Public methods . . . . . . . . . . 61<br />
CclEPI class . . . . . . . . . . . . 63<br />
CclEPI constructor . . . . . . . . . 63<br />
Public methods . . . . . . . . . . 63<br />
Enumerations . . . . . . . . . . 65<br />
CclException class . . . . . . . . . . 66<br />
Public methods . . . . . . . . . . 66<br />
CclField class . . . . . . . . . . . 67<br />
Public methods . . . . . . . . . . 67<br />
© Copyright IBM Corp. 1989, 2002 iii
Enumerations . . . . . . . . . . 71<br />
CclFlow class . . . . . . . . . . . 73<br />
CclFlow constructor . . . . . . . . 73<br />
Public methods . . . . . . . . . . 74<br />
Enumerations . . . . . . . . . . 76<br />
CclMap class. . . . . . . . . . . . 77<br />
CclMap constructor . . . . . . . . 77<br />
Public methods . . . . . . . . . . 77<br />
Protected methods . . . . . . . . . 78<br />
CclScreen class . . . . . . . . . . . 79<br />
Public methods . . . . . . . . . . 79<br />
Enumerations . . . . . . . . . . 81<br />
CclSecAttr . . . . . . . . . . . . 82<br />
Public Methods . . . . . . . . . . 82<br />
CclSecTime . . . . . . . . . . . . 82<br />
Public Methods . . . . . . . . . . 83<br />
CclSession class . . . . . . . . . . . 84<br />
CclSession constructor . . . . . . . 84<br />
Public methods . . . . . . . . . . 84<br />
Enumerations . . . . . . . . . . 85<br />
CclTerminal class . . . . . . . . . . 86<br />
CclTerminal constructor . . . . . . . 86<br />
Public methods . . . . . . . . . . 88<br />
Enumerations . . . . . . . . . . 94<br />
CclUOW class . . . . . . . . . . . 95<br />
CclUOW constructor . . . . . . . . 95<br />
Public methods . . . . . . . . . . 95<br />
Chapter 4. C and COBOL . . . . . . . 97<br />
External Call Interface . . . . . . . . 97<br />
<strong>CICS</strong>_ExternalCall ECI_Parms . . . 97<br />
Call types for the <strong>CICS</strong>_ExternalCall . . 100<br />
ECI status block . . . . . . . . . 128<br />
<strong>CICS</strong>_EciListSystems NameSpace<br />
Systems List . . . . . . . . . . 129<br />
External Presentation Interface . . . . . 130<br />
EPI constants and data structures . . . 130<br />
EPI functions . . . . . . . . . . 137<br />
EPI events . . . . . . . . . . . 166<br />
External Security Interface . . . . . . . 169<br />
ESI constants and data structures . . . 169<br />
ESI functions . . . . . . . . . . 171<br />
Appendix A. COM Global Constants. . . 181<br />
Appendix B. COM EPI Specific Constants 183<br />
Synchronization Types . . . . . . . . 183<br />
CclEPI States . . . . . . . . . . . 183<br />
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
|<br />
|<br />
CclSession States . . . . . . . . . . 183<br />
CclTerminal States . . . . . . . . . 183<br />
CclTerminal ATI States . . . . . . . . 184<br />
CclTerminal EndTermReasons. . . . . . 184<br />
CclTerminal Signon Types . . . . . . . 184<br />
CclScreen AID key codes . . . . . . . 185<br />
CclField Protected State Attributes . . . . 186<br />
CclField Numeric Attributes . . . . . . 186<br />
CclField Intensity Attributes . . . . . . 186<br />
CclField Modified Attributes . . . . . . 186<br />
CclField Highlight Attributes . . . . . . 187<br />
CclField Transparency Attributes. . . . . 187<br />
CclField Color Attributes . . . . . . . 187<br />
Appendix C. ECI Constants . . . . . . 189<br />
Synchronization Types . . . . . . . . 189<br />
Flow status types . . . . . . . . . . 189<br />
Connection Status Codes . . . . . . . 189<br />
Appendix D. COM Error Code References 191<br />
Appendix E. Java encodings . . . . . 195<br />
Appendix F. C++ Exception Objects . . . 199<br />
The product library and related literature 205<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 205<br />
Sample configuration documents. . . . . 206<br />
Redbooks . . . . . . . . . . . . 207<br />
Other Useful Books . . . . . . . . . 207<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 207<br />
Microsoft ® Windows Family publications 208<br />
APPC-related publications . . . . . . 208<br />
TCP62–related publications . . . . . 209<br />
Obtaining books from IBM. . . . . . . 209<br />
Accessibility . . . . . . . . . . . 211<br />
Documentation. . . . . . . . . . . 211<br />
Glossary . . . . . . . . . . . . 213<br />
Index . . . . . . . . . . . . . 225<br />
Notices . . . . . . . . . . . . . 251<br />
Trademarks . . . . . . . . . . . . 253<br />
Sending your comments to IBM . . . . 255
About this book<br />
This book provides information about the APIs of the programming languages<br />
that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> supports (Java , C++, C, and COM). It is<br />
a quick reference for anyone writing Client applications for the <strong>Gateway</strong>. For<br />
information about programming methodology see the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide, SC34-6141.<br />
Who should read this book<br />
This book is intended for anyone involved with programming for <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
It is assumed that you are familiar with the operating system under which<br />
your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runs.<br />
An understanding of Internet terminology is helpful.<br />
Conventions and terminology used in this book<br />
A number of parts, both internal and external to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>, are used when creating a business solution using the product.<br />
Figure 1 on page vi shows some of the possible scenarios you will encounter,<br />
and the terminology used in each case.<br />
© Copyright IBM Corp. 1989, 2002 v
Distributed platforms running in remote mode<br />
Java client<br />
application<br />
z/OS running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Distributed platforms running in local mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
Client<br />
daemon<br />
Distributed platforms running non-Java applications<br />
Client<br />
application<br />
Client<br />
daemon<br />
z/OS running in remote mode<br />
Java client<br />
application<br />
<strong>Gateway</strong><br />
classes<br />
<strong>CICS</strong><br />
server<br />
<strong>Gateway</strong><br />
daemon<br />
Client<br />
daemon<br />
<strong>CICS</strong><br />
server<br />
<strong>CICS</strong><br />
server<br />
Figure 1. <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses, with their associated terminology<br />
<strong>CICS</strong><br />
server<br />
The following explains the terms used in Figure 1:<br />
<strong>Gateway</strong> daemon<br />
Used only in remote mode, the <strong>Gateway</strong> daemon listens on protocols<br />
defined in CTG.INI for gateway requests from remote Java client<br />
applications. It issues these requests to the Client daemon on<br />
distributed platforms, and directly to <strong>CICS</strong> over the EXCI on z/OS ® .<br />
The <strong>Gateway</strong> daemon runs the protocol listener threads, the worker<br />
threads and the connection manager threads. It uses the GATEWAY<br />
section of CTG.INI (and on z/OS the ctgenvvar script) for its<br />
configuration.<br />
Client daemon<br />
The Client daemon (process cclclnt) exists only on distributed<br />
platforms. It manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending and receiving the<br />
appropriate flows from the <strong>CICS</strong> server to satisfy the application<br />
requests. It uses the CLIENT section of CTG.INI for its configuration.<br />
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>Gateway</strong> classes<br />
The interface for Java Client applications to connect to the <strong>Gateway</strong><br />
daemon. The <strong>Gateway</strong> classes, which are supplied with the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, must be in the classpath for Java Client<br />
applications to run.<br />
Client application<br />
A user application, written in a supported programming language<br />
other than Java, that communicates directly with the Client daemon.<br />
Java Client application<br />
A Java application, servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Installation path<br />
The term is used in file paths to represent the directory where<br />
you installed the product. See the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Administration<br />
book for your operating system, for the default installation locations.<br />
Directory delimiters<br />
References to directory path names in this book use the Microsoft ® Windows ®<br />
convention of a backslash (\) as delimiter, instead of the forward slash (/)<br />
delimiter used on z/OS and UNIX ® operating systems.<br />
Programming language specific<br />
The term C refers to both the C and C++ programming languages.<br />
Operating system specific<br />
Unless otherwise specified, the term Windows refers to Windows NT ® ,<br />
Windows 2000, and Windows XP.<br />
The term Windows 2000 Terminal Server means a server with the Terminal<br />
Services feature installed.<br />
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.<br />
About this book vii
viii <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
|<br />
|<br />
Summary of changes<br />
This book contains material that previously appeared in these books:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Gateway</strong> Programming, SC34-5938<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> C++ Programming, SC34-5945<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> COM Automation Programming, SC35-5946<br />
v <strong>CICS</strong> Family Client/Server Programming, SC34-5947<br />
Vertical lines at the left side of the page indicate material that is new to this<br />
edition.<br />
The following functional changes have been made for <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> <strong>Version</strong> <strong>5.0</strong>:<br />
v The Windows XP operating system is supported.<br />
v COBOL is supported on the Windows operating system.<br />
The Java API has the following changes:<br />
v The setCommareaInboundLength() method has been deprecated.<br />
v A new method, getInboundDataLength(), is introduced. The new method<br />
returns the amount of data flowed over the network (with trailing nulls<br />
removed), not the amount of data returned from the <strong>CICS</strong> transaction.<br />
See the online Java programming reference information for details.<br />
A new state enumeration, CclTerminal::txnTimedOut, has been added for the<br />
C++ libraries.<br />
© Copyright IBM Corp. 1989, 2002 ix
x <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Chapter 1. COM<br />
Buffer COM class<br />
A CclOBuffer object contains a data area in memory which can be used to<br />
hold information. A particular use for a CclOBuffer object is to hold a<br />
COMMAREA used to pass data to and from a <strong>CICS</strong> server.<br />
The CclOBuffer object is primarily intended for use with byte (binary) data.<br />
Typically a COMMAREA contains an application-specific data structure, often<br />
originating from a <strong>CICS</strong> server C program. The preferred method for handling<br />
binary data in Visual Basic is now the Byte data type. The SetData and Data<br />
methods allow the contents of the CclOBuffer object to be accessed as a Byte<br />
array. The CclOBuffer object can be used for string data, and stores strings as<br />
single-byte ANSI characters, but it does not provide any support for<br />
code-page conversions or DBCS. Note that in 32-bit environments Visual Basic<br />
uses 2-byte Unicode character representation; the COM class converts this to<br />
and from single-byte ANSI.<br />
When a CclOBuffer object is created it allocates an area of memory as its<br />
buffer. The length of this buffer can be set explicitly via the SetLength<br />
method.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOBuf<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
set var = CreateObject("Ccl.Buffer")<br />
set var = New CclOBuf<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
© Copyright IBM Corp. 1989, 2002 1
COM class: Buffer<br />
Methods<br />
AppendString<br />
AppendString(string as String)<br />
string<br />
The source string.<br />
Appends a string to existing data in the Ccl.Buffer object.<br />
Data<br />
Data() as Variant<br />
Returns the contents of the buffer as a Byte array.<br />
ExtractString<br />
ExtractString (offset as Integer[,<br />
length as Integer]) as String<br />
offset<br />
The offset into the data area.<br />
length<br />
(optional) The length, in bytes, of the string to be extracted.<br />
Returns a string from the data area starting at the specified offset.<br />
If length is not specified, ExtractString returns data until it finds the first null<br />
terminator. If length is specified, ExtractString returns the number of bytes<br />
requested, including any nulls found in the string.<br />
InsertString<br />
InsertString (offset as Integer,<br />
string as String)<br />
offset<br />
The offset in the data area where the string is to be inserted.<br />
string<br />
The source string.<br />
Inserts the given string into the data area at the given offset.<br />
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Length<br />
Length() as Integer<br />
Returns the length of the data area in bytes.<br />
Overlay<br />
Overlay (offset as Integer,<br />
string as String)<br />
offset<br />
The offset in the data area where the string is to be inserted.<br />
string<br />
The source string.<br />
Overlays the data area with the given string, starting at the given offset.<br />
SetData<br />
SetData(array as Variant)<br />
array<br />
The array containing the source data.<br />
Copies the supplied array into the buffer. Byte, Integer, and Long arrays are<br />
supported.<br />
SetLength<br />
SetLength(length as Integer)<br />
length<br />
The new length of the data area, in bytes.<br />
Changes the current length of the data area. If you increase the length of the<br />
buffer object, the extra space is padded with nulls. The Client daemon<br />
truncates any nulls before sending the buffer to a <strong>CICS</strong> server.<br />
SetString<br />
SetString(string as String)<br />
COM class: Buffer<br />
Chapter 1. COM 3
COM class: Buffer<br />
string<br />
Source string<br />
Copies the supplied string into the object.<br />
String<br />
Connect COM class<br />
Returns the contents of the Ccl.Buffer object as a string.<br />
The Connect COM class is used to maintain and represent an ECI connection<br />
between a client and a named server. Access to the server is optionally<br />
controlled by a user ID and password. It can call a program in the server or<br />
get information on the state of the connection.<br />
Before the Connect COM class can be used to make calls to <strong>CICS</strong>, it must be<br />
initialized using the Details method and, optionally, the TranDetails method.<br />
Any interaction between client and server requires a CclOFlow object and a<br />
CclOConnect object.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOConn<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
Methods<br />
String() as String<br />
set var = CreateObject("Ccl.Connect")<br />
set var = New CclOConn<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
AlterSecurity<br />
AlterSecurity(newUserid as String, newPassword as String)<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
newUserid<br />
The new userid<br />
newPassword<br />
The new password corresponding to the new userid.<br />
Sets the userid and password to be used on the next link call.<br />
Cancel<br />
Cancel(flow as Object)<br />
or<br />
Cancel(flow as CclOFlow)<br />
flow<br />
The CclOFlow object used to control the client/server call<br />
Cancels any Changed call that was previously issued to the server associated<br />
with this connection.<br />
Changed<br />
Changed(flow as Object)<br />
or<br />
Changed(flow as CclOFlow)<br />
flow<br />
The CclOFlow object used to control the client/server call.<br />
Requests the server to notify the client when the current connection status<br />
changes. The call is ignored if there is an outstanding Changed call for this<br />
connection.<br />
ChangePassword<br />
ChangePassword (newPassword as String) as Object<br />
or<br />
ChangePassword (newPassword as String) as CclOSecAttr<br />
COM class: Connect<br />
Chapter 1. COM 5
COM class: Connect<br />
newPassword<br />
The new password<br />
Allows a client application to change the password held in the Connect object<br />
and the password recorded by an external security manager for the userid<br />
held in the Connect object. The external security manager is assumed to be<br />
located in the server defined by the Connect object. A CclOSecAttr object is<br />
returned if no errors occur.<br />
Details<br />
Details (serverName as String,<br />
userId as String,<br />
password as String)<br />
serverName<br />
The name of the server. If no name is supplied the default server—the<br />
first server named in the <strong>Gateway</strong> initialization file—is used. You can<br />
discover this name, after the first call to the server by using the<br />
ServerName method. The length is adjusted to 8 characters by padding<br />
with blanks.<br />
userId<br />
The user ID, if needed. The length is adjusted to 16 characters by padding<br />
with blanks.<br />
password<br />
The password corresponding to the user ID in userID, if needed. The<br />
length is adjusted to 16 characters by padding with blanks.<br />
Use this method to supply details of the <strong>CICS</strong> server. No interaction with the<br />
<strong>CICS</strong> server takes place until the Link, Status or Changed methods are called.<br />
The user ID and password are not needed if the connection is only used for<br />
status calls or if the server has no security.<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Link<br />
Link (flow as Object,<br />
programName as String,<br />
commArea as Object,<br />
unitOfWork as Object)<br />
or<br />
Link (flow as CclOFlow,<br />
programName as String,<br />
commArea as CclOBuf,<br />
unitOfWork as CclOUOW)<br />
flow<br />
The CclOFlow object used to control the client/server call.<br />
programName<br />
The name of the server program that is being called. The length is<br />
adjusted to 8 characters by padding with blanks or truncating, if<br />
necessary.<br />
commArea<br />
A CclOBuffer object that holds the data to be passed to the called program<br />
in a COMMAREA. A NULL value should be supplied if no COMMAREA<br />
is to be sent.<br />
unitOfWork<br />
The CclOUOW object that identifies the unit of work (UOW) with which<br />
this call is being associated. A NULL value should be supplied if no UOW<br />
is to be used.<br />
Calls the specified program on the server. The server program sees the<br />
incoming call as an EXEC <strong>CICS</strong> LINK call.<br />
MakeSecurityDefault<br />
MakeSecurityDefault()<br />
Informs the client that the current userid and password for this object is to<br />
become the default for ECI and EPI requests passed to the server as specified<br />
in the construction of the Connect object.<br />
Password<br />
Password() as String<br />
COM class: Connect<br />
Returns the password held by the CclOConnect object, padded with spaces.<br />
Chapter 1. COM 7
COM class: Connect<br />
ServerName<br />
ServerName() as String<br />
Returns the name of the server system held by the CclOConnect object and<br />
listed by the <strong>Gateway</strong> initialization file, or blanks if the default server is being<br />
used and no calls have yet been made.<br />
ServerStatus<br />
ServerStatus() as Integer<br />
or<br />
ServerStatus() as CclConnectStatusCodes<br />
Returns the status of the server connection, set by an earlier status or changed<br />
request. Possible values are:<br />
cclUnknown<br />
The <strong>CICS</strong> server status is unknown<br />
cclAvailable<br />
The <strong>CICS</strong> server is available<br />
cclUnavailable<br />
The <strong>CICS</strong> server is not available<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
ServerStatusText<br />
ServerStatusText() as String<br />
Returns a string, set by an earlier status or changed request, indicating the<br />
availability of the server.<br />
Status<br />
Status(flow as Object)<br />
or<br />
Status(flow as CclOFlow)<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
flow<br />
The CclOFlow object used to control the client/server call<br />
Request the status of the server connection.<br />
TranDetails<br />
TranDetails (runTran as String,<br />
attachTran as String)<br />
runTran<br />
The <strong>CICS</strong> transaction under which called programs will run. The default<br />
is to use the default server transaction. The length is adjusted to four<br />
characters by padding with blanks.<br />
attachTran<br />
The <strong>CICS</strong> transaction to which called programs are attached. The default<br />
is to use the default CPMI. The length is adjusted to four characters by<br />
padding with blanks.<br />
This method is used to supply additional information to the <strong>CICS</strong> server. The<br />
information is optional, but can be used to affect the environment in which<br />
programs are run on the <strong>CICS</strong> server.<br />
Note: Use the Details method, to supply details of the <strong>CICS</strong> server, before<br />
using the TranDetails method; see “Details” on page 6.<br />
UnpaddedPassword<br />
UnpaddedPassword() as String<br />
Returns the password held by the CclOConnect object, but with no padding<br />
with spaces at the end.<br />
UnpaddedServerName<br />
UnpaddedServerName() as String<br />
Returns the server name held by the CclOConnect object, but with no<br />
padding with spaces at the end.<br />
UnpaddedUserid<br />
UnpaddedUserid() as String<br />
COM class: Connect<br />
Chapter 1. COM 9
COM class: Connect<br />
Returns the userid held by the CclOConnect object, but with no padding with<br />
spaces at the end.<br />
UserId<br />
UserId() as String<br />
Returns the user ID held by the CclOConnect object, padded with spaces, or<br />
blanks if none.<br />
VerifyPassword<br />
VerifyPassword() as Object<br />
or<br />
VerifyPassword() as CclOSecAttr<br />
Allows a client application to verify that the password held in the Connect<br />
object matches the password recorded by an external security manager for the<br />
userid held in the Connect object. The external security manager is assumed<br />
to be located in the server defined by the Connect object. A CclOSecAttr<br />
Object is returned if no errors occur.<br />
ECI COM class<br />
All applications using the ECI COM class must first create a CclOECI object.<br />
The ECI COM class provides details of candidate <strong>CICS</strong> servers. It can also be<br />
used to obtain error information.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOECI<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
set var = CreateObject("Ccl.ECI")<br />
set var = New CclOECI<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Methods<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
ErrorFormat<br />
ErrorFormat() as Integer<br />
Returns a value indicating the current setting for the Error Message Format.<br />
Refer to SetErrorFormat for a current list of valid values.<br />
ErrorOffset<br />
ErrorOffset() as Long<br />
Returns a value which can be used to convert a Client daemon error value<br />
retrieved from the ERR.Number method into the documented ExCode error<br />
values. For more information on how to do this, refer to <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide.<br />
ErrorWindow<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ErrorWindow(display as Boolean)<br />
display<br />
true Permits the error window to be displayed to the user. This is the<br />
default setting.<br />
false The error window will not be displayed to the user. The<br />
application must check for errors using the ExCode method.<br />
ExCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCode() as Integer<br />
COM class: ECI<br />
Chapter 1. COM 11
COM class: ECI<br />
or<br />
ExCode() as CclECIExceptionCodes<br />
Returns an enumeration that indicates the last ECI error.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
The ExCodeText method returns a text string describing the error value.<br />
ExCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCodeText() as String<br />
Returns a text string describing the last ECI error.<br />
ServerCount<br />
ServerCount() as Integer<br />
Returns the number of candidate servers to which the client may be<br />
connected, as configured in the <strong>Gateway</strong> initialization file.<br />
ServerDesc<br />
ServerDesc(index as Integer) as String<br />
index<br />
The number of a connected server in the list, starting from 1<br />
Returns the description of the indexth server.<br />
ServerName<br />
ServerName(index as Integer) as String<br />
index<br />
The number of a connected server in the list, starting from 1<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Returns the name of the indexth server.<br />
SetErrorFormat<br />
SetErrorFormat(format as Integer)<br />
format<br />
0 Old format, provided for backward compatability only.<br />
1 New format, provides more information in the Visual Basic and<br />
VBScript Err object. This format is recommended.<br />
This method allows you to select an error message format.<br />
EPI COM class<br />
The EPI COM class initializes the Client daemon EPI function. It also has<br />
methods that allow you to obtain information about <strong>CICS</strong> servers which could<br />
be used. You create a CclOEPI object before you create CclOTerminal objects<br />
to connect to <strong>CICS</strong> servers. The Diagnose, ExCode, and State methods<br />
provide information on error conditions.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOEPI<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways<br />
Methods<br />
set var = CreateObject("Ccl.EPI")<br />
set var = New CclOEPI<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
Diagnose<br />
Diagnose() as String<br />
Returns a character string which holds a description of the last error.<br />
COM class: ECI<br />
Chapter 1. COM 13
COM class: EPI<br />
ErrorFormat<br />
ErrorFormat() as Integer<br />
Returns a value indicating the current setting for the Error Message Format.<br />
Refer to “SetErrorFormat” on page 16 for a current list of valid values.<br />
ErrorOffset<br />
ErrorOffset() as Long<br />
Returns a value which can be used to convert a Client daemon error value<br />
retrieved from the ERR.Number method into the documented ExCode error<br />
values. For more information on how to do this, refer to <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide.<br />
ErrorWindow<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ErrorWindow(display as Boolean)<br />
display<br />
true Permits the error window to be displayed to the user. This is the<br />
default setting.<br />
false The error window will not be displayed to the user. The<br />
application must check for errors using the ExCode method.<br />
ExCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCode() as Integer<br />
or<br />
ExCode() as CclEPIExceptionCodes<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Returns the condition code. Possible values are:<br />
cclSystemError<br />
An internal Client daemon system error occurred.<br />
cclUnknownServer<br />
There is no <strong>CICS</strong> server corresponding to the supplied index on<br />
ServerDesc or ServerName methods.<br />
cclNoError<br />
The call has executed normally.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
ExCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCodeText() as String<br />
Returns a string containing descriptive text for the most recent exception.<br />
ServerCount<br />
ServerCount() as Integer<br />
Returns the number of candidate servers to which the Client daemon may be<br />
connected, as configured in the <strong>Gateway</strong> initialization file.<br />
ServerDesc<br />
ServerDesc(index as Integer) as String<br />
index<br />
The index number of a connected server (starting from 1).<br />
COM class: EPI<br />
Returns a description of the selected <strong>CICS</strong> server, or a NULL string if no<br />
information is available in the <strong>Gateway</strong> initialization file for the specified<br />
server.<br />
Chapter 1. COM 15
COM class: EPI<br />
ServerName<br />
ServerName(index as Integer) as String<br />
index<br />
The index number of a connected server (starting from 1).<br />
Returns the name of the requested <strong>CICS</strong> server, or a NULL string if no<br />
information is available in the <strong>Gateway</strong> initialization file for the specified<br />
server.<br />
SetErrorFormat<br />
SetErrorFormat(format as Integer)<br />
format<br />
0 Old format, provided for backward compatability only.<br />
1 New format, provides more information in the Visual Basic and<br />
VBScript Err object. This format is recommended.<br />
This method allows you to select an error message format.<br />
State<br />
State() as Integer<br />
or<br />
State() as CclEPIStates<br />
Returns a value which indicates the state of the EPI. Possible values are:<br />
cclActive<br />
Initialized<br />
cclDiscon<br />
Terminated<br />
cclError<br />
Error. Refer to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Terminate<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
Terminates the Client daemon EPI in a controlled manner.<br />
Field COM class<br />
The Field COM class is used to access a single field on a 3270 screen.<br />
CclOField objects are created and deleted when 3270 data from the <strong>CICS</strong><br />
server is processed by a CclOScreen object.<br />
Field objects are returned by invoking a CclOScreen object’s fieldbyIndex or<br />
fieldbyPosition method. For example:<br />
set var=Screen.fieldbyIndex(1)<br />
Methods in this class allow field text and attributes to be read and updated.<br />
Updated fields are sent to the <strong>CICS</strong> server on the next transmission.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOField<br />
Methods<br />
Terminate()<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
AppendText<br />
AppendText(textString as String)<br />
textString<br />
The text string to be appended to the field.<br />
COM class: EPI<br />
Chapter 1. COM 17
COM class: Field<br />
Appends the characters within textString to the end of the text already in the<br />
field.<br />
BackgroundColor<br />
BackgroundColor() as Integer<br />
or<br />
BackgroundColor() as CclColorAttributes<br />
Returns a value which indicates the background color of the field as listed in<br />
“CclField Color Attributes” on page 187.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
BaseAttribute<br />
BaseAttribute() as Integer<br />
Returns the 3270 base attribute of the field.<br />
Column<br />
Column() as Integer<br />
Returns the column number of the position of the start of the field on the<br />
screen, with the leftmost column being 1.<br />
DataTag<br />
DataTag() as Integer<br />
or<br />
DataTag() as CclModifiedAttributes<br />
Returns a value which indicates whether the data in the field has been<br />
modified. Possible values are:<br />
cclModified<br />
cclUnmodified<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ForegroundColor<br />
ForegroundColor() as Integer<br />
or<br />
ForegroundColor() as CclColorAttributes<br />
Returns a value which indicates the foreground color of the field as listed in<br />
“CclField Color Attributes” on page 187.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Highlight<br />
Highlight() as Integer<br />
or<br />
Highlight() as CclHighlightAttributes<br />
Returns a value which indicates which type of highlight is being used as<br />
listed in “CclField Highlight Attributes” on page 187.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
InputProt<br />
InputProt() as Integer<br />
or<br />
InputProt() as CclProtAttributes<br />
COM class: Field<br />
Returns a value which indicates whether the field is protected. Possible values<br />
are:<br />
cclProtect<br />
cclUnprotect<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Chapter 1. COM 19
COM class: Field<br />
InputType<br />
InputType() as Integer<br />
or<br />
InputType() as CclNumericAttributes<br />
Returns a value which indicates whether the field is alphanumeric or numeric.<br />
Possible values are:<br />
cclAlphanumeric<br />
cclNumeric<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Intensity<br />
Intensity() as Integer<br />
or<br />
Intensity() as CclIntensityAttributes<br />
Returns a value which indicates whether the field is normal, intense or dark.<br />
Possible values are:<br />
cclDark<br />
cclNormal<br />
cclIntense<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Length<br />
Length() as Integer<br />
Returns the total length of the field. This includes one byte used to store the<br />
3270 attribute byte information; therefore the actual space for data is one less<br />
byte than the value returned by this method. See also the TextLength method.<br />
Position<br />
Position() as Integer<br />
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Returns the position of the start of the field as an offset from the top left<br />
corner of the screen. The top row consists of positions 0 to 79; the second row,<br />
positions 80 to 159; etc.<br />
ResetDataTag<br />
ResetDataTag()<br />
Resets the modified data tag (MDT) to cclUnmodified.<br />
Row<br />
Row() as Integer<br />
Returns the row number of the position of the start of the field on the screen.<br />
The top row is 1.<br />
SetBaseAttribute<br />
SetBaseAttribute(Attribute as Integer)<br />
Attribute<br />
The value of the base 3270 attribute to be entered into the field.<br />
Sets the 3270 base attribute.<br />
SetExtAttribute<br />
SetExtAttribute(Attribute as Integer, Value as Integer)<br />
Attribute<br />
The type of extended attribute to be set.<br />
Value<br />
The value of the extended attribute.<br />
Sets the extended 3270 attribute. If an invalid 3270 attribute type or value is<br />
supplied a parameter exception is raised.<br />
SetText<br />
SetText(textString as String)<br />
COM class: Field<br />
Chapter 1. COM 21
COM class: Field<br />
textString<br />
The null-terminated text to be entered into the field.<br />
Copies textString into the field.<br />
Text<br />
Text() as String<br />
Returns the text currently held in the field.<br />
TextLength<br />
TextLength() as Integer<br />
Returns the number of characters currently held in the field.<br />
Transparency<br />
Transparency() as Integer<br />
or<br />
Transparency() as CclTransparencyAttributes<br />
Returns a value which indicates the background transparency of the field as<br />
listed in “CclField Transparency Attributes” on page 187.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Flow COM class<br />
A CclOFlow object is used to control ECI communications for a client/server<br />
pair.<br />
A CclOFlow object is created for each client server interaction (call from client<br />
and response from server) and destroyed when it has been used. CclOFlow<br />
objects can be reused but an attempt to reuse a CclOFlow object that is<br />
already in use is rejected.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOFlow<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
Methods<br />
set var = CreateObject("Ccl.Flow")<br />
set var = New CclOFlow<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
AbendCode<br />
AbendCode() as String<br />
Returns a four-character <strong>CICS</strong> transaction abend code, or spaces if no abend<br />
has occurred.<br />
CallType<br />
CallType() as Integer<br />
or<br />
CallType() as CclFlowCallTypes<br />
Returns the type of call the flow is currently executing.current<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
CallTypeText<br />
CallTypeText() as String<br />
Returns the type of call the flow is currently executing as text.<br />
Diagnose<br />
Diagnose() as String<br />
Returns text describing the current state of the flow object.<br />
COM class: Flow<br />
Chapter 1. COM 23
COM class: Flow<br />
Flowid<br />
Flowid() as Integer<br />
Returns a unique identifier for this flow object.<br />
ForceReset<br />
ForceReset()<br />
Makes the flow inactive and resets it. Typically, this method is used to prepare<br />
a flow object for re-use or deletion after a flow has been abandoned.<br />
Poll<br />
Poll(commArea as Object) as Boolean<br />
or<br />
Poll(commArea as CclOBuf) as Boolean<br />
commArea<br />
A CclOBuffer object into which the returned COMMAREA will be placed.<br />
This parameter can be set to Nothing if no COMMAREA should be<br />
returned.<br />
Indicates whether a reply has been received from a deferred synchronous<br />
Backout, Cancel, Changed, Commit, Link, orStatus call request. This method<br />
is only valid for deferred synchronous communications. Possible values are:<br />
True A reply has been received.<br />
False A reply has not been received.<br />
SetSyncType<br />
SetSyncType(syncType as Integer)<br />
or<br />
SetSyncType(syncType as CclFlowSyncTypes)<br />
syncType<br />
The synchronization type required for this CclOFlow object. Possible<br />
values are:<br />
cclSync<br />
cclDSync<br />
Sets the synchronization type required for this CclOFlow object. If cclSync is<br />
used, link and status calls using this flow block the calling program until a<br />
reply is received from <strong>CICS</strong>. If cclDSync is used, link and status calls using<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
this flow return immediately to the calling program. The program can then<br />
use the Poll method to receive the reply from <strong>CICS</strong> later.<br />
SetTimeout<br />
SetTimeout(Timeout as Integer)<br />
Sets the timeout value for the flow object for the next activation of the flow.<br />
This value can be set while a flow is active, but does not affect the current<br />
active flow.<br />
SyncType<br />
SyncType() as Integer<br />
or<br />
SyncType() as CclFlowSyncTypes<br />
Returns the type of synchronisation being used.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Timeout<br />
Timeout() as Integer<br />
Returns the current timeout value set for the flow object.<br />
Wait<br />
Wait()<br />
COM class: Flow<br />
Waits for a reply from the server, blocking the client process in the meantime.<br />
This method is used when a deferred synchronous call was made, but the<br />
application now wants to wait synchronously for a reply.<br />
Chapter 1. COM 25
|<br />
|<br />
|<br />
|<br />
COM class: Map<br />
Map COM class<br />
The Map COM class provides validation and access to 3270 screen data using<br />
symbolic information obtained from <strong>CICS</strong> BMS maps. To use this interface,<br />
run the <strong>CICS</strong>BMSC utility on your server program BMS maps.<br />
Linux<br />
Note: <strong>CICS</strong>BMSC is not provided with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for the<br />
Linux operating system. If you require this functionality, contact your<br />
local IBM ® support representative and ask them to forward your<br />
request to the <strong>CICS</strong> service team.<br />
End of Linux<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOMap<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
Methods<br />
set var = CreateObject("Ccl.Map")<br />
set var = New CclOMap<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
ExCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCode() as Integer<br />
or<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ExCode() as CclEPIExceptionCodes<br />
Returns a value that indicates the current condition code.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
FieldByName<br />
FieldByName(name as Integer) as Object<br />
or<br />
FieldByName(name as Integer) as CclOField<br />
name<br />
Symbolic value for the required field. This value is provided in the<br />
.BAS file generated from the source BMS by the <strong>CICS</strong>BMSC<br />
utility.<br />
Returns the specified CclOField object.<br />
Validate<br />
Validate (screenRef as Object, mapname as String) as Boolean<br />
or<br />
Validate (screenRef as CclOScreen, mapname as String) as Boolean<br />
screenRef<br />
CclOScreen object<br />
mapname<br />
String value supplied in .BAS file generated from the source<br />
BMS by the <strong>CICS</strong>BMSC utility.<br />
Validate map against the current screen.<br />
COM class: Map<br />
This method can be used to verify that a specific BMS map has been received<br />
from the <strong>CICS</strong> server. Possible return values are:<br />
TRUE<br />
Specified BMS map matches current screen contents.<br />
FALSE<br />
Specified BMS map does not match current screen contents<br />
If TRUE is returned, the FieldByName method can be used to access fields<br />
using their BMS name.<br />
Chapter 1. COM 27
COM class: Screen<br />
Screen COM class<br />
The Screen COM class maintains all data on the 3270 virtual screen and<br />
provides access to this data. It contains a collection of CclOField objects which<br />
represent the fields on the current 3270 screen.<br />
A single Screen object is created by the Terminal object when the terminal is<br />
installed either with the Ccl Terminal connect or install method. The<br />
application gets access to the CclOScreen object via the Ccl Terminal Screen<br />
method.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOScreen<br />
Methods<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
CursorCol<br />
CursorCol() as Integer<br />
Returns the current cursor column (the left col is 1).<br />
CursorRow<br />
CursorRow() as Integer<br />
Returns the current cursor row (the top row is 1).<br />
Depth<br />
Depth() as Integer<br />
Returns the number of rows on the screen.<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
FieldByIndex<br />
FieldByIndex(index as Integer) as Object<br />
or<br />
FieldByIndex(index as Integer) as CclOField<br />
index<br />
The index number of the field required. The first field is number 1.<br />
FieldByPosition<br />
FieldByPosition (rowPos as Integer, colPos as Integer) as Object<br />
or<br />
FieldByPosition (rowPos as Integer, colPos as Integer) as CclOField<br />
rowPos<br />
The row number of the field (topmost row = 1).<br />
colPos<br />
The column number of the field (leftmost column = 1).<br />
FieldCount<br />
FieldCount() as Integer<br />
Returns the number of fields on the screen.<br />
MapName<br />
MapName() as String<br />
Returns a string specifying the name of the map that was most recently<br />
referenced in the MAP option of a SEND MAP command processed for the<br />
terminal resource. If the terminal resource is not supported by BMS, or the<br />
server has no record of any map being sent, the value returned is blank.<br />
MapSetName<br />
MapSetName() as String<br />
COM class: Screen<br />
Returns a string specifying the name of the mapset that was most recently<br />
referenced in the MAPSET option of a SEND MAP command processed for<br />
the terminal resource. If the MAPSET option was not specified on the most<br />
recent request, BMS used the map name as the mapset name. In both cases,<br />
the mapset name used may have been suffixed by a terminal suffix. If the<br />
Chapter 1. COM 29
COM class: Screen<br />
terminal resource is not supported by BMS, or the server has no record of any<br />
mapset being sent, the value returned is blank.<br />
SetAID<br />
SetAID(key as Integer)<br />
or<br />
SetAID(key as CclADIKeys)<br />
key<br />
The AID key value as listed in “CclScreen AID key codes” on page 185.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
Sets the AID key value to be passed to the server on the next transmission.<br />
SetCursor<br />
rowPos<br />
The required row number of the cursor (the top row is 1).<br />
colPos<br />
The required column number of the cursor (the left column is 1).<br />
Width<br />
SecAttr COM class<br />
SetCursor (rowPos as Integer, colPos as Integer)<br />
Width() as Integer<br />
Returns the number of columns on the screen.<br />
The SecAttr COM class provides information about passwords reported back<br />
by the external security manager when issuing verifySecurity or<br />
changePassword methods on CclOConnect or CclOTerminal objects.<br />
This object is created and owned by the CclOConnect or CclOTerminal Object<br />
and access to this object is provided when invoking the VerifyPassword or<br />
ChangePassword methods.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Methods<br />
Dim var as Object<br />
Dim var as CclOSecAttr<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
ExpiryTime<br />
ExpiryTime() as Object<br />
or<br />
ExpiryTime() as CclOSecTime<br />
Returns a CclOSecTime object that contains the date and time when the<br />
password will expire.<br />
InvalidCount<br />
InvalidCount() as Integer<br />
Returns the number of times an invalid password has been entered for the<br />
userid.<br />
LastAccessTime<br />
LastAccessTime() as Object<br />
or<br />
LastAccessTime() as CclOSecTime<br />
Returns a CclOSecTime object which contains the date and time when the<br />
userid was last accessed.<br />
LastVerifiedTime<br />
LastVerifiedTime() as Object<br />
or<br />
LastVerifiedTime() as CclOSecTime<br />
COM class: Screen<br />
Chapter 1. COM 31
COM class: Screen<br />
Returns a CclOSecTime object which contains the date and time of the last<br />
verification.<br />
SecTime COM class<br />
The SecTime COM class provides date and time information in the<br />
CclOSecAttr object for various entries reported back by the external security<br />
manager when issuing verifySecurity or changePassword methods on Connect<br />
or Terminal objects.<br />
These objects are created and owned by the CclOSecAttr object and access is<br />
obtained via the various methods available on this object. No constructors or<br />
destructors are available.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOSecTime<br />
Methods<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Day<br />
unsigned short Day() as Integer<br />
Returns the day in the range 1 to 31.<br />
GetDate<br />
GetDate() as Date<br />
Returns the date and time in a Visual Basic DATE type format.<br />
Hours<br />
unsigned short Hours() as Integer<br />
Returns the hours in the range 0 to 23.<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Hundredths<br />
unsigned short Hundredths() as Integer<br />
Returns the hundredths of a second in the range 0 to 99.<br />
Minutes<br />
unsigned short Minutes() as Integer<br />
Returns the minutes in the range 0 to 59.<br />
Month<br />
unsigned short Month() as Integer<br />
Returns the month in the range 1 to 12.<br />
Seconds<br />
unsigned short Seconds() as Integer<br />
Returns the seconds in the range 0 to 59.<br />
Year<br />
Session COM class<br />
unsigned short Year() as Integer<br />
Returns a 4 digit year.<br />
The Session COM class controls the flow of data to and from <strong>CICS</strong> within a<br />
single EPI session.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOSession<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
COM class: Screen<br />
Chapter 1. COM 33
COM class: Session<br />
Methods<br />
set var = CreateObject("Ccl.Session")<br />
set var = New CclOSession<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
Diagnose<br />
Diagnose() as String<br />
Returns the text description of the current state of the session.<br />
SetSyncType<br />
SetSyncType(syncType as Integer)<br />
or<br />
SetSyncType(syncType as CclFlowSyncTypes)<br />
syncType<br />
The synchronization type required for this CclOSession object. Possible<br />
values are:<br />
cclSync<br />
cclDSync<br />
Sets the synchronization type required for this CclOSession object. If cclSync is<br />
used, Start and Send calls using this flow will block the calling program until<br />
a reply is received from <strong>CICS</strong>. If cclDSync is used, Start and Send calls using<br />
this flow will return immediately to the calling program. The program can<br />
then use the Poll method to receive the reply from <strong>CICS</strong> at a later time.<br />
State<br />
State() as Integer<br />
or<br />
State() as CclEPIStates<br />
Returns a value which indicates the current state of the session. Possible<br />
values are:<br />
cclActive<br />
Connected<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
cclServer<br />
<strong>Transaction</strong> in progress in the <strong>CICS</strong> server.<br />
cclClient<br />
<strong>CICS</strong> server is waiting for a response from the client<br />
cclDiscon<br />
Disconnected<br />
cclError<br />
Error, call ExCode and Diagnose methods for further information.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
TransId<br />
TransId() as String<br />
Returns the four-letter name of the current transaction.<br />
Terminal COM class<br />
The Terminal COM class represents a 3270 terminal connection to a <strong>CICS</strong><br />
server. A <strong>CICS</strong> connection is established when the Connect method is called.<br />
Methods can then be used to converse with a 3270 terminal application (often<br />
a BMS application) in the <strong>CICS</strong> server.<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOTerminal<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
set var = CreateObject("Ccl.Terminal")<br />
set var = New CclOTerminal<br />
COM class: Session<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
Chapter 1. COM 35
COM class: Terminal<br />
Methods<br />
AlterSecurity<br />
AlterSecurity(newUserid as String,newPassword as String)<br />
newPassword<br />
The new password to be given to newUserid.<br />
newUserid<br />
The new userid.<br />
Allows you to redefine the userid and password for a terminal resource that<br />
has been constructed without them (a signon incapable terminal). The method<br />
can be called before you install a terminal. It changes the terminal definition;<br />
the new userid and password are be used for the terminal when install is<br />
called.<br />
CCSId<br />
CCSId() as long<br />
Returns a long showing the selected code page.<br />
ChangePassword<br />
ChangePassword(newPassword as String) as Object<br />
or<br />
ChangePassword(newPassword as String) as CclOSecAttr<br />
newPassword<br />
The new password to be given<br />
Allows a client application to change the password held in the terminal object<br />
and the password recorded by an external security manager for the userid<br />
held in the terminal object. The external security manager is assumed to be<br />
located in the server defined by the terminal object. A CclOSecAttr Object is<br />
returned if no errors occurred.<br />
Connect<br />
Connect(servName as String,<br />
devType as String,<br />
nworkName as String)<br />
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
servName<br />
The name of the server with which you want to communicate. If a NULL<br />
string is provided, the default server system, defined in the <strong>Gateway</strong><br />
initialization file, is assumed. The name is expanded to 8 characters by<br />
padding with blanks, if necessary.<br />
devType<br />
The name of the model terminal definition which the server uses to<br />
generate a terminal resource definition. If a NULL string is provided the<br />
default model is used. The name is expanded to 16 characters by padding<br />
with blanks, if necessary.<br />
nworkName<br />
The name of the terminal resource to be installed or reserved. The name is<br />
expanded to 8 characters by padding with blanks, if necessary. If a NULL<br />
string is supplied, the <strong>CICS</strong> server allocates a name.<br />
Establishes a 3270 communication to the specified <strong>CICS</strong> server.<br />
Devtype<br />
Devtype() as String<br />
Returns the terminal device type as a string.<br />
Diagnose<br />
Diagnose() as String<br />
Returns a character string which holds a description of the error returned by<br />
the most recent server call.<br />
Disconnect<br />
Disconnect()<br />
Disconnects the terminal from <strong>CICS</strong>. No attempt is made to purge any<br />
outstanding running transaction.<br />
DisconnectWithPurge<br />
DisconnectWithPurge()<br />
COM class: Terminal<br />
Disconnects the terminal from <strong>CICS</strong> and attempts to purge any outstanding<br />
running transaction. This purge function does not cancel ATI requests queued<br />
against the terminal.<br />
Chapter 1. COM 37
COM class: Terminal<br />
DiscReason<br />
DiscReason() as CclEndTermReasons<br />
This method will return an enumeration showing the reason the terminal has<br />
been disconnected. Possible values are shown in “CclTerminal<br />
EndTermReasons” on page 184.<br />
ExCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCode() as Integer<br />
or<br />
ExCode() as CclEPIExceptionCodes<br />
Returns a value which indicates the most recent condition code returned by<br />
the server.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
ExCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
ExCodeText() as String<br />
Returns a text string describing the most recent condition code returned by<br />
the server.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Install<br />
Install(session as Object, timeout as Integer)<br />
or<br />
Install(session as CclOSession, timeout as Integer)<br />
session<br />
The session object to be used by this terminal object.<br />
InstallTimeout<br />
A value in the range 0 through 3600, specifying the maximum time in<br />
seconds that installation of the terminal resource is allowed to take. A<br />
value of 0 means that no limit is set.<br />
This method installs a non-connected terminal resource. A cclInvalidState<br />
error is raised if the terminal is already installed.<br />
MakeSecurityDefault<br />
MakeSecurityDefault()<br />
Informs the client that the current userid and password for this object is to<br />
become the default for ECI and EPI requests passed to the server as specified<br />
in the construction of the Terminal object.<br />
NetName<br />
NetName() as String<br />
Returns the network name of the terminal.<br />
Password<br />
Password() as String<br />
Returns a text string containing the current password for the userid associated<br />
with the terminal. The string is empty if there is no password.<br />
Poll<br />
Poll() as Boolean<br />
COM class: Terminal<br />
Checks to see if a replies have been received from a deferred synchronous<br />
Start or Send request. Possible values are:<br />
True No further replies outstanding<br />
Chapter 1. COM 39
COM class: Terminal<br />
False Further replies outstanding<br />
A <strong>CICS</strong> server transaction may send more than one reply in response to a<br />
Terminal.Start or Terminal.Send call. More than one Terminal.Poll call may<br />
therefore be needed to collect all the replies. The return code indicates<br />
whether you need to perform more poll requests.<br />
PollForReply<br />
PollForReply() as Boolean<br />
Checks to see if replies have been received from a deferred synchronous Start<br />
or Send request. Possible values are<br />
true Replies have been received<br />
false No replies have been received<br />
A <strong>CICS</strong> server transaction may send more than one reply in response to a<br />
Terminal.Start or Terminal.Send call. More than one Terminal.PollForReply call<br />
may therefore be needed to collect all replies. Use the Terminal.State method<br />
to find out if further replies are expected. If there are, the value returned will<br />
be cclServer.<br />
QueryATI<br />
QueryATI() as Integer<br />
or<br />
QueryATI() as CclATIStates<br />
Returns a value that indicates whether Automatic <strong>Transaction</strong> Initiation (ATI)<br />
is enabled or disabled. Possible values are:<br />
cclATIEnabled<br />
cclATIDisabled<br />
ReadTimeout<br />
ReadTimeout() as Integer<br />
Returns the read timeout setting for the terminal.<br />
ReceiveATI<br />
ReceiveATI (session as Object)<br />
or<br />
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ReceiveATI (session as CclOSession)<br />
session<br />
A pointer to the CclOSession object which is to be used for the <strong>CICS</strong><br />
server interaction.<br />
Waits for and receives 3270 datastream for a <strong>CICS</strong> ATI transaction. The<br />
CclOSession object supplied can only be synchronous.<br />
Screen<br />
Screen() as Object<br />
Returns the CclOScreen object that is handling the 3270 screen associated with<br />
this terminal.<br />
Send<br />
Send(session as Object)<br />
or<br />
Send(session as CclOSession)<br />
session<br />
The CclOSession object which controls the session which is to be used. It<br />
is set to NULL if no CclOSession object is used.<br />
Generates a 3270 data stream from the current contents of the CclOScreen<br />
object and transmits it to the <strong>CICS</strong> server.<br />
ServerName<br />
ServerName() as String<br />
Returns the name of the server system held by the CclOTerminal object and<br />
listed by the <strong>Gateway</strong> initialization file, or blanks if the default server is being<br />
used and no calls have yet been made.<br />
SetATI<br />
SetATI(stateVal as Integer)<br />
or<br />
SetATI(stateVal as CclATIStates)<br />
COM class: Terminal<br />
Chapter 1. COM 41
COM class: Terminal<br />
stateVal<br />
A value which indicates whether the ATI is to be enabled or disabled.<br />
Possible values are:<br />
cclATIEnabled<br />
cclATIDisabled<br />
SetTermDefns<br />
SetTermDefns (servName as String,<br />
devType as String,<br />
nworkName as String<br />
signonCapability as CclSignonTypes<br />
userid as String<br />
password as String<br />
ReadTimeout as Integer<br />
CCSid as Long)<br />
servName<br />
The name of the server with which you want to communicate. If a<br />
NULL string is provided, the default server system, defined in the<br />
<strong>Gateway</strong> initialization file, is assumed. The name is expanded to 8<br />
characters by padding with blanks, if necessary.<br />
devType<br />
The name of the model terminal definition which the server uses to<br />
generate a terminal resource definition. If a NULL string is provided<br />
the default model is used. The name is expanded to 16 characters by<br />
padding with blanks, if necessary.<br />
nworkName<br />
The name of the terminal resource to be installed or reserved. The<br />
name is expanded to 8 characters by padding with blanks, if<br />
necessary. If a NULL string is supplied, the <strong>CICS</strong> server will allocate a<br />
name.<br />
signonCapability<br />
Set the signon capability to one of the following:<br />
cclSignonCapable<br />
cclSignonIncapable<br />
ReadTimeout<br />
A value in the range 0 through 3600, specifying the maximum time in<br />
seconds between the time the classes go clientrepl state and the time<br />
that the application program invokes the reply method.<br />
userid The name of the userid to associate with this terminal resource.<br />
password<br />
The password to associate with the userid.<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
CCSid A long specifying the coded character set indentifier (CCSID) that<br />
identifies the coded graphic character set used by the client<br />
application for data passed between the terminal resource and <strong>CICS</strong><br />
transactions. A zero indicates that a default will be used.<br />
Creates a terminal resource but does not make the connection to the Server.<br />
SignonCapability<br />
SignonCapability() as Integer<br />
or<br />
SignonCapability() as CclSignonTypes<br />
Returns the type of terminal installed. Possible values are:<br />
v cclSignonCapable<br />
v cclSignonIncapable<br />
Start<br />
Start (session as Object,<br />
tranCode as String,<br />
startData as String)<br />
or<br />
COM class: Terminal<br />
Start (session as CclOSession,<br />
tranCode as String,<br />
startData as String)<br />
session<br />
The CclOSession object which controls the session which is to be used. It<br />
is set to NULL if no CclOSession object is used.<br />
tranCode<br />
The name of the transaction which is to be started<br />
startData<br />
Start transaction data. A NULL value indicates no data is required for the<br />
transaction being started.<br />
Generates a 3270 data stream from the supplied data and transmits it to the<br />
<strong>CICS</strong> server, starting the named transaction.<br />
Chapter 1. COM 43
COM class: Terminal<br />
State<br />
State() as Integer<br />
or<br />
State() as CclEPIStates<br />
Returns a value which indicates the current state of the session. These values<br />
are the same as those returned by the state method in the Session COM class.<br />
Constants are available in the type library. Use the Visual Basic Object<br />
Browser to view them.<br />
TermId<br />
TermId() as String<br />
Returns the terminal ID.<br />
TransId<br />
TransId() as String<br />
Returns the 4-character name of the current <strong>CICS</strong> transaction. Note that if a<br />
RETURN IMMEDIATE is run from the current transaction, TransId does not<br />
provide the name of the new transaction; it still contains the name of the first<br />
transaction.<br />
Userid<br />
Userid() as String<br />
Returns a text string containing the current userid for the terminal. The string<br />
is empty if there is no userid.<br />
VerifyPassword<br />
VerifyPassword() as Object<br />
or<br />
VerifyPassword() as CclOSecAttr<br />
Allows a client application to verify that the password held in the terminal<br />
object matches the password recorded by an external security manager for the<br />
userid held in the terminal object. The external security manager is assumed<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
to be located in the server defined by the terminal object. A CclOSecAttr<br />
Object is returned if no errors occurred.<br />
UOW COM class<br />
Use this COM class when you make updates to recoverable resources in the<br />
server within a “unit of work” (UOW). Each update in a UOW is identified<br />
by a reference to its CclOUOW object — see Link method in Connect COM<br />
class (“Link” on page 7).<br />
Interface Selection<br />
For Visual Basic, the following types of interface are available:<br />
Dim var as Object<br />
Dim var as CclOUOW<br />
The second method is preferred.<br />
If you do not dim a variable, dim it with no type, or are using VBScript, the<br />
variable is assumed to be of type Object.<br />
Object Creation<br />
You can create an object in two ways:<br />
Methods<br />
set var = CreateObject("Ccl.UOW")<br />
set var = New CclOUOW<br />
New is the preferred method in Visual Basic. For VBScript, you can use only<br />
the CreateObject method.<br />
BackOut<br />
BackOut(flow as Object)<br />
or<br />
COM class: Terminal<br />
BackOut(flow as CclOFlow)<br />
flow<br />
The CclOFlow object which is used to control the client/server call<br />
Terminate this UOW and back out all changes made to recoverable resources<br />
in the server.<br />
Chapter 1. COM 45
COM class: UOW<br />
Commit<br />
Commit(flow as Object)<br />
or<br />
Commit(flow as CclOFlow)<br />
flow<br />
The CclOFlow object which is used to control the client/server call<br />
Terminate this UOW and commit all changes made to recoverable resources in<br />
the server.<br />
ForceReset<br />
ForceReset()<br />
Makes this UOW inactive and resets it. The UOW is neither commited or<br />
backed out.<br />
UowId<br />
UowId() as long<br />
Returns the identifier of the UOW. A zero return indicates that the UOW is<br />
either complete or has not yet started, in other words it is inactive.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Chapter 2. Java<br />
Online programming reference information is provided for the Java classes<br />
and interfaces provided with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
The reference information is in HTML format and is generated using the<br />
Javadoc tool provided with the JDK .<br />
To get to the reference information:<br />
v On Windows, select the Programming Reference icon.<br />
v On AIX ® , Solaris, Linux, and HP-UX, run the ctgdoc script.<br />
This displays the library home page, from where you can follow the links<br />
to the reference information.<br />
The following sections describe the different kinds of HTML pages that are<br />
provided within the reference information.<br />
See the README file for the latest information on using the programming<br />
reference information.<br />
Class/interface page<br />
In the reference pages, each class and interface has its own page. In each of<br />
these pages, there are three sections:<br />
1. Class/interface description:<br />
v Class inheritance diagram<br />
v Direct Subclasses<br />
v All Known Subinterfaces<br />
v All Known Implementing Classes<br />
v Class/interface declaration<br />
v Class/interface description<br />
2. Summary tables:<br />
v Inner Class Summary<br />
v Field Summary<br />
v Constructor Summary<br />
v Method Summary<br />
3. Class/interface description:<br />
v Field Detail<br />
© Copyright IBM Corp. 1989, 2002 47
Use page<br />
v Constructor Detail<br />
v Method Detail<br />
Each summary entry contains the first sentence from the detailed description<br />
for that item. The summary entries are alphabetical, while the detailed<br />
descriptions are in the order they appear in the source code. This preserves<br />
the logical groupings established by the programmer.<br />
Each documented class and interface has its own Use page. This page<br />
describes what packages, classes, methods, constructors and fields use any<br />
part of the given class. The Use page for a package or interface A includes:<br />
v Subclasses of A<br />
v Fields declared as A<br />
v Methods that return A<br />
v Methods and constructors with parameters of type A.<br />
To access this page, go to the class or interface, then click on the Use link in<br />
the navigation bar.<br />
Tree (Class Hierarchy)<br />
When viewing a particular class or interface page, selecting Tree displays the<br />
class and interface hierarchy for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
Deprecated API<br />
The Deprecated API page lists all of the API that have been deprecated. A<br />
deprecated API is not recommended for use, generally due to improvements.<br />
Deprecated APIs may be removed in future implementations.<br />
Index page<br />
The Index contains an alphabetic list of all classes, interfaces, constructors,<br />
methods, and fields.<br />
48 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Chapter 3. C++<br />
Ccl class<br />
This class defines enumerations which are used by other classes—both ECI<br />
and EPI.<br />
Enumerations<br />
Bool<br />
There are two equivalent pairs of values:<br />
no and yes<br />
off and on<br />
Sync<br />
Possible values are:<br />
async asynchronous<br />
dsync deferred synchronous<br />
sync synchronous<br />
ExCode<br />
For possible values, refer to Table 20 on page 199.<br />
CclBuf class<br />
A CclBuf object contains a data area in memory that can be used to hold<br />
information. A particular use for a CclBuf object is to hold a COMMAREA,<br />
which passes data to and from a <strong>CICS</strong> server.<br />
The CclBuf object is primarily intended for use with byte (binary) data. A<br />
typical COMMAREA contains an application-specific data structure, often<br />
originating from a <strong>CICS</strong> server PL/1 or C program. Methods such as assign()<br />
and insert() therefore provide a void* parameter type for application data<br />
input. There is limited support for SBCS null-terminated strings (some of the<br />
code samples make use of this), but there is no code-page conversion or DBCS<br />
support in the CclBuf class.<br />
The maximum data length for a buffer is the maximum value for unsigned<br />
long (2 32 ) for 32 bit platforms. <strong>CICS</strong> imposes a limit of 32500 bytes in<br />
COMMAREAs. This may be reduced by setting the MaxBufferSize parameter<br />
in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file. See the <strong>CICS</strong> <strong>Transaction</strong><br />
© Copyright IBM Corp. 1989, 2002 49
CclBuf Class<br />
<strong>Gateway</strong>: Administration book for your operating system, for more information.<br />
If a buffer object used as a COMMAREA is too long, a data length exception<br />
is raised.<br />
When a CclBuf object is created it either uses an area of memory passed to it<br />
as its buffer, or allocates its own. The length of the data in this buffer can be<br />
reduced after the CclBuf object is created. The length of the data in this buffer<br />
can only be increased beyond the original length if the CclBuf object is created<br />
with a DataAreaType of extensible, rather than fixed.<br />
If a buffer object has a DataAreaType of fixed and a method is called which<br />
would result in its data area length being exceeded, a buffer overflow<br />
exception is raised. If the exception is not handled, the buffer will contain the<br />
result of the call, truncated to the data area length.<br />
If a method is called that results in a buffer object having a data length<br />
smaller than its data area length, the data is padded with nulls.<br />
Many of the methods return object references. This makes it possible for users<br />
to chain calls to member functions. For example, the code:<br />
CclBuf comma1;<br />
comma1="Some text";<br />
comma1.insert( 9,"inserted ",5) += " at the end";<br />
would create the following string:<br />
Some inserted text at the end<br />
CclBuf constructors<br />
CclBuf (1)<br />
CclBuf(unsigned long length, DataAreaType type = extensible)<br />
length<br />
The initial length of the data area, in bytes. The default is 0.<br />
type<br />
An enumeration indicating whether the data area can be extended.<br />
Possible values are extensible or fixed. The default is extensible.<br />
Creates a CclBuf object, allocating its own data area with the given length. All<br />
the bytes within it are set to null. The data length is set to zero and remains<br />
zero until data is put in the buffer.<br />
CclBuf (2)<br />
CclBuf(unsigned long length, void* dataArea)<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
length<br />
The length of the supplied data area, in bytes.<br />
dataArea<br />
The address of the first byte of the supplied data area.<br />
Creates a CclBuf object that cannot be extended, adopting the given data area<br />
as its own. The DataAreaOwner is set external.<br />
CclBuf (3)<br />
CclBuf(const char* text, DataAreaType type = extensible)<br />
text<br />
A string to be copied into the new CclBuf object.<br />
type<br />
An enumeration indicating whether the data area can be extended.<br />
Possible values are extensible or fixed. The default is extensible.<br />
Creates a CclBuf object, allocating its own data area with the same length as<br />
the text string and copies the string into its data area.<br />
CclBuf (4)<br />
CclBuf(const CclBuf& buffer)<br />
buffer<br />
A reference to the CclBuf object that is to be copied.<br />
This copy constructor creates a new CclBuf object, which is a copy of the<br />
given object. The data length, data area length and data area type of the new<br />
buffer are the same as the old buffer. The data area owner of the new buffer is<br />
internal.<br />
Public methods<br />
assign<br />
CclBuf& assign(unsigned long length, const void* dataArea)<br />
length<br />
The length of the source data area, in bytes.<br />
dataArea<br />
The address of the source data area.<br />
Overwrites the current contents of the data area with the source data and<br />
resets the data length.<br />
cut<br />
CclBuf& cut(unsigned long length, unsigned long offset =0)<br />
CclBuf Class<br />
Chapter 3. C++ 51
CclBuf Class<br />
length<br />
The number of bytes to be cut from the data area.<br />
offset<br />
The offset into the data area. The default is zero.<br />
Cuts the specified data from the data area. Data in the data area is padded<br />
with nulls.<br />
dataArea<br />
const void* dataArea(unsigned long offset = 0) const<br />
offset<br />
The offset into the data area. The default is zero.<br />
Returns the address of the given offset into the data area.<br />
dataAreaLength<br />
unsigned long dataAreaLength() const<br />
Returns the length of the data area in bytes.<br />
dataAreaOwner<br />
DataAreaOwner dataAreaOwner() const<br />
Returns an enumeration value indicating whether the data area has been<br />
allocated by the CclBuf constructor or has been supplied from elsewhere.<br />
Possible values are internal and external.<br />
dataAreaType<br />
DataAreaType dataAreaType() const<br />
Returns an enumeration value indicating whether the data area can be<br />
extended. Possible values are extensible and fixed.<br />
dataLength<br />
unsigned long dataLength() const<br />
Returns the length of data in the data area. This cannot be greater than the<br />
value returned by dataAreaLength.<br />
52 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
insert<br />
CclBuf& insert(unsigned long length,<br />
const void* dataArea,<br />
unsigned long offset =0)<br />
length<br />
The length of the data, in bytes, to be inserted into the CclBuf object.<br />
dataArea<br />
The start of the source data to be inserted into the CclBuf object.<br />
offset<br />
The offset into the data area where the data is to be inserted. The default<br />
is zero.<br />
Inserts the source data into the data area at the given offset.<br />
listState<br />
const char* listState() const<br />
Returns a formatted string containing the current state of the object. For<br />
example:<br />
Buffer state..&CclBuf=000489B4 &CclBufI=00203A00<br />
dataLength=8 &dataArea=002039C0<br />
dataAreaLength=8 dataAreaOwner=0 dataAreaType=1<br />
operator= (1)<br />
CclBuf& operator=(const CclBuf& buffer)<br />
buffer<br />
A reference to a CclBuf object.<br />
Assigns data from another buffer object.<br />
operator= (2)<br />
CclBuf& operator=(const char* text)<br />
text<br />
The string to be assigned to the CclBuf object.<br />
Assigns data from a string.<br />
operator+= (1)<br />
CclBuf& operator+=(const CclBuf& buffer)<br />
buffer<br />
A reference to a CclBuf object.<br />
CclBuf Class<br />
Chapter 3. C++ 53
CclBuf Class<br />
Appends data from another buffer object to the data in the data area.<br />
operator+= (2)<br />
CclBuf& operator+=(const char* text)<br />
text<br />
The string to be appended to the CclBuf object.<br />
Appends a string to the data in the data area.<br />
operator==<br />
Ccl::Bool operator==(const CclBuf& buffer) const<br />
buffer<br />
A reference to a CclBuf object.<br />
Returns an enumeration indicating whether the data contained in the buffers<br />
of the two CclBuf objects is the same. Possible values are yes, indicating that<br />
the data lengths and contents are the same, or no.<br />
operator!=<br />
Ccl::Bool operator!=(const CclBuf& buffer) const<br />
buffer<br />
A reference to a CclBuf object.<br />
Returns an enumeration indicating whether the data contained in the buffers<br />
of the two CclBuf objects is different. Possible values are yes or no. no means<br />
that the data lengths are the same and the contents are the same.<br />
replace<br />
CclBuf& replace(unsigned long length,<br />
const void* dataArea,<br />
unsigned long offset =0)<br />
length<br />
The length of the source data area, in bytes.<br />
dataArea<br />
The address of the start of the source data area.<br />
offset<br />
The position where the new data is to be written, relative to the start of<br />
the CclBuf data area. The default is zero.<br />
Overwrites the current contents of the data area at the given offset with the<br />
source data. The data length remains the same.<br />
54 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
setDataLength<br />
unsigned long setDataLength(unsigned long length)<br />
length<br />
The new length of the data area, in bytes.<br />
Changes the current length of the data area and returns the new length. If the<br />
CclBuf object is not extensible, the data area length is set to either the original<br />
length of the data area, or length, whichever is less.<br />
Enumerations<br />
If length is greater than the data area length, the data is padded with nulls.<br />
DataAreaOwner<br />
Indicates whether the data area of a CclBuf object has been allocated outside<br />
the object. Possible values are:<br />
internal<br />
The data area has been allocated by the CclBuf constructor.<br />
external<br />
The data area has been allocated externally.<br />
DataAreaType<br />
CclBuf Class<br />
Indicates whether the data area of a CclBuf object can be made longer than its<br />
original length. Possible values are:<br />
extensible<br />
The data area of a CclBuf object can be made longer than its original<br />
length.<br />
fixed The data area of a CclBuf object cannot be made longer than its<br />
original length.<br />
CclConn class<br />
An object of class CclConn is used to represent an ECI connection between a<br />
client and a named server. See Server connection in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide. Access to the server is optionally controlled by a<br />
userId and password. It can call a program in the server or get information on<br />
the state of the connection. See Passing data to a server program in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide and Monitoring server availability in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more information.<br />
The creation of a CclConn object does not cause any interaction with the <strong>CICS</strong><br />
server, nor does it guarantee that the server is available to process requests.<br />
Chapter 3. C++ 55
C++ Class: CclConn<br />
Any interaction between client and server requires the use of a CclFlow<br />
object. See Compiling and Linking in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide for more information.<br />
A CclConn object cannot be copied or assigned. Any attempt to delete a<br />
CclConn object for which there are active CclFlow or CclUOW objects raises<br />
an activeFlow or an activeUOW exception.<br />
CclConn constructor<br />
CclConn(const char* serverName =0,<br />
const char* userId =0,<br />
const char* password =0,<br />
const char* runTran =0,<br />
const char* attachTran =0)<br />
serverName<br />
The name of the server. If no name is supplied the default server is used.<br />
After the first call to the server you can discover this name by using the<br />
serverName method. The length is adjusted to 8 characters by padding<br />
with blanks or truncating, if necessary.<br />
userId<br />
The userId, if needed. The length is adjusted to 16 characters by padding<br />
with blanks or truncating, if necessary.<br />
password<br />
The password corresponding to the userId in userID, if needed. The length<br />
is adjusted to 16 characters by padding with blanks or truncating, if<br />
necessary.<br />
runTran<br />
The <strong>CICS</strong> transaction under which the called program will run. The<br />
default is to use the default server transaction. The length is adjusted to 4<br />
characters by padding with blanks or truncating, if necessary.<br />
attachTran<br />
The <strong>CICS</strong> transaction to which the called program is attached. The default<br />
is to use the default CPMI. The length is adjusted to 4 characters by<br />
padding with blanks or truncating, if necessary.<br />
This constructor creates a CclConn object; it does not cause any interaction<br />
with the <strong>CICS</strong> server or guarantee that the server is available to process<br />
requests. The userId and password are not needed if the connection is used<br />
only for status calls, or if the server has no security.<br />
Public methods<br />
alterSecurity<br />
void alterSecurity(const char* newUserid, const char* newPassword)<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
newUserid<br />
The new userid<br />
newPassword<br />
The new password corresponding to the new userid<br />
Updates the Userid and Password to be used on the next link call<br />
cancel<br />
void cancel(CclFlow& flow)<br />
flow<br />
A reference to the CclFlow object used to control the server request call.<br />
Cancels any changed call that was previously issued to the server associated<br />
with this connection.<br />
changed<br />
void changed(CclFlow& flow)<br />
flow<br />
A reference to the CclFlow object used to control the server request call.<br />
Requests the server to notify the Client daemon when the current connection<br />
status changes. The call is ignored if there is already an outstanding changed<br />
call for this connection. Use serverStatus or serverStatusText to obtain server<br />
availability.<br />
changePassword<br />
CclSecAttr* changePassword(const char* newPassword)<br />
newPassword<br />
the new password to be given<br />
Allows a Client application to change:<br />
v The password held in the terminal object<br />
v The password recorded by an external security manager for the userid held<br />
in the terminal object<br />
The external security manager is assumed to be located in the server defined<br />
by the terminal object.<br />
link<br />
void link(CclFlow& flow,<br />
const char* programName,<br />
CclBuf* commarea =0,<br />
CclUOW* unit =0)<br />
C++ Class: CclConn<br />
Chapter 3. C++ 57
C++ Class: CclConn<br />
flow<br />
A reference to the CclFlow object used to control the server request call.<br />
programName<br />
The name of the server program that is being called. The length is<br />
adjusted to 8 characters by padding with blanks or truncating, if<br />
necessary.<br />
commarea<br />
A pointer to a CclBuf object that holds the data to be passed to the called<br />
program in a COMMAREA. The default is not to pass a COMMAREA.<br />
unit<br />
A pointer to the CclUOW object that identifies the unit of work (UOW) in<br />
which this call participates. The default is none. See Managing logical units<br />
of work in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
Requests execution of the specified program on the server. The server<br />
program sees the incoming call as an EXEC <strong>CICS</strong> LINK call.<br />
If the commarea buffer object is too long, a dataLength exception is raised and<br />
the request is denied. <strong>CICS</strong> imposes a limit of 32500 bytes which can be made<br />
smaller by using the MaxBufferSize parameter in the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> Initialization file.<br />
listState<br />
const char* listState() const<br />
Returns a formatted string containing the current state of the object. For<br />
example:<br />
Connection state..&CclConn=000489AC &CclConnI=00203A50<br />
flowCount=0 &CclFlow(changed)=00000000 token(changed)=0<br />
serverName="server " userId="userId " password="password "<br />
&CclUOWI=00000000 runTran="run " attachTran="att "<br />
makeSecurityDefault<br />
void makeSecurityDefault()<br />
Informs the client that the current userid and password for this object is to<br />
become the default for ECI and EPI requests passed to the server as specified<br />
in the construction of the connection object.<br />
password (1)<br />
const char* password() const<br />
Returns the password held by the CclConn object, padded with spaces to 10<br />
characters, or blanks if there is no password.<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
password (2)<br />
void password(Ccl::Bool unpadded)<br />
unpadded<br />
Ccl::Yes<br />
returns a null terminated string of the stored password with no<br />
space padding in the string.<br />
Ccl::No<br />
returns the string padded with spaces — the same as invoking the<br />
password method with no parameters.<br />
serverName (1)<br />
const char* serverName() const<br />
Returns the name of the server system held by the CclConn object, padded<br />
with spaces, or blanks if the default server is being used and no calls have yet<br />
been made.<br />
serverName (2)<br />
void serverName(Ccl::Bool unpadded)<br />
unpadded<br />
Ccl::Yes<br />
returns a null terminated string of the stored server name with no<br />
space padding in the string.<br />
Ccl::No<br />
returns the string padded with spaces — the same as invoking the<br />
serverName method with no parameters.<br />
status<br />
void status(CclFlow& flow)<br />
flow<br />
A reference to the CclFlow object used to control the server request call.<br />
Requests the status of the server connection. When the reply has been<br />
received, use serverStatus or serverStatusText to obtain server availability.<br />
serverStatus<br />
ServerStatus serverStatus() const<br />
C++ Class: CclConn<br />
Chapter 3. C++ 59
C++ Class: CclConn<br />
Returns an enumeration value, set by an earlier status or changed request,<br />
indicating the availability of the server. Possible values are listed under<br />
Enumerations.<br />
serverStatusText<br />
const char* serverStatusText() const<br />
Returns a string, set by an earlier status or changed request, indicating the<br />
availability of the server.<br />
userId (1)<br />
const char* userId() const<br />
Returns the user ID held by the CclConn object, padded with spaces, or<br />
blanks if none.<br />
userId (2)<br />
void userId(Ccl::Bool unpadded)<br />
unpadded<br />
Ccl::Yes<br />
returns a null terminated string of the stored userid with no space<br />
padding in the string.<br />
Ccl::No<br />
returns the string padded with spaces exactly as invoking the<br />
userId method with no parameters.<br />
verifyPassword<br />
CclSecAttr* verifyPassword()<br />
Allows a Client application to verify that the password held in the CclConn<br />
object matches the password recorded by an external security manager for the<br />
userid held in the CclConn object. The external security manager is assumed<br />
to be located in the server defined by the CclConn object.<br />
Enumerations<br />
ServerStatus<br />
Indicates the availability of the server. Possible values are:<br />
unknown<br />
The server status is unknown.<br />
available<br />
The server is available.<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
unavailable<br />
The server is not available.<br />
CclECI class<br />
Only one instance of the CclECI class can exist. It is created by the instance<br />
class method. It controls the client interface to the available servers.<br />
CclECI should be sub-classed to implement your own handleException<br />
method.<br />
Only one instance of a CclECI subclass can exist. Any attempt to create more<br />
than one raises a multipleInstance exception.<br />
A CclECI object cannot be copied or assigned.<br />
CclECI constructor (protected)<br />
CclECI()<br />
This constructor is protected and can be accessed only from a subclass.<br />
Public methods<br />
exCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
Ccl::ExCode exCode() const<br />
Returns an enumeration indicating the most recent exception code. The<br />
possible values are listed under Table 20 on page 199.<br />
exCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
const char* exCodeText() const<br />
Returns a text string describing the most recent exception code.<br />
C++ Class: CclConn<br />
Chapter 3. C++ 61
C++ Class: CclECI<br />
handleException<br />
virtual void handleException(CclException &except)<br />
except<br />
A CclException object that contains information about the exception just<br />
raised.<br />
This method is called whenever an exception is raised. To deal with<br />
exceptions, you should always subclass CclECI, and provide your own<br />
implementation of handleException. See Handling Exceptions in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide. The default implementation merely<br />
throws the exception object.<br />
instance<br />
static CclECI* instance()<br />
A class method that returns a pointer to the single CclECI object that exists on<br />
the client. Here is an example of its use:<br />
CclECI* pmgr = CclECI::instance();<br />
listState<br />
const char* listState() const<br />
Returns a formatted string containing the current state of the object. For<br />
example:<br />
ECI state..&CclECI=00203AE0 &CclECII=00203B20<br />
retCode=0 exCode=0<br />
serverCount=0 &serverBuffer=00000000<br />
serverCount<br />
unsigned short serverCount() const<br />
Returns the number of available servers to which the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> may be connected, as configured in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
initialization file. In practice, some or all of these servers may not be available.<br />
See Finding potential servers in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide.<br />
serverDesc<br />
const char* serverDesc(unsigned short index = 1) const<br />
index<br />
The index of a connected server in the list. The default index is 1.<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
CclEPI class<br />
Returns the description of the indexth server. See Finding potential servers in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
serverName<br />
const char* serverName(unsigned short index = 1) const<br />
index<br />
The index of a connected server in the list. The default index is 1.<br />
Returns the name of the indexth server. See Finding potential servers in the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
The CclEPI class initializes and terminates the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI<br />
function. It also has methods which allow you to obtain information about<br />
<strong>CICS</strong> servers configured in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file.<br />
You must create one object of this class for each application process before<br />
you create CclTerminal objects to connect to <strong>CICS</strong> servers.<br />
CclEPI constructor<br />
CclEPI()<br />
This method initializes the <strong>CICS</strong> EPI interface on the client. An initEPI<br />
exception is raised if initialization fails. Initialization of the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> EPI is synchronous. In other words, initialization is complete when<br />
the call to the CclEPI constructor returns.<br />
Public methods<br />
diagnose<br />
const char* diagnose() const<br />
Returns a character string that holds a description of the condition returned<br />
by the most recent server call.<br />
exCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
Ccl::ExCode exCode() const<br />
C++ Class: CclECI<br />
Chapter 3. C++ 63
C++ Class: CclEPI<br />
Returns an enumeration indicating the most recent exception code. The<br />
possible values are listed under Table 20 on page 199.<br />
exCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
const char* exCodeText() const<br />
Returns a text string describing the most recent exception code.<br />
handleException<br />
virtual void handleException(CclException &except)<br />
except<br />
A CclException object that contains information about the exception just<br />
raised.<br />
This method is called whenever an exception is raised. To deal with<br />
exceptions, use try...catch, or subclass CclEPI and provide your own<br />
implementation of handleException. The default implementation merely<br />
throws the exception object.<br />
serverCount<br />
unsigned short serverCount()<br />
Returns the number of available servers to which the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> may be connected, as configured in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
initialization file.<br />
serverDesc<br />
const char* serverDesc(unsigned short index =1)<br />
index<br />
The index of a configured server<br />
Returns a description of the selected <strong>CICS</strong> server, or NULL if no information<br />
is available in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file for the specified<br />
server. If the index exceeds the number of servers configured, a maxServers<br />
exception is raised.<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
serverName<br />
const char* serverName(unsigned short index =1)<br />
index<br />
The index of a configured server<br />
Returns the name of the requested <strong>CICS</strong> server, or NULL if no information is<br />
available in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file for the specified<br />
server. If the index exceeds the number of servers configured, a maxServers<br />
exception is raised.<br />
state<br />
State state() const<br />
Returns an enumeration indicating the state of the EPI. Possible values are:<br />
active<br />
EPI has been initialized successfully<br />
discon<br />
EPI has terminated<br />
error<br />
EPI initialization has failed<br />
terminate<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
void terminate()<br />
Terminates the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> EPI in a controlled manner. The<br />
CclEPI object remains in existence, so that anything which occurs during the<br />
termination can be monitored by the application.<br />
Because the terminate method is invoked during CclEPI object destruction,<br />
you do not need to invoke this method.<br />
Enumerations<br />
State<br />
C++ Class: CclEPI<br />
An enumeration indicating the state of the EPI. Possible values are:<br />
active EPI has been initialized successfully<br />
discon EPI has terminated<br />
Chapter 3. C++ 65
C++ Class: CclEPI<br />
CclException class<br />
error EPI initialization has failed<br />
A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> object constructs an object of the CclException<br />
class if it encounters a problem.<br />
To deal with such a problem, you should subclass the CclECI or CclEPI class<br />
and provide your own implementation of the handleException method. See<br />
Handling Exceptions in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide. This<br />
method has access to the methods of the CclException object and can be<br />
coded to take whatever action is necessary. For example, it can stop the<br />
program or display a dialog box.<br />
Alternatively, you can use a C++ try...catch block to handle exceptions.<br />
A CclException object cannot be assigned and its constructors are intended for<br />
use by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> class implementation only.<br />
Public methods<br />
abendCode<br />
const char* abendCode()<br />
Returns a null-terminated string containing the ECI abend code, or blanks if<br />
no abend code is available.<br />
className<br />
const char* className() const<br />
Returns the name of the class in which the exception was raised.<br />
diagnose<br />
const char* diagnose() const<br />
Returns text explaining the exception for use in diagnostic output, for<br />
example:<br />
unknown server, classname=CclFlowI, methodName=afterReply, originCode=13<br />
"link", flowId=2, retCode=-22, abendCode=" "<br />
66 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
exCode<br />
Ccl::ExCode exCode() const<br />
Returns the exception code. See Table 20 on page 199.<br />
exCodeText<br />
const char* exCodeText() const<br />
Returns a text string that describes the exception code.<br />
exObject<br />
void* exObject() const<br />
This method is relevant to to both the ECI and EPI.<br />
exObject returns a pointer to the object controlling any server interaction at<br />
the time of the exception. If there was no such object, a null pointer is<br />
returned.<br />
v In the case of ECI the pointer should be cast to a CclFlow*. For example:<br />
CclFlow* pflo = (CclFlow*) ex.exObject();<br />
v In the case of EPI exObject returns the relevant CclTerminal object pointer<br />
in the exception block. Cast this to a CclTerminal*; for example:<br />
CclTerminal* pTerm = (CclFlow*)ex.exObject();<br />
methodName<br />
const char* methodName() const<br />
Returns the name of the method in which the exception was raised.<br />
CclField class<br />
An object of the CclField class is responsible for looking after a single field on<br />
a 3270 screen. CclField objects are created and deleted when 3270 data from<br />
the <strong>CICS</strong> server is processed by a CclScreen object.<br />
Methods in this class allow field text and attributes to be read and updated.<br />
Modified fields are sent to the <strong>CICS</strong> server on the next send.<br />
Public methods<br />
appendText (1)<br />
void appendText(const char* text, unsigned short length)<br />
C++ Class: CclException<br />
Chapter 3. C++ 67
C++ Class: CclField<br />
text<br />
The text to be appended to the field<br />
length<br />
The number of characters to be appended to the field<br />
Appends length characters from text to the end of the text already in the field.<br />
appendText (2)<br />
void appendText(const char* text)<br />
text<br />
The null-terminated text string to be appended to the field<br />
Appends the characters within the text string to the end of the text already in<br />
the field.<br />
backgroundColor<br />
Color backgroundColor() const<br />
Returns an enumeration indicating the background color of the field. The<br />
possible values are shown under Color at the end of the description of this<br />
class.<br />
baseAttribute<br />
char baseAttribute() const<br />
Returns the 3270 base attribute of the field.<br />
column<br />
unsigned short column() const<br />
Returns the column number of the position of the start of the field on the<br />
screen, with the leftmost column being 1.<br />
dataTag<br />
BaseMDT dataTag() const<br />
Returns an enumeration indicating whether the data in the field has been<br />
modified. Possible values are:<br />
modified<br />
unmodified<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
foregroundColor<br />
Color foregroundColor() const<br />
Returns an enumeration indicating the foreground color of the field. The<br />
possible values are shown under Color at the end of the description of this<br />
class.<br />
highlight<br />
Highlight highlight() const<br />
Returns an enumeration indicating which type of highlight is being used. The<br />
possible values are shown under Highlight at the end of the description of<br />
this class.<br />
inputProt<br />
BaseProt inputProt() const<br />
Returns an enumeration indicating whether the field is protected. Possible<br />
values are:<br />
protect<br />
unprotect<br />
inputType<br />
BaseType inputType() const<br />
Returns an enumeration indicating the input data type for this field. Possible<br />
values are:<br />
alphanumeric<br />
numeric<br />
intensity<br />
BaseInts intensity() const<br />
Returns an enumeration indicating the field intensity. Possible values are :<br />
dark<br />
normal<br />
intense<br />
length<br />
unsigned short length() const<br />
C++ Class: CclField<br />
Chapter 3. C++ 69
C++ Class: CclField<br />
Returns the total length of the field. This includes one byte used to store the<br />
3270 attribute byte information. The actual space for data is one byte less than<br />
the value returned by this method. See also the textLength method.<br />
position<br />
unsigned short position() const<br />
Returns the position of the start of the field on the screen, given by position =<br />
column number + (n x row number), where n is the number of columns in a<br />
row (usually 80).<br />
resetDataTag<br />
void resetDataTag()<br />
Resets the modified data tag (MDT) to unmodified.<br />
row<br />
unsigned short row() const<br />
Returns the row number of the position of the start of the field on the screen.<br />
The top row is 1.<br />
setBaseAttribute<br />
void setBaseAttribute(char attribute)<br />
attribute<br />
The value of the base 3270 attribute byte to be entered into the field<br />
Sets the 3270 base attribute.<br />
setExtAttribute<br />
void setExtAttribute(char attribute, char value)<br />
attribute<br />
The type of extended attribute being set<br />
value<br />
The value of the extended attribute<br />
Sets an extended 3270 attribute. If an invalid 3270 attribute type or value is<br />
supplied, a parameter exception is raised.<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
setText (1)<br />
These methods update the field with the given text.<br />
void setText(const char* text, unsigned short length)<br />
text<br />
The text to be entered into the field<br />
length<br />
The number of characters to be entered into the field<br />
Copies length characters from text into the field.<br />
setText (2)<br />
void setText(const char* text)<br />
text<br />
The null-terminated text to be entered into the field<br />
Copies text, without the terminating null, into the field.<br />
text<br />
const char* text() const<br />
Returns the text currently held in the field.<br />
textLength<br />
unsigned short textLength() const<br />
Returns the number of characters currently held in the field.<br />
transparency<br />
Transparency transparency() const<br />
Returns an enumeration indicating the background transparency of the field.<br />
Possible values are shown under Transparency at the end of the description of<br />
this class.<br />
Enumerations<br />
BaseInts<br />
Indicates the field intensity. Possible values are:<br />
normal<br />
intense<br />
dark<br />
C++ Class: CclField<br />
Chapter 3. C++ 71
C++ Class: CclField<br />
BaseMDT<br />
Indicates whether data in the field has been modified. Possible values are:<br />
unmodified<br />
modified<br />
BaseProt<br />
Indicates whether the field is protected. Possible values are:<br />
protect<br />
unprotect<br />
BaseType<br />
Indicates field input data type. Possible values are:<br />
alphanumeric<br />
numeric<br />
Color<br />
Possible values are:<br />
defaultColor yellow paleGreen<br />
blue neutral paleCyan<br />
red black gray<br />
pink darkBlue white<br />
green orange<br />
cyan purple<br />
Highlight<br />
Indicates which type of highlight is being used. Possible values are:<br />
defaultHlt blinkHlt underscoreHlt<br />
normalHlt reverseHlt intenseHlt<br />
Transparency<br />
Indicates the background transparency of the field. Possible values are:<br />
defaultTran<br />
default transparency<br />
orTran<br />
OR with underlying color<br />
xorTran<br />
XOR with underlying color<br />
72 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
opaqueTran<br />
opaque<br />
CclFlow class<br />
A CclFlow object is used to control ECI communications for a client/server<br />
pair and to determine the synchronization of reply processing. Refer to<br />
Compiling and Linking in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for<br />
an explanation of synchronization. CclFlow automatically calls its<br />
handleReply method when a reply is available; this simplifies control of<br />
interleaved replies. Subclass CclFlow to implement your own handleReply<br />
method.<br />
A CclFlow object is created for each client/server interaction (request from<br />
client and response from server). CclFlow objects can be reused when they<br />
become inactive, that is, when reply processing is complete. An attempt to<br />
delete or reuse an active CclFlow object raises an activeFlow exception.<br />
CclFlow constructor<br />
CclFlow (1)<br />
CclFlow(Ccl::Sync syncType, unsigned long stackPages =3)<br />
syncType<br />
The type of synchronization<br />
stackPages<br />
If asynchronous, the number of 4kb stack pages. The default is 3. If not<br />
asynchronous, this parameter is ignored.<br />
CclFlow (2)<br />
C++ Class: CclField<br />
CclFlow(Ccl::Sync syncType,<br />
unsigned long stackPages,<br />
const unsigned short &timeout)<br />
syncType<br />
The type of synchronization<br />
stackPages<br />
If asynchronous, the number of 4kb stack pages. If not asynchronous, this<br />
parameter is ignored.<br />
timeout<br />
The time in seconds to wait for the ECI program to respond. If a timeout<br />
occurs, the HandleException method is called with a timeout CclException<br />
Object. Valid values are 0-32767.<br />
Chapter 3. C++ 73
C++ Class: CclFlow<br />
Public methods<br />
abendCode<br />
const char* abendCode() const<br />
Returns the abend code from the most recently executed <strong>CICS</strong> transaction, or<br />
blank if there have been none.<br />
callType<br />
CallType callType() const<br />
Returns an enumeration value indicating the most recent type of server<br />
request.<br />
callTypeText<br />
const char* callTypeText() const<br />
Returns the name of the most recent server request.<br />
connection<br />
CclConn* connection() const<br />
Returns a pointer to the CclConn object that represents the server being used,<br />
if any, or zeros.<br />
diagnose<br />
const char* diagnose() const<br />
Returns text explaining the exception for use in diagnostic output; for<br />
example:<br />
"link", flowId=2, retCode=-22, abendCode=" "<br />
flowId<br />
unsigned short flowId() const<br />
Returns the unique identity of this CclFlow object.<br />
forceReset<br />
void forceReset()<br />
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Makes the flow inactive and resets it. This is typically used to prepare a<br />
CclFlow object for re-use or deletion after a flow has been abandoned, for<br />
example when a C++ throw is used in a exception handler. This applies only<br />
to dsync and async flows. You cannot issue this on a sync call from another<br />
thread.<br />
handleReply<br />
virtual void handleReply(CclBuf* commarea)<br />
commarea<br />
A pointer to the CclBuf object containing the returned COMMAREA or<br />
zero if none.<br />
This method is called whenever a reply is received from a server, irrespective<br />
of the type of synchronization or the type of call. See Compiling and Linking in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide. To deal with replies, you<br />
should subclass CclFlow and provide your own implementation of<br />
handleReply. The default implementation merely returns to the caller.<br />
listState<br />
const char* listState() const<br />
Returns a formatted string containing the current state of the object. For<br />
example:<br />
Flow state..&CclFlow=000489A4 &CclFlowI=00203B70<br />
syncType=2 threadId=0 stackPages=9 callType=0 flowId=0 commLength=0<br />
retCode=0 systemRC=0 abendCode=" " &CclConnI=00000000 &CclUOWI=00000000<br />
poll<br />
C++ Class: CclFlow<br />
Ccl::Bool poll(CclBuf* commarea =0)<br />
commarea<br />
An optional pointer to the CclBuf object that will be used to contain the<br />
returned COMMAREA.<br />
Returns an enumeration, defined within the Ccl class indicating whether a<br />
reply has been received from a deferred synchronous Backout, Cancel,<br />
Changed, Commit, Link, orStatus call request. If poll is used on a flow<br />
object that is not deferred synchronous, a syncType exception is raised.<br />
Possible values are:<br />
yes A reply has been received. handleReply has been called<br />
synchronously.<br />
no No reply has been received. The client process is not blocked.<br />
Chapter 3. C++ 75
C++ Class: CclFlow<br />
setTimeout<br />
void setTimeout(const unsigned short &timeout)<br />
timeout<br />
the defined time in seconds to wait for the ECI program to respond. If a<br />
timeout occurs, the HandleException method is called with a timeout<br />
CclException Object. Valid values are 0-32767.<br />
Sets the timeout value for the flow object for the next activation of the flow.<br />
This value can be set while a flow is active but does not affect the current<br />
active flow<br />
syncType<br />
Ccl::Sync syncType() const<br />
Returns an enumeration, defined within the Ccl class indicating the type of<br />
synchronization being used. Possible values are shown in “Sync” on page 49.<br />
timeout<br />
short timeout()<br />
Retrieves the current timeout value set for the flow object.<br />
uow<br />
CclUOW* uow() const<br />
Returns a pointer to any CclUOW object containing information on any units<br />
of work (UOWs) associated with this interaction.<br />
wait<br />
void wait()<br />
Waits for a reply from the server, blocking the client process in the meantime.<br />
If wait is used on a synchronous flow object, a syncType exception is raised.<br />
Enumerations<br />
CallType<br />
The possible values for server requests in progress under the control of a<br />
CclFlow object are:<br />
inactive<br />
No server call is currently in progress<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
CclMap class<br />
link<br />
A CclConn::link call to a server program<br />
backout<br />
A CclUOW::backout call to back out changes made to recoverable<br />
resources on the server<br />
commit<br />
A CclUOW::commit call to commit changes made to recoverable<br />
resources on the server<br />
status<br />
A CclConn::status call to determine the status of a server connection<br />
changed<br />
A CclConn::changed call to request notification when the status of a<br />
connection to a server changes<br />
cancel<br />
A CclConn::cancel call to cancel an earlier CclConn::changed request.<br />
The CclMap class is a base class for map classes created by the <strong>CICS</strong> BMS<br />
Map Conversion Utility. The methods provided by CclMap class are inherited<br />
by the classes generated from BMS maps.<br />
CclMap constructor<br />
CclMap(CclScreen* screen)<br />
screen<br />
A pointer to the matching CclScreen object.<br />
Creates a CclMap object and checks (validates) that the map matches the<br />
content of the screen, defined by the CclScreen object. If validation was<br />
unsuccessful, an invalidMap exception is raised. If the supplied CclScreen<br />
object is invalid, a parameter exception is raised.<br />
Public methods<br />
exCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
Ccl::ExCode exCode() const<br />
C++ Class: CclFlow<br />
Returns an enumeration indicating the most recent exception code. The<br />
possible values are listed in Table 20 on page 199.<br />
Chapter 3. C++ 77
C++ Class: CclMap<br />
exCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
const char* exCodeText() const<br />
Returns a text string describing the most recent exception code.<br />
field (1)<br />
CclField* field(unsigned short index)<br />
index<br />
The index number of the required CclField object.<br />
Returns a pointer to the CclField object identified by index in the BMS map.<br />
field (2)<br />
CclField* field(unsigned short row, unsigned short column)<br />
row<br />
The row number of the required CclField object within the map. The top<br />
rowis1.<br />
column<br />
The column number of the required CclField object within the map. The<br />
left column is 1.<br />
Returns a pointer to the CclField object identified by position in the BMS<br />
map.<br />
Protected methods<br />
namedField<br />
CclField* namedField(unsigned long index)<br />
index<br />
The index number of the required CclField object.<br />
Returns the address of the indexth object.<br />
validate<br />
void validate(const MapData* map,<br />
const FieldIndex* index,<br />
const FieldData* fields)<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
map<br />
A structure that contains information about the map. The structure is<br />
defined within this class and contains the following members, which are<br />
all unsigned short integers:<br />
row Map row position on screen<br />
col Map column position on screen<br />
width Map width in columns<br />
depth Map depth in rows<br />
fields Number of fields<br />
labels Number of labeled fields<br />
index<br />
The index number of the required CclField object. FieldIndex is a typedef<br />
of this class and is equivalent to an unsigned short integer.<br />
fields<br />
A structure that contains information about a particular field. The<br />
structure is defined within this class and contains the following members,<br />
which are all unsigned short integers:<br />
row Field row (within map)<br />
col Field column (within map)<br />
len Field length<br />
Validate map against the current screen.<br />
CclScreen class<br />
The CclScreen EPI class maintains all data on the 3270 virtual screen and<br />
provides access to this data. It contains a collection of CclField objects which<br />
represent the fields on the current 3270 screen.<br />
A single CclScreen object is created by the CclTerminal object; use the screen<br />
method on the CclTerminal object to obtain it. The CclScreen object is updated<br />
by the CclTerminal object when 3270 data is received from <strong>CICS</strong>. A<br />
dataStream exception is raised if an unsupported datastream is received.<br />
Public methods<br />
cursorCol<br />
unsigned short cursorCol() const<br />
Returns the column number of the current position of the cursor. The left<br />
column is 1.<br />
cursorRow<br />
unsigned short cursorRow() const<br />
C++ Class: CclMap<br />
Chapter 3. C++ 79
C++ Class: CclScreen<br />
Returns the row number of the current position of the cursor. The top row is<br />
1.<br />
depth<br />
unsigned short depth() const<br />
Returns the number of rows in the screen.<br />
field (1)<br />
These methods allow you to access fields on the current screen by returning a<br />
pointer to the relevant CclField object.<br />
CclField* field(unsigned short index)<br />
index<br />
The index number of the field of interest<br />
field (2)<br />
CclField* field(unsigned short row, unsigned short column)<br />
row<br />
The row number of the field<br />
column<br />
The column number of the field<br />
fieldCount<br />
unsigned short fieldCount() const<br />
Returns the number of fields in the screen.<br />
mapName<br />
const char* mapName()<br />
Returns a padded null terminated string specifying the name of the map that<br />
was most recently referenced in the MAP option of a SEND MAP command<br />
processed for the terminal resource. If the terminal resource is not supported<br />
by BMS, or the server has no record of any map being sent, the value<br />
returned is spaces.<br />
mapSetName<br />
const char* mapSetName()<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Returns a padded null terminated string specifying the name of the mapset<br />
that was most recently referenced in the MAPSET option of a SEND MAP<br />
command processed for the terminal resource. If the MAPSET option was not<br />
specified on the most recent request, BMS used the map name as the mapset<br />
name. In both cases, the mapset name used may have been suffixed by a<br />
terminal suffix. If the terminal resource is not supported by BMS, or the server<br />
has no record of any mapset being sent, the value returned is spaces.<br />
setAID<br />
void setAID(const AID key)<br />
key<br />
An AID key. See the AID enumerations at the end of this chapter.<br />
Sets the AID key value to be passed to the server on the next transmission.<br />
setCursor<br />
void setCursor(unsigned short row, unsigned short col)<br />
row<br />
The required row number of the cursor. The top row is 1.<br />
col<br />
The required column number of the cursor. The left column is 1.<br />
Requests that the cursor position be set. If the supplied row or column values<br />
are outside the screen boundaries, a parameter exception is raised.<br />
width<br />
unsigned short width() const<br />
Returns the number of columns on the screen.<br />
Enumerations<br />
AID<br />
Indicates an AID key. Possible values are:<br />
enter<br />
clear<br />
PA1—PA3<br />
PF1—PF24<br />
C++ Class: CclScreen<br />
Chapter 3. C++ 81
C++ Class: CclScreen<br />
CclSecAttr<br />
CclSecTime<br />
The CclSecAttr class provides information about passwords reported back by<br />
the external security manager when verifyPassword or changePassword<br />
methods are issued on CclConn or CclTerminal objects.<br />
This object is created and owned by the CclConn or CclTerminal Object;<br />
access to this object is provided when the verifyPassword or changePassword<br />
methods are invoked.<br />
Public Methods<br />
expiryTime<br />
CclSecTime* expiryTime() const<br />
Returns a CclSecTime object that contains the Date and Time at which the<br />
password will expire<br />
invalidCount<br />
unsigned short invalidCount() const<br />
Returns the Number of times that an invalid password has been entered for<br />
the userid.<br />
lastAccessTime<br />
CclSecTime* lastAccessTime() const<br />
Returns a CclSecTime object that contains the date and time when the userid<br />
was last accessed.<br />
lastVerifiedTime<br />
CclSecTime* lastVerifiedTime() const<br />
Returns a CclSecTime object that contains the date and time of the Last<br />
Verification.<br />
The CclSecTime class provides date and time information in the CclSecAttr<br />
object for various entries reported back by the external security manager<br />
when verifyPassword or changePassword methods are issued on CclConn or<br />
CclTerminal objects.<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
These objects are created and owned by the CclSecAttr object and access is<br />
obtained via the various methods available on this object. No Constructors or<br />
Destructors are available.<br />
Public Methods<br />
day<br />
unsigned short day() const<br />
Returns the day with a range from 1 to 31; 1 represents the first day of the<br />
month.<br />
get_time_t<br />
time_t get_time_t() const<br />
Returns the date and time in a time_t format.<br />
get_tm<br />
tm get_tm() const<br />
Returns the date and time in a tm structure.<br />
hours<br />
unsigned short hours() const<br />
Returns the hours with a range from 0 to 23.<br />
hundredths<br />
unsigned short hundredths() const<br />
Returns the hundredths of seconds with a range from 0 to 99.<br />
minutes<br />
unsigned short minutes() const<br />
Returns the minutes with a range from 0 to 59.<br />
month<br />
unsigned short month() const<br />
Returns the month with a range from 1 to 12. January is 1.<br />
C++ Class: CclScreen<br />
Chapter 3. C++ 83
C++ Class: CclScreen<br />
seconds<br />
unsigned short seconds() const<br />
Returns the seconds with a range from 0 to 59.<br />
year<br />
unsigned short year() const<br />
Returns a 4–digit year<br />
CclSession class<br />
The CclSession class allows the programmer to implement reusable code to<br />
handle a segment (one or more transmissions) of a 3270 conversation. In<br />
multi-threaded environments it provides asynchronous handling of replies<br />
from <strong>CICS</strong>.<br />
The CclSession class controls the flow of data to and from <strong>CICS</strong> within a<br />
single 3270 session. You should derive your own classes from CclSession.<br />
CclSession constructor<br />
CclSession(Ccl::Sync syncType)<br />
syncType<br />
The protocol to be used on transmissions to the <strong>CICS</strong> server. Possible<br />
values are:<br />
async asynchronous<br />
dsync deferred synchronous<br />
sync synchronous<br />
Public methods<br />
diagnose<br />
const char* diagnose() const<br />
Returns a text description of the last error.<br />
handleReply<br />
virtual void handleReply(State state, CclScreen* screen)<br />
state<br />
An enumeration indicating the state of the data flow. The scope of the<br />
values is shown under State at the end of the description of this class.<br />
screen<br />
A pointer to the CclScreen object.<br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
This is a virtual method which you can override when you develop your own<br />
class derived from CclSession. It is called when data is received from <strong>CICS</strong>.<br />
state<br />
State state() const<br />
Returns an enumeration indicating the current state of the session. Possible<br />
values are shown under State at the end of the description of this class.<br />
terminal<br />
CclTerminal* terminal() const<br />
Returns a pointer to the CclTerminal object for this session. This method<br />
returns a NULL pointer until the CclSession object has been associated with a<br />
CclTerminal object (that is, until the CclSession object has been used as a<br />
parameter on a CclTerminal send method).<br />
transID<br />
const char* transID() const<br />
Returns the 4-letter name of the current transaction.<br />
Enumerations<br />
State<br />
C++ Class: CclSession<br />
Indicates the state of a session. Possible values are:<br />
idle<br />
The terminal is connected and no <strong>CICS</strong> transaction is in progress.<br />
server<br />
A <strong>CICS</strong> transaction is in progress in the server.<br />
client<br />
A <strong>CICS</strong> transaction is in progress, and the server is waiting for a response<br />
from the client.<br />
discon<br />
The terminal is disconnected.<br />
error<br />
There is an error in the terminal.<br />
Chapter 3. C++ 85
|<br />
|<br />
C++ Class: CclTerminal<br />
CclTerminal class<br />
An object of class CclTerminal represents a 3270 terminal connection to a<br />
<strong>CICS</strong> server. A <strong>CICS</strong> connection is established when the object is created.<br />
Methods can then be used to converse with a 3270 terminal application (often<br />
a BMS application) in the <strong>CICS</strong> server.<br />
The EPI must be initialized (that is, a CclEPI object created) before a<br />
CclTerminal object can be created.<br />
The CclTerminal class destructor does not purge ATI requests queued against<br />
the terminal.<br />
CclTerminal constructor<br />
CclTerminal (1)<br />
CclTerminal(const char* server = NULL,<br />
const char* devtype = NULL,<br />
const char* netname = NULL)<br />
server<br />
The name of the server with which you want to communicate. If no name<br />
is provided the default server system is assumed. The length is adjusted<br />
to 8 characters by padding with blanks.<br />
devtype<br />
The name of the model terminal definition that the server uses to generate<br />
a terminal resource definition. If no string is provided the default model is<br />
used. The length is adjusted to 16 characters by padding with blanks.<br />
netname<br />
The name of the terminal resource to be installed or reserved. The default<br />
is to use the contents of devtype. The length is adjusted to 8 characters by<br />
padding with blanks.<br />
Creates the CclTerminal object that is used for EPI communication between<br />
the client and server.<br />
This constructor does an implicit install terminal. You do not need to invoke<br />
the install method if you construct a terminal object this way.<br />
If the named server is not configured in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
initialization file, an unknownServer exception is raised.<br />
If invalid values are supplied for server, devtype or netname, a parameter<br />
exception is raised.<br />
If a CclEPI object has not been created, an initEPI exception is raised.<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
If the maximum number of supported terminal connections has been<br />
exceeded, a maxRequests exception is raised.<br />
CclTerminal (2)<br />
C++ Class: CclTerminal<br />
CclTerminal(const char* server,<br />
const char* devtype,<br />
const char* netname,<br />
signonType signonCapability<br />
const char* userid<br />
const char* password<br />
const unsigned short &readTimeOut,<br />
const unsigned short &CCSid)<br />
server<br />
The name of the server with which you want to communicate. If no name<br />
is provided the default server system is assumed. The length is adjusted<br />
to 8 characters by padding with blanks.<br />
devtype<br />
The name of the model terminal definition which the server uses to<br />
generate a terminal resource definition. If no string is provided the default<br />
model is used. The length is adjusted to 16 characters by padding with<br />
blanks.<br />
netname<br />
The name of the terminal resource to be installed or reserved. The default<br />
is to use the contents of devtype. The length is adjusted to 8 characters by<br />
padding with blanks.<br />
signonCapability<br />
Sets the type of signon capability for the terminal.<br />
Possible values are:<br />
CclTerminal::SignonCapable<br />
CclTerminal::SignonIncapable<br />
userid<br />
The name of the userid to associate with this terminal resource<br />
password<br />
The password to associate with the userid<br />
readTimeOut<br />
A value in the range 0 through 3600, specifying the maximum time in<br />
seconds between the time the classes go clientrepl state and the<br />
application program invokes the reply method.<br />
CCSid<br />
An unsigned short specifying the coded character set identifier (CCSID)<br />
that identifies the coded graphic character set used by the Client<br />
application for data passed between the terminal resource and <strong>CICS</strong><br />
transactions. A zero string means that a default will be used.<br />
Chapter 3. C++ 87
C++ Class: CclTerminal<br />
Creates a Terminal object that does not do an implicit install terminal. You<br />
must run the install method to install the terminal.<br />
Public methods<br />
alterSecurity<br />
void alterSecurity(const char* userid,const char* password)<br />
userid<br />
The new userid<br />
password<br />
The new password for userid<br />
Allows you to re-define the userid and password for a terminal resource. You<br />
may call the method before you install a terminal. It changes only the<br />
terminal definition; the new userid and password will be used for the<br />
terminal when install is called.<br />
changePassword<br />
CclSecAttr* changePassword(const char* newPassword)<br />
newPassword<br />
The new password<br />
Allows a Client application to change the password held in the terminal object<br />
and the password recorded by an external security manager for the userid<br />
held in the terminal object. The external security manager is assumed to be<br />
located in the server defined by the terminal object.<br />
CCSid<br />
unsigned short CCSid()<br />
Returns the selected code page as an unsigned short.<br />
diagnose<br />
const char* diagnose()<br />
Returns a character string that holds a description of the error returned by the<br />
most recent server call.<br />
disconnect (1)<br />
void disconnect()<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Disconnects the terminal from <strong>CICS</strong>. No attempt is made to purge any<br />
outstanding running transaction.<br />
disconnect (2)<br />
void disconnect(Ccl::Bool withPurge)<br />
withPurge<br />
Ccl::Yes<br />
Disconnects the terminal from <strong>CICS</strong> and attempts to purge any<br />
outstanding running transaction. This purge function does not<br />
cancel ATI requests queued against the terminal.<br />
Ccl::No<br />
Disconnects the terminal from <strong>CICS</strong>. No attempt is made to purge<br />
outstanding running transactions.<br />
discReason<br />
void discReason(void)<br />
Returns the reasons for a disconnection. See “EndTerminalReason” on page 95.<br />
exCode<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
Ccl::ExCode exCode() const<br />
Returns an enumeration indicating the most recent exception code. The<br />
possible values are listed in Table 20 on page 199.<br />
exCodeText<br />
Deprecated method<br />
Do not use this method in new applications. The method has been<br />
deprecated and is provided only for compatibility.<br />
const char* exCodeText() const<br />
Returns a text string describing the most recent exception code.<br />
C++ Class: CclTerminal<br />
Chapter 3. C++ 89
C++ Class: CclTerminal<br />
install<br />
void install(CclSession *session,<br />
const unsigned short &installTimeOut)<br />
session<br />
A pointer to the CclSession object that is to be used for the <strong>CICS</strong> server<br />
interaction.<br />
installTimeOut<br />
A value in the range 0 to 3600, specifying the maximum time in seconds<br />
that installation of the terminal resource is allowed to take. A value of 0<br />
means that no limit is set.<br />
Connects a non-connected terminal resource. Throws an invalidState error if<br />
already connected, or a timeout error if a timeout occurs.<br />
makeSecurityDefault<br />
void makeSecurityDefault()<br />
Informs the client that the current userid and password for this object are to<br />
become the default for ECI and EPI requests passed to the server as specified<br />
in the construction of the Terminal object.<br />
netName<br />
const char* netName() const<br />
Returns the network name of the terminal as a null terminated string.<br />
password<br />
const char* password()<br />
Returns a null terminated string containing the current password setting for<br />
the terminal, or null if the terminal has no password.<br />
poll<br />
Ccl::Bool poll()<br />
Polls for data from the <strong>CICS</strong> server.<br />
For deferred synchronous transmissions (that is, if a deferred synchronous<br />
CclSession object was used on a previous send call) the poll method is called<br />
by the application when it wants to receive data from the <strong>CICS</strong> server. If a<br />
reply from <strong>CICS</strong> is ready, the CclTerminal object updates the CclScreen object<br />
90 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
with the contents of the 3270 datastream received from <strong>CICS</strong>, the<br />
handleReply virtual function on the CclSession object is called, and the poll<br />
method returns Ccl::yes. If no reply has been received from <strong>CICS</strong>, the poll<br />
method returns Ccl::no.<br />
The poll method is used only for deferred synchronous transmissions; a<br />
syncType exception is raised if the poll method is called when a synchronous<br />
or asynchronous session is in use. An invalidState exception is raised if the<br />
poll method is called when there was no previous send call. The CclTerminal<br />
object should be in server state for poll to be called.<br />
A <strong>CICS</strong> server transaction may send more than one reply in response to a<br />
CclTerminal send call. More than one CclTerminal poll call may therefore be<br />
needed to collect all the replies. Use the CclTerminal state method to find out<br />
if further replies are expected. If there are, the value returned will be server.<br />
See EPI call synchronization types in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide.<br />
queryATI<br />
ATIState queryATI()<br />
Returns an enumeration indicating whether the “Automatic <strong>Transaction</strong><br />
Initiation” (ATI) is enabled or disabled. Possible values are:<br />
disabled<br />
enabled<br />
readTimeout<br />
const char* readTimeout()<br />
Returns the read timout value for the terminal as a null terminated string .<br />
receiveATI<br />
C++ Class: CclTerminal<br />
void receiveATI(CclSession* session)<br />
session<br />
pointer to the CclSession object that is to be used for the <strong>CICS</strong> server<br />
interaction.<br />
Waits for and receives 3270 datastream for a <strong>CICS</strong> ATI transaction. The<br />
CclSession object supplied as a parameter determines whether the call is<br />
synchronous or asynchronous, and can be subclassed to provide a reply<br />
handler<br />
Chapter 3. C++ 91
C++ Class: CclTerminal<br />
screen<br />
CclScreen* screen() const<br />
Returns a pointer to the CclScreen object that is handling the 3270 screen<br />
associated with this terminal session.<br />
send (1)<br />
void send(CclSession* session,<br />
const char* transid,<br />
const char* startdata = NULL)<br />
session<br />
A pointer to the CclSession object that controls the session which is to be<br />
used. If no valid CclSession object is supplied, a parameter exception is<br />
raised.<br />
transid<br />
The name of the transaction which is to be started<br />
startdata<br />
start transaction data. The default is to have no data for the transaction<br />
being started.<br />
Formats and sends a 3270 datastream, starting the named transaction. The<br />
CclTerminal object must be in idle state (connected to a <strong>CICS</strong> server but with<br />
no transaction in progress). If the object is not in idle state, an invalidState<br />
exception is raised.<br />
send (2)<br />
void send(CclSession* session)<br />
The session parameter is described above.<br />
Formats and sends a 3270 datastream. The CclTerminal object must be in idle<br />
state (see above) or in client state (that is, with a transaction in progress and<br />
the <strong>CICS</strong> server waiting for a response). If the object is not in idle or client<br />
state, an invalidState exception is raised.<br />
setATI<br />
void setATI(ATIState newstate)<br />
newstate<br />
An enumeration indicating whether the ATI is to be enabled or disabled.<br />
The scope of the values is within this class and the possible values are<br />
disabled and enabled.<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
signonCapability<br />
signonType signonCapability()<br />
Returns the type of signon capability applied to the terminal at installation.<br />
Possible values are:<br />
CclTerminal::signonCapable<br />
CclTerminal::signonIncapable<br />
CclTerminal::signonUnknown<br />
state<br />
State state() const<br />
Returns an enumeration indicating the current state of the session. Possible<br />
values are shown at the end of the description of this class.<br />
serverName<br />
const char* serverName() const<br />
Returns the name of the <strong>CICS</strong> server to which this terminal session is<br />
connected.<br />
termID<br />
const char* termID() const<br />
Returns the 4-character terminal ID.<br />
transID<br />
const char* transID() const<br />
Returns the 4-character name of the current <strong>CICS</strong> transaction. If a RETURN<br />
IMMEDIATE is run from the current transaction, TransId does not provide the<br />
name of the new transaction; it still contains the name of the first transaction.<br />
userId<br />
const char* userId()<br />
C++ Class: CclTerminal<br />
Returns a null terminated string containing the current userid setting for the<br />
terminal, Null if none.<br />
Chapter 3. C++ 93
|<br />
|<br />
|<br />
C++ Class: CclTerminal<br />
verifyPassword<br />
CclSecAttr* verifyPassword()<br />
Allows a Client application to verify that the password held in the terminal<br />
object matches the password recorded by an external security manager for the<br />
userid held in the terminal object. The external security manager is assumed<br />
to be located in the server defined by the terminal object.<br />
Enumerations<br />
ATIState<br />
Indicates whether “Automatic <strong>Transaction</strong> Initiation” (ATI) is enabled or<br />
disabled. Possible values are:<br />
enabled<br />
disabled<br />
signonType<br />
Indicates the signon capability of a terminal. Possible values are:<br />
signonCapable<br />
Signon Capable<br />
signonIncapable<br />
Signon Incapable<br />
signonUnknown<br />
Signon Unknown<br />
State<br />
Indicates the state of the CclTerminal object. Possible values are:<br />
client<br />
A <strong>CICS</strong> transaction is in progress and the server is waiting for a response<br />
from the client.<br />
discon<br />
The terminal is disconnected.<br />
error<br />
There is an error in the terminal.<br />
idle<br />
The terminal is connected and no <strong>CICS</strong> transaction is in progress.<br />
server<br />
A <strong>CICS</strong> transaction is in progress in the server.<br />
termDefined<br />
A terminal has been defined but not installed.<br />
txnTimedOut<br />
A conversational transaction has timed out, but the END_TRAN event<br />
has not been retrieved. For synchronous and asynchronous terminals the<br />
94 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
|<br />
|<br />
|<br />
|<br />
terminal method blocks until the event has been received and the<br />
terminal becomes idle. For deferred synchronous terminals it indicates<br />
that a poll() needs to be done to get the event. This resets the terminal to<br />
the idle state; handleException() and handleReply() are not invoked.<br />
EndTerminalReason<br />
Indicates the EndTerminalReason of the CclTerminal object. Possible values<br />
are:<br />
signoff<br />
A disconnect was requested or the user has signed off the terminal.<br />
shutdown<br />
The <strong>CICS</strong> server has been shutdown.<br />
outofService<br />
The terminal has been switched to out of service.<br />
unknown<br />
An unknown situation has occurred.<br />
failed<br />
The terminal failed to disconnect.<br />
notDiscon<br />
The terminal is not disconnected.<br />
CclUOW class<br />
Use this ECI class when you make updates to recoverable resources in the<br />
server within a “unit of work” (UOW). Each update in a UOW is identified at<br />
the client by a reference to its CclUOW—see link in CclConn (“link” on<br />
page 57).<br />
A CclUOW object cannot be copied or assigned. An attempt to delete a<br />
CclUOW object for which there is an active CclFlow object raises an<br />
activeFlow exception. Any attempt to delete an active CclUOW object, that is<br />
one which has not been committed or backed out, raises an activeUOW<br />
exception.<br />
CclUOW constructor<br />
CclUOW()<br />
Creates a CclUOW object.<br />
Public methods<br />
backout<br />
void backout(CclFlow& flow)<br />
C++ Class: CclTerminal<br />
Chapter 3. C++ 95
C++ Class: CclUOW<br />
flow<br />
A reference to the CclFlow object that is used to control the client/server<br />
call<br />
Terminate this UOW and back out all changes made to recoverable resources<br />
in the server.<br />
commit<br />
void commit(CclFlow& flow)<br />
flow<br />
A reference to the CclFlow object that is used to control the client/server<br />
call<br />
Terminate this UOW and commit all changes made to recoverable resources in<br />
the server.<br />
forceReset<br />
void forceReset()<br />
Make this UOW inactive and reset it.<br />
listState<br />
const char* listState() const<br />
Returns a zero-terminated formatted string containing the current state of the<br />
object. For example:<br />
UOW state..&CclUOW=0004899C &CclUOWI=00203BD0<br />
&CclConnI=00000000 uowId=0 &CclFlowI=00000000<br />
uowId<br />
unsigned long uowId() const<br />
Returns the identifier of the UOW. 0 means that the UOW is either complete<br />
or has not yet started. In other words, it is inactive.<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Chapter 4. C and COBOL<br />
External Call Interface<br />
<strong>CICS</strong>_ExternalCall ECI_Parms<br />
Purpose<br />
<strong>CICS</strong>_ExternalCall gives access to the program link calls, status information<br />
calls, and reply solicitation calls. The function performed is controlled by the<br />
eci_call_type field in the ECI parameter block.<br />
Parameters<br />
ECI_Parms<br />
A pointer to the ECI parameter block. Set the parameter block to nulls<br />
before use. The parameter block fields that are used as input and<br />
output are described in detail for each call type in the following<br />
sections. A brief summary of the fields follows:<br />
eci_call_type<br />
An integer field defining the type of call being made. For<br />
details of the functions provided, see Types of ECI call in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
eci_program_name<br />
The name of a program to be called.<br />
eci_userid<br />
User ID for security checking.<br />
eci_password<br />
Password for security checking.<br />
eci_transid<br />
A transaction identifier.<br />
eci_abend_code<br />
Abend code for a failed program.<br />
eci_commarea<br />
A COMMAREA for use by a called program, or for returned<br />
status information.<br />
eci_commarea_length<br />
The length of the COMMAREA. The size of the COMMAREA<br />
must be set to the largest size of the input or output data.<br />
This length must not exceed 32 500 bytes. If the input data is<br />
less than the length of the COMMAREA, pad the<br />
© Copyright IBM Corp. 1989, 2002 97
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
COMMAREA with nulls. The Client daemon strips off the null<br />
padding and sends only the data on the ECI request to the<br />
<strong>CICS</strong> server.<br />
eci_timeout<br />
The time to wait for a response from the <strong>CICS</strong> server. For<br />
more information on the ECI time-out support, see the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide.<br />
reserved1<br />
A return code giving more information about an unexpected<br />
error.<br />
This field was previously eci_system_ return_code. In <strong>Version</strong><br />
3.1 and higher of the product, this field is kept for<br />
compatibility. No information is returned in this field; all<br />
system errors are written to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s<br />
error log.<br />
eci_extend_mode<br />
A field that qualifies the function to be performed in various<br />
ways.<br />
eci_message_qualifier<br />
A user-provided reference to an asynchronous call.<br />
eci_luw_token<br />
An identifier for a logical unit of work.<br />
eci_sysid<br />
Reserved for future use; leave null.<br />
eci_version<br />
The version of the ECI for which the application is coded. You<br />
may use the values ECI_VERSION_1 or ECI_VERSION_1A.<br />
All the facilities of version 1 are available in version 1A.<br />
Facilities available only in version 1A are noted where they<br />
occur.<br />
eci_system_name<br />
The name of a <strong>CICS</strong> server.<br />
eci_callback<br />
A pointer to a callback routine for an asynchronous request.<br />
eci_userid2<br />
User ID for security checking. This is used if the User ID or<br />
password is more than 8 Characters.<br />
eci_password2<br />
Password for security checking. This is used if the User ID or<br />
password is more than 8 Characters.
eci_tpn<br />
A transaction identifier for a mirror transaction. This field is<br />
available only when eci_version has the value<br />
ECI_VERSION_1A.<br />
Return Codes<br />
In addition to the return codes described for each call type in the following<br />
sections, the following return codes are possible.<br />
ECI_ERR_INVALID_CALL_TYPE<br />
The call type was not one of the valid call types.<br />
ECI_ERR_CALL_FROM_CALLBACK<br />
The call was made from a callback routine.<br />
ECI_ERR_REQUEST_TIMEOUT<br />
The time-out interval expired before the request could be processed,<br />
or the specified interval was negative.<br />
ECI_ERR_RESPONSE_TIMEOUT<br />
The time-out interval expired while the program was running.<br />
ECI_ERR_SYSTEM_ERROR<br />
An internal system error occurred. The error might have been in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or in the server. The programmer should<br />
save the information returned in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s error<br />
log, as this will help service personnel to diagnose the error.<br />
ECI_ERR_INVALID_VERSION<br />
The value supplied for eci_version was invalid.<br />
ECI_ERR_REQUEST_TIMEOUT<br />
The value in the eci_timeout field of the ECI parameter block is<br />
negative.<br />
In some implementations, some of the return codes documented here and for<br />
each call type will never be returned.<br />
The mapping of actual return code values to the symbolic names is contained<br />
in the following file for the Windows operating systems:<br />
C \include\cics_eci.h<br />
Cobol \copybook\cicseci.cbl<br />
and in the following files for the UNIX operating systems:<br />
C /include/cics_eci.h<br />
Chapter 4. C and COBOL 99
Call types for the <strong>CICS</strong>_ExternalCall<br />
ECI_SYNC call type<br />
Environment: The ECI_SYNC call type is available in all environments.<br />
Purpose: The ECI_SYNC call type provides a synchronous program link call<br />
to start, continue, or end a logical unit of work. The calling application does<br />
not get control back until the called <strong>CICS</strong> program has run to completion.<br />
ECI parameter block fields: The ECI parameter block should be set to nulls<br />
before setting the input parameter fields.<br />
eci_call_type<br />
Required input parameter, which must be set to ECI_SYNC.<br />
eci_program_name<br />
Input parameter, required except when eci_extend_mode is<br />
ECI_COMMIT or ECI_BACKOUT. (See the Logical units of work in ECI<br />
table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more details.)<br />
An 8-character field containing the name of the program to be called.<br />
Pad unused characters with spaces. This field is transmitted to the<br />
server without conversion to uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
eci_userid<br />
Required input parameter.<br />
An 8-character field containing a user ID. Pad unused characters with<br />
spaces.<br />
Consult the documentation for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the<br />
server to check whether this field is converted to upper case before<br />
being transmitted to the server. If a user ID or password longer than 8<br />
characters is required, set eci_userid and eci_password to nulls, and<br />
use fields eci_userid2 and eci_password2 instead.<br />
If a user ID is supplied, the server uses the user ID and any supplied<br />
password to authenticate the user. The supplied user ID and<br />
password are used in subsequent security checking in the server.<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
eci_password<br />
Required input parameter.<br />
An 8-character field containing a password. Pad unused characters<br />
with spaces.<br />
Consult the documentation for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the<br />
server to check whether this field is converted to upper case before<br />
being transmitted to the server. If a user ID or password longer than 8<br />
characters is required, set this field and eci_userid to nulls, and use<br />
fields eci_userid2 and eci_password2 instead.<br />
eci_transid<br />
Optional input parameter<br />
A 4-character field optionally containing the ID of a <strong>CICS</strong> transaction.<br />
Pad unused characters with spaces. The parameter is ignored if<br />
eci_tpn is used (set to any value other than nulls). The use of this<br />
parameter depends on the client from which the request is sent. The<br />
value of eci_transid is converted from ASCII to EBCDIC, with no<br />
upper case translation, and stored in EIBTRNID for the duration of<br />
the LINK to the program specified in the eci_program_name.<br />
The called program runs under the mirror transaction CPMI, but is<br />
linked to under the eci_transid transaction name. This name is<br />
available to the called program for querying the transaction ID. Some<br />
servers use the transaction ID to determine security and performance<br />
attributes for the called program. In those servers, you are<br />
recommended to use this parameter to control the processing of your<br />
called programs.<br />
If the ECI request is extended (see the description of<br />
eci_extend_mode), the eci_transid parameter has a meaning only for<br />
the first call in the unit of work.<br />
If the field is all nulls, and eci_tpn is not specified, the default server<br />
transaction ID is used.<br />
eci_abend_code<br />
Output parameter.<br />
A 4-character field in which a <strong>CICS</strong> abend code is returned if the<br />
transaction that executes the called program abends. Unused<br />
characters are padded with spaces.<br />
eci_commarea<br />
Optional input parameter.<br />
A pointer to the data to be passed to the called <strong>CICS</strong> program as its<br />
COMMAREA. The COMMAREA will be used by the called program<br />
to return information to the application.<br />
Chapter 4. C and COBOL 101
If no COMMAREA is required, supply a null pointer and set the<br />
length (specified in eci_commarea_length) to zero.<br />
If the code page of the application is different from the code page of<br />
the server, data conversion must be performed at the server. To do<br />
this, use <strong>CICS</strong>-supplied resource conversion capabilities, such as the<br />
DFHCNV macro definitions.<br />
eci_commarea_length<br />
Optional input parameter.<br />
The length of the COMMAREA in bytes. This value may not exceed<br />
32 500. (Some client/server combinations may allow larger<br />
COMMAREAs, but this is not guaranteed to work.)<br />
If no COMMAREA is required, set this field to zero and supply a null<br />
pointer in eci_commarea.<br />
eci_timeout<br />
The time in seconds to wait for a response from the <strong>CICS</strong> server. A<br />
value of 0 means that no limit is set.<br />
If timeout occurs, the conversation is abended.<br />
reserved1<br />
Output parameter.<br />
This field was previously eci_system_ return_code. In the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.1, and higher, this field is reserved for<br />
backward compatibility. No information is returned in this field; all<br />
system errors are written to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>’s error log.<br />
eci_extend_mode<br />
Required input parameter.<br />
An integer field determining whether a logical unit of work is<br />
terminated at the end of this call.) (See the Logical units of work in ECI<br />
table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more details.)<br />
The values for this field (shown by their symbolic names) are as<br />
follows:<br />
ECI_NO_EXTEND<br />
1. If the input eci_luw_token field is zero, this is the only<br />
call for a logical unit of work.<br />
2. If the input eci_luw_token field is not zero, this is the last<br />
call for the specified logical unit of work.<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
In either case, changes to recoverable resources are committed<br />
by a <strong>CICS</strong> end-of-task syncpoint, and the logical unit of work<br />
ends.
If you set eci_extend_mode to ECI_NO_EXTEND and<br />
eci_luw_token to 0, you will observe one request flowing from<br />
client to server and one reply flowing from server to client.<br />
The server sends the reply after the program specified in<br />
eci_program_name has been invoked and the changes made<br />
by that program have been committed.<br />
ECI_EXTENDED<br />
1. If the input eci_luw_token field is zero, this is the first call<br />
for a logical unit of work that is to be continued.<br />
2. If the input eci_luw_token field is not zero, this call is<br />
intended to continue the specified logical unit of work.<br />
In either case the logical unit of work continues after the<br />
called program completes successfully, and changes to<br />
recoverable resources remain uncommitted.<br />
ECI_COMMIT<br />
Terminate the current logical unit of work, identified by the<br />
input eci_luw_token field, and commit all changes made to<br />
recoverable resources.<br />
ECI_BACKOUT<br />
Terminate the logical unit of work identified by the input<br />
eci_luw_token field, and back out all changes made to<br />
recoverable resources.<br />
eci_luw_token<br />
Required input and output parameter.<br />
An integer field used for identifying the logical unit of work to which<br />
a call belongs. It must be set to zero at the start of a logical unit of<br />
work (regardless of whether the logical unit of work is going to be<br />
extended). If the logical unit of work is to be extended, the ECI<br />
updates eci_luw_token with a valid value on the first call of the<br />
logical unit of work, and this value should be used as input to all<br />
later calls related to the same logical unit of work. (See the Logical<br />
units of work in ECI table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide for more details.)<br />
If the return code is not ECI_NO_ERROR, and the call was continuing<br />
or ending an existing logical unit of work, this field is used as output<br />
to report the condition of the logical unit of work. If it is set to zero,<br />
the logical unit of work has ended, and its updates have been backed<br />
out. If it is nonzero, it is the same as the input value, the logical unit<br />
of work is continuing, and its updates are still pending.<br />
eci_sysid<br />
Required input parameter.<br />
Chapter 4. C and COBOL 103
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
eci_system_name<br />
Optional input parameter.<br />
An 8-character field that specifies the name of the server to which the<br />
ECI request is to be directed. Pad unused characters with spaces. If<br />
supplied, it should be one of the server names returned by<br />
<strong>CICS</strong>_EciListSystems. The value may be supplied whenever<br />
eci_luw_token is set to zero. (If it is supplied when eci_luw_token is<br />
not zero, it is ignored, because the server was established at the start<br />
of the logical unit of work.)<br />
If the field is set to nulls, the default server is selected; the name of<br />
the chosen server is returned in this field, and must be used in<br />
subsequent related ECI requests. If ECI requests made in different<br />
logical units of work must be directed to the same server,<br />
eci_system_name must identify that server by name.<br />
eci_userid2<br />
Optional input parameter.<br />
If the eci_userid field is set to nulls, the eci_userid2 field specifies the<br />
user ID (if any) to be used at the server for any authority validation.<br />
The user ID can be up to 16 characters.<br />
See the description of the eci_userid field for information about how<br />
the user ID is used.<br />
eci_password2<br />
Optional input parameter.<br />
If the eci_password field is set to nulls, the eci_password2 field<br />
specifies the password (if any) to be used at the server for any<br />
authority validation. The password can be up to 16 characters.<br />
See the description of the eci_password field for information about<br />
how the password is used.<br />
eci_tpn<br />
Optional input parameter. Available only if the value of eci_version is<br />
ECI_VERSION_1A.<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
A 4-character field that specifies the transaction ID of the transaction<br />
that will be used in the server to process the ECI request. This<br />
transaction must be defined in the server as a <strong>CICS</strong> mirror transaction.<br />
If the field is not set, the default mirror transaction CPMI is used.<br />
If the ECI request is extended (see the description of<br />
eci_extend_mode), this parameter has a meaning only for the first<br />
request.<br />
If this field is used, the contents of eci_transid are ignored.<br />
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
ECI_NO_ERROR<br />
The call completed successfully.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is outside the valid range, or<br />
is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null eci_commarea<br />
pointer.<br />
ECI_ERR_INVALID_EXTEND_MODE<br />
The value in eci_extend_mode field is not valid.<br />
ECI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is unavailable, or the server<br />
implementation is unavailable, or a logical unit of work was to be<br />
begun, but the <strong>CICS</strong> server specified in eci_system_name is not<br />
available. No resources have been updated.<br />
ECI_ERR_<strong>CICS</strong>_DIED<br />
A logical unit of work was to be begun or continued, but the <strong>CICS</strong><br />
server was no longer available. If eci_extend_mode was<br />
ECI_EXTENDED, the changes are backed out, and the logical unit of<br />
work ends. If eci_extend_mode was ECI_NO_EXTEND,<br />
ECI_COMMIT, or ECI_BACKOUT, the application cannot determine<br />
whether the changes have been committed or backed out, and must<br />
log this condition to aid future manual recovery.<br />
ECI_ERR_TRANSACTION_ABEND<br />
The <strong>CICS</strong> transaction that executed the requested program abended.<br />
The abend code will be found in eci_abend_code. For information<br />
about abend codes and their meaning, consult the documentation for<br />
the server system to which the request was directed.<br />
ECI_ERR_LUW_TOKEN<br />
The value supplied in eci_luw_token is invalid.<br />
Chapter 4. C and COBOL 105
ECI_ERR_ALREADY_ACTIVE<br />
An attempt was made to continue an existing logical unit of work, but<br />
there was an outstanding asynchronous call for the same logical unit<br />
of work.<br />
ECI_ERR_RESOURCE_SHORTAGE<br />
The server implementation or the Client daemon did not have enough<br />
resources to complete the request.<br />
ECI_ERR_NO_SESSIONS<br />
A new logical unit of work was being created, but the application<br />
already has as many outstanding logical units of work as the<br />
configuration will support.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_ERR_ROLLEDBACK<br />
An attempt was made to commit a logical unit of work, but the server<br />
was unable to commit the changes, and backed them out instead.<br />
ECI_ERR_UNKNOWN_SERVER<br />
The requested server could not be located. Only servers returned by<br />
<strong>CICS</strong>_EciListSystems are acceptable.<br />
ECI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy the<br />
request. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control communication resources.<br />
ECI_ERR_MAX_SYSTEMS<br />
You tried to start requests to more servers than your configuration<br />
allows. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control the number of servers you<br />
can use.<br />
ECI_ERR_SECURITY_ERROR<br />
You did not supply a valid combination of user ID and password.<br />
ECI_ASYNC call type<br />
Environment:<br />
Purpose: The ECI_ASYNC call type provides an asynchronous program link<br />
call to start, continue, or end a logical unit of work. The calling application<br />
gets control back when the ECI has accepted the request. At this point the<br />
parameters have been validated; however, the request might still be queued<br />
for later processing.<br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
If no callback routine is provided, the application must use a reply solicitation<br />
call to determine whether the request has ended and what the outcome was.<br />
If a callback routine is provided, the callback routine eci_callback is invoked<br />
when a response is available.<br />
Note: Some compilers do not support the use of callback routines. Consult<br />
your compiler documentation for more information.<br />
It is important that the Eci parameter blocks of outstanding<br />
ECI_ASYNC calls are not modified before the results of the call are<br />
received. Results will be incorrect if these blocks are modified before<br />
this stage.<br />
When the callback routine is called, it is passed a single parameter—the value<br />
specified in eci_message_qualifier. This enables the callback routine to<br />
identify the asynchronous call that is completing. Follow these guidelines<br />
when using the callback routine:<br />
1. The minimum possible processing should be performed within the<br />
callback routine.<br />
2. ECI functions cannot be invoked from within the callback routine.<br />
3. The callback routine should indicate to the main body of the application<br />
that the reply is available using an appropriate technique for the operating<br />
system upon which the ECI application is executing. For example, in a<br />
multithreaded environment, the callback routine might post a semaphore<br />
to signal another thread that an event has occurred.<br />
4. The application, not the callback routine, must use a reply solicitation call<br />
to receive the actual response.<br />
ECI parameter block fields: Set the ECI parameter block to nulls before you<br />
set the input parameter fields.<br />
eci_call_type<br />
Required input parameter.<br />
Must be set to ECI_ASYNC.<br />
eci_program_name<br />
Input only, required parameter except when eci_extend_mode is<br />
ECI_COMMIT or ECI_BACKOUT. (See the Logical units of work in ECI<br />
table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more details.)<br />
An 8-character field containing the name of the program to be called.<br />
Pad unused characters with spaces. This field is transmitted to the<br />
server without conversion to uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
Chapter 4. C and COBOL 107
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
eci_userid<br />
Required input parameter.<br />
An 8-character field containing a user ID. Pad unused characters with<br />
spaces.<br />
Consult the documentation for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the<br />
server to check whether this field is converted to upper case before<br />
being transmitted to the server. (If a user ID or password longer than<br />
8 characters is required, set eci_userid and eci_password to nulls, and<br />
use eci_userid2 and eci_password2 instead.)<br />
If a user ID is supplied, the server uses the user ID and any supplied<br />
password to authenticate the user. The supplied user ID and<br />
password are used in subsequent security checking in the server.<br />
eci_password<br />
Required input parameter.<br />
An 8-character field containing a password. Pad unused characters<br />
with spaces.<br />
Consult the documentation for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and the<br />
server to check whether this field is converted to upper case before<br />
being transmitted to the server. (If a user ID or password longer than<br />
8 characters is required, set eci_userid and eci_password to nulls, and<br />
use eci_userid2 and eci_password2 instead.)<br />
eci_transid<br />
Optional input parameter<br />
A 4-character field optionally containing the ID of a <strong>CICS</strong> transaction.<br />
Pad unused characters with spaces. The parameter is ignored if<br />
eci_tpn is used (set to any value other than nulls). The use of this<br />
parameter depends on the client from which the request is sent. The<br />
value of eci_transid is converted from ASCII to EBCDIC, with no<br />
upper case translation, and stored in EIBTRNID for the duration of<br />
the LINK to the program specified in the eci_program_name.<br />
The called program runs under the mirror transaction CPMI, but is<br />
linked to under the eci_transid transaction name. This name is<br />
available to the called program for querying the transaction ID. Some<br />
servers use the transaction ID to determine security and performance<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
attributes for the called program. In those servers, you are<br />
recommended to use this parameter to control the processing of your<br />
called programs.<br />
If the ECI request is extended (see “eci_extend_mode”), the<br />
eci_transid parameter has a meaning only for the first call in the unit<br />
of work.<br />
If the field is all nulls, and eci_tpn is not specified, the default server<br />
transaction ID is used.<br />
eci_commarea<br />
Required input parameter.<br />
A pointer to the data to be passed to the called <strong>CICS</strong> program as its<br />
COMMAREA.<br />
If no COMMAREA is required, supply a null pointer and set the<br />
length (specified in eci_commarea_length) to zero.<br />
If the code page of the application is different from the code page of<br />
the server, data conversion must be performed at the server. To do<br />
this, use <strong>CICS</strong>-supplied resource conversion capabilities, such as the<br />
DFHCNV macro definitions.<br />
eci_commarea_length<br />
Required input parameter.<br />
The length of the COMMAREA in bytes. This value may not exceed<br />
32 500. (Some client/server combinations may allow larger<br />
COMMAREAs, but this is not guaranteed to work.)<br />
If no COMMAREA is required, set this field to zero and supply a null<br />
pointer in eci_commarea.<br />
eci_timeout<br />
The time in seconds to wait for a response from the <strong>CICS</strong> server. A<br />
value of 0 means that no limit is set.<br />
If timeout occurs, the conversation is abended.<br />
reserved1<br />
Output parameter.<br />
This field was previously eci_system_ return_code. In the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.1, and higher, this field is reserved for<br />
backward compatibility. No information is returned in this field; all<br />
system errors are written to the error log.<br />
eci_extend_mode<br />
Required input parameter.<br />
Chapter 4. C and COBOL 109
An integer field determining whether a logical unit of work is<br />
terminated at the end of this call. (See the Logical units of work in ECI<br />
table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more details.)<br />
Values (shown by their symbolic names) for this field are as follows:<br />
ECI_NO_EXTEND<br />
1. If the input eci_luw_token field is zero, this is the only<br />
call for a logical unit of work.<br />
2. If the input eci_luw_token field is not zero, this is the last<br />
call for the specified logical unit of work.<br />
In either case, changes to recoverable resources are committed<br />
by a <strong>CICS</strong> end-of-task syncpoint, and the logical unit of work<br />
ends.<br />
ECI_EXTENDED<br />
1. If the input eci_luw_token field is zero, this is the first call<br />
for a logical unit of work that is to be continued.<br />
2. If the input eci_luw_token field is not zero, this call is<br />
intended to continue the specified logical unit of work.<br />
In either case the logical unit of work continues after the<br />
called program completes, and changes to recoverable<br />
resources remain uncommitted.<br />
ECI_COMMIT<br />
Terminate the current logical unit of work, identified by the<br />
input eci_luw_token field, and commit all changes made to<br />
recoverable resources.<br />
ECI_BACKOUT<br />
Terminate the logical unit of work identified by the input<br />
eci_luw_token field, and back out all changes made to<br />
recoverable resources.<br />
eci_message_qualifier<br />
Optional input parameter.<br />
An integer field allowing the application to identify each<br />
asynchronous call if it is making more than one. If a callback routine<br />
is specified, the value in this field is returned to the callback routine<br />
during the notification process.<br />
eci_luw_token<br />
Required input and output parameter.<br />
An integer field used for identifying the logical unit of work to which<br />
a call belongs. It must be set to zero at the start of a logical unit of<br />
work (regardless of whether the logical unit of work is going to be<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
extended), and the ECI updates it with a valid value on the first or<br />
only call of the logical unit of work. If the logical unit of work is to be<br />
extended, this value should be used as input to all later calls related<br />
to the same logical unit of work. (See the Logical units of work in ECI<br />
table in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide for more details.)<br />
If the return code is not ECI_NO_ERROR, and the call was continuing<br />
or ending an existing logical unit of work, this field is used as output<br />
to report the condition of the logical unit of work. If it is set to zero,<br />
the logical unit of work has ended, and its updates have been backed<br />
out. If it is nonzero, it is the same as the input value, the logical unit<br />
of work is continuing, and its updates are still pending.<br />
eci_sysid<br />
Required input parameter.<br />
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
eci_system_name<br />
Optional input parameter.<br />
An 8-character field that specifies the name of the server to which the<br />
ECI request is to be directed. Pad unused characters with spaces. The<br />
value may be supplied whenever eci_luw_token is set to zero. (If it is<br />
supplied when eci_luw_token is not zero, it is ignored, because the<br />
server was established at the start of the logical unit of work.)<br />
If the field is set to nulls, the default server is selected.You can obtain<br />
the name of the chosen server from the eci_system_name field of the<br />
reply solicitation call you use to get the result of this asynchronous<br />
request. (If later ECI requests made in different logical units of work<br />
must be directed to the same server as this request, eci_system_name<br />
in those requests must identify that server by name.)<br />
eci_callback<br />
Optional input parameter.<br />
A pointer to the routine to be called when the asynchronous request<br />
completes. (The callback routine will be called only if the return code<br />
is ECI_NO_ERROR, and the pointer is not null.)<br />
Chapter 4. C and COBOL 111
eci_userid2<br />
Optional input parameter.<br />
If the eci_userid field is set to nulls, the eci_userid2 field specifies the<br />
user ID (if any) to be used at the server for any authority validation.<br />
The user ID can be up to 16 characters.<br />
See the description of the eci_userid field for information about how<br />
the user ID is used.<br />
eci_password2<br />
Optional input parameter.<br />
If the eci_password field is set to nulls, the eci_password2 field<br />
specifies the password (if any) to be used at the server for any<br />
authority validation. The password can be up to 16 characters.<br />
See the description of the eci_password field for information about<br />
how the password is used.<br />
eci_tpn<br />
Optional input parameter. Available only if the value of eci_version is<br />
ECI_VERSION_1A.<br />
A 4-character field that specifies the transaction ID of the transaction<br />
that will be used in the server to process the ECI request. This<br />
transaction must be defined in the server as a <strong>CICS</strong> mirror transaction.<br />
If the field is not set, the default mirror transaction CPMI is used.<br />
If the ECI request is extended (see the description of<br />
eci_extend_mode), this parameter has a meaning only for the first<br />
request.<br />
If this field is used, the contents of eci_transid are ignored.<br />
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
If the return code is not ECI_NO_ERROR, the callback routine will not be<br />
called, and there will be no asynchronous reply for this request.<br />
ECI_NO_ERROR<br />
The call to the ECI completed successfully. No errors have yet been<br />
detected. The callback routine will be called when the request<br />
completes.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is outside the valid range, or<br />
is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null eci_commarea<br />
pointer.<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ECI_ERR_INVALID_EXTEND_MODE<br />
The value in eci_extend_mode field is not valid.<br />
ECI_ERR_NO_<strong>CICS</strong><br />
Either the client or the server implementation is not available.<br />
ECI_ERR_LUW_TOKEN<br />
The value supplied in eci_luw_token is invalid.<br />
ECI_ERR_THREAD_CREATE_ERROR<br />
The server implementation or the client failed to create a thread to<br />
process the request.<br />
ECI_ERR_ALREADY_ACTIVE<br />
An attempt was made to continue an existing logical unit of work, but<br />
there was an outstanding asynchronous call for the same logical unit<br />
of work.<br />
ECI_ERR_RESOURCE_SHORTAGE<br />
The server implementation or the client did not have enough<br />
resources to complete the request.<br />
ECI_ERR_NO_SESSIONS<br />
A new logical unit of work was being created, but the application<br />
already has as many outstanding logical units of work as the<br />
configuration will support.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_STATE_SYNC call type<br />
Environment: The ECI_STATE_SYNC call type is available in all<br />
environments.<br />
Purpose: The ECI_STATE_SYNC call type provides a synchronous status<br />
information call.<br />
ECI parameter block fields: The ECI parameter block should be set to nulls<br />
before setting the input parameter fields.<br />
eci_call_type<br />
Required input parameter.<br />
Must be set to ECI_STATE_SYNC.<br />
eci_commarea<br />
Input parameter, required except when eci_extend_mode has the<br />
value ECI_STATE_CANCEL.<br />
Chapter 4. C and COBOL 113
A pointer to the area of storage where the application receives the<br />
returned COMMAREA containing status information. See Status<br />
information calls, intheExternal call interface chapter, in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and “ECI status block” on<br />
page 128, for more details.<br />
If eci_extend_mode has the value ECI_STATE_CANCEL, supply a<br />
null pointer and set the length (specified in eci_commarea_length) to<br />
zero.<br />
eci_commarea_length<br />
Required input and output parameter, except when eci_extend_mode<br />
has the value ECI_STATE_CANCEL.<br />
The length of the COMMAREA in bytes, which must be the length of<br />
the ECI_STATUS structure that gives the layout of the status<br />
information COMMAREA. See Status information calls, intheExternal<br />
call interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide,<br />
and “ECI status block” on page 128, for more details. Area size must<br />
not exceed 32 500 bytes<br />
If no COMMAREA is required, set this field to zero and supply a null<br />
pointer in eci_commarea.<br />
reserved1<br />
Output parameter.<br />
This field was previously eci_system_ return_code. In the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.1, and higher, this field is reserved for<br />
backward compatibility. No information is returned in this field; all<br />
system errors are written to the error log.<br />
eci_extend_mode<br />
Required input parameter.<br />
An integer field further qualifying the call type. The values for this<br />
field (shown by their symbolic names) are as follows:<br />
ECI_STATE_IMMEDIATE<br />
Force a status reply to be sent immediately it is available. The<br />
layout of the returned COMMAREA is defined in the<br />
ECI_STATUS structure. See Status information calls, inthe<br />
External call interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide, and “ECI status block” on page 128, for<br />
more details.<br />
ECI_STATE_CHANGED<br />
Force a status reply to be sent only when the status changes.<br />
The supplied COMMAREA must contain the status as<br />
perceived by the application. A reply is sent only when there<br />
is a change from the status that the application supplied. The<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
layout of the COMMAREA is defined in the ECI_STATUS<br />
structure. See Status information calls, intheExternal call<br />
interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide, and “ECI status block” on page 128, for more details.<br />
The eci_luw_token field that is returned on the immediate<br />
response provides a token to identify the request.<br />
ECI_STATE_CANCEL<br />
Cancel an ECI_STATE_CHANGED type of operation. No<br />
COMMAREA is required for this request. The eci_luw_token<br />
field must contain the token that was received during the<br />
ECI_STATE_CHANGED call.<br />
eci_luw_token<br />
Optional input and output parameter.<br />
When a deferred status request is being set up (eci_extend_mode set<br />
to ECI_STATE_CHANGED), the token identifying the request is<br />
returned in the eci_luw_token field.<br />
When a deferred status request is being cancelled (eci_extend_mode<br />
set to ECI_STATE_CANCEL), the eci_luw_token field must contain<br />
the token that was received during the ECI_STATE_CHANGED call.<br />
This field is not used when other values of eci_extend_mode are<br />
specified.<br />
eci_sysid<br />
Required input parameter.<br />
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
eci_system_name<br />
Optional input parameter.<br />
An 8-character field that specifies the name of the server for which<br />
status information is required. Pad unused characters with spaces. If<br />
supplied, it should be one of the server names returned by<br />
<strong>CICS</strong>_EciListSystems. The value may be supplied whenever<br />
eci_luw_token is set to zero.<br />
If the field is set to nulls, the default server is selected; the name of<br />
the chosen server is returned in this field.<br />
Chapter 4. C and COBOL 115
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
ECI_NO_ERROR<br />
The call completed successfully.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is outside the valid range, or<br />
is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null eci_commarea<br />
pointer.<br />
ECI_ERR_INVALID_EXTEND_MODE<br />
The value in eci_extend_mode field is not valid.<br />
ECI_ERR_LUW_TOKEN<br />
The value supplied in eci_luw_token is invalid.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_ERR_UNKNOWN_SERVER<br />
The requested server could not be located. Only servers returned by<br />
<strong>CICS</strong>_EciListSystems are acceptable.<br />
ECI_STATE_ASYNC call type<br />
Environment:<br />
Purpose: The ECI_STATE_ASYNC call type provides an asynchronous status<br />
information call. The calling application gets control back when the ECI<br />
accepts the request. At this point the parameters have been validated;<br />
however, the request might still be queued for later processing.<br />
If no callback routine is provided, the application must use a reply solicitation<br />
call to determine that the request has ended and what the outcome was.<br />
If a callback routine is provided, the callback routine eci_callback is invoked<br />
when a response is available.<br />
Note: Some compilers do not support the use of callback routines. Consult<br />
your compiler documentation for more information.<br />
Note: It is important that the Eci parameter blocks of outstanding<br />
ECI_STATE_ASYNC calls are not modified before the results of the call<br />
are received. Results will be incorrect if these blocks are modified<br />
before this stage.<br />
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
When the callback routine is called, it is passed a single parameter—the value<br />
specified in eci_message_qualifier. This enables the callback routine to<br />
identify the asynchronous call that is completing. Note the following<br />
guidelines on the use of the callback routine:<br />
1. The minimum possible processing should be performed within the<br />
callback routine.<br />
2. ECI functions cannot be invoked from within the callback routine.<br />
3. The callback routine should indicate to the main body of the application<br />
that the reply is available using an appropriate technique for the operating<br />
system upon which the ECI application is executing. For example, in a<br />
multithreaded environment, the callback routine might post a semaphore<br />
to signal another thread that an event has occurred.<br />
4. The application, not the callback routine, must use a reply solicitation call<br />
to receive the actual response.<br />
ECI parameter block fields: The ECI parameter block should be set to nulls<br />
before setting the input parameter fields.<br />
eci_call_type<br />
Required input parameter.<br />
Must be set to ECI_STATE_ASYNC.<br />
eci_commarea<br />
Input parameter, required except when eci_extend_mode has the<br />
value ECI_STATE_CANCEL.<br />
A pointer to the area of storage where the application receives the<br />
returned COMMAREA containing status information. See Status<br />
information calls, intheExternal call interface chapter, in <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and “ECI status block” on<br />
page 128, for more details.<br />
If eci_extend_mode has the value ECI_STATE_CANCEL, supply a<br />
null pointer and set the length (specified in eci_commarea_length) to<br />
zero.<br />
eci_commarea_length<br />
Required input parameter, except when eci_extend_mode has the<br />
value ECI_STATE_CANCEL.<br />
The length of the COMMAREA in bytes, which must be the length of<br />
the ECI_STATUS structure that gives the layout of the status<br />
information COMMAREA. See Status information calls, intheExternal<br />
call interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide,<br />
and “ECI status block” on page 128, for more details. Area size must<br />
not exceed 32 500 bytes<br />
Chapter 4. C and COBOL 117
If no COMMAREA is required, set this field to zero and supply a null<br />
pointer in eci_commarea.<br />
reserved1<br />
Output parameter.<br />
This field was previously eci_system_ return_code. In the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.1, and higher, this field is reserved for<br />
backward compatibility. No information is returned in this field; all<br />
system errors are written to the error log.<br />
eci_extend_mode<br />
Required input parameter.<br />
An integer field further qualifying the call type. The values for this<br />
field (shown by their symbolic names) are as follows:<br />
ECI_STATE_IMMEDIATE<br />
Force a status reply to be sent immediately it is available. The<br />
layout of the returned COMMAREA is defined in the<br />
ECI_STATUS structure. See Status information calls, inthe<br />
External call interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide, and “ECI status block” on page 128, for<br />
more details.<br />
ECI_STATE_CHANGED<br />
Force a status reply to be sent only when the status changes.<br />
The supplied COMMAREA must contain the status as<br />
perceived by the application. A reply is sent only when there<br />
is a change from the status that the application supplied. The<br />
layout of the COMMAREA is defined in the ECI_STATUS<br />
structure. See Status information calls, intheExternal call<br />
interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide, and “ECI status block” on page 128, for more details.<br />
The eci_luw_token field that is returned on the immediate<br />
response identifies the logical unit of work to which this call<br />
belongs.<br />
ECI_STATE_CANCEL<br />
Cancel an ECI_STATE_CHANGED type of operation. No<br />
COMMAREA is required for this request. The eci_luw_token<br />
field must contain the token that was received during the<br />
ECI_STATE_CHANGED call.<br />
eci_message_qualifier<br />
Optional input parameter.<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
An integer field allowing you to identify each asynchronous call if<br />
you are making more than one. If a callback routine is specified, the<br />
value in this field is returned to the callback routine during the<br />
notification process.<br />
eci_luw_token<br />
Optional input and output parameter.<br />
When a deferred status request is being set up (eci_extend_mode set<br />
to ECI_STATE_CHANGED), the token identifying the request is<br />
returned in the eci_luw_token field.<br />
When a deferred status request is being cancelled (eci_extend_mode<br />
set to ECI_STATE_CANCEL), the eci_luw_token field must contain<br />
the token that was received during the ECI_STATE_CHANGED call.<br />
This field is not used when other values of eci_extend_mode are<br />
specified.<br />
eci_sysid<br />
Required input parameter.<br />
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
eci_system_name<br />
Optional input parameter.<br />
An 8-character field that specifies the name of the server for which<br />
status information is requested. Pad unused characters with spaces. If<br />
supplied, it should be one of the server names returned by<br />
<strong>CICS</strong>_EciListSystems. The value may be supplied whenever<br />
eci_luw_token is set to zero.<br />
If the field is set to nulls, the default server is selected.You can find<br />
out the name of the server from the eci_system_name field of the<br />
reply solicitation call you use to get the result of this asynchronous<br />
request. field.<br />
eci_callback<br />
Optional input parameter.<br />
Chapter 4. C and COBOL 119
A pointer to the routine to be called when the asynchronous request<br />
completes. (The callback routine will be called only if the return code<br />
is ECI_NO_ERROR, and the pointer is not null.)<br />
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
If the return code is not ECI_NO_ERROR, the callback routine will not be<br />
called, and there will be no asynchronous reply for this request.<br />
ECI_NO_ERROR<br />
The call completed successfully.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is outside the valid range, or<br />
is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null eci_commarea<br />
pointer.<br />
ECI_ERR_INVALID_EXTEND_MODE<br />
The value in eci_extend_mode field is not valid.<br />
ECI_ERR_LUW_TOKEN<br />
The value supplied in eci_luw_token is invalid.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_GET_REPLY call type<br />
Environment:<br />
Purpose: The ECI_GET_REPLY call type provides a reply solicitation call to<br />
return information appropriate to any outstanding reply for any asynchronous<br />
request. If there is no such reply, ECI_ERR_NO_REPLY is returned. (To cause<br />
the application to wait until a reply is available, use call type<br />
ECI_GET_REPLY_WAIT instead.)<br />
Note: It is important that the Eci parameter blocks of outstanding<br />
ECI_ASYNC calls are not modified before the results of the call are<br />
received (for example using this get reply call). Results will be incorrect<br />
if these blocks are modified before this stage.<br />
ECI parameter block fields: The ECI parameter block should be set to nulls<br />
before setting the input parameter fields.<br />
The following fields are the fields of the ECI parameter block that might be<br />
supplied as input.<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
In the course of an ECI_GET_REPLY call, the ECI parameter block is updated<br />
as follows:<br />
1. All the outputs from the reply, some of which overwrite input fields, are<br />
added. These fields are those that are output from the corresponding<br />
synchronous version of the asynchronous request.<br />
2. The eci_message_qualifier value supplied as input to the asynchronous<br />
request to which this reply relates is restored.<br />
3. Any inputs that are not updated become undefined, except the pointer to<br />
the COMMAREA. Do not use the contents of these fields again.<br />
eci_call_type<br />
Required input parameter.<br />
Must be set to ECI_GET_REPLY.<br />
eci_commarea<br />
Optional input parameter.<br />
A pointer to the area of storage where the application receives the<br />
returned COMMAREA. The contents of the returned commarea<br />
depend on the type of asynchronous call to which a reply is being<br />
sought. For a program link call, it is the COMMAREA expected to be<br />
returned from the called program, if any. For a status information call,<br />
except when eci_extend_mode has the value ECI_STATE_CANCEL, it<br />
is a COMMAREA containing status information. See Status information<br />
calls, intheExternal call interface chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide, and “ECI status block” on page 128, for more<br />
details.<br />
If no COMMAREA is required, supply a null pointer and set the<br />
length (specified in eci_commarea_length) to zero.<br />
If the code page of the application is different from the code page of<br />
the server, data conversion must be performed at the server. To do<br />
this, use <strong>CICS</strong>-supplied resource conversion capabilities, such as the<br />
DFHCNV macro definitions.<br />
eci_commarea_length<br />
Required input parameter.<br />
The length of the COMMAREA in bytes. This value may not exceed<br />
32 500. (Some client/server combinations may allow larger<br />
COMMAREAs, but this is not guaranteed to work.)<br />
If no COMMAREA is required, set this field to zero and supply a null<br />
pointer in eci_commarea.<br />
eci_sysid<br />
Required input parameter.<br />
Chapter 4. C and COBOL 121
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
ECI_NO_ERROR<br />
The asynchronous request to which this reply relates completed<br />
successfully.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is unacceptable for one of the<br />
following reasons:<br />
v It is outside the valid range.<br />
v It is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null<br />
eci_commarea pointer.<br />
v It is not large enough for the output COMMAREA from the<br />
asynchronous request to which this reply relates.<br />
In the last case, you can use the output eci_commarea_length to<br />
allocate more storage for the COMMAREA, and then use the output<br />
eci_message_qualifier (if it identifies the asynchronous request<br />
uniquely) with an ECI_GET_SPECIFIC_REPLY call type to retrieve the<br />
reply.<br />
ECI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> server specified in eci_system_name in the asynchronous<br />
request to which this reply relates is not available. No resources have<br />
been updated.<br />
ECI_ERR_<strong>CICS</strong>_DIED<br />
A logical unit of work was to be begun or continued by the<br />
asynchronous request to which this reply relates, but the <strong>CICS</strong> server<br />
was no longer available. If eci_extend_mode was ECI_EXTENDED,<br />
the changes are backed out, and the logical unit of work ends. If<br />
eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or<br />
ECI_BACKOUT, the application cannot determine whether the<br />
changes have been committed or backed out, and must log this<br />
condition to aid future manual recovery.<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ECI_ERR_NO_REPLY<br />
There was no outstanding reply.<br />
ECI_ERR_TRANSACTION_ABEND<br />
The asynchronous request to which this reply relates caused a<br />
program to be executed in the server, but the <strong>CICS</strong> transaction that<br />
executed the requested program abended. The abend code will be<br />
found in eci_abend_code. For information about abend codes and<br />
their meaning, consult the documentation for the server system to<br />
which the request was directed.<br />
ECI_ERR_THREAD_CREATE_ERROR<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> failed to create the<br />
thread to process the asynchronous call to which this reply relates.<br />
ECI_ERR_RESOURCE_SHORTAGE<br />
The server implementation or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have<br />
enough resources to complete the asynchronous request to which this<br />
reply relates.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_ERR_ROLLEDBACK<br />
The asynchronous request to which this reply relates attempted to<br />
commit a logical unit of work, but the server was unable to commit<br />
the changes, and backed them out instead.<br />
ECI_ERR_UNKNOWN_SERVER<br />
The asynchronous request to which this reply relates specified a<br />
server that could not be located. Only servers returned by<br />
<strong>CICS</strong>_EciListSystems are acceptable.<br />
ECI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy the<br />
asynchronous request to which this reply relates. Consult the<br />
documentation for your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or server to see<br />
how to control communication resources.<br />
ECI_ERR_MAX_SYSTEMS<br />
The asynchronous request to which this reply relates attempted to<br />
start requests to more servers than your configuration allows. Consult<br />
the documentation for your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or server to<br />
see how to control the number of servers you can use.<br />
ECI_ERR_SECURITY_ERROR<br />
You did not supply a valid combination of userid and password on<br />
the asynchronous request to which this reply relates.<br />
Chapter 4. C and COBOL 123
ECI_GET_REPLY_WAIT call type<br />
Environment:<br />
Purpose: The ECI_GET_REPLY_WAIT call type provides a reply solicitation<br />
call to return information appropriate to any outstanding reply for any<br />
asynchronous request. If there is no such reply, the application waits until<br />
there is. (You can get an indication that no reply is available by using call type<br />
ECI_GET_REPLY instead.)<br />
Note: It is important that the Eci parameter blocks of outstanding<br />
ECI_STATE_ASYNC calls are not modified before the results of the call<br />
are received. Results will be incorrect if these blocks are modified<br />
before this stage.<br />
ECI parameter block fields: Same as for ECI_GET_REPLY, but eci_call_type<br />
must be set to ECI_GET_REPLY_WAIT.<br />
Return codes: Same as for ECI_GET_REPLY, except that<br />
ECI_ERR_NO_REPLY cannot be returned.<br />
ECI_GET_SPECIFIC_REPLY call type<br />
Purpose: The ECI_GET_SPECIFIC_REPLY call type provides a reply<br />
solicitation call to return information appropriate to any outstanding reply<br />
that matches the eci_message_qualifier input. If there is no such reply,<br />
ECI_ERR_NO_REPLY is returned. (To cause the application to wait until a<br />
reply is available, use call type ECI_GET_REPLY_WAIT instead.)<br />
Note: It is important that the Eci parameter blocks of outstanding<br />
ECI_STATE_ASYNC calls are not modified before the results of the call<br />
are received. Results will be incorrect if these blocks are modified<br />
before this stage.<br />
ECI parameter block fields: Set the ECI parameter block to nulls before<br />
setting the input parameter fields.<br />
The following fields are the fields of the ECI parameter block that might be<br />
supplied as input.<br />
In the course of an ECI_GET_REPLY call, the ECI parameter block is updated<br />
as follows:<br />
1. All the outputs from the reply, some of which overwrite input fields, are<br />
added. These fields are those that are output from the corresponding<br />
synchronous version of the asynchronous request.<br />
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
2. Any inputs that are not updated become undefined, except the pointer to<br />
the COMMAREA and the input eci_message_qualifier. Do not use the<br />
contents of these fields again.<br />
eci_call_type<br />
Required input parameter.<br />
Must be set to ECI_GET_SPECIFIC_REPLY.<br />
eci_commarea<br />
Optional input parameter.<br />
A pointer to the area of storage where the application receives the<br />
returned COMMAREA. The contents of the returned commarea<br />
depend on the type of asynchronous call to which a reply is being<br />
sought. For a program link call, it is the COMMAREA expected to be<br />
returned from the called program, if any. For a status information call,<br />
except one in which eci_extend_mode had the value<br />
ECI_STATE_CANCEL, it is a COMMAREA containing status<br />
information. See Status information calls, intheExternal call interface<br />
chapter, in <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, and “ECI<br />
status block” on page 128, for more details.<br />
If the code page of the application is different from the code page of<br />
the server, data conversion must be performed at the server. To do<br />
this, use <strong>CICS</strong>-supplied resource conversion capabilities, such as the<br />
DFHCNV macro definitions.<br />
eci_commarea_length<br />
Required input parameter.<br />
The length of the COMMAREA in bytes. This value may not exceed<br />
32 500. (Some client/server combinations may allow larger<br />
COMMAREAs, but this is not guaranteed to work.)<br />
eci_message_qualifier<br />
Required input parameter.<br />
An integer field that identifies the asynchronous call for which a reply<br />
is being solicited.<br />
eci_sysid<br />
Required input parameter.<br />
Reserved for future use, but this field should be initialized with nulls<br />
before the start of each logical unit of work.<br />
eci_version<br />
Required input parameter.<br />
The version of the ECI for which the application is coded. You may<br />
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the<br />
Chapter 4. C and COBOL 125
facilities of version 1 are available in version 1A. Facilities available<br />
only in version 1A are noted where they occur.<br />
Return codes: See also the general list of return codes for <strong>CICS</strong>_ExternalCall<br />
in “<strong>CICS</strong>_ExternalCall ECI_Parms” on page 97.<br />
ECI_NO_ERROR<br />
The call completed successfully.<br />
ECI_ERR_INVALID_DATA_LENGTH<br />
The value in eci_commarea_length field is unacceptable for one of the<br />
following reasons:<br />
v It is outside the valid range.<br />
v It is inconsistent with the value in eci_commarea, being zero for a<br />
non-null eci_commarea pointer, or non-zero for a null<br />
eci_commarea pointer.<br />
v It is not large enough for the output COMMAREA from the<br />
asynchronous request to which this reply relates.<br />
In the last case, you can use the output eci_commarea_length to<br />
allocate more storage for the COMMAREA, and then retry the<br />
ECI_GET_SPECIFIC_REPLY call.<br />
ECI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> server specified in eci_system_name in the asynchronous<br />
request to which this reply relates is not available. No resources have<br />
been updated.<br />
ECI_ERR_<strong>CICS</strong>_DIED<br />
A logical unit of work was to be begun or continued by the<br />
asynchronous request to which this reply relates, but the <strong>CICS</strong> server<br />
was no longer available. If eci_extend_mode was ECI_EXTENDED,<br />
the changes are backed out, and the logical unit of work ends. If<br />
eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or<br />
ECI_BACKOUT, the application cannot determine whether the<br />
changes have been committed or backed out, and must log this<br />
condition to aid future manual recovery.<br />
ECI_ERR_NO_REPLY<br />
There was no outstanding reply that matched the input<br />
eci_message_qualifier.<br />
ECI_ERR_TRANSACTION_ABEND<br />
The asynchronous request to which this reply relates caused a<br />
program to be executed in the server, but the <strong>CICS</strong> transaction that<br />
executed the requested program abended. The abend code will be<br />
found in eci_abend_code. For information about abend codes and<br />
their meaning, consult the documentation for the server system to<br />
which the request was directed.<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ECI_ERR_THREAD_CREATE_ERROR<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> failed to create the<br />
thread to process the asynchronous request to which this reply relates.<br />
ECI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough<br />
resources to complete the asynchronous request to which this reply<br />
relates.<br />
ECI_ERR_INVALID_DATA_AREA<br />
Either the pointer to the ECI parameter block is invalid, or the pointer<br />
supplied in eci_commarea is invalid.<br />
ECI_ERR_ROLLEDBACK<br />
The asynchronous request to which this reply relates attempted to<br />
commit a logical unit of work, but the server was unable to commit<br />
the changes, and backed them out instead.<br />
ECI_ERR_UNKNOWN_SERVER<br />
The asynchronous request to which this reply relates specified a<br />
server that could not be located. Only servers returned by<br />
<strong>CICS</strong>_EciListSystems are acceptable.<br />
ECI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy the<br />
asynchronous request to which this reply relates. Consult the<br />
documentation for your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or server to see<br />
how to control communication resources.<br />
ECI_ERR_MAX_SYSTEMS<br />
The asynchronous request to which this reply relates attempted to<br />
start requests to more servers than your configuration allows. Consult<br />
the documentation for your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or server to<br />
see how to control the number of servers you can use.<br />
ECI_ERR_SECURITY_ERROR<br />
You did not supply a valid combination of userid and password on<br />
the asynchronous request to which this reply relates.<br />
ECI_GET_SPECIFIC_REPLY_WAIT call type<br />
Environment:<br />
Purpose: The ECI_GET_SPECIFIC_REPLY_WAIT call type provides a reply<br />
solicitation call to return information appropriate to any outstanding reply<br />
that matches the input eci_message_qualifier. If there is no such reply, the<br />
application waits until there is. (You can get an indication that no reply is<br />
available by using call type ECI_GET_SPECIFIC_REPLY instead.)<br />
Chapter 4. C and COBOL 127
Note: It is important that the Eci parameter blocks of outstanding<br />
ECI_STATE_ASYNC calls are not modified before the results of the call<br />
are received. Results will be incorrect if these blocks are modified<br />
before this stage.<br />
ECI parameter block fields: Same as for ECI_GET_SPECIFIC_REPLY, but<br />
eci_call_type must be set to ECI_GET_SPECIFIC_REPLY_WAIT.<br />
Return codes: Same as for ECI_GET_SPECIFIC_REPLY, except that<br />
ECI_ERR_NO_REPLY cannot be returned.<br />
Note: If you issue an ECI_GET_SPECIFIC_REPLY_WAIT call against an<br />
outstanding ECI_STATE_AYSNC call with eci_extend mode set to<br />
ECI_STATE_CHANGED, no response will ever be received if an<br />
ECI_STATE_ASYNC call with eci_extend_mode set to<br />
ECI_STATE_CANCEL is issued.<br />
ECI status block<br />
The ECI status block is used in status information calls to pass information to<br />
and from the ECI. It contains the following fields:<br />
ConnectionType<br />
An integer field specifying the type of system on which the<br />
application is running, with the following possible values:<br />
ECI_CONNECTED_NOWHERE<br />
Application is not connected to anything.<br />
ECI_CONNECTED_TO_CLIENT<br />
Application is running on a client system.<br />
ECI_CONNECTED_TO_SERVER<br />
Application is using a server implementation of the ECI.<br />
CicsServerStatus<br />
An integer field specifying the state of the <strong>CICS</strong> server, with the<br />
following possible values:<br />
ECI_SERVERSTATE_UNKNOWN<br />
The <strong>CICS</strong> server state could not be determined.<br />
ECI_SERVERSTATE_UP<br />
The <strong>CICS</strong> server is available to run programs.<br />
ECI_SERVERSTATE_DOWN<br />
The <strong>CICS</strong> server is not available to run programs.<br />
CicsClientStatus<br />
An integer field specifying the state of the Client daemon, with the<br />
following possible values:<br />
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ECI_CLIENTSTATE_UNKNOWN<br />
The Client daemon state could not be determined.<br />
ECI_CLIENTSTATE_UP<br />
The Client daemon is available to receive ECI calls.<br />
ECI_CLIENTSTATE_INAPPLICABLE<br />
The application is using a server implementation of the ECI.<br />
<strong>CICS</strong>_EciListSystems NameSpace Systems List<br />
ECI status block<br />
Purpose<br />
The <strong>CICS</strong>_EciListSystems function provides a list of <strong>CICS</strong> servers to which<br />
<strong>CICS</strong>_ExternalCall requests may be directed. There is no guarantee that a<br />
communications link exists between the Client daemon and any server in the<br />
list, or that any of the servers is available to process requests.<br />
The list of servers is returned as an array of system information structures,<br />
one element for each <strong>CICS</strong> server. The structure, called <strong>CICS</strong>_EciSystem_t,<br />
defines the following fields.<br />
SystemName<br />
A pointer to a null-terminated string specifying the name of a <strong>CICS</strong><br />
server. If the name is shorter than <strong>CICS</strong>_ECI_SYSTEM_MAX, it is<br />
padded with nulls to a length of <strong>CICS</strong>_ECI_SYSTEM_MAX + 1.<br />
Description<br />
A pointer to a null-terminated string that provides a description of the<br />
system, if one is available. If the description is shorter than<br />
<strong>CICS</strong>_ECI_DESCRIPTION_MAX characters, it is padded with nulls to<br />
a length of <strong>CICS</strong>_ECI_DESCRIPTION_MAX + 1.<br />
Parameters<br />
NameSpace<br />
A pointer reserved for future use. Ensure that this is a null pointer.<br />
Systems<br />
On entry to the function, this parameter specifies the number of<br />
elements in the array provided in the List parameter. On return it<br />
contains the actual number of systems found.<br />
List An array of <strong>CICS</strong>_EciSystem_t structures that are filled in and<br />
returned by the function. The application must provide storage for the<br />
array, and must set the Systems parameter to indicate the number of<br />
elements in the array. The first name in the list is the default server.<br />
However, the way in which the default is defined depends upon the<br />
operating system.<br />
Chapter 4. C and COBOL 129
ECI status block<br />
Return Codes<br />
ECI_NO_ERROR<br />
The function completed successfully. The number of systems found is<br />
at least one, and does not exceed the value supplied as input in the<br />
Systems parameter.<br />
ECI_ERR_MORE_SYSTEMS<br />
There was not enough space in the List array to store the information.<br />
The supplied array has been filled, and the Systems parameter has<br />
been updated to contain the total number of systems found, so that<br />
you can reallocate an array of suitable size and try the function again.<br />
ECI_ERR_NO_SYSTEMS<br />
No <strong>CICS</strong> servers can be located. In this case, the value returned in<br />
Systems is zero.<br />
ECI_ERR_NO_<strong>CICS</strong><br />
The Client daemon is not active.<br />
ECI_ERR_INVALID_DATA _LENGTH<br />
The value specified in the Systems parameter is so large that the<br />
length of storage for the List parameter exceeds 32 767.<br />
ECI_ERR_CALL_FROM_CALLBACK<br />
The call was made from a callback routine.<br />
ECI_ERR_SYSTEM_ERROR<br />
An internal system error occurred.<br />
External Presentation Interface<br />
EPI constants and data structures<br />
This section describes the constants and data structures that you will need to<br />
use the EPI. They are referred to in “EPI functions” on page 137.<br />
EPI constants<br />
The following constants are referred to symbolically in the descriptions of the<br />
EPI data structures, functions, and events in this Chapter. Their values are<br />
given here to help you understand the descriptions. However, your code<br />
should always use the symbolic names of EPI constants provided for the<br />
programming language you are using.<br />
Lengths of fields<br />
v <strong>CICS</strong>_EPI_SYSTEM_MAX (8)<br />
v <strong>CICS</strong>_EPI_DESCRIPTION_MAX (60)<br />
v <strong>CICS</strong>_EPI_NETNAME_MAX (8)<br />
v <strong>CICS</strong>_EPI_TRANSID_MAX (4)<br />
v <strong>CICS</strong>_EPI_ABEND_MAX (4)<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
v <strong>CICS</strong>_EPI_DEVTYPE_MAX (16)<br />
v <strong>CICS</strong>_EPI_ERROR_MAX (60).<br />
v <strong>CICS</strong>_EPI_PASSWORD_MAX (10)<br />
v <strong>CICS</strong>_EPI_USERID_MAX (10)<br />
v <strong>CICS</strong>_EPI_MAPNAME_MAX (7)<br />
v <strong>CICS</strong>_EPI_MAPSETNAME_MAX (8)<br />
v <strong>CICS</strong>_EPI_TERMID_MAX (4)<br />
Relating to TermIndex<br />
v <strong>CICS</strong>_EPI_TERM_INDEX_NONE 0xFFFF.<br />
<strong>Version</strong> numbers (See EPI versions, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming<br />
Guide.)<br />
v <strong>CICS</strong>_EPI_VERSION_100<br />
v <strong>CICS</strong>_EPI_VERSION_101.<br />
v <strong>CICS</strong>_EPI_VERSION_200.<br />
EPI data structures<br />
The following data structures are available for use with the EPI.<br />
v <strong>CICS</strong>_EpiSystem_t<br />
v <strong>CICS</strong>_EpiAttributes_t<br />
v <strong>CICS</strong>_EpiDetails_t<br />
v <strong>CICS</strong>_EpiEventData_t<br />
v <strong>CICS</strong>_EpiSysError_t.<br />
In the descriptions of the fields in the data structures, fields described as<br />
strings are null-terminated strings.<br />
<strong>CICS</strong>_EpiSystem_t:<br />
EPI constants and data structures<br />
Purpose: The <strong>CICS</strong>_EpiSystem_t structure contains the name and description<br />
of a <strong>CICS</strong> server. An array of these structures is returned from the<br />
<strong>CICS</strong>_EpiListSystems function.<br />
Fields:<br />
SystemName<br />
A string naming the <strong>CICS</strong> server. It can be passed as a parameter to<br />
the <strong>CICS</strong>_EpiAddTerminal and <strong>CICS</strong>_EpiAddExTerminal functions,<br />
to identify the <strong>CICS</strong> server in which the terminal resource should be<br />
installed. If the name is shorter than <strong>CICS</strong>_EPI_SYSTEM_MAX<br />
characters, it is padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_SYSTEM_MAX + 1.<br />
Description<br />
A string giving a brief description of the server. If the description is<br />
shorter than <strong>CICS</strong>_EPI_DESCRIPTION_MAX, it is padded with nulls<br />
to a length of <strong>CICS</strong>_EPI_DESCRIPTION_MAX + 1.<br />
Chapter 4. C and COBOL 131
EPI constants and data structures<br />
<strong>CICS</strong>_EpiAttributes_t:<br />
Purpose: The <strong>CICS</strong>_EpiAttributes_t structure holds information about the<br />
attributes to be associated with a terminal resource installed by the<br />
<strong>CICS</strong>_EpiAddExTerminal function.<br />
This data structure is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
Fields:<br />
EpiAddType<br />
Indicates whether the application is prepared to wait until the request<br />
to install the terminal is complete. Use one of the following values:<br />
<strong>CICS</strong>_EPI_ADD_ASYNC<br />
The calling application gets control back when the request to<br />
install the terminal resource has been accepted; at this point<br />
the parameters have been validated.<br />
Assuming valid parameters, the<br />
<strong>CICS</strong>_EPI_EVENT_ADD_TERM event is generated when the<br />
request to install the terminal has completed.<br />
The TermIndex is returned for use with the<br />
<strong>CICS</strong>_EpiGetEvent function.<br />
<strong>CICS</strong>_EPI_ADD_SYNC<br />
The calling application gets control back when the request to<br />
install the terminal resource has completed. Returned<br />
information is immediately available.<br />
InstallTimeOut<br />
A value in the range 0 through 3600, specifying the maximum time in<br />
seconds that installation of the terminal resource is allowed to take; a<br />
value of 0 means that no limit is set.<br />
A value of 3600 is assumed if a larger value is specified.<br />
ReadTimeOut<br />
A value in the range 0 through 3600, specifying the maximum time in<br />
seconds that is allowed between notification of a<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE event for the terminal resource and<br />
the following invocation of the <strong>CICS</strong>_EpiReply; a value of 0 means<br />
that no limit is set.<br />
A value of 3600 is assumed if a larger value is specified.<br />
If time-out occurs, the conversation is abended. This results in a<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event being generated; the<br />
EndReason field is set to <strong>CICS</strong>_EPI_READTIMEOUT_EXPIRED; the<br />
AbendCode field is not set.<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
SignonCapability<br />
Indicates whether the application may start server-provided signon<br />
and signoff transactions from the terminal resource. Use one of the<br />
following values:<br />
<strong>CICS</strong>_EPI_SIGNON_CAPABLE<br />
The terminal resource is to be installed as signon capable.<br />
<strong>CICS</strong>_EPI_SIGNON_INCAPABLE<br />
The resource is to be installed as signon incapable.<br />
CCSId<br />
A value in the range 1 through 65536 specifying the coded character<br />
set identifier (CCSID) that identifies the coded graphic character set<br />
used by the client application for data passed between the terminal<br />
resource and <strong>CICS</strong> transactions.<br />
A value of 0 means that a default CCSID is used.<br />
For details on the CCSID values for various character sets see Data<br />
conversion when using the Client daemon, inthe<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Administration book for your operating system.<br />
UserId<br />
A string specifying the userid to be associated with the terminal<br />
resource. If the userid is shorter than <strong>CICS</strong>_EPI_USERID_MAX, it<br />
must be padded with nulls to a length of <strong>CICS</strong>_EPI_USERID_MAX+1.<br />
Password<br />
A string specifying the password to be associated with the terminal<br />
resource. If the password is shorter than <strong>CICS</strong>_EPI_PASSWORD_MAX<br />
characters, it must be padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_PASSWORD_MAX+1.<br />
<strong>CICS</strong>_EpiDetails_t:<br />
EPI constants and data structures<br />
Purpose: The <strong>CICS</strong>_EpiDetails_t structure holds information about a terminal<br />
resource installed by the <strong>CICS</strong>_EpiAddTerminal or the<br />
<strong>CICS</strong>_EpiAddExTerminal function.<br />
Fields:<br />
NetName<br />
A string specifying the VTAM ® -style netname of the terminal<br />
resource. If the name is shorter than <strong>CICS</strong>_EPI_NETNAME_MAX<br />
characters, it is padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_NETNAME_MAX + 1.<br />
Chapter 4. C and COBOL 133
EPI constants and data structures<br />
NumLines<br />
The number of rows supported by the terminal resource.<br />
NumColumns<br />
The number of columns supported by the terminal resource.<br />
MaxData<br />
The maximum size of data that can be sent to this terminal resource<br />
from a <strong>CICS</strong> transaction, and the maximum size of data that can be<br />
sent from this terminal resource to a <strong>CICS</strong> transaction by a<br />
<strong>CICS</strong>_EpiStartTran call or <strong>CICS</strong>_EpiReply call.<br />
The maximum size may be defined in the model terminal definition<br />
specified by the DevType parameter on the <strong>CICS</strong>_EpiAddTerminal<br />
call that installed the terminal resource in the server. If the value<br />
either is not specified in the model terminal definition, a default value<br />
of 12000 is assumed.<br />
ErrLastLine<br />
1 if the terminal resource should display error messages on its last<br />
row, 0 otherwise.<br />
ErrIntensify<br />
1 if the terminal resource should display error messages intensified, 0<br />
otherwise.<br />
ErrColor<br />
The 3270 attribute defining the color to be used to display error<br />
messages.<br />
ErrHilight<br />
The 3270 attribute defining the highlight value to be used to display<br />
error messages.<br />
Hilight<br />
1 if the terminal resource is defined to support extended highlighting,<br />
0 otherwise.<br />
Color 1 if the terminal resource is defined to support color, 0 otherwise.<br />
System<br />
TermId<br />
A string specifying the name of the server in which the terminal<br />
resource has been installed. If the name is shorter than<br />
<strong>CICS</strong>_EPI_SYSTEM_MAX characters, it is padded with nulls to a<br />
length of <strong>CICS</strong>_EPI_SYSTEM_MAX + 1.<br />
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
A string specifying the name of the terminal resource. If the name is<br />
shorter than <strong>CICS</strong>_EPI_TERMID_MAX characters, it is padded with<br />
nulls to a length of <strong>CICS</strong>_EPI_TERMID_MAX + 1.<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
SignonCapability<br />
The signon capability assigned by the server to the terminal resource:<br />
<strong>CICS</strong>_EPI_SIGNON_CAPABLE<br />
if the application may start server-provided signon and<br />
signoff transactions at the terminal resource.<br />
<strong>CICS</strong>_EPI_SIGNON_INCAPABLE<br />
if the application may not start server-provided signon and<br />
signoff transactions at the terminal resource.<br />
<strong>CICS</strong>_EPI_SIGNON_UNKNOWN<br />
if the <strong>CICS</strong>_EpiAddTerminal function was used to add the<br />
terminal resource. (This value is also returned if the<br />
<strong>CICS</strong>_EpiAddExTerminal function was used to add the<br />
terminal resource and prerequisite changes have not been<br />
applied to the server.)<br />
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
<strong>CICS</strong>_EpiEventData_t:<br />
EPI constants and data structures<br />
Purpose: The <strong>CICS</strong>_EpiEventData_t structure holds details of a<br />
terminal-related event. Not all fields are valid for all events, and fields that<br />
are not valid are set to nulls. This structure is an output from<br />
<strong>CICS</strong>_EpiGetEvent.<br />
Fields:<br />
TermIndex<br />
The terminal index for the terminal resource against which this event<br />
occurred.<br />
Event The event indicator; that is, one of the event codes listed in “EPI<br />
events” on page 166.<br />
EndReason<br />
The reason for termination, if the event is a<br />
<strong>CICS</strong>_EPI_EVENT_END_TERM or <strong>CICS</strong>_EPI_EVENT_END_TRAN<br />
event.<br />
TransId<br />
A string specifying a transaction name. If the name is shorter than<br />
<strong>CICS</strong>_EPI_TRANSID_MAX characters, it is padded with spaces to this<br />
length, followed by a single null character.<br />
Reserved1<br />
A reserved field.<br />
Chapter 4. C and COBOL 135
EPI constants and data structures<br />
Prior to <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong> 3.1, this field was called<br />
AbendCode.<br />
Data A pointer to a buffer that is updated with any terminal data stream<br />
associated with the event.<br />
On input the Data parameter should be set to point to a<br />
<strong>CICS</strong>_EpiDetails_t structure on the first invocation of<br />
<strong>CICS</strong>_EpiGetEvent for a terminal being added asynchronously. The<br />
details structure is updated on return from <strong>CICS</strong>_EpiGetEvent.<br />
Size The maximum size of the buffer addressed by Data. On return from<br />
the <strong>CICS</strong>_EpiGetEvent call, this contains the actual length of data<br />
returned.<br />
EndReturnCode<br />
A string containing the <strong>CICS</strong>_EPI_returncode.<br />
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
MapName<br />
A string specifying the name of the map that was most recently<br />
referenced in the MAP option of a SEND MAP command processed<br />
for the terminal resource, if the event is a <strong>CICS</strong>_EPI_EVENT_SEND or<br />
a <strong>CICS</strong>_EPI_EVENT_CONVERSE event. If the terminal resource is not<br />
supported by BMS, or the server has no record of any map being sent,<br />
the value returned is spaces. If the name is shorter than<br />
<strong>CICS</strong>_EPI_MAPNAME_MAX characters, it is padded with spaces to<br />
this length, followed by a single null character.<br />
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
MapSetName<br />
A string specifying the name of the mapset that was most recently<br />
referenced in the MAPSET option of a SEND MAP command<br />
processed for the terminal resource, if the event is a<br />
<strong>CICS</strong>_EPI_EVENT_SEND or a <strong>CICS</strong>_EPI_EVENT_CONVERSE event.<br />
If the MAPSET option was not specified on the most recent request,<br />
BMS used the map name as the mapset name. In both cases, the<br />
mapset name used may have been suffixed by a terminal suffix. If the<br />
terminal resource is not supported by BMS, or the server has no<br />
record of any mapset being sent, the value returned is spaces. If the<br />
name is shorter than <strong>CICS</strong>_EPI_MAPSETNAME_MAX characters, it is<br />
padded with spaces to this length, followed by a single null character.<br />
This field is supported only for <strong>CICS</strong>_EPI_VERSION_200.<br />
Note: The Data and Size fields should be set before the call to<br />
<strong>CICS</strong>_EpiGetEvent is made.<br />
<strong>CICS</strong>_EpiSysError_t:<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Purpose: The <strong>CICS</strong>_EpiSysError_t structure holds system error information. It<br />
is an output of <strong>CICS</strong>_EpiGetSysError.<br />
This data structure is not supported for <strong>CICS</strong>_EPI_VERSION_200.<br />
All error information is written to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> log file.<br />
Fields:<br />
Cause A value, specific to the operating environment, indicating the cause of<br />
the last error.<br />
Value A value, specific to the operating environment, indicating the nature<br />
of the last error.<br />
Msg A text message, specific to the operating environment, describing the<br />
last error. If the message is shorter than <strong>CICS</strong>_EPI_ERROR_MAX, it is<br />
padded with nulls to a length of <strong>CICS</strong>_EPI_ERROR_MAX + 1.<br />
EPI functions<br />
This section describes the functions provided by the EPI that can be called<br />
from an application program:<br />
v <strong>CICS</strong>_EpiInitialize<br />
v <strong>CICS</strong>_EpiTerminate<br />
v <strong>CICS</strong>_EpiListSystems<br />
v <strong>CICS</strong>_EpiAddTerminal<br />
v <strong>CICS</strong>_EpiAddExTerminal<br />
v <strong>CICS</strong>_EpiInquireSystem<br />
v <strong>CICS</strong>_EpiDelTerminal<br />
v <strong>CICS</strong>_EpiPurgeTerminal<br />
v <strong>CICS</strong>_EpiSetSecurity<br />
v <strong>CICS</strong>_EpiStartTran<br />
v <strong>CICS</strong>_EpiReply<br />
v <strong>CICS</strong>_EpiATIState<br />
v <strong>CICS</strong>_EpiSenseCode<br />
v <strong>CICS</strong>_EpiGetEvent<br />
v <strong>CICS</strong>_EpiGetSysError.<br />
Table 1 on page 138 summarizes the functions of the interface, the parameters<br />
passed to each function, and the possible return codes from each function.<br />
The mapping of actual return code values to the symbolic names is contained<br />
in the following file for the Windows operating systems:<br />
C \include\cics_eci.h<br />
Cobol \copybook\cicsepi.cbl<br />
and in the following files for the UNIX operating systems:<br />
EPI constants and data structures<br />
Chapter 4. C and COBOL 137
EPI functions<br />
C /include/cics_eci.h<br />
Table 1. Summary of EPI functions<br />
Function name Parameters Return codes: <strong>CICS</strong>_EPI_<br />
<strong>CICS</strong>_EpiInitialize <strong>Version</strong> ERR_FAILED<br />
ERR_IS_INIT<br />
ERR_VERSION<br />
NORMAL<br />
<strong>CICS</strong>_EpiTerminate none ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_IN_CALLBACK<br />
NORMAL<br />
<strong>CICS</strong>_EpiListSystems NameSpace ERR_FAILED<br />
Systems ERR_MORE_SYSTEMS<br />
List<br />
ERR_NO_SYSTEMS<br />
ERR_NOT_INIT<br />
ERR_NULL_PARM<br />
ERR_IN_CALLBACK<br />
NORMAL<br />
<strong>CICS</strong>_EpiAddTerminal NameSpace ERR_FAILED<br />
System ERR_NOT_INIT<br />
Netname ERR_SYSTEM<br />
DevType ERR_SECURITY<br />
NotifyFn ERR_NULL_PARM<br />
Details ERR_IN_CALLBACK<br />
TermIndex ERR_SERVER_DOWN<br />
NORMAL<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
For <strong>CICS</strong>_EPI_VERSION_200<br />
only:<br />
ERR_TERMID_INVALID<br />
ERR_MODELID_INVALID<br />
ERR_NOT_3270_DEVICE<br />
ERR_ALREADY_INSTALLED<br />
ERR_SERVER_BUSY<br />
ERR_RESOURCE_SHORTAGE<br />
ERR_MAX_SESSIONS<br />
ERR_MAX_SYSTEMS
EPI functions<br />
Table 1. Summary of EPI functions (continued)<br />
Function name Parameters Return codes: <strong>CICS</strong>_EPI_<br />
<strong>CICS</strong>_EpiAddExTerminal System ERR_FAILED<br />
Netname ERR_NOT_INIT<br />
DevType ERR_SYSTEM<br />
NotifyFn ERR_SECURITY<br />
Details ERR_NULL_PARM<br />
TermIndex ERR_VERSION<br />
Attributes ERR_IN_CALLBACK<br />
ERR_SERVER_DOWN<br />
ERR_RESPONSE_TIMEOUT<br />
ERR_SIGNON_NOT_POSS<br />
ERR_PASSWORD_INVALID<br />
ERR_ADDTYPE_INVALID<br />
ERR_SIGNONCAP_INVALID<br />
ERR_USERID_INVALID<br />
ERR_TERMID_INVALID<br />
ERR_MODELID_INVALID<br />
ERR_NOT_3270_DEVICE<br />
ERR_ALREADY_INSTALLED<br />
ERR_CCSID_INVALID<br />
ERR_SERVER_BUSY<br />
ERR_RESOURCE_SHORTAGE<br />
ERR_MAX_SESSIONS<br />
ERR_MAX_SYSTEMS<br />
NORMAL<br />
<strong>CICS</strong>_EpiInquireSystem TermIndex ERR_BAD_INDEX<br />
System ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_NULL_PARM<br />
ERR_IN_CALLBACK<br />
NORMAL<br />
<strong>CICS</strong>_EpiDelTerminal TermIndex ERR_BAD_INDEX<br />
ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_TRAN_ACTIVE<br />
ERR_IN_CALLBACK<br />
NORMAL<br />
<strong>CICS</strong>_EpiPurgeTerminal TermIndex ERR_BAD_INDEX<br />
ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_IN_CALLBACK<br />
ERR_VERSION<br />
NORMAL<br />
Chapter 4. C and COBOL 139
EPI functions<br />
Table 1. Summary of EPI functions (continued)<br />
Function name Parameters Return codes: <strong>CICS</strong>_EPI_<br />
<strong>CICS</strong>_EpiSetSecurity TermIndex ERR_NOT_INIT<br />
UserId<br />
ERR_BAD_INDEX<br />
Password ERR_IN_CALLBACK<br />
ERR_SYSTEM_ERROR<br />
ERR_VERSION<br />
ERR_PASSWORD_INVALID<br />
ERR_USERID_INVALID<br />
ERR_NULL_PASSWORD<br />
ERR_NULL_USERID<br />
NORMAL<br />
<strong>CICS</strong>_EpiStartTran TermIndex ERR_ATI_ACTIVE<br />
TransId ERR_BAD_INDEX<br />
Data<br />
ERR_FAILED<br />
Size<br />
ERR_NO_DATA<br />
ERR_NOT_INIT<br />
ERR_TTI_ACTIVE<br />
ERR_IN_CALLBACK<br />
ERR_SERVER_DOWN<br />
ERR_RESOURCE_SHORTAGE<br />
(v 200 only)<br />
ERR_MAX_SESSIONS<br />
(v 200 only)<br />
NORMAL<br />
<strong>CICS</strong>_EpiReply TermIndex ERR_BAD_INDEX<br />
Data<br />
ERR_FAILED<br />
Size<br />
ERR_NO_CONVERSE<br />
ERR_NO_DATA<br />
ERR_NOT_INIT<br />
ERR_IN_CALLBACK<br />
ERR_ABENDED (v 200 only)<br />
ERR_SERVER_DOWN<br />
NORMAL<br />
<strong>CICS</strong>_EpiATIState TermIndex ERR_ATI_STATE<br />
ATIState ERR_BAD_INDEX<br />
ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_IN_CALLBACK<br />
ERR_NULL_PARAM<br />
NORMAL<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Table 1. Summary of EPI functions (continued)<br />
Function name Parameters Return codes: <strong>CICS</strong>_EPI_<br />
<strong>CICS</strong>_EpiSenseCode TermIndex ERR_BAD_INDEX<br />
SenseCode ERR_FAILED<br />
ERR_NOT_INIT<br />
ERR_SENSE_CODE<br />
ERR_IN_CALLBACK<br />
ERR_VERSION<br />
NORMAL<br />
<strong>CICS</strong>_EpiGetEvent TermIndex ERR_BAD_INDEX<br />
Wait<br />
ERR_FAILED<br />
ERR_MORE_DATA<br />
ERR_MORE_EVENTS<br />
ERR_NO_EVENT<br />
ERR_NOT_INIT<br />
ERR_WAIT<br />
ERR_NULL_PARAM<br />
ERR_IN_CALLBACK<br />
NORMAL<br />
<strong>CICS</strong>_GetSysError TermIndex ERR_NOT_INIT<br />
SysErr<br />
ERR_BAD_INDEX<br />
ERR_FAILED<br />
ERR_NULL_PARAM<br />
ERR_VERSION<br />
NORMAL<br />
Refer to the definitions of the functions to discover the types and usage of the<br />
parameters, the data structures used by the functions, and the meanings of the<br />
return codes.<br />
<strong>CICS</strong>_EpiInitialize<br />
<strong>CICS</strong>_EpiInitialize <strong>Version</strong><br />
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiInitialize function initializes the EPI. All other EPI<br />
calls from this application are invalid before this call is made.<br />
Parameters:<br />
<strong>Version</strong><br />
The version of the EPI for which this application is coded. This makes<br />
it possible for old applications to remain compatible with future<br />
versions of the EPI. The version described here is<br />
<strong>CICS</strong>_EPI_VERSION_200. See EPI versions, in<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide, for more information.<br />
Chapter 4. C and COBOL 141
EPI functions<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_IS_INIT<br />
The EPI is already initialized.<br />
<strong>CICS</strong>_EPI_ERR_VERSION<br />
The EPI cannot support the version requested.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiTerminate<br />
<strong>CICS</strong>_EpiTerminate<br />
Purpose: The <strong>CICS</strong>_EpiTerminate function ends the application’s use of the<br />
EPI, typically just before the application terminates. All other EPI calls (except<br />
for <strong>CICS</strong>_EpiInitialize) are invalid when this call has completed.<br />
The application should issue <strong>CICS</strong>_EpiDelTerminal calls before terminating,<br />
to delete any terminal resources.<br />
Parameters: None.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_TTI_ACTIVE<br />
A transaction started from the EPI is still active or a<br />
<strong>CICS</strong>_EpiGetEvent call is still outstanding.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_EpiListSystems<br />
<strong>CICS</strong>_EpiListSystems NameSpace<br />
Systems<br />
List<br />
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiListSystems function returns a list of <strong>CICS</strong> servers<br />
that are candidates to act as servers for EPI requests. There is no guarantee<br />
that a communications link exists between the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and<br />
any server in the list, or that any of the servers is available to process<br />
requests.<br />
The list is returned as an array of system information structures, one element<br />
for each <strong>CICS</strong> server. See “<strong>CICS</strong>_EpiSystem_t” on page 131 for the contents of<br />
the structure.<br />
EPI applications should call this function immediately after each<br />
<strong>CICS</strong>_EpiInitialize call made to determine which <strong>CICS</strong> servers are available.<br />
Parameters:<br />
NameSpace<br />
A pointer reserved for future use. Ensure that this is a null pointer.<br />
Systems<br />
A pointer to a number. On entry to the function, this number specifies<br />
the number of elements in the array specified in the List parameter.<br />
This value should accurately reflect the amount of storage that is<br />
available to the EPI to store the result. On return, it contains the<br />
actual number of servers found.<br />
The EPI uses this parameter for both input and output.<br />
List An array of <strong>CICS</strong>_EpiSystem_t structures that are filled in and<br />
returned by the function. The application should provide the storage<br />
for the array and must set the Systems parameter to indicate the<br />
number of elements in the array. The first name in the list is the<br />
default server. However, the way in which the default is defined is<br />
operating system dependent.<br />
The EPI uses this parameter only for output.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_MORE_SYSTEMS<br />
There was not enough space in the List array to store the details of all<br />
Chapter 4. C and COBOL 143
EPI functions<br />
the <strong>CICS</strong> servers found. The supplied array has been filled, and the<br />
Systems parameter has been updated to contain the total number of<br />
servers found, thus allowing you to reallocate an array of suitable size<br />
and try the function again.<br />
<strong>CICS</strong>_EPI_ERR_NO_SYSTEMS<br />
No <strong>CICS</strong> servers can be located. In this case, the value returned in<br />
Systems is zero.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
Systems is a null pointer.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully. The number of systems found is<br />
at least one, and does not exceed the value supplied as input in the<br />
Systems parameter.<br />
<strong>CICS</strong>_EpiAddTerminal<br />
<strong>CICS</strong>_EpiAddTerminal NameSpace<br />
System<br />
NetName<br />
DevType<br />
NotifyFn<br />
Details<br />
TermIndex<br />
Purpose: The <strong>CICS</strong>_EpiAddTerminal function installs a new terminal<br />
resource, or reserves an existing terminal resource, for the application’s use. It<br />
provides a terminal index, which should be used to identify the terminal<br />
resource on all further EPI calls. It also provides the information defined in<br />
the <strong>CICS</strong>_EpiDetails_t data structure.<br />
There is a limit on the number of terminals you can add with this operation:<br />
The maximum varies according to the resources available on the client system.<br />
Note: The <strong>CICS</strong>_EpiAddTerminal function adds terminal resources whose<br />
signon capability is dependant upon the server in which the terminal<br />
resource is installed, for example, they would be signon incapable on<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS servers.<br />
Parameters:<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
EPI functions<br />
NameSpace<br />
A pointer reserved for future use. Ensure that this is a null pointer.<br />
System<br />
A pointer to a null-terminated string that specifies the name of the<br />
server in which the terminal resource is to be installed or reserved. If<br />
the name is shorter than <strong>CICS</strong>_EPI_SYSTEM_MAX characters, it must<br />
be padded with nulls to a length of <strong>CICS</strong>_EPI_SYSTEM_MAX + 1.<br />
If the string is all nulls, the default server is selected by the EPI. To<br />
determine the name of the server chosen, use<br />
<strong>CICS</strong>_EpiInquireSystem. (Specifying a null string is allowed only if<br />
the EPI was initialized with EPI_VERSION_101, or greater.)<br />
The EPI uses this parameter only for input.<br />
NetName<br />
A pointer to a null-terminated string that specifies the name of the<br />
terminal resource to be installed or reserved, or null. The<br />
interpretation of this name is server-dependent.<br />
If a string is supplied that is shorter than<br />
<strong>CICS</strong>_EPI_NETNAME_MAX, it must be padded with nulls to a length<br />
of <strong>CICS</strong>_EPI_NETNAME_MAX + 1.<br />
The string is transmitted to the server without conversion to<br />
uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
The use of NetName is as follows:<br />
1. If a name is supplied using the NetName, and it matches the<br />
name of an existing terminal resource in the server, the server<br />
attempts to reserve that terminal resource.<br />
2. If a name is supplied, but it does not match the name of an<br />
existing terminal resource in the server, the server installs a<br />
terminal resource using the model terminal definition specified by<br />
the DevType parameter described below, and gives it the input<br />
name. (If DevType is a null pointer,<br />
<strong>CICS</strong>_EPI_ERR_TERMID_INVALID is returned for<br />
<strong>CICS</strong>_EPI_VERSION_200 or later, otherwise<br />
<strong>CICS</strong>_EPI_ERR_FAILED is returned.)<br />
Chapter 4. C and COBOL 145
EPI functions<br />
3. If NetName is a null pointer, a terminal resource is installed using<br />
the model terminal definition specified in DevType. IfDevType is<br />
a null pointer, the selected terminal type is not predictable, so you<br />
are advised to use DevType to ensure consistent results. The name<br />
of the terminal resource is returned in the NetName field of the<br />
<strong>CICS</strong>_EpiDetails_t structure.<br />
The EPI uses this parameter only for input.<br />
DevType<br />
A pointer to a null-terminated string that is used in the server to<br />
select a model terminal definition from which a terminal resource<br />
definition is generated, or a null pointer.<br />
If a string is supplied that is shorter than <strong>CICS</strong>_EPI_DEVTYPE_MAX<br />
characters, it should be padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_DEVTYPE_MAX + 1.<br />
The string is transmitted to the server without conversion to<br />
uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
The EPI uses this parameter only for input.<br />
NotifyFn<br />
A pointer to a callback routine that is called whenever an event occurs<br />
for the terminal resource, such as the arrival of an ATI request. If a<br />
callback routine is not required, this parameter should be set to null.<br />
The EPI uses this parameter only for input.<br />
Details<br />
A pointer to the <strong>CICS</strong>_EpiDetails_t structure that on return contains<br />
various details about the terminal resource that was installed or<br />
reserved.<br />
The EPI uses the fields in this structure only for output.<br />
TermIndex<br />
A pointer to a terminal index for the terminal resource just installed or<br />
reserved. The returned terminal index must be used as input to all<br />
146 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
EPI functions<br />
further EPI function calls to identify the terminal resource to which<br />
the function is directed. The terminal index supplied is the first<br />
available integer starting from 0.<br />
The EPI uses this parameter only for output.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM<br />
The specified server is not known to the client.<br />
<strong>CICS</strong>_EPI_ERR_SECURITY<br />
The server rejected the attempt for security reasons.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
TermIndex was a null pointer.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_DOWN<br />
The function failed because the server was down.<br />
<strong>CICS</strong>_EPI_ERR_TERMID_INVALID<br />
The function failed because an invalid TermId was supplied.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_MODELID_INVALID<br />
The function failed because an invalid Model terminal definition was<br />
supplied.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_NOT_3270_DEVICE<br />
The function failed because the device type supplied was not for a<br />
3270 device.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_ALREADY_INSTALLED<br />
The function failed because the terminal was already installed.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_BUSY<br />
The function failed because the server was busy.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
Chapter 4. C and COBOL 147
EPI functions<br />
<strong>CICS</strong>_EPI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough<br />
resources to complete the terminal install.<br />
<strong>CICS</strong>_EPI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy this<br />
request.<br />
<strong>CICS</strong>_EPI_ERR_MAX_SYSTEMS<br />
An attempt was made to start connections to more servers than your<br />
configuration allows.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiAddExTerminal<br />
<strong>CICS</strong>_EpiAddExTerminal System<br />
NetName<br />
DevType<br />
NotifyFn<br />
Details<br />
TermIndex<br />
Attributes<br />
Purpose: Supported only for EPI <strong>Version</strong> 2 or later.<br />
The <strong>CICS</strong>_EpiAddExTerminal function installs a new terminal resource, or<br />
reserves an existing terminal resource, for the application’s use. It provides a<br />
terminal index, which should be used to identify the terminal resource on all<br />
further EPI calls. It also provides the information defined in the<br />
<strong>CICS</strong>_EpiDetails_t data structure.<br />
Some attributes, for example the character set and encoding scheme to be<br />
used for 3270 data and the signon capability, may be determined by the<br />
application. These attributes are specified in the CCSID and<br />
SignonCapability fields in the <strong>CICS</strong>_EpiAttributes_t structure.<br />
Parameters:<br />
System<br />
A pointer to a null-terminated string that specifies the name of the<br />
server in which the terminal resource is to be installed or reserved. If<br />
the name is shorter than <strong>CICS</strong>_EPI_SYSTEM_MAX characters, it must<br />
be padded with nulls to a length of <strong>CICS</strong>_EPI_SYSTEM_MAX + 1.<br />
If the string is all nulls, the default server is selected by the EPI. To<br />
determine the name of the server chosen, use<br />
<strong>CICS</strong>_EpiInquireSystem.<br />
148 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
EPI functions<br />
The EPI uses this parameter only for input.<br />
NetName<br />
A pointer to a null-terminated string that specifies the name of the<br />
terminal resource to be installed or reserved, or null. The<br />
interpretation of this name is server-dependent.<br />
If a string is supplied that is shorter than<br />
<strong>CICS</strong>_EPI_NETNAME_MAX, it must be padded with nulls to a length<br />
of <strong>CICS</strong>_EPI_NETNAME_MAX + 1.<br />
The string is transmitted to the server without conversion to<br />
uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
The use of NetName is as follows:<br />
1. If a name is supplied using the NetName, and it matches the<br />
name of an existing terminal resource in the server, the server<br />
attempts to reserve that terminal resource.<br />
2. If a name is supplied, but does not match the name of an existing<br />
terminal resource in the server, the server installs a terminal<br />
resource using the model terminal definition specified by the<br />
DevType parameter described below, and gives it the input name.<br />
(If DevType is a null pointer, <strong>CICS</strong>_EPI_ERR_TERMID_INVALID<br />
is returned for <strong>CICS</strong>_EPI_VERSION_200 or later, otherwise<br />
<strong>CICS</strong>_EPI_ERR_FAILED is returned.)<br />
3. If NetName is a null pointer, a terminal resource is installed using<br />
the model terminal definition specified in DevType. IfDevType is<br />
a null pointer, the selected terminal type is not predictable, so you<br />
are advised to use DevType to ensure consistent results. The name<br />
of the terminal resource is returned in the NetName field of the<br />
<strong>CICS</strong>_EpiDetails_t structure.<br />
The EPI uses this parameter only for input.<br />
DevType<br />
A pointer to a null-terminated string that is used in the server to<br />
select a model terminal definition from which a terminal resource<br />
definition is generated, or a null pointer.<br />
Chapter 4. C and COBOL 149
EPI functions<br />
If a string is supplied that is shorter than <strong>CICS</strong>_EPI_DEVTYPE_MAX<br />
characters, it should be padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_DEVTYPE_MAX + 1.<br />
The string is transmitted to the server without conversion to<br />
uppercase.<br />
The characters used are translated from the client’s code page to an<br />
EBCDIC code page before transmission. If the server uses an ASCII<br />
code page, they will be retranslated. The only characters guaranteed<br />
to be invariant under these translations are the uppercase characters A<br />
to Z, and the numeric characters 0 to 9. Some EBCDIC servers<br />
(Katakana and Hebrew character set A) do not use the standard<br />
representations of the lowercase alphabetic characters; use them with<br />
care when communicating with such servers.<br />
The EPI uses this parameter only for input.<br />
NotifyFn<br />
A pointer to a callback routine that is called whenever an event occurs<br />
for the terminal resource, such as the arrival of an ATI request. If a<br />
callback routine is not required, this parameter should be set to null.<br />
The EPI uses this parameter only for input.<br />
Details<br />
A pointer to the <strong>CICS</strong>_EpiDetails_t structure that on return contains<br />
various details about the terminal resource that was installed or<br />
reserved. For asynchronous calls, the Details parameter should be set<br />
to NULL. If the pointer is not set to nulls, the details are added to the<br />
structure when the request to install the terminal resource has<br />
completed. For asynchronous calls this is done when the<br />
<strong>CICS</strong>_EPI_EVENT_ADD_TERM event occurs.<br />
The EPI uses the fields in this structure only for output.<br />
TermIndex<br />
A pointer to a terminal index for the terminal resource just installed or<br />
reserved. The returned terminal index must be used as input to all<br />
further EPI function calls to identify the terminal resource to which<br />
the function is directed. The terminal index supplied is the first<br />
available integer starting from 0.<br />
The EPI uses this parameter only for output.<br />
Attributes<br />
A pointer to the <strong>CICS</strong>_EpiAttributes_t structure that specifies<br />
attributes definable by the client application for the terminal resource<br />
that is to be installed The structure must be set to nulls before use.<br />
Default attributes are assumed if the pointer is set to null.<br />
150 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
The EPI uses this parameter only for input.<br />
EPI functions<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM<br />
The specified server is not known to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong>_EPI_ERR_SECURITY<br />
The server rejected the attempt for security reasons.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
TermIndex was a null pointer.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_RESPONSE_TIMEOUT<br />
No response was received from the server within the specified<br />
interval.<br />
<strong>CICS</strong>_EPI_ERR_SIGNON_NOT_POSS<br />
The server does not allow terminal resources to be installed as signon<br />
capable.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_DOWN<br />
The function failed because the server was down.<br />
<strong>CICS</strong>_EPI_ERR_PASSWORD_INVALID<br />
The length of the password exceeds <strong>CICS</strong>_EPI_PASSWORD_MAX.<br />
<strong>CICS</strong>_EPI_ERR_ADDTYPE_INVALID<br />
The value assigned to the EpiAddType field in the<br />
<strong>CICS</strong>_EpiAttributes_t structure is neither <strong>CICS</strong>_EPI_ADD_ASYNC<br />
nor <strong>CICS</strong>_EPI_ADD_SYNC.<br />
<strong>CICS</strong>_EPI_ERR_SIGNONCAP_INVALID<br />
The value assigned to the SignonCapability field in the<br />
<strong>CICS</strong>_EpiAttributes_t structure is neither<br />
<strong>CICS</strong>_EPI_SIGNON_CAPABLE nor <strong>CICS</strong>_EPI_SIGNON_INCAPABLE.<br />
<strong>CICS</strong>_EPI_ERR_USERID_INVALID<br />
The length of the userid exceeds <strong>CICS</strong>_EPI_USERID_MAX.<br />
<strong>CICS</strong>_EPI_ERR_TERMID_INVALID<br />
The function failed because an invalid TermId was supplied.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
Chapter 4. C and COBOL 151
EPI functions<br />
<strong>CICS</strong>_EPI_ERR_MODELID_INVALID<br />
The function failed because an invalid Model terminal definition was<br />
supplied.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_NOT_3270_DEVICE<br />
The function failed because the device type supplied was not for a<br />
3270 device.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_ALREADY_INSTALLED<br />
The function failed because the terminal was already installed.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_CCSID_INVALID<br />
The function failed because an invalid CCSID was supplied.<br />
For details on the CCSID values for various character sets, see Data<br />
conversion when using the Client daemon, inthe<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Administration book for your operating system.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_BUSY<br />
The function failed because the server was busy.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_VERSION<br />
The function is not supported for the version at which the EPI was<br />
initialized.<br />
<strong>CICS</strong>_EPI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough<br />
resources to complete the terminal install.<br />
<strong>CICS</strong>_EPI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy this<br />
request.<br />
<strong>CICS</strong>_EPI_ERR_MAX_SYSTEMS<br />
An attempt was made to start connections to more servers than your<br />
configuration allows.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiInquireSystem<br />
<strong>CICS</strong>_EpiInquireSystem TermIndex<br />
System<br />
152 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Purpose: The <strong>CICS</strong>_EpiInquireSystem function returns the name of the<br />
server on which a given terminal resource (identified by its terminal index) is<br />
installed.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource whose location is to be<br />
determined.<br />
The EPI uses this parameter only for input.<br />
System<br />
A pointer to a string of length <strong>CICS</strong>_ECI_SYSTEM_MAX +1inwhich<br />
the name of the server will be returned.<br />
The EPI uses this parameter only for output.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
System was a null pointer.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully. The name of the server is<br />
returned in the System parameter padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_SYSTEM_MAX +1.<br />
<strong>CICS</strong>_EpiDelTerminal<br />
<strong>CICS</strong>_EpiDelTerminal TermIndex<br />
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiDelTerminal function deletes a previously added<br />
terminal resource. The application should not consider the deletion complete<br />
until it receives the corresponding <strong>CICS</strong>_EPI_EVENT_END_TERM event. The<br />
terminal index remains allocated until a <strong>CICS</strong>_EpiGetEvent call retrieves the<br />
<strong>CICS</strong>_EPI_EVENT_END_TERM event. A call to this function fails if the<br />
Chapter 4. C and COBOL 153
EPI functions<br />
terminal resource is currently running a transaction. To ensure that a terminal<br />
resource is deleted, the application must wait until the current transaction<br />
finishes and process all outstanding events before issuing the<br />
<strong>CICS</strong>_EpiDelTerminal call.<br />
If the terminal resource was autoinstalled, its definition is deleted from the<br />
server. When a <strong>CICS</strong>_EpiDelTerminal call has completed successfully for a<br />
terminal resource, use of the terminal index is restricted to <strong>CICS</strong>_EpiGetEvent<br />
and <strong>CICS</strong>_EpiGetSysError calls until the application has received the<br />
corresponding <strong>CICS</strong>_EPI_EVENT_END_TERM event.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource to be deleted.<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_TRAN_ACTIVE<br />
A transaction is currently running against the terminal resource, or<br />
there are unprocessed events for the terminal resource.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiPurgeTerminal<br />
<strong>CICS</strong>_EpiPurgeTerminal TermIndex<br />
Purpose: Supported only for EPI <strong>Version</strong> 2 or later.<br />
The <strong>CICS</strong>_EpiPurgeTerminal function purges a previously added terminal<br />
resource. The application should not consider the deletion complete until it<br />
receives the corresponding <strong>CICS</strong>_EPI_EVENT_END_TERM event.<br />
154 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
The <strong>CICS</strong>_EpiPurgeTerminal call differs from the <strong>CICS</strong>_EpiDelTerminal call<br />
in that the application does not have to wait until the current transaction<br />
finishes or process all outstanding events before issuing the call.<br />
If the terminal resource was autoinstalled, its definition is deleted from the<br />
server.<br />
This purge function does not cancel ATI requests queued against the terminal.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource to be deleted.<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_VERSION<br />
The function is not supported for the version at which the EPI was<br />
initialized.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiSetSecurity<br />
<strong>CICS</strong>_EpiSetSecurity TermIndex<br />
UserId<br />
Password<br />
Purpose:<br />
Supported only for EPI <strong>Version</strong> 2 or later.<br />
EPI functions<br />
The <strong>CICS</strong>_EpiSetSecurity function allows a client application to specify a<br />
userid and password to be associated with a terminal resource previously<br />
installed as signon incapable.<br />
Chapter 4. C and COBOL 155
EPI functions<br />
The <strong>CICS</strong>_EpiSetSecurity function may be invoked at any time; the userid<br />
and password will be used as further transactions are started for the terminal<br />
resource. A <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> determined userid and password will<br />
be used if the function either has not been invoked for the terminal resource<br />
or has been invoked and has set the userid, and by implication the password,<br />
to nulls.<br />
Note that the client application is responsible for verifying the userid and<br />
password.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal.<br />
The EPI uses this parameter only for input.<br />
UserId<br />
A pointer to a null-terminated string that specifies the userid. If the<br />
userid is shorter than <strong>CICS</strong>_EPI_USERID_MAX characters, it must be<br />
padded with nulls to a length of <strong>CICS</strong>_EPI_USERID_MAX+1.<br />
The EPI uses this parameter only for input.<br />
Password<br />
A pointer to a null-terminated string that specifies the password. If<br />
the password is shorter than <strong>CICS</strong>_EPI_PASSWORD_MAX characters,<br />
it must be padded with nulls to a length of<br />
<strong>CICS</strong>_EPI_PASSWORD_MAX+1.<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM_ERROR<br />
An internal system error occurred.<br />
<strong>CICS</strong>_EPI_ERR_VERSION<br />
The function is not supported for the version at which the EPI was<br />
initialized.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PASSWORD<br />
Password was a null pointer.<br />
156 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_EPI_ERR_NULL_USERID<br />
Userid was a null pointer.<br />
<strong>CICS</strong>_EPI_ERR_PASSWORD_INVALID<br />
The length of the password exceeds <strong>CICS</strong>_EPI_PASSWORD_MAX.<br />
<strong>CICS</strong>_EPI_ERR_USERID_INVALID<br />
The length of the userid exceeds <strong>CICS</strong>_EPI_USERID_MAX.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiStartTran<br />
Purpose:<br />
<strong>CICS</strong>_EpiStartTran TermIndex<br />
TransId<br />
Data<br />
Size<br />
EPI functions<br />
The <strong>CICS</strong>_EpiStartTran function starts a new transaction from a terminal<br />
resource, or continues a pseudoconversation.<br />
v Starting a new transaction—do this after <strong>CICS</strong>_EpiAddTerminal, or after a<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event indicated that the previous<br />
transaction did not specify a transaction to process the next input from the<br />
terminal resource.<br />
v Continuing a pseudoconversation—do this after a<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event that indicated that the previous<br />
transaction specified did specify a transaction to process the next input<br />
from the terminal resource.<br />
If the call is successful, no further start requests can be issued for this terminal<br />
resource until the transaction ends; this is indicated by the<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource that is to run the<br />
transaction.<br />
The EPI uses this parameter only for input.<br />
TransId<br />
A pointer to a string specifying the transaction to be run, or the null<br />
pointer. If a new transaction is being started, and this input is the null<br />
pointer, the name of the transaction is extracted from the data stream<br />
Chapter 4. C and COBOL 157
EPI functions<br />
supplied in the Data parameter. If a pseudoconversation is being<br />
continued, and the pointer is not null, the string must be the name of<br />
the transaction returned in the preceding<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event for this terminal resource. If the<br />
pointer is not null, and the string is shorter than<br />
<strong>CICS</strong>_EPI_TRANSID_MAX characters, it should be padded with<br />
spaces to this length.<br />
The EPI uses this parameter only for input.<br />
Data A pointer to the 3270 data stream to be associated with the<br />
transaction. This parameter must not be a null pointer, because the<br />
data stream must contain at least an AID byte.<br />
If a new transaction is being started, and the TransId parameter is the<br />
null pointer, the data stream must be at least 4 bytes long, must<br />
contain the name of the transaction to be started, and might contain<br />
data to be supplied to the transaction on its first EXEC <strong>CICS</strong> RECEIVE<br />
command.<br />
If a new transaction is being started, and the TransId parameter is not<br />
the null pointer, the data stream might be only one byte (an AID<br />
byte), or 3 bytes (an AID byte and a cursor address), or longer than 3<br />
bytes (an AID byte, a cursor address, and data and SBA commands).<br />
In the last case, the data is supplied to the transaction program on the<br />
first EXEC <strong>CICS</strong> RECEIVE command.<br />
If a pseudoconversation is being continued, the data stream might be<br />
only one byte (an AID byte), or 3 bytes (an AID byte and a cursor<br />
address), or longer than 3 bytes (an AID byte, a cursor address, and<br />
data and SBA commands). In the last case the data is supplied to the<br />
transaction program on the first EXEC <strong>CICS</strong> RECEIVE command.<br />
The details of the format of 3270 data streams for <strong>CICS</strong> are described<br />
in 3270 data streams for the EPI, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>:<br />
Programming Guide.<br />
The length of the 3270 data stream must not exceed the value that<br />
was returned in MaxData in <strong>CICS</strong>_EpiDetails_t when the terminal<br />
resource was installed with <strong>CICS</strong>_EpiAddTerminal.<br />
The EPI uses this parameter only for input.<br />
Size The size in bytes of the initial data to be passed to the transaction.<br />
The EPI uses this parameter only for input.<br />
Note: The application might expect a terminal resource to be free to start a<br />
transaction and yet get an unexpected return code of<br />
<strong>CICS</strong>_EPI_ERR_ATI_ACTIVE from a call to <strong>CICS</strong>_EpiStartTran. If this<br />
happens, it means that the EPI has started an ATI request against the<br />
158 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
terminal resource and issued the corresponding<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI event, but the application has not yet<br />
retrieved the event by issuing a <strong>CICS</strong>_EpiGetEvent call.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_ATI_ACTIVE<br />
An ATI transaction is active for this terminal resource.<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NO_DATA<br />
No initial data was supplied.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_TTI_ACTIVE<br />
A transaction started from the EPI is already active for this terminal<br />
resource.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_DOWN<br />
The function failed because the server was down.<br />
<strong>CICS</strong>_EPI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> server or <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough<br />
resources to complete the terminal install.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_ERR_MAX_SESSIONS<br />
There were not enough communication resources to satisfy this<br />
request.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiReply<br />
<strong>CICS</strong>_EpiReply TermIndex<br />
Data<br />
Size<br />
EPI functions<br />
Chapter 4. C and COBOL 159
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiReply function sends data from a terminal resource<br />
to a <strong>CICS</strong> transaction. It should only be issued in response to a<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE event.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource from which the data is<br />
being sent.<br />
The EPI uses this parameter only for input.<br />
Data A pointer to the 3270 data stream to be sent to the transaction. This<br />
parameter must not be a null pointer, because the data stream must<br />
contain at least an AID byte. The data stream might be one byte (an<br />
AID byte), 3 bytes (an AID byte and a cursor address), or more than 3<br />
bytes (an AID byte, a cursor address, and data and SBA commands).<br />
In the last case, what follows the cursor address is supplied to the<br />
transaction program on the first EXEC <strong>CICS</strong> RECEIVE command.<br />
The length of the 3270 data stream must not exceed the value that<br />
was returned in MaxData in <strong>CICS</strong>_EpiDetails_t when the terminal<br />
resource was installed with <strong>CICS</strong>_EpiAddTerminal.<br />
The EPI uses this parameter only for input.<br />
Size The size of the data in bytes.<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NO_CONVERSE<br />
No reply is expected by the terminal resource.<br />
<strong>CICS</strong>_EPI_ERR_NO_DATA<br />
No reply data was supplied.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_ERR_SERVER_DOWN<br />
The function failed because the server was down.<br />
160 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_EPI_ERR_ABENDED<br />
The read timeout period has expired and the conversation has<br />
abended, but the <strong>CICS</strong>_EPI_EVENT_END_TRAN event has not yet<br />
been received by the application.<br />
This is supported for <strong>CICS</strong>_EPI_VERSION_200 only.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiATIState<br />
<strong>CICS</strong>_EpiATIState TermIndex<br />
ATIState<br />
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiATIState function allows the calling application to<br />
query and alter the way in which ATI requests for a terminal resource are<br />
handled. If ATI requests are enabled (<strong>CICS</strong>_EPI_ATI_ON) and an ATI request<br />
is issued in the server, the request is started when the terminal resource<br />
becomes free. If ATI requests are held (<strong>CICS</strong>_EPI_ATI_HOLD), any ATI<br />
requests issued are queued, and started when ATI requests are next enabled.<br />
The state for ATI requests after a <strong>CICS</strong>_EpiAddTerminal call is<br />
<strong>CICS</strong>_EPI_ATI_HOLD. The EPI application may change the state to<br />
<strong>CICS</strong>_EPI_ATI_ON when it is ready to allow ATI requests to be processed.<br />
(The server also maintains a ATI state for terminal resources, which is<br />
independent of the ATI state maintained in the EPI. Changes to the ATI state<br />
on the server do not affect the ATI status in the EPI.)<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource whose ATI state is<br />
required.<br />
The EPI uses this parameter only for input.<br />
ATIState<br />
The EPI uses this parameter for both input and output depending on<br />
the input value as follows:<br />
<strong>CICS</strong>_EPI_ATI_ON<br />
Enable ATI requests, and return the previous ATI state in this<br />
parameter.<br />
<strong>CICS</strong>_EPI_ATI_HOLD<br />
Hold ATI requests until they are next enabled, and return the<br />
previous ATI state in this parameter.<br />
Chapter 4. C and COBOL 161
EPI functions<br />
<strong>CICS</strong>_EPI_ATI_QUERY<br />
Do not change the ATI state; just return the current state in<br />
this parameter.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_ATI_STATE<br />
An invalid ATIState value was provided.<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NULL_PARAM<br />
ATIState was a null pointer.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiSenseCode<br />
<strong>CICS</strong>_EpiSenseCode TermIndex<br />
SenseCode<br />
Purpose: This function allows the calling application to inform the EPI of<br />
any errors in the 3270 data sent by a transaction.<br />
Not supported for EPI <strong>Version</strong> 2.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource for which the error is to<br />
be raised.<br />
The EPI uses this parameter only for input.<br />
SenseCode<br />
The sense code failure reason, which can be one of the following<br />
values:<br />
<strong>CICS</strong>_EPI_SENSE_OPCHECK<br />
Errors were detected in the 3270 data stream.<br />
162 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_EPI_SENSE_REJECT<br />
Invalid 3270 commands were received.<br />
The EPI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_SENSE_CODE<br />
An invalid sense code was provided.<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_VERSION<br />
The function is not supported for the version at which the EPI was<br />
initialized.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
<strong>CICS</strong>_EpiGetEvent<br />
<strong>CICS</strong>_EpiGetEvent TermIndex<br />
Wait<br />
Event<br />
EPI functions<br />
Purpose: The <strong>CICS</strong>_EpiGetEvent function obtains information about an<br />
event that has occurred for a terminal resource.<br />
Remember that this call may be attempted only from the application, not from<br />
the callback routine.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource for which to obtain an<br />
event. This can be set to the constant <strong>CICS</strong>_EPI_TERM_INDEX_NONE<br />
to indicate that the next event for any terminal resource used by this<br />
application is to be returned. The application can examine the<br />
Chapter 4. C and COBOL 163
EPI functions<br />
TermIndex field in the returned <strong>CICS</strong>_EpiEventData_t structure to<br />
determine the terminal resource against which the event was<br />
generated.<br />
The EPI uses this parameter for both input and output.<br />
Wait An indication of what should happen if no event has been generated<br />
for the terminal resource. Use one of the following values:<br />
<strong>CICS</strong>_EPI_WAIT<br />
Do not return until the next event occurs.<br />
<strong>CICS</strong>_EPI_NOWAIT<br />
Return immediately with an error code. This option is used if<br />
the application elects to poll for events.<br />
The EPI uses this parameter only for input.<br />
Event A pointer to a <strong>CICS</strong>_EpiEventData_t structure that on return contains<br />
the details of the event that occurred. The Data field in the structure<br />
should be set to point to the data buffer that is updated with any<br />
terminal data stream associated with the event. The Size field should<br />
be set to indicate the maximum size of this buffer, and is updated to<br />
contain the actual length of data returned.<br />
Return codes:<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_MORE_DATA<br />
The supplied data buffer was not large enough to contain the terminal<br />
data; the data has been truncated.<br />
<strong>CICS</strong>_EPI_ERR_MORE_EVENTS<br />
An event was successfully obtained, but there are more events<br />
outstanding against this terminal resource.<br />
<strong>CICS</strong>_EPI_ERR_NO_EVENT<br />
No events are outstanding for this terminal resource.<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has not been executed.<br />
<strong>CICS</strong>_EPI_ERR_WAIT<br />
The Wait parameter is not valid.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
Event is a null pointer.<br />
164 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK<br />
The function was called from a callback routine.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully, and there are no more events.<br />
<strong>CICS</strong>_EpiGetSysError<br />
<strong>CICS</strong>_EpiGetSysError TermIndex<br />
SysErr<br />
Purpose: The <strong>CICS</strong>_EpiGetSysError function obtains detailed information<br />
describing the last error that occurred when the <strong>CICS</strong>_EPI_ERR_FAILED<br />
return code was generated. The values returned in the Cause and Value fields<br />
in the supplied SysErr parameter can be used to further qualify the return<br />
code from any other EPI function. These values are environment-dependent.<br />
You might need to consult documentation for your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
environment, and the documentation for the appropriate <strong>CICS</strong> server.<br />
Not supported for EPI <strong>Version</strong> 2.<br />
The Msg field in the supplied SysErr parameter may return a message,<br />
specific to the operating environment, describing the error that occurred. If no<br />
message is available, this field is set to nulls.<br />
Note: This function is reserved for backward compatibility. No information is<br />
returned, and all system errors are written to the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>’s error log.<br />
Parameters:<br />
TermIndex<br />
The terminal index of the terminal resource for which to obtain the<br />
detailed error code. This parameter may be set to the constant<br />
<strong>CICS</strong>_EPI_TERM_INDEX_NONE, if further error information<br />
associated with a <strong>CICS</strong>_EpiInitialize, <strong>CICS</strong>_EpiTerminate,<br />
<strong>CICS</strong>_EpiListSystems, or<strong>CICS</strong>_EpiAddTerminal call is required.<br />
The EPI uses this parameter only for input.<br />
SysErr<br />
A pointer to a <strong>CICS</strong>_EpiSysError_t structure that, on return, contains<br />
the system error information.<br />
The EPI uses the structure only for output.<br />
Return codes:<br />
EPI functions<br />
Chapter 4. C and COBOL 165
EPI functions<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT<br />
<strong>CICS</strong>_EpiInitialize has never been called. (If a <strong>CICS</strong>_EpiInitialize call<br />
is made and fails, <strong>CICS</strong>_EpiGetSysError will still succeed.)<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX<br />
The TermIndex value is not a valid terminal index.<br />
<strong>CICS</strong>_EPI_ERR_FAILED<br />
The function failed for an unexpected reason.<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM<br />
SysErr is a null pointer.<br />
<strong>CICS</strong>_EPI_VERSION<br />
The funcion is not supported for the version at which the EPI was<br />
initialized.<br />
<strong>CICS</strong>_EPI_NORMAL<br />
The function completed successfully.<br />
EPI events<br />
EPI events occur when <strong>CICS</strong> has data to pass to the EPI application. The<br />
application can handle EPI events in a variety of ways. See Events and<br />
callbacks, in<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide. Whichever<br />
mechanism is used, the data from <strong>CICS</strong> is obtained by calling<br />
<strong>CICS</strong>_EpiGetEvent.<br />
<strong>CICS</strong>_EPI_EVENT_ADD_TERM<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_ADD_TERM event indicates that an<br />
asynchronous request to install a terminal resource has completed. If the<br />
terminal resource was installed details will have been placed in the<br />
<strong>CICS</strong>_EpiDetails_t structure, pointed to by Data.<br />
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_ADD_TERM event code.<br />
EndReturnCode<br />
The reason for termination. Refer to the <strong>CICS</strong>_EpiAddExTerminal<br />
function for details of return codes.<br />
Data A pointer to the <strong>CICS</strong>_EpiDetails_t structure that is updated with the<br />
terminal details, if the EndReturnCode is <strong>CICS</strong>_EPI_NORMAL.<br />
<strong>CICS</strong>_EPI_EVENT_SEND<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_SEND event indicates that a transaction has<br />
sent some 3270 data to a terminal resource, typically as a result of an EXEC<br />
<strong>CICS</strong> SEND command. No reply is expected, and none should be attempted.<br />
166 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_SEND event code.<br />
Data A pointer to the buffer that is updated to contain the data sent by the<br />
transaction. See 3270 data streams for the EPI, in<strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>: Programming Guide, for details of the data stream format.<br />
Size The length of the data in the Data buffer.<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_CONVERSE event indicates that a<br />
transaction is expecting a reply as a result of either an EXEC <strong>CICS</strong> RECEIVE<br />
command, or an EXEC <strong>CICS</strong> CONVERSE command.<br />
The application should issue a <strong>CICS</strong>_EpiReply call to return the data to <strong>CICS</strong>,<br />
as follows:<br />
v If the transaction has issued an EXEC <strong>CICS</strong> RECEIVE command without<br />
specifying the BUFFER option, the buffer might contain data sent from the<br />
transaction, or it might be empty. If there is data to process, deal with it<br />
before replying. Send the reply when the data to be sent is available.<br />
v If the transaction has issued an EXEC <strong>CICS</strong> RECEIVE BUFFER command,<br />
the data buffer contains the 3270 Read Buffer command and the Size field<br />
is set to 1. The reply should be sent immediately.<br />
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_CONVERSE event code.<br />
Data A pointer to the buffer that is updated to contain the data sent by the<br />
transaction, as defined above.<br />
Size The length of the data in the buffer. This may be set to zero to<br />
indicate that no data was sent, but a reply is still expected.<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN<br />
EPI events<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_END_TRAN event indicates the end of a<br />
transaction that was running against a terminal resource. If the transaction<br />
failed, the EndReason and EndReturnCode specify the cause. If the<br />
transaction completed normally, the EndReason field is set to<br />
<strong>CICS</strong>_EPI_TRAN_NO_ERROR and EndReturnCode is set to<br />
<strong>CICS</strong>_EPI_NORMAL. If the transaction was pseudoconversational, the<br />
TransId field contains the name of the next transaction required. The<br />
application should start this transaction by issuing a <strong>CICS</strong>_EpiStartTran call.<br />
Chapter 4. C and COBOL 167
EPI events<br />
The <strong>CICS</strong>_EPI_EVENT_END_TRAN event occurs when a transaction running<br />
against a terminal resource abends or ends following execution of a RETURN<br />
command for which the IMMEDIATE option was not specified.<br />
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_END_TRAN event code.<br />
EndReason<br />
An indication of what caused the end transaction event. It can be one<br />
of the following values:<br />
<strong>CICS</strong>_EPI_TRAN_NO_ERROR<br />
Normal transaction termination.<br />
<strong>CICS</strong>_EPI_TRAN_NOT_STARTED<br />
The transaction failed to start.<br />
<strong>CICS</strong>_EPI_TRAN_STATE_UNKNOWN<br />
The transaction failed to complete.<br />
<strong>CICS</strong>_EPI_READTIMEOUT_EXPIRED<br />
The read timout expired.<br />
TransId<br />
The name of the next transaction to start, if the previous transaction<br />
was pseudoconversational. This name is 4 characters long and<br />
null-terminated. If there is no next transaction, the field is set to nulls.<br />
EndReturnCode<br />
A string containing the <strong>CICS</strong>_EPI_returncode.<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_START_ATI event indicates that an ATI<br />
transaction has been started against the terminal resource. If the terminal<br />
resource receives an ATI request while it is running another transaction, the<br />
request is held until the transaction ends. The transaction is then started on<br />
behalf of the terminal resource, and the <strong>CICS</strong>_EPI_EVENT_START_ATI event<br />
is generated to inform the application.<br />
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_START_ATI event code.<br />
TransId<br />
The name of the transaction that was started. This name is 4<br />
characters long and null-terminated.<br />
168 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
External Security Interface<br />
<strong>CICS</strong>_EPI_EVENT_END_TERM<br />
Purpose: The <strong>CICS</strong>_EPI_EVENT_END_TERM event indicates that a terminal<br />
resource no longer exists. After this event, the terminal index that was<br />
previously used for the terminal resource is not valid. If the EPI detects that a<br />
<strong>CICS</strong> server has shut down, <strong>CICS</strong>_EPI_EVENT_END_TERM events are<br />
generated for all terminal resources that the application has installed in that<br />
server and not subsequently deleted.<br />
Fields completed:<br />
Event The <strong>CICS</strong>_EPI_EVENT_END_TERM event code.<br />
EndReason<br />
An indication of why the terminal resource was deleted. It can be one<br />
of the following values:<br />
<strong>CICS</strong>_EPI_END_SIGNOFF<br />
The terminal resource was signed off. This can be as a result<br />
of running the CESF transaction or of calling the<br />
<strong>CICS</strong>_EpiDelTerminal function.<br />
<strong>CICS</strong>_EPI_END_SHUTDOWN<br />
The <strong>CICS</strong> server is shutting down.<br />
<strong>CICS</strong>_EPI_END_OUTSERVICE<br />
The terminal resource has been switched out of service.<br />
<strong>CICS</strong>_EPI_END_UNKNOWN<br />
An unexpected error has occurred.<br />
<strong>CICS</strong>_EPI_END_FAILED<br />
An attempt to delete a terminal resource failed.<br />
ESI constants and data structures<br />
This section describes the constants and data structures that you need to use<br />
the ESI.<br />
ESI constants<br />
The following constants are referred to symbolically in the descriptions of the<br />
ESI data structures, and functions in this Chapter. Their values are given here<br />
to help you understand the descriptions. However, your code should always<br />
use the symbolic names of ESI constants provided for the programming<br />
language you are using.<br />
Lengths of fields<br />
v <strong>CICS</strong>_ESI_PASSWORD_MAX (10)<br />
EPI events<br />
Chapter 4. C and COBOL 169
ESI constants and data structures<br />
v <strong>CICS</strong>_ESI_SYSTEM_MAX (8)<br />
v <strong>CICS</strong>_ESI_USERID_MAX (10)<br />
ESI data structures<br />
The following data structures are available for use with the ESI.<br />
v <strong>CICS</strong>_EsiDate_t<br />
v <strong>CICS</strong>_EsiTime_t<br />
v <strong>CICS</strong>_EsiDetails_t<br />
In the descriptions of the fields in the data structures, fields described as<br />
strings are null-terminated strings.<br />
<strong>CICS</strong>_EsiDate_t:<br />
Purpose: The <strong>CICS</strong>_EsiDate_t structure contains a date represented as year,<br />
month, and day.<br />
Fields:<br />
Year 4-digit year held in cics_ushort_t format.<br />
Month<br />
Month held in cics_ushort_t format; values range from 1 to 12 with 1<br />
representing January.<br />
Day Day held in cics_ushort_t format; values range from 1 to 31 with 1<br />
representing the first day of the month.<br />
<strong>CICS</strong>_EsiTime_t:<br />
Purpose: The <strong>CICS</strong>_EsiTime structure contains a time represented as hours,<br />
minutes, seconds, and hundredths of a second.<br />
Fields:<br />
Hours Hours held in cics_ushort_t format; values range from 0 to 23.<br />
Minutes Minutes held in cics_ushort_t format; values range from 0 to<br />
59.<br />
Seconds Seconds held in cics_ushort_t format; values range from 0 to<br />
59.<br />
Hundredths Hundredths of a second held in cics_ushort_t format; values<br />
range from 0 to 99.<br />
<strong>CICS</strong>_EsiDetails_t:<br />
170 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Purpose: The <strong>CICS</strong>_EsiDetails_t structure contains information returned from<br />
a successful invocation of either the <strong>CICS</strong>_VerifyPassword or the<br />
<strong>CICS</strong>_ChangePassword functions.<br />
Fields:<br />
LastVerifiedDate<br />
The date on which the password was last verified.<br />
LastVerifiedTime<br />
The time at which the password was last verified.<br />
ExpiryDate<br />
The date on which the password will expire.<br />
ExpiryTime<br />
The time at which the password will expire.<br />
LastAccessDate<br />
The date on which the userid was last accessed.<br />
LastAccessTime<br />
The time at which the userid was last accessed.<br />
InvalidCount<br />
The number of times that an invalid password has been entered for<br />
the userid.<br />
ESI functions<br />
This section describes the functions provided by the ESI that can be called<br />
from an application program:<br />
v <strong>CICS</strong>_VerifyPassword<br />
v <strong>CICS</strong>_ChangePassword<br />
v <strong>CICS</strong>_SetDefaultSecurity<br />
<strong>CICS</strong>_VerifyPassword<br />
<strong>CICS</strong>_VerifyPassword UserId<br />
Password<br />
System<br />
Details<br />
Purpose: The <strong>CICS</strong>_VerifyPassword function allows a client application to<br />
verify that a password matches the password recorded by an external security<br />
manager for a specified userid.<br />
Note that the external security manager is assumed to be located in a server<br />
to which the client is connected.<br />
Parameters:<br />
ESI constants and data structures<br />
Chapter 4. C and COBOL 171
ESI functions<br />
UserId<br />
Password<br />
System<br />
172 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
A pointer to a null-terminated string that specifies the userid<br />
whose password is to be verified. If the userid is shorter than<br />
<strong>CICS</strong>_ESI_USERID_MAX characters, it must be padded with<br />
nulls to a length of <strong>CICS</strong>_ESI_USERID_MAX+1.<br />
The ESI uses this parameter only for input.<br />
A pointer to a null-terminated string that specifies the<br />
password to be checked by the external security manager for<br />
the specified userid. If the password is shorter than<br />
<strong>CICS</strong>_ESI_PASSWORD_MAX characters, it must be padded<br />
with nulls to a length of <strong>CICS</strong>_ESI_PASSWORD_MAX+1.<br />
The ESI uses this parameter only for input.<br />
A pointer to a null-terminated string that specifies the name of<br />
the server in which the password is to be verified. If the name<br />
is shorter than <strong>CICS</strong>_ESI_SYSTEM_MAX characters, it must be<br />
padded with nulls to a length of <strong>CICS</strong>_ESI_SYSTEM_MAX+1.<br />
If the string is all nulls, the default server is selected.<br />
The ESI uses this parameter only for input.
Details<br />
ESI functions<br />
A pointer to the <strong>CICS</strong>_EsiDetails_t structure that on return<br />
contains further information returned by the external security<br />
manager.<br />
The ESI uses the fields in this structure only for output.<br />
Return codes:<br />
<strong>CICS</strong>_ESI_NO_ERROR<br />
The function completed successfully.<br />
<strong>CICS</strong>_ESI_ERR_CALL_FROM_CALLBACK<br />
The function was invoked from a callback routine.<br />
<strong>CICS</strong>_ESI_ERR_SYSTEM_ERROR<br />
An internal system error occurred.<br />
<strong>CICS</strong>_ESI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is unavailable, or the specified server<br />
is unavailable.<br />
<strong>CICS</strong>_ESI_ERR_<strong>CICS</strong>_DIED<br />
The specified server is no longer available.<br />
<strong>CICS</strong>_ESI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough resources to<br />
complete the request.<br />
<strong>CICS</strong>_ESI_ERR_NO_SESSIONS<br />
The application has as many outstanding ECI and EPI requests as the<br />
configuration will support.<br />
<strong>CICS</strong>_ESI_ERR_UNKNOWN_SERVER<br />
The requested server could not be located. Only servers returned by<br />
the <strong>CICS</strong>_EciListSystems and <strong>CICS</strong>_EpiListSystems functions are<br />
acceptable.<br />
<strong>CICS</strong>_ESI_ERR_MAX_SESSIONS<br />
There were not enough communications resources to satisfy the<br />
request. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control the number of servers you<br />
can use.<br />
<strong>CICS</strong>_ESI_ERR_MAX_SYSTEMS<br />
You tried to start requests to more servers than your configuration<br />
allows. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control the number of servers you<br />
can use.<br />
<strong>CICS</strong>_ESI_ERR_NULL_USERID<br />
The userid is set to nulls.<br />
Chapter 4. C and COBOL 173
ESI functions<br />
<strong>CICS</strong>_ESI_ERR_NULL_PASSWORD<br />
The password is set to nulls.<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT_SUPPORTED<br />
Password expiry managment is supported only for communications<br />
with the requested server over SNA and TCP62.<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT_ACTIVE<br />
The requested server does not support password expiry management.<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_EXPIRED<br />
The password has expired.<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_INVALID<br />
The password is invalid.<br />
<strong>CICS</strong>_ESI_ERR_USERID_INVALID<br />
The userid is not known to the external security manager.<br />
<strong>CICS</strong>_ESI_ERR_SECURITY_ERROR<br />
An error has been detected by the external security manager. The<br />
most likely explanation is that the userid has been revoked.<br />
The mapping of actual return code values to the symbolic names is contained<br />
in the \include\cics_esi.h file for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for Windows. and in the /include/cics_esi.h file for <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for UNIX operating systems. COBOL users can find it in<br />
the \copybook\cicsesi.cbl file.<br />
<strong>CICS</strong>_ChangePassword<br />
<strong>CICS</strong>_ChangePassword UserId<br />
OldPassword<br />
NewPassword<br />
System<br />
Details<br />
Purpose: The <strong>CICS</strong>_ChangePassword function allows a client application to<br />
change the password recorded by an external security manager for a specified<br />
userid.<br />
Note that the external security manager is assumed to be located in a server<br />
to which the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is connected.<br />
Parameters:<br />
UserId<br />
174 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
A pointer to a null-terminated string that specifies the userid<br />
whose password is to be changed. If the userid is shorter than
<strong>CICS</strong>_ESI_USERID_MAX characters, it must be padded with<br />
nulls to a length of <strong>CICS</strong>_ESI_USERID_MAX+1.<br />
The ESI uses this parameter only for input.<br />
OldPassword<br />
A pointer to a null-terminated string that specifies the current<br />
password for the specified userid. If the password is shorter<br />
than <strong>CICS</strong>_ESI_PASSWORD_MAX characters, it must be<br />
padded with nulls to a length of<br />
<strong>CICS</strong>_ESI_PASSWORD_MAX+1.<br />
The ESI uses this parameter only for input.<br />
NewPassword<br />
A pointer to a null-terminated string that specifies the new<br />
password for the specified userid. If the password is shorter<br />
than <strong>CICS</strong>_ESI_PASSWORD_MAX characters, it must be<br />
padded with nulls to a length of<br />
<strong>CICS</strong>_ESI_PASSWORD_MAX+1.<br />
The password is changed only if the currently password is<br />
correctly specified.<br />
The ESI uses this parameter only for input.<br />
System<br />
A pointer to a null-terminated string that specifies the name of<br />
the server in which the password is to be verified. If the name<br />
is shorter than <strong>CICS</strong>_ESI_SYSTEM_MAX characters, it must be<br />
padded with nulls to a length of <strong>CICS</strong>_ESI_SYSTEM_MAX+1.<br />
If the string is all nulls, the default server is selected.<br />
The ESI uses this parameter only for input.<br />
Details<br />
A pointer to the <strong>CICS</strong>_EsiDetails_t structure that on return<br />
contains further information returned by the external security<br />
manager.<br />
The ESI uses the fields in this structure only for output.<br />
Return codes:<br />
<strong>CICS</strong>_ESI_NO_ERROR<br />
The function completed successfully.<br />
<strong>CICS</strong>_ESI_ERR_CALL_FROM_CALLBACK<br />
The function was invoked from a callback routine.<br />
ESI functions<br />
Chapter 4. C and COBOL 175
ESI functions<br />
<strong>CICS</strong>_ESI_ERR_SYSTEM_ERROR<br />
An internal system error occurred.<br />
<strong>CICS</strong>_ESI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is unavailable, or the specified server<br />
is unavailable.<br />
<strong>CICS</strong>_ESI_ERR_<strong>CICS</strong>_DIED<br />
The specified server is no longer available. To confirm that the<br />
password has been changed, use the <strong>CICS</strong>_VerifyPassword function.<br />
<strong>CICS</strong>_ESI_ERR_RESOURCE_SHORTAGE<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> did not have enough resources to<br />
complete the request.<br />
<strong>CICS</strong>_ESI_ERR_NO_SESSIONS<br />
The application has as many outstanding ECI and EPI requests as the<br />
configuration will support.<br />
<strong>CICS</strong>_ESI_ERR_UNKNOWN_SERVER<br />
The requested server could not be located. Only servers returned by<br />
the <strong>CICS</strong>_EciListSystems and <strong>CICS</strong>_EpiListSystems functions are<br />
acceptable.<br />
<strong>CICS</strong>_ESI_ERR_MAX_SESSIONS<br />
There were not enough communications resources to satisfy the<br />
request. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control the number of servers you<br />
can use.<br />
<strong>CICS</strong>_ESI_ERR_MAX_SYSTEMS<br />
You tried to start requests to more servers than your configuration<br />
allows. Consult the documentation for your <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or server to see how to control the number of servers you<br />
can use.<br />
<strong>CICS</strong>_ESI_ERR_NULL_USERID<br />
The userid is set to nulls.<br />
<strong>CICS</strong>_ESI_ERR_NULL_OLD_PASSWORD<br />
The current password is set to nulls.<br />
<strong>CICS</strong>_ESI_ERR_NULL_NEW_PASSWORD<br />
The new password is set to nulls.<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT_SUPPORTED<br />
Password expiry management is supported only for communications<br />
with the requested server over SNA and TCP62.<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT_ACTIVE<br />
The requested server does not support password expiry management.<br />
176 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
<strong>CICS</strong>_ESI_ERR_PASSWORD_INVALID<br />
The password is invalid.<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_REJECTED<br />
The new password does not confirm to the standards defined for the<br />
external security manager.<br />
<strong>CICS</strong>_ESI_ERR_USERID_INVALID<br />
The userid is not known to the external security manager.<br />
<strong>CICS</strong>_ESI_ERR_SECURITY_ERROR<br />
An error has been detected by the external security manager. The<br />
most likely explanation is that the userid has been revoked.<br />
The mapping of actual return code values to the symbolic names is contained<br />
in the \include\cics_esi.h file for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for Windows and in the /include/cics_esi.h file for <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for UNIX operating systems. COBOL users can find it in<br />
the \copybook\cicsesi.cbl file.<br />
<strong>CICS</strong>_SetDefaultSecurity<br />
<strong>CICS</strong>_SetDefaultSecurity UserId<br />
Password<br />
System<br />
ESI functions<br />
Purpose: The <strong>CICS</strong>_SetDefaultSecurity function allows a client application<br />
to specify a default userid and password to be used for ECI and EPI requests<br />
passed to the server.<br />
The userid, and the password, can be set to nulls, that is, binary zeroes. In<br />
this case the default userid and password are unset, so that <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> acts as if no userid and password has been set.<br />
The userid, and the password, can also be set to spaces. However, this is valid<br />
only if Usedfltuser=yes is specified in the <strong>CICS</strong> connection definition. In this<br />
case <strong>CICS</strong> uses its default userid. Refer to the documentation for your <strong>CICS</strong><br />
server for more information on the Usedfltuser specification.<br />
The client application is responsible for verifying the userid and password.<br />
Note that the userid and password, if required, may be obtained from any one<br />
of several places. The assumption is that the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> uses<br />
the following search order:<br />
1. Either the ECI parameter block for the ECI or the terminal specific values<br />
set by the <strong>CICS</strong>_EpiSetSecurity function.<br />
2. The server specific values set by the <strong>CICS</strong>_SetDefaultSecurity function.<br />
Chapter 4. C and COBOL 177
ESI functions<br />
3. Defaults, for example the Windows userid, from the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>’s pop up window, and so on<br />
Parameters:<br />
UserId<br />
Password<br />
System<br />
A pointer to a null-terminated string that specifies the userid<br />
to be set. If the userid is shorter than<br />
<strong>CICS</strong>_ESI_USERID_MAX characters, it must be padded with<br />
nulls to a length of <strong>CICS</strong>_ESI_USERID_MAX+1.<br />
The ESI uses this parameter only for input.<br />
A pointer to a null-terminated string that specifies the<br />
password to be set for the specified userid. If the password is<br />
shorter than <strong>CICS</strong>_ESI_PASSWORD_MAX characters, it must<br />
be padded with nulls to a length of<br />
<strong>CICS</strong>_ESI_PASSWORD_MAX+1.<br />
The ESI uses this parameter only for input.<br />
A pointer to a null-terminated string that specifies the name of<br />
the server for which the password and userid are to be set. If<br />
the name is shorter than <strong>CICS</strong>_ESI_SYSTEM_MAX characters,<br />
it must be padded with nulls to a length of<br />
<strong>CICS</strong>_ESI_SYSTEM_MAX+1.<br />
If the string is all nulls, the default server is selected.<br />
The ESI uses this parameter only for input.<br />
Return codes:<br />
<strong>CICS</strong>_ESI_NO_ERROR<br />
The function completed successfully.<br />
<strong>CICS</strong>_ESI_ERR_CALL_FROM_CALLBACK<br />
The function was invoked from a callback routine.<br />
<strong>CICS</strong>_ESI_ERR_SYSTEM_ERROR<br />
An internal system error occurred.<br />
<strong>CICS</strong>_ESI_ERR_NO_<strong>CICS</strong><br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is unavailable, or the specified server<br />
is unavailable.<br />
178 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
ESI functions<br />
<strong>CICS</strong>_ESI_ERR_UNKNOWN_SERVER<br />
The requested server could not be located. Only servers returned by<br />
the <strong>CICS</strong>_EciListSystems and <strong>CICS</strong>_EpiListSystems functions are<br />
acceptable.<br />
<strong>CICS</strong>_ESI_ERR_USERID_INVALID<br />
The length of the userid exceeds <strong>CICS</strong>_ESI_USERID_MAX.<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_INVALID<br />
The length of the password exceeds <strong>CICS</strong>_ESI_PASSWORD_MAX.<br />
The mapping of actual return code values to the symbolic names is contained<br />
in the \include\cics_esi.h file for <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
for Windows and in the /include/cics_esi.h file for <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> for UNIX operating systems. COBOL users can find it in<br />
the \copybook\cicsesi.cbl file.<br />
Chapter 4. C and COBOL 179
ESI functions<br />
180 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix A. COM Global Constants<br />
Constants are provided in the type libraries for the Client daemon COM<br />
libraries. The libraries are in CCLIECI.DLL and CCLIEPI.DLL.<br />
If you are using Visual Basic, you can look at the definitions in the type<br />
libraries by using Visual Basic Object viewer or another type library viewer.<br />
If you are using VBScript, you cannot access the enumerations defined in the<br />
type library; use the numeric values provided here.<br />
The exception code constants are listed in Appendix D, “COM Error Code<br />
References” on page 191.<br />
© Copyright IBM Corp. 1989, 2002 181
182 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix B. COM EPI Specific Constants<br />
Synchronization Types<br />
CclEPI States<br />
CclSession States<br />
CclTerminal States<br />
Table 2. Synchronization types<br />
VB Enumeration Value Description<br />
cclSync 0 Synchronous call type<br />
cclDsync 1 Deferred synchronous call type<br />
Table 3. CclEPI States<br />
VB Enumeration Value Description<br />
cclEPIActive 0 EPI initialized OK<br />
cclDiscon 1 EPI Terminated<br />
cclEPIError 2 EPI failed to initialize, handle exception<br />
for more information<br />
Table 4. CclSession States<br />
VB Enumeration Value Description<br />
cclSessionIdle 0 Idle, client needs to initiate transaction<br />
cclSessionServer 1 Waiting for server<br />
ccISessionClient 2 Waiting for Client daemon to respond<br />
ccISessionDiscon 3 Disconnected<br />
ccISessionError 4 Session Error, handle exception for more<br />
information<br />
Table 5. CclTerminal States<br />
VB Enumeration Value Description<br />
cclInit 0 Terminal defined but not installed<br />
© Copyright IBM Corp. 1989, 2002 183
CclTerminal ATI States<br />
Table 5. CclTerminal States (continued)<br />
VB Enumeration Value Description<br />
cclActive 1 Terminal connected (not used)<br />
cclIdle 2 Idle, Client daemon needs to initiate<br />
transaction<br />
cclServer 3 Waiting for server<br />
cclClient 4 Waiting for client to respond<br />
cclDiscon 5 Disconnected<br />
cclError 6 Terminal error, handle exception for more<br />
information<br />
Table 6. CclTerminal ATI states<br />
VB Enumeration Value Description<br />
cclATIEnabled 0 ATIs are allowed<br />
cclATIDisabled 1 ATIs are not allowed<br />
CclTerminal EndTermReasons<br />
CclTerminal Signon Types<br />
Table 7. CclTerminal ATI states<br />
VB Enumeration Value Description<br />
cclSignoff 0 Disconnect request or user has signed off<br />
the terminal<br />
cclShutdown 1 The <strong>CICS</strong> server has been shut down<br />
cclOutOfService 2 The terminal has been switched to out of<br />
use<br />
cclUnknown 3 An unknown situation as occurred<br />
cclFailed 4 The terminal failed to disconnect<br />
cclNotDiscon 5 The terminal is not disconnected<br />
Table 8. CclTerminal Signon Types<br />
VB Enumeration Value Description<br />
cclSignonCapable 0 Terminal supports signon transaction<br />
184 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
CclScreen AID key codes<br />
Table 8. CclTerminal Signon Types (continued)<br />
VB Enumeration Value Description<br />
cclSignonIncapable 1 Terminal does not support signon<br />
transaction<br />
cclSignonUnknown 2 Terminal signon capability is unknown<br />
Table 9. CclScreen AID key codes<br />
VB Enumeration Value Description<br />
cclEnter 0 Enter key<br />
cclClear 1 Clear key<br />
cclPA1 2 Program Attention key 1<br />
cclPA2 3 Program Attention key 2<br />
cclPA3 4 Program Attention key 3<br />
cclPF1 5 Program Function key 1<br />
cclPF2 6 Program Function key 2<br />
cclPF3 7 Program Function key 3<br />
cclPF4 8 Program Function key 4<br />
cclPF5 9 Program Function key 5<br />
cclPF6 10 Program Function key 6<br />
cclPF7 11 Program Function key 7<br />
cclPF8 12 Program Function key 8<br />
cclPF9 13 Program Function key 9<br />
cclPF10 14 Program Function key 10<br />
cclPF11 15 Program Function key 11<br />
cclPF12 16 Program Function key 12<br />
cclPF13 17 Program Function key 13<br />
cclPF14 18 Program Function key 14<br />
cclPF15 19 Program Function key 15<br />
cclPF16 20 Program Function key 16<br />
cclPF17 21 Program Function key 17<br />
cclPF18 22 Program Function key 18<br />
cclPF19 23 Program Function key 19<br />
cclPF20 24 Program Function key 20<br />
Appendix B. COM EPI Specific Constants 185
Table 9. CclScreen AID key codes (continued)<br />
VB Enumeration Value Description<br />
cclPF21 25 Program Function key 21<br />
cclPF22 26 Program Function key 22<br />
cclPF23 27 Program Function key 23<br />
cclPF24 28 Program Function key 24<br />
CclField Protected State Attributes<br />
Table 10. CclField Protected state attributes<br />
VB Enumeration Value Description<br />
cclProtect 0 Protected Field (cannot be modified)<br />
cclUnprotect 1 Unprotected (input) field<br />
CclField Numeric Attributes<br />
Table 11. CclField Numeric Attributes<br />
VB Enumeration Value Description<br />
cclAlphanumeric 0 Alphanumeric input field<br />
cclNnumeric 1 Numeric input field<br />
CclField Intensity Attributes<br />
Table 12. CclField Intensity attributes<br />
VB Enumeration Value Description<br />
cclNormal 0 Normal display<br />
cclIntense 1 Intensified display<br />
cclDark 2 Non-display field<br />
CclField Modified Attributes<br />
Table 13. CclField Modified Attributes<br />
VB Enumeration Value Description<br />
cclUnmodified 0 Field has not been changed<br />
cclModified 1 Field has been changed<br />
186 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
CclField Highlight Attributes<br />
Table 14. CclField Highlight attributes<br />
VB Enumeration Value Description<br />
cclHltDefault 0 Default field text highlighting<br />
cclHltNormal 1 Field text highlight as specified by 3270<br />
base attribute<br />
cclHltBlink 2 Blinking text<br />
cclHltReverse 3 Reverse video text<br />
cclHltUnderscore 4 Underscored text<br />
cclHltIntense 5 High intensity text<br />
CclField Transparency Attributes<br />
CclField Color Attributes<br />
Table 15. CclField Transparency attributes<br />
VB Enumeration Value Description<br />
cclTrnDefault 0 Default (opaque) field background<br />
cclTrnOr 1 Transparent field background (OR)<br />
cclTrnXor 2 Transparent field background (XOR)<br />
cclTrnOpaque 3 Opaque field background<br />
Table 16. CclField Color attributes<br />
VB Enumeration Value Description<br />
cclDefaultColor 0<br />
cclBlue 1<br />
cclRed 2<br />
cclPink 3<br />
cclGreen 4<br />
cclCyan 5<br />
cclYellow 6<br />
cclNeutral 7<br />
cclBlack 8<br />
Appendix B. COM EPI Specific Constants 187
Table 16. CclField Color attributes (continued)<br />
VB Enumeration Value Description<br />
cclDarkBlue 9<br />
cclOrange 10<br />
cclPurple 11<br />
cclPaleGreen 12<br />
cclPaleCyan 13<br />
cclGray 14<br />
cclWhite 15<br />
188 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix C. ECI Constants<br />
Synchronization Types<br />
Flow status types<br />
Connection Status Codes<br />
Table 17. Synchronization types<br />
VB Enumeration Value Description<br />
cclSync 0 Synchronous call type<br />
cclDsync 1 Deferred synchronous call type<br />
Table 18. Flow status types<br />
VB Enumeration Value Description<br />
cclInactive 0 Flow is inactive<br />
cclLink 1 Flow is currently making a link call<br />
cclBackout 2 Flow is currently backing out a UOW<br />
cclCommit 3 Flow is currently committing a UOW<br />
cclStatus 4 Flow is requesting status<br />
cclChanged 5 Flow is requesting a status change<br />
cclCancel 6 Flow is requesting a status cancel<br />
Table 19. Connection status code<br />
VB Enumeration Value Description<br />
cclUnknown 0 The <strong>CICS</strong> server status is unknown<br />
cclAvailable 1 The <strong>CICS</strong> server status is available<br />
cclUnavailable 2 The <strong>CICS</strong> server status is unavailable<br />
© Copyright IBM Corp. 1989, 2002 189
190 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix D. COM Error Code References<br />
Enumeration Value Description ECI EPI<br />
cclNoError 0 No error occurred Yes Yes<br />
cclBufferOverflow 1 Attempted to increase a CclBuf<br />
object which isn’t Extensible<br />
Yes<br />
cclMultipleInstance 2 Attempted to create more than one<br />
ECI object<br />
Yes<br />
cclActiveFlow 3 Current Flow is still active, you<br />
cannot use this flow until it is<br />
inactive<br />
Yes<br />
cclActiveUOW 4 Current UOW is still active, you<br />
need to backout or commit.<br />
cclSyncType 5 Incorrect synchronisation type for<br />
method call.<br />
cclDataLength 9 CommArea > 32768 Bytes or<br />
inbound 3270 data stream too large<br />
for Terminal Buffer size.<br />
cclNo<strong>CICS</strong> 10 The Client daemon is unavailable,<br />
or the server implementation is<br />
unavailable, or a logical unit of<br />
work was to be begun, but the<br />
<strong>CICS</strong> server specified is not<br />
available. No resources have been<br />
updated<br />
ccl<strong>CICS</strong>Died 11 A logical unit of work was to be<br />
begun or continued, but the <strong>CICS</strong><br />
server was no longer available. If<br />
this is a link call with an active<br />
UOW, the changes are backed out.<br />
If This was a UOW Commit or the<br />
application cannot determine<br />
whether the changes have been<br />
committed or backed out, and<br />
must log this condition to aid<br />
future manual recovery<br />
Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
cclNoReply 12 There was no outstanding reply Yes<br />
ccl<strong>Transaction</strong> 13 ECI Program Abended Yes<br />
cclSystemError 14 Unknown internal error occurred Yes Yes<br />
© Copyright IBM Corp. 1989, 2002 191<br />
Yes
Enumeration Value Description ECI EPI<br />
cclResource 15 The server implementation or the<br />
Client daemon did not have<br />
enough resources to complete the<br />
request e.g. insufficient SNA<br />
sessions.<br />
Yes Yes<br />
cclMaxUOWs 16 A new logical unit of work was<br />
being created, but the application<br />
already has as many outstanding<br />
logical units of work as the<br />
configuration will support.<br />
cclUnknownServer 17 The requested server could not be<br />
located<br />
cclSecurity 18 You did not supply a valid<br />
combination of user ID and<br />
password, though the server<br />
expects it.<br />
cclMaxServers 19 You attempted to start requests to<br />
more servers than your<br />
configuration allows. You should<br />
consult the documentation for<br />
your Client daemon or server to<br />
see how to control the number of<br />
servers you can use.<br />
cclMaxRequests 20 There were not enough<br />
communication resources to satisfy<br />
the request. You should consult the<br />
documentation for your <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> Client<br />
daemon or server to see how to<br />
control communication resources<br />
cclRolledBack 21 An attempt was made to commit a<br />
logical unit of work, but the server<br />
was unable to commit the changes,<br />
and backed them out instead<br />
Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
cclParameter 22 Incorrect parameter supplied Yes Yes<br />
cclInvalidState 23 The Object is not in the correct<br />
state to invoke the method, e.g.<br />
terminal object still in server state<br />
and an attempt to send data is<br />
made.<br />
Yes Yes<br />
ccltransId 24 Null transid supplied or returned<br />
for a pseudo conversational<br />
transaction<br />
192 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Yes<br />
Yes
Enumeration Value Description ECI EPI<br />
cclInitEPI 25 No EPI object or EPI failed to<br />
initialize correctly<br />
Yes<br />
cclConnect 26 Unexpected error trying to add the<br />
terminal<br />
Yes<br />
cclDataStream 27 Unsupported Data Stream Yes<br />
cclInvalidMap 28 Map definition and Screen do not<br />
match<br />
Yes<br />
cclClass 29 Unknown internal Class error<br />
occurred.<br />
Yes Yes<br />
cclStartTranFailure 30 <strong>Transaction</strong> failed to start Yes<br />
cclTimeout 31 Timeout occurred before response<br />
from Server<br />
Yes Yes<br />
cclNoPassword 32 The object’s password is null. Yes Yes<br />
cclNoUserid 33 The object’s userid is null Yes Yes<br />
cclNullNewPassword 34 The provided password is null Yes Yes<br />
cclPemNotSupported 35 The <strong>CICS</strong> Server doesn’t support<br />
the Password Expiry Management<br />
facilities. The method cannot be<br />
used<br />
Yes Yes<br />
cclPemNotActive 36 Password Expiry Management is<br />
not active<br />
Yes Yes<br />
cclPasswordExpired 37 The password has expired. No<br />
information has been returned<br />
Yes Yes<br />
cclPasswordInvalid 38 The password is invalid. Yes Yes<br />
cclPasswordRejected 39 Change password failed because<br />
the password doesn’t conform to<br />
standards defined<br />
Yes Yes<br />
cclUseridInvalid 40 The userid is unknown Yes Yes<br />
cclInvalidTermid 41 Invalid Terminal ID Yes<br />
cclInvalidModelId 42 Invalid Model/Type Yes<br />
cclnot3270 43 Not a 3270 device Yes<br />
cclinvalidCCSId 44 Invalid CCSid Yes<br />
cclServerBusy 45 <strong>CICS</strong> server is busy Yes<br />
cclSignonNotPoss 46 The server does not allow the<br />
terminal to be installed as signon<br />
capable.<br />
Yes<br />
Appendix D. COM Error Code References 193
194 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix E. Java encodings<br />
This appendix lists the supported Java encodings. A canonical name is<br />
converted to the corresponding CCSid so that a <strong>CICS</strong> server can determine in<br />
which codepage a datastream can be located.<br />
Notes:<br />
1. Your <strong>CICS</strong> server must support EPI <strong>Version</strong> 2 for the encodings to be<br />
implemented.<br />
2. Check your <strong>CICS</strong> Server documentation to find out which CCSids your<br />
server supports.<br />
Canonical name Description CCSid<br />
Cp1252 Windows Latin-1 5348<br />
ISO8859_1 ISO 8859-1, Latin alphabet No. 1 819<br />
UTF8 Eight-bit Unicode Transformation format 1208<br />
ASCII American Standard Code for Information<br />
Interchange<br />
437<br />
Big5 Big 5, Traditional Chinese 950<br />
Cp037 USA, Canada (Bilingual, French), Netherlands,<br />
Portugal, Brazil, Australia<br />
37<br />
Cp273 IBM Austria, Germany 273<br />
Cp277 IBM Denmark, Norway 277<br />
Cp278 IBM Finland, Sweden 278<br />
Cp280 IBM Italy 280<br />
Cp284 IBM Catalan/Spain, Spanish Latin America 284<br />
Cp285 IBM United Kingdom, Ireland 285<br />
Cp297 IBM France 297<br />
Cp420 IBM Arabic 420<br />
Cp424 IBM Hebrew 424<br />
Cp437 MS-DOS United States, Australia, New Zealand,<br />
South Africa<br />
437<br />
Cp500 EBCDIC 500V1 500<br />
Cp838 IBM Thailand extended SBCS 9030<br />
Cp850 MS-DOS Latin-1 850<br />
Cp852 MS-DOS Latin-2 852<br />
© Copyright IBM Corp. 1989, 2002 195
Java encodings<br />
Canonical name Description CCSid<br />
Cp855 IBM Cyrillic 855<br />
Cp856 IBM Hebrew 856<br />
Cp857 IBM Turkish 857<br />
Cp858 Variant of Cp850 with Euro character 858<br />
Cp862 PC Hebrew 862<br />
Cp864 PC Arabic 864<br />
Cp865 MS-DOS Nordic 865<br />
Cp866 MS-DOS Russian 866<br />
Cp868 MS-DOS Pakistan 868<br />
Cp869 IBM Modern Greek 869<br />
Cp870 IBM Multilingual Latin-2 870<br />
Cp871 IBM Iceland 871<br />
Cp874 IBM Thai 9066<br />
Cp875 IBM Greek 875<br />
Cp918 IBM Pakistan (Urdu) 918<br />
Cp921 IBM Latvia, Lithuania (AIX, DOS) 921<br />
Cp922 IBM Estonia (AIX, DOS) 922<br />
Cp923 IBM Latin-9 923<br />
Cp930 Japanese Katakana-Kanji mixed with 4370 UDC,<br />
superset of 5026<br />
930<br />
Cp933 Korean Mixed with 1880 UDC, superset of 5029 933<br />
Cp935 Simplified Chinese Host mixed with 1880 UDC,<br />
superset of 5031<br />
935<br />
Cp937 Traditional Chinese Host mixed with 6204 UDC,<br />
superset of 5033<br />
937<br />
Cp939 Japanese Latin Kanji mixed with 4370 UDC, superset<br />
of 5035<br />
939<br />
Cp942 IBM OS/2 Japanese, superset of Cp932 942<br />
Cp942C Variant of Cp942 942<br />
Cp943 IBM OS/2 Japanese, superset of Cp932 and Shift-JIS 943<br />
Cp943C Variant of Cp943 943<br />
Cp948 OS/2 Chinese (Taiwan) superset of 938 948<br />
Cp949 PC Korean 949<br />
Cp949C Variant of Cp949 949<br />
196 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Java encodings<br />
Canonical name Description CCSid<br />
Cp950 PC Chinese (Hong Kong, Taiwan) 950<br />
Cp964 AIX Chinese (Taiwan) 964<br />
Cp970 AIX Korean 970<br />
Cp1006 IBM AIX Pakistan (Urdu) 1006<br />
Cp1025 IBM Multilingual Cyrillic: Bulgaria, Bosnia,<br />
Herzegovinia, Macedonia (FYR)<br />
1025<br />
Cp1026 IBM Latin-5, Turkey 1026<br />
Cp1097 IBM Iran (Farsi)/Persian 1097<br />
Cp1098 IBM Iran (Farsi)/Persian 1098<br />
Cp1112 IBM Latvia, Lithuania 1112<br />
Cp1122 IBM Estonia 1122<br />
Cp1123 IBM Ukraine 1123<br />
Cp1124 IBM AIX Ukraine 1124<br />
Cp1140 Variant of Cp037 with Euro character 1140<br />
Cp1141 Variant of Cp273 with Euro character 1141<br />
Cp1142 Variant of Cp277 with Euro character 1142<br />
Cp1143 Variant of Cp278 with Euro character 1143<br />
Cp1144 Variant of Cp280 with Euro character 1144<br />
Cp1145 Variant of Cp284 with Euro character 1145<br />
Cp1146 Variant of Cp285 with Euro character 1146<br />
Cp1147 Variant of Cp297 with Euro character 1147<br />
Cp1148 Variant of Cp500 with Euro character 1148<br />
Cp1149 Variant of Cp871 with Euro character 1149<br />
Cp1250 Windows Eastern European 5346<br />
Cp1251 Windows Cyrillic 5347<br />
Cp1253 Windows Greek 5349<br />
Cp1254 Windows Turkish 5350<br />
Cp1255 Windows Hebrew 5351<br />
Cp1256 Windows Arabic 5352<br />
Cp1257 Windows Baltic 5353<br />
Cp1258 Windows Vietnamese 5354<br />
Cp1381 IBM OS/2, DOS People’s Republic of China (PRC) 1381<br />
Cp1383 IBM AIX, People’s Republic of China (PRC) 1383<br />
Appendix E. Java encodings 197
Java encodings<br />
Canonical name Description CCSid<br />
EUC_CN GB2312, EUC encoding, Simplified Chinese 1383<br />
EUC_JP JIS X 0201, 0208, 0212, EUC encoding, Japanese 954<br />
EUC_KR KS C 5601, EUC encoding, Korean 970<br />
GBK GBK, Simplified Chinese 1386<br />
ISO8859_2 ISO 8859-2, Latin alphabet No. 2 912<br />
ISO8859_5 ISO 8859-5, Latin/Cyrillic alphabet 915<br />
ISO8859_6 ISO 8859-6, Latin/Arabic alphabet 1089<br />
ISO8859_7 ISO 8859-7, Latin/Greek alphabet 813<br />
ISO8859_8 ISO 8859-8, Latin/Hebrew alphabet 916<br />
ISO8859_9 ISO 8859-9, Latin alphabet No. 5 920<br />
ISO8859_15_FDIS ISO 8859-15, Latin alphabet No. 9 923<br />
JIS0201 JIS X 0201, Japanese 5050<br />
JIS0208 JIS X 0208, Japanese 5050<br />
JIS0212 JIS X 0212, Japanese 5050<br />
EUC_TW CNS 11643 (Plane 1-3), EUC encoding, Traditional<br />
Chinese<br />
964<br />
MS932 Windows Japanese 943<br />
MS936 Windows Simplified Chinese 1386<br />
MS949 Windows Korean 1363<br />
198 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Appendix F. C++ Exception Objects<br />
All exception objects provide the following information<br />
v Class Name<br />
v Method Name<br />
v Exception Code<br />
v Exception Text<br />
v Abend Code (ECI Only)<br />
v Origin Point<br />
The Class name can contain a trailing ’I’ for example CclFlowI which implies<br />
it is a internally contained class for the well known class, e.g. CclFlowI is<br />
contained by CclFlow. if an internal class is reported the method reported<br />
may be an internal method, not an external one.<br />
The Origin Point is a unique value which defines the exact point within the<br />
class library where the exception was generated. These are mainly useful for<br />
service.<br />
The more important items of information are the Exception Code, Exception<br />
Text and Abend Code (ECI only). The following is a Summary of these<br />
Exception Codes and Text and whether they are relevent to ECI or EPI or<br />
both.<br />
Table 20. Exception codes<br />
Enumeration Text Description ECI EPI<br />
Ccl::noError no error No error occurred Yes Yes<br />
Ccl::bufferOverflow buffer overflow Attempted to increase<br />
a CclBuf object which<br />
isn’t Extensible<br />
Yes<br />
Ccl::multipleInstance multiple instance Attempted to create<br />
more than one ECI<br />
object<br />
Ccl::activeFlow flow is active Current Flow is still<br />
active, you cannot use<br />
this flow until it is<br />
inactive<br />
Ccl::activeUOW UOW is active Current UOW is still<br />
active, you need to<br />
backout or commit.<br />
© Copyright IBM Corp. 1989, 2002 199<br />
Yes<br />
Yes<br />
Yes
Table 20. Exception codes (continued)<br />
Enumeration Text Description ECI EPI<br />
Ccl::syncType sync error Incorrect<br />
synchronisation type<br />
for method call.<br />
Yes Yes<br />
Ccl::threadCreate thread create error Internal thread<br />
creation error<br />
Ccl::threadWait thread wait error Internal thread wait<br />
error<br />
Ccl::threadKill thread kill error Internal thread kill<br />
error<br />
Ccl::dataLength data length invalid CommArea > 32768<br />
Bytes or inbound 3270<br />
data stream too large<br />
for Terminal Buffer<br />
size.<br />
Ccl::no<strong>CICS</strong> no <strong>CICS</strong> The <strong>Gateway</strong> is<br />
unavailable, or the<br />
server implementation<br />
is unavailable, or a<br />
logical unit of work<br />
was to be begun, but<br />
the <strong>CICS</strong> server<br />
specified is not<br />
available. No resources<br />
have been updated<br />
Ccl::<strong>CICS</strong>Died <strong>CICS</strong> died A logical unit of work<br />
was to be begun or<br />
continued, but the<br />
<strong>CICS</strong> server was no<br />
longer available. If this<br />
is a link call with an<br />
active UOW, the<br />
changes are backed<br />
out. If this was a UOW<br />
Commit or Backout,<br />
the application cannot<br />
determine whether the<br />
changes have been<br />
committed or backed<br />
out, and must log this<br />
condition to aid future<br />
manual recovery.<br />
Ccl::noReply no reply There was no<br />
outstanding reply<br />
200 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Yes Yes<br />
Yes<br />
Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes<br />
Yes
Table 20. Exception codes (continued)<br />
Enumeration Text Description ECI EPI<br />
Ccl::transaction transaction abend ECI Program Abended Yes<br />
Ccl::systemError system error Unknown internal<br />
error occurred<br />
Yes Yes<br />
Ccl::resource resource shortage The server<br />
implementation or the<br />
<strong>Gateway</strong> did not have<br />
enough resources to<br />
complete the request<br />
e.g. insufficient SNA<br />
sessions.<br />
Yes Yes<br />
Ccl::maxUOWs exceeded max UOWs A new logical unit of<br />
work was being<br />
created, but the<br />
application already has<br />
as many outstanding<br />
logical units of work<br />
as the configuration<br />
will support.<br />
Ccl::unknownServer unknown server The requested server<br />
could not be located<br />
Ccl::security security error You did not supply a<br />
valid combination of<br />
user ID and password,<br />
though the server<br />
expects it.<br />
Ccl::maxServers exceeded max servers You attempted to start<br />
requests to more<br />
servers than your<br />
configuration allows.<br />
You should consult the<br />
documentation for<br />
your <strong>Gateway</strong> or<br />
server to see how to<br />
control the number of<br />
servers you can use.<br />
Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Appendix F. C++ Exception Objects 201
Table 20. Exception codes (continued)<br />
Enumeration Text Description ECI EPI<br />
Ccl::maxRequests exceeded max requests There were not enough<br />
communication<br />
resources to satisfy the<br />
request. You should<br />
consult the<br />
documentation for<br />
your <strong>Gateway</strong> or<br />
server to see how to<br />
control communication<br />
resources<br />
Yes Yes<br />
Ccl::rolledBack rolled back An attempt was made<br />
to commit a logical<br />
unit of work, but the<br />
server was unable to<br />
commit the changes,<br />
and backed them out<br />
instead<br />
Ccl::parameter parameter error Incorrect parameter<br />
supplied<br />
Ccl::invalidState invalid object state The Object is not in<br />
the correct state to<br />
invoke the method,<br />
e.g. terminal object still<br />
in server state and an<br />
attempt to send data is<br />
made.<br />
Ccl::transId invalid transaction Null transid supplied<br />
or returned for a<br />
pseudo conversational<br />
transaction<br />
Ccl::initEPI EPI not initialised EPI has failed to<br />
initialize correctly or<br />
EPI object is missing<br />
Ccl::connect connection failed Unexpected error<br />
trying to add the<br />
terminal<br />
Ccl::dataStream 3270 datastream error Unsupported Data<br />
Stream<br />
Ccl::invalidMap map/screen mismatch Map definition and<br />
Screen do not match<br />
Ccl::cclClass <strong>CICS</strong> class error Unknown internal<br />
Class error occurred.<br />
202 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes<br />
Yes<br />
Yes<br />
Yes<br />
Yes<br />
Yes Yes
Table 20. Exception codes (continued)<br />
Enumeration Text Description ECI EPI<br />
Ccl::startTranFailure Start <strong>Transaction</strong> <strong>Transaction</strong> failed to<br />
Yes<br />
Failure<br />
start<br />
Ccl::timeout Timeout Occurred Timeout occurred<br />
before response from<br />
Server<br />
Yes Yes<br />
Ccl::noPassword Password is Null The object’s password<br />
is null.<br />
Ccl::noUserid Userid is Null The object’s userid is<br />
null<br />
Ccl::nullNewPassword A NULL new<br />
password was<br />
supplied<br />
Ccl::pemNotSupported PEM is not supported<br />
on the server<br />
Ccl::pemNotActive PEM is not active on<br />
the server<br />
The provided<br />
password is null<br />
The <strong>CICS</strong> Server<br />
doesn’t support the<br />
Password Expiry<br />
Management facilities.<br />
The method cannot be<br />
used<br />
Password Expiry<br />
Management is not<br />
active<br />
Ccl::passwordExpired Password has expired The password has<br />
expired. No<br />
information has been<br />
returned<br />
Ccl::passwordInvalid Password is invalid The password is<br />
invalid.<br />
Ccl::passwordRejected New password was<br />
rejected<br />
Change password<br />
failed because the<br />
password doesn’t<br />
conform to standards<br />
defined<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Yes Yes<br />
Ccl::useridInvalid Userid unknown at<br />
server<br />
The userid is unknown Yes Yes<br />
Ccl:invalidTermid Termid is invalid The terminal ID is<br />
invalid<br />
Yes<br />
Ccl:invalidModelid Modelid is invalid Invalid Model/Device<br />
Type<br />
Yes<br />
Ccl:not3270 Not a 3270 device Not a 3270 device Yes<br />
Appendix F. C++ Exception Objects 203
Table 20. Exception codes (continued)<br />
Enumeration Text Description ECI EPI<br />
Ccl:invalidCCSid Codepage (CCSid<br />
value) is invalid<br />
Invalid CCSid Yes<br />
Ccl:serverBusy Server is too busy <strong>CICS</strong> server is busy Yes<br />
Ccl:signonNotPossible Signon Capable The server does not<br />
Yes<br />
terminal is not possible allow the terminal to<br />
be installed as signon<br />
capable.<br />
204 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 206<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks ” on page 207 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 207 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 209 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 1989, 2002 205
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX for IBM eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere ® Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
206 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Redbooks <br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT: Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA : Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400 ® : Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 207
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
Microsoft ® Windows Family publications<br />
The following book provides introductory material about the Windows Family<br />
of operating systems:<br />
v Windows NT System Guide<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for Windows NT and Windows 2000:<br />
Communications Server for Windows: Quick Beginnings, GC31-8424<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
IBM eNetwork Personal Communications:<br />
IBM Personal Communications for Windows NT: Quick Beginnings,<br />
GC31-8679-02<br />
IBM Personal Communications: Administrator’s Reference, SC31-8840<br />
Microsoft products<br />
Microsoft SNA Server Installation Guide<br />
Microsoft SNA Server Administration Guide<br />
Microsoft SNA Server Reference<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
208 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
Other publications<br />
The product library and related literature 209
210 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
© Copyright IBM Corp. 1989, 2002 211
212 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans .<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 1989, 2002 213
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX,<br />
TXSeries for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390 ® . A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA ,<strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
214 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 215
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
216 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 217
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
218 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed. The default keyboard mapping file for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is <strong>CICS</strong>KEY.INI.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.<br />
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
Glossary 219
Glossary<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
220 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
R<br />
RACF ® . Resource Access Control Facility. An<br />
IBM licensed program that provides access<br />
control by identifying users to the system;<br />
verifying users of the system; authorizing access<br />
to protected resources; logging detected,<br />
unauthorized attempts to enter the system; and<br />
logging detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.<br />
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
Glossary 221
Glossary<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
222 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for<br />
OS/2 ® , <strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.<br />
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 223
Glossary<br />
224 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Index<br />
Special characters<br />
(parameter)<br />
in changed 57<br />
vii<br />
A<br />
abendCode<br />
in CclException class 66<br />
in CclFlow class 74<br />
in Public methods 66, 74<br />
AbendCode<br />
in Methods<br />
in Flow COM Class 23<br />
accessibility 211<br />
active<br />
in state 65<br />
in State 65<br />
activeFlow<br />
in CclConn class 56<br />
in CclFlow class 73<br />
in CclUOW class 95<br />
activeUOW<br />
in CclConn class 56<br />
in CclUOW class 95<br />
AID<br />
in CclScreen class 81<br />
in Enumerations 81<br />
alphanumeric<br />
in BaseType 72<br />
in inputType 69<br />
alterSecurity<br />
in CclConn class 56<br />
in CclTerminal class 88<br />
in Public methods 56, 88<br />
AlterSecurity<br />
in Methods<br />
in Connect COM Class 4<br />
in Terminal COM Class 36<br />
alterSecurity (parameter)<br />
in alterSecurity 56<br />
AppendString<br />
in Methods<br />
in Buffer COM Class 2<br />
appendText<br />
in CclField class 67, 68<br />
in Public methods 67, 68<br />
AppendText<br />
in Methods<br />
in Field COM Class 17<br />
array (parameter)<br />
in SetData 3<br />
assign<br />
in CclBuf class 51<br />
in Public methods 51<br />
async<br />
in CclSession constructor 84<br />
in Sync 49<br />
ATIState<br />
in CclTerminal class 94<br />
in Enumerations 94<br />
ATIState parameter<br />
<strong>CICS</strong>_EpiATIState function 161<br />
attachTran (parameter)<br />
in CclConn constructor 56<br />
in TranDetails 9<br />
attribute (parameter)<br />
in setBaseAttribute 70<br />
in setExtAttribute 70<br />
Attribute (parameter)<br />
in SetBaseAttribute 21<br />
in SetExtAttribute 21<br />
Attributes parameter<br />
<strong>CICS</strong>_EpiAddExTerminal function 150<br />
available<br />
in ServerStatus 60<br />
B<br />
backgroundColor<br />
in CclField class 68<br />
in Public methods 68<br />
BackgroundColor<br />
in Methods<br />
in Field COM Class 18<br />
backout<br />
in CallType 77<br />
in CclUOW class 95<br />
in Public methods 95<br />
Backout<br />
in Poll 24<br />
BackOut<br />
in Methods<br />
in UOW COM Class 45<br />
baseAttribute<br />
in CclField class 68<br />
in Public methods 68<br />
BaseAttribute<br />
in Methods<br />
in Field COM Class 18<br />
© Copyright IBM Corp. 1989, 2002 225
BaseInts<br />
in CclField class 71<br />
in Enumerations 71<br />
BaseMDT<br />
in CclField class 72<br />
in Enumerations 72<br />
BaseProt<br />
in CclField class 72<br />
in Enumerations 72<br />
BaseType<br />
in CclField class 72<br />
in Enumerations 72<br />
black<br />
in Color 72<br />
blinkHlt<br />
in Highlight 72<br />
blue<br />
in Color 72<br />
books 205<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 205<br />
Bool<br />
in Ccl class 49<br />
in Enumerations 49<br />
Buffer<br />
in AppendString 2<br />
in Buffer COM Class 1<br />
in Link 7<br />
in Poll 24<br />
in String 4<br />
buffer (parameter)<br />
in CclBuf 51<br />
in operator!= 54<br />
in operator+= 53<br />
in operator= 53<br />
in operator== 54<br />
Buffer COM class<br />
Methods<br />
AppendString 2<br />
Data 2<br />
ExtractString 2<br />
InsertString 2<br />
Length 3<br />
Overlay 3<br />
SetData 3<br />
SetLength 3<br />
SetString 3<br />
String 4<br />
C<br />
callback routine<br />
ECI 107, 111, 116, 120<br />
EPI 146, 150<br />
callType<br />
in CclFlow class 74<br />
in Public methods 74<br />
226 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
CallType<br />
in CclFlow class 76<br />
in Enumerations 76<br />
in Methods<br />
in Flow COM Class 23<br />
callTypeText<br />
in CclFlow class 74<br />
in Public methods 74<br />
CallTypeText<br />
in Methods<br />
in Flow COM Class 23<br />
cancel<br />
in CallType 77<br />
in CclConn class 57<br />
in Public methods 57<br />
Cancel<br />
in Methods<br />
in Connect COM Class 5<br />
in Poll 24<br />
Ccal Screen.fieldbyPosition method<br />
in Field COM class 17<br />
Ccl class<br />
Bool 49<br />
Sync 49<br />
Ccl.Field<br />
in FieldByName 27<br />
Ccl.Screen<br />
in Send 41<br />
cclActive<br />
in State 16, 34<br />
cclAlphanumeric<br />
in InputType 20<br />
cclATIDisabled<br />
in QueryATI 40<br />
in SetATI 42<br />
cclATIEnabled<br />
in QueryATI 40<br />
in SetATI 42<br />
cclAvailable<br />
in ServerStatus 8<br />
CclBuf<br />
in CclBuf class 50, 51<br />
in CclBuf constructors 50, 51<br />
CclBuf class<br />
assign 51<br />
CclBuf 50, 51<br />
cut 51<br />
dataArea 52<br />
dataAreaLength 52<br />
dataAreaOwner 52<br />
DataAreaOwner 55<br />
dataAreaType 52<br />
DataAreaType 55<br />
dataLength 52<br />
insert 53
CclBuf class (continued)<br />
listState 53<br />
operator!= 54<br />
operator+= 53, 54<br />
operator= 53<br />
operator== 54<br />
replace 54<br />
setDataLength 55<br />
CclBuf constructors<br />
CclBuf 50, 51<br />
in CclBuf class 50<br />
cclClient<br />
in State 35<br />
CclConn class<br />
alterSecurity 56<br />
cancel 57<br />
change password 57<br />
changed 57<br />
link 57<br />
listState 58<br />
makeSecurityDefault 58<br />
password 58, 59<br />
serverName 59<br />
serverStatus 59<br />
ServerStatus 60<br />
serverStatusText 60<br />
status 59<br />
userId 60<br />
verifyPassword 60<br />
CclConn constructor<br />
in CclConn class 56<br />
cclDark<br />
in Intensity 20<br />
cclDiscon<br />
in State 16, 35<br />
cclDSync<br />
in SetSyncType 24, 25, 34<br />
CclECI class<br />
exCode 61<br />
exCodeText 61<br />
handleException 62<br />
instance 62<br />
listState 62<br />
serverCount 62<br />
serverDesc 62<br />
serverName 63<br />
CclECI constructor (protected)<br />
in CclECI class 61<br />
CclEPI class<br />
diagnose 63<br />
exCode 63<br />
exCodeText 64<br />
handleException 64<br />
serverCount 64<br />
serverDesc 64<br />
CclEPI class (continued)<br />
serverName 65<br />
state 65<br />
State 65<br />
terminate 65<br />
CclEPI constructor<br />
in CclEPI class 63<br />
cclError<br />
in State 16, 35<br />
CclException class<br />
abendCode 66<br />
className 66<br />
diagnose 66<br />
exCode 67<br />
exCodeText 67<br />
exObject 67<br />
methodName 67<br />
CclField class<br />
appendText 67, 68<br />
backgroundColor 68<br />
baseAttribute 68<br />
BaseInts 71<br />
BaseMDT 72<br />
BaseProt 72<br />
BaseType 72<br />
Color 72<br />
column 68<br />
dataTag 68<br />
foregroundColor 69<br />
highlight 69<br />
Highlight 72<br />
inputProt 69<br />
inputType 69<br />
intensity 69<br />
length 69<br />
position 70<br />
resetDataTag 70<br />
row 70<br />
setBaseAttribute 70<br />
setExtAttribute 70<br />
setText 71<br />
text 71<br />
textLength 71<br />
transparency 71<br />
Transparency 72<br />
CclFlow<br />
in CclFlow class 73<br />
in CclFlow constructor 73<br />
CclFlow class<br />
abendCode 74<br />
callType 74<br />
CallType 76<br />
callTypeText 74<br />
CclFlow 73<br />
connection 74<br />
Index 227
CclFlow class (continued)<br />
diagnose 74<br />
flowId 74<br />
forceReset 74<br />
handleReply 75<br />
listState 75<br />
poll 75<br />
setTimeout 76<br />
syncType 76<br />
timeout 76<br />
uow 76<br />
wait 76<br />
CclFlow constructor<br />
CclFlow 73<br />
in CclFlow class 73<br />
cclIntense<br />
in Intensity 20<br />
CclMap class<br />
exCode 77<br />
exCodeText 78<br />
field 78<br />
namedField 78<br />
validate 78<br />
CclMap constructor<br />
in CclMap class 77<br />
cclModified<br />
in DataTag 18<br />
cclNoError<br />
in ExCode 15<br />
cclNormal<br />
in Intensity 20<br />
cclNumeric<br />
in InputType 20<br />
CclOSecTime<br />
in Ccl SecAttr interface 32<br />
cclProtect<br />
in InputProt 19<br />
CclScreen class<br />
AID 81<br />
cursorCol 79<br />
cursorRow 79<br />
depth 80<br />
field 80<br />
fieldCount 80<br />
mapName 80<br />
mapSetName 80<br />
setAID 81<br />
setCursor 81<br />
width 81<br />
CclSecAttr 82<br />
cclServer<br />
in State 35<br />
CclSession class<br />
diagnose 84<br />
handleReply 84<br />
228 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
CclSession class (continued)<br />
state 85<br />
State 85<br />
terminal 85<br />
transID 85<br />
CclSession constructor<br />
in CclSession class 84<br />
cclSync<br />
in SetSyncType 24, 25, 34<br />
cclSystemError<br />
in ExCode 15<br />
CclTerminal class<br />
alterSecurity 88<br />
ATIState 94<br />
CCSid 88<br />
changePassword 88<br />
diagnose 88<br />
disconnect 88, 89<br />
discReason 89<br />
EndTerminalReason 95<br />
exCode 89<br />
exCodeText 89<br />
install 90<br />
makeSecurityDefault 90<br />
netName 90<br />
password 90<br />
poll 90<br />
queryATI 91<br />
readTimeout 91<br />
receiveATI 91<br />
screen 92<br />
send 92<br />
serverName 93<br />
setATI 92<br />
signonCapability 93<br />
signonType 94<br />
state 93<br />
State 94<br />
termID 93<br />
transID 93<br />
userId 93<br />
verifyPassword 94<br />
CclTerminal constructor<br />
in CclTerminal class 86<br />
cclUnavailable<br />
in ServerStatus 8<br />
cclUnknown<br />
in ServerStatus 8<br />
cclUnknownServer<br />
in ExCode 15<br />
cclUnmodified<br />
in DataTag 18<br />
in ResetDataTag 21<br />
cclUnprotect<br />
in InputProt 19
CclUOW class<br />
backout 95<br />
commit 96<br />
forceReset 96<br />
listState 96<br />
uowId 96<br />
CclUOW constructor<br />
in CclUOW class 95<br />
CCSid<br />
in CclTerminal class 88<br />
in Public methods 88<br />
CCSId<br />
in Methods<br />
in Terminal COM class 36<br />
CCSid (parameter)<br />
in CclTerminal constructor 87<br />
in SetTermDefns 42<br />
change password<br />
in CclConn class 57<br />
in Public methods 57<br />
changed<br />
in CallType 77<br />
in CclConn class 57<br />
in Public methods 57<br />
in ServerStatus 8<br />
in ServerStatusText 8<br />
Changed<br />
in Cancel 5<br />
in Changed 5<br />
in Details 6<br />
in Methods<br />
in Connect COM Class 5<br />
in Poll 24<br />
changePassword<br />
in CclTerminal class 88<br />
in Public methods 88<br />
ChangePassword<br />
in Methods<br />
in Connect COM Class 5<br />
in Terminal COM Class 36<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> initialization file<br />
in CclTerminal constructor 86<br />
in serverCount 62, 64<br />
in serverDesc 64<br />
in serverName 65<br />
<strong>CICS</strong>_ChangePassword function<br />
definition 174<br />
<strong>CICS</strong>_ECI_DESCRIPTION_MAX 129<br />
<strong>CICS</strong>_ECI_SYSTEM_MAX 129<br />
<strong>CICS</strong>_EciListSystems function 129<br />
ECI_ERR_INVALID_DATA _LENGTH 130<br />
ECI_ERR_MORE_SYSTEMS 130<br />
ECI_ERR_NO_<strong>CICS</strong> 130<br />
ECI_ERR_NO_SYSTEMS 130<br />
ECI_ERR_SYSTEM_ERROR 130<br />
<strong>CICS</strong>_EciListSystems function (continued)<br />
ECI_NO_ERROR 130<br />
<strong>CICS</strong>_EciSystem_t data structure<br />
definition 129<br />
use 129<br />
<strong>CICS</strong>_EPI_ADD_TERM event<br />
definition 166<br />
<strong>CICS</strong>_EPI_ATI_HOLD 161<br />
<strong>CICS</strong>_EPI_ATI_ON 161<br />
<strong>CICS</strong>_EPI_ATI_QUERY 162<br />
<strong>CICS</strong>_EPI_DESCRIPTION_MAX, 131<br />
<strong>CICS</strong>_EPI_DEVTYPE_MAX 146, 150<br />
<strong>CICS</strong>_EPI_END_FAILED 169<br />
<strong>CICS</strong>_EPI_END_OUTSERVICE 169<br />
<strong>CICS</strong>_EPI_END_SHUTDOWN 169<br />
<strong>CICS</strong>_EPI_END_SIGNOFF 169<br />
<strong>CICS</strong>_EPI_END_UNKNOWN 169<br />
<strong>CICS</strong>_EPI_ERR_ABENDED return code<br />
<strong>CICS</strong>_EpiReply function 161<br />
<strong>CICS</strong>_EPI_ERR_ADDTYPE_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EPI_ERR_ALREADY_INSTALLED return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_ATI_ACTIVE return code<br />
<strong>CICS</strong>_EpiStartTran function 158, 159<br />
<strong>CICS</strong>_EPI_ERR_ATI_STATE return code<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EPI_ERR_BAD_INDEX return code<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EpiGetSysError function 166<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EPI_ERR_CCSID_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EPI_ERR_FAILED return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EpiGetSysError function 165, 166<br />
<strong>CICS</strong>_EpiInitialize function 142<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiListSystems function 143<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
Index 229
<strong>CICS</strong>_EPI_ERR_FAILED return code (continued)<br />
<strong>CICS</strong>_EpiTerminate function 142<br />
<strong>CICS</strong>_EPI_ERR_IN_CALLBACK return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 165<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiListSystems function 144<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EpiTerminate function 142<br />
<strong>CICS</strong>_EPI_ERR_IS_INIT return code<br />
<strong>CICS</strong>_EpiInitialize function 142<br />
<strong>CICS</strong>_EPI_ERR_MAX_SESSIONS return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 148<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EPI_ERR_MAX_SYSTEMS return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 148<br />
<strong>CICS</strong>_EPI_ERR_MODEL_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_MORE_DATA return code<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EPI_ERR_MORE_EVENTS return code<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EPI_ERR_MORE_SYSTEMS return code<br />
<strong>CICS</strong>_EpiListSystems function 143<br />
<strong>CICS</strong>_EPI_ERR_NO_CONVERSE return code<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EPI_ERR_NO_DATA return code<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EPI_ERR_NO_EVENT return code<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EPI_ERR_NO_SYSTEMS return code<br />
<strong>CICS</strong>_EpiListSystems function 144<br />
<strong>CICS</strong>_EPI_ERR_NOT_3270_DEVICE return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EpiGetSysError function 166<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiListSystems function 144<br />
230 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
<strong>CICS</strong>_EPI_ERR_NOT_INIT return code (continued)<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EpiTerminate function 142<br />
<strong>CICS</strong>_EPI_ERR_NULL_PARM return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EpiGetSysError function 166<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiListSystems function 144<br />
<strong>CICS</strong>_EPI_ERR_NULL_PASSWORD return code<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EPI_ERR_NULL_USERID return code<br />
<strong>CICS</strong>_EpiSetSecurity function 157<br />
<strong>CICS</strong>_EPI_ERR_PASSWORD_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiSetSecurity function 157<br />
<strong>CICS</strong>_EPI_ERR_RESOURCE _SHORTAGE return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 148<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EPI_ERR_RESPONSE_TIMEOUT return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EPI_ERR_SECURITY return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_SENSE_CODE return code<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EPI_ERR_SERVER_BUSY return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_SERVER_DOWN return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EPI_ERR_SIGNON_NOT_POSS return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EPI_ERR_SIGNONCAP_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_SYSTEM_ERROR return code<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EPI_ERR_TERMID_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiAddTerminal function 147<br />
<strong>CICS</strong>_EPI_ERR_TRAN_ACTIVE return code<br />
<strong>CICS</strong>_EpiDelTerminal function 154
<strong>CICS</strong>_EPI_ERR_TTI_ACTIVE return code<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EpiTerminate function 142<br />
<strong>CICS</strong>_EPI_ERR_USERID_INVALID return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 151<br />
<strong>CICS</strong>_EpiSetSecurity function 157<br />
<strong>CICS</strong>_EPI_ERR_VERSION return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiInitialize function 142<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EPI_ERR_WAIT return code<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
<strong>CICS</strong>_EPI_ERROR_MAX 137<br />
<strong>CICS</strong>_EPI_EVENT_CONVERSE event<br />
definition 167<br />
use 160, 167<br />
<strong>CICS</strong>_EPI_EVENT_END_TERM event<br />
definition 169<br />
use 135, 153, 154<br />
<strong>CICS</strong>_EPI_EVENT_END_TRAN event<br />
definition 167<br />
use 135, 157, 158<br />
<strong>CICS</strong>_EPI_EVENT_SEND event<br />
definition 166<br />
<strong>CICS</strong>_EPI_EVENT_START_ATI event<br />
definition 168<br />
use 159<br />
<strong>CICS</strong>_EPI_NETNAME_MAX 133, 145, 149<br />
<strong>CICS</strong>_EPI_NORMAL return code<br />
<strong>CICS</strong>_EpiAddExTerminal function 152<br />
<strong>CICS</strong>_EpiAddTerminal function 148<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 165<br />
<strong>CICS</strong>_EpiGetSysError function 166<br />
<strong>CICS</strong>_EpiInitialize function 142<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiListSystems function 144<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 161<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EpiSetSecurity function 157<br />
<strong>CICS</strong>_EpiStartTran function 159<br />
<strong>CICS</strong>_EpiTerminate function 142<br />
<strong>CICS</strong>_EPI_NOWAIT 164<br />
<strong>CICS</strong>_EPI_NULL_PARAM return code<br />
<strong>CICS</strong>_EpiATIState function 162<br />
<strong>CICS</strong>_EPI_READTIMEOUT _EXPIRED 168<br />
<strong>CICS</strong>_EPI_SENSE_OPCHECK 162<br />
<strong>CICS</strong>_EPI_SENSE_REJECT 163<br />
<strong>CICS</strong>_EPI_SYSTEM_MAX 131, 145, 148<br />
<strong>CICS</strong>_EPI_TERM_INDEX_NONE 163<br />
<strong>CICS</strong>_EPI_TRAN_NO_ERROR 168<br />
<strong>CICS</strong>_EPI_TRAN_NOT_STARTED 168<br />
<strong>CICS</strong>_EPI_TRAN_STATE _UNKNOWN 168<br />
<strong>CICS</strong>_EPI_TRANSID_MAX 135, 158<br />
<strong>CICS</strong>_EPI_VERSION return code<br />
<strong>CICS</strong>_EpiGetSysError function 166<br />
<strong>CICS</strong>_EpiSenseCode function 163<br />
<strong>CICS</strong>_EPI_VERSION_200 141<br />
<strong>CICS</strong>_EPI_WAIT 164<br />
<strong>CICS</strong>_EpiAddExTerminal function<br />
definition 148<br />
use 131, 132, 133<br />
<strong>CICS</strong>_EpiAddTerminal function<br />
definition 144<br />
use 131, 133, 157, 161, 165<br />
<strong>CICS</strong>_EpiATIState function<br />
definition 161<br />
<strong>CICS</strong>_EpiAttributes_t data structure<br />
definition 132<br />
<strong>CICS</strong>_EpiDelTerminal function<br />
definition 153<br />
use 142, 154, 169<br />
<strong>CICS</strong>_EpiDetails_t data structure<br />
definition 133<br />
use 144, 146, 148, 150<br />
<strong>CICS</strong>_EpiEventData_t data structure<br />
definition 135<br />
use 164<br />
<strong>CICS</strong>_EpiGetEvent function<br />
definition 163<br />
use 135, 136, 154, 159<br />
<strong>CICS</strong>_EpiGetSysError function<br />
definition 165<br />
use 137<br />
<strong>CICS</strong>_EpiInitialize function<br />
definition 141<br />
use 142, 143, 165<br />
<strong>CICS</strong>_EpiInquireSystem function<br />
definition 152<br />
<strong>CICS</strong>_EpiListSystems function<br />
definition 143<br />
use 131, 165<br />
<strong>CICS</strong>_EpiPurgeTerminal function<br />
ATI request cancellation 155<br />
definition 154<br />
<strong>CICS</strong>_EpiReply function<br />
definition 159<br />
use 167<br />
<strong>CICS</strong>_EpiSenseCode function<br />
definition 162<br />
<strong>CICS</strong>_EpiSetSecurity function<br />
definition 155<br />
<strong>CICS</strong>_EpiStartTran function<br />
definition 157<br />
use 158, 167<br />
<strong>CICS</strong>_EpiSysError_t data structure<br />
definition 136<br />
Index 231
<strong>CICS</strong>_EpiSysError_t data structure (continued)<br />
use 165<br />
<strong>CICS</strong>_EpiSystem_t data structure<br />
definition 131<br />
use 143<br />
<strong>CICS</strong>_EpiTerminate function<br />
definition 142<br />
use 165<br />
<strong>CICS</strong>_ESI_ERR_CALL_ FROM_CALLBACK return code<br />
<strong>CICS</strong>_ChangePassword function 175<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_<strong>CICS</strong>_DIED return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_MAX_SESSIONS return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_MAX_SYSTEMS return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_NO_<strong>CICS</strong> return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_NO_SESSIONS return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_NULL_ NEW_PASSWORD return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_ESI_ERR_NULL_ OLD_PASSWORD return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_ESI_ERR_NULL_PASSWORD return code<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_NULL_USERID return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD _REJECTED return code<br />
<strong>CICS</strong>_ChangePassword function 177<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_EXPIRED return code<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_PASSWORD_INVALID return code<br />
<strong>CICS</strong>_ChangePassword function 177<br />
<strong>CICS</strong>_SetDefaultSecurity function 179<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT _SUPPORTED return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_PEM_NOT_ACTIVE return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_RESOURCE_SHORTAGE return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
232 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
<strong>CICS</strong>_ESI_ERR_SECURITY_ERROR return code<br />
<strong>CICS</strong>_ChangePassword function 177<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_ERR_SYSTEM_ERROR return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_UNKNOWN_SERVER return code<br />
<strong>CICS</strong>_ChangePassword function 176<br />
<strong>CICS</strong>_SetDefaultSecurity function 179<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_ESI_ERR_USERID_INVALID return code<br />
<strong>CICS</strong>_ChangePassword function 177<br />
<strong>CICS</strong>_SetDefaultSecurity function 179<br />
<strong>CICS</strong>_VerifyPassword function 174<br />
<strong>CICS</strong>_ESI_NO_ERROR return code<br />
<strong>CICS</strong>_ChangePassword function 175<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
<strong>CICS</strong>_EsiDate_t data structure<br />
definition 170<br />
<strong>CICS</strong>_EsiDetails_t data structure<br />
definition 170<br />
<strong>CICS</strong>_EsiTime_t data structure<br />
definition 170<br />
<strong>CICS</strong>_ExternalCall 129<br />
<strong>CICS</strong>_SetDefaultSecurity function<br />
definition 177<br />
<strong>CICS</strong>_VerifyPassword function<br />
definition 171<br />
CicsClientStatus 128<br />
CicsServerStatus 128<br />
className<br />
in CclException class 66<br />
in Public methods 66<br />
clear<br />
in AID 81<br />
client<br />
in send 92<br />
in State 85, 94<br />
code page 102, 109, 121, 125<br />
col<br />
in validate 79<br />
col (parameter)<br />
in setCursor 81<br />
Color<br />
in CclField class 72<br />
in Enumerations 72<br />
colPos (parameter)<br />
in FieldByPosition 29<br />
in SetCursor 30<br />
column<br />
in CclField class 68<br />
in Public methods 68
Column<br />
in Methods<br />
in Field COM Class 18<br />
column (parameter)<br />
in field 78, 80<br />
commarea (parameter)<br />
in handleReply 75<br />
in link 57, 58<br />
in poll 75<br />
commArea (parameter)<br />
in AbendCode 23<br />
in Link 7<br />
in Poll 24<br />
commit<br />
in CallType 77<br />
in CclUOW class 96<br />
in Public methods 96<br />
Commit<br />
in Methods<br />
in UOW COM Class 46<br />
in Poll 24<br />
Connect<br />
in Connect COM Class 4<br />
in Methods<br />
in Terminal COM Class 36<br />
in ServerName 8<br />
in Terminal COM class 35<br />
in UOW COM Class 45<br />
in UserId 10<br />
Connect COM class<br />
Methods<br />
AlterSecurity 4<br />
Cancel 5<br />
Changed 5<br />
ChangePassword 5<br />
Details 6<br />
Link 7<br />
MakeSecurityDefault 7<br />
Password 7<br />
ServerName 8<br />
ServerStatus 8<br />
ServerStatusText 8<br />
Status 8<br />
TranDetails 9<br />
UnpaddedPassword 9<br />
UnpaddedServerName 9<br />
UnpaddedUserid 9<br />
UserId 10<br />
VerifyPassword 10<br />
connection<br />
in CclFlow class 74<br />
in Public methods 74<br />
ConnectionType 128<br />
CreateObject 1, 4, 11, 13, 23, 26, 34, 35, 45<br />
cursorCol<br />
in CclScreen class 79<br />
in Public methods 79<br />
CursorCol<br />
in Methods<br />
in Screen COM Class 28<br />
cursorRow<br />
in CclScreen class 79<br />
in Public methods 79<br />
CursorRow<br />
in Methods<br />
in Screen COM Class 28<br />
cut<br />
in CclBuf class 51<br />
in Public methods 51<br />
cyan<br />
in Color 72<br />
D<br />
dark<br />
in BaseInts 71<br />
in intensity 69<br />
darkBlue<br />
in Color 72<br />
Data<br />
in Methods<br />
in Buffer COM Class 2<br />
data conversion 102, 109, 121, 125<br />
Data parameter<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiStartTran function 158<br />
dataArea<br />
in CclBuf class 52<br />
in Public methods 52<br />
dataArea (parameter)<br />
in assign 51<br />
in CclBuf 50, 51<br />
in insert 53<br />
in replace 54<br />
dataAreaLength<br />
in CclBuf class 52<br />
in Public methods 52<br />
dataAreaOwner<br />
in CclBuf class 52<br />
in Public methods 52<br />
DataAreaOwner<br />
in CclBuf class 55<br />
in Enumerations 55<br />
dataAreaType<br />
in CclBuf class 52<br />
in Public methods 52<br />
DataAreaType<br />
in CclBuf class 55<br />
in Enumerations 55<br />
Index 233
dataLength<br />
in CclBuf class 52<br />
in link 58<br />
in Public methods 52<br />
dataStream<br />
in CclScreen class 79<br />
dataTag<br />
in CclField class 68<br />
in Public methods 68<br />
DataTag<br />
in Methods<br />
in Field COM Class 18<br />
Day<br />
in SecTime COM Class 32<br />
defaultColor<br />
in Color 72<br />
defaultHlt<br />
in Highlight 72<br />
defaultTran<br />
in Transparency 72<br />
depth<br />
in CclScreen class 80<br />
in Public methods 80<br />
in validate 79<br />
Depth<br />
in Methods<br />
in Screen COM Class 28<br />
Description<br />
<strong>CICS</strong>_EciListSystems 129<br />
Details<br />
in Connect COM class 4<br />
in Methods<br />
in Connect COM Class 6<br />
Details parameter<br />
<strong>CICS</strong>_ChangePassword function 175<br />
<strong>CICS</strong>_EpiAddExTerminal function 150<br />
<strong>CICS</strong>_EpiAddTerminal function 146<br />
<strong>CICS</strong>_VerifyPassword function 173<br />
Devtype<br />
in Methods<br />
in Terminal COM Class 37<br />
devtype (parameter)<br />
in CclTerminal constructor 86, 87<br />
devType (parameter)<br />
in Connect 36, 37<br />
in SetTermDefns 42<br />
DevType parameter<br />
<strong>CICS</strong>_EpiAddExTerminal function 149<br />
<strong>CICS</strong>_EpiAddTerminal function 146<br />
DFHCNV macro 102, 109, 121, 125<br />
diagnose<br />
in CclEPI class 63<br />
in CclException class 66<br />
in CclFlow class 74<br />
in CclSession class 84<br />
234 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
diagnose (continued)<br />
in CclTerminal class 88<br />
in Public methods 63, 66, 74, 84, 88<br />
Diagnose<br />
in EPI COM Class 13<br />
in Methods<br />
in EPI COM Class 13<br />
in Flow COM Class 23<br />
in Session COM Class 34<br />
in Terminal COM Class 37<br />
in State 16, 35<br />
disability 211<br />
disabled<br />
in ATIState 94<br />
in queryATI 91<br />
in setATI 92<br />
discon<br />
in state 65<br />
in State 65, 85, 94<br />
disconnect<br />
in CclTerminal class 88, 89<br />
in Public methods 88, 89<br />
Disconnect<br />
in Disconnect 37<br />
in Methods<br />
in Terminal COM Class 37<br />
DisconnectWithPurge<br />
in Methods<br />
in Terminal COM Class 37<br />
discReason<br />
in CclTerminal class 89<br />
in Public methods 89<br />
DiscReason<br />
in DiscReason 38<br />
in Methods<br />
in Terminal COM Class 38<br />
display (parameter)<br />
in ErrorWindow 11, 14<br />
documentation 205<br />
dsync<br />
in CclSession constructor 84<br />
in Sync 49<br />
E<br />
ECI COM class<br />
Methods<br />
ErrorFormat 11<br />
ErrorOffset 11<br />
ErrorWindow 11<br />
ExCode 11<br />
ExCodeText 12<br />
ServerCount 12<br />
ServerDesc 12<br />
ServerName 12<br />
SetErrorFormat 13
ECI parameter block 97<br />
ECI status block 128<br />
eci_abend_code<br />
field in ECI parameter block 97<br />
with ECI_SYNC call type 101<br />
ECI_ASYNC call type<br />
definition 106<br />
ECI_BACKOUT 100, 103, 107, 110<br />
eci_call_type 97<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 107<br />
with ECI_GET_REPLY call type 121<br />
with ECI_GET_REPLY_WAIT call type 124<br />
with ECI_GET_SPECIFIC_REPLY call type 125<br />
with ECI_GET_SPECIFIC_REPLY_WAIT call<br />
type 128<br />
with ECI_STATE_ASYNC call type 117<br />
with ECI_STATE_SYNC call type 113<br />
with ECI_SYNC call type 100<br />
eci_callback 107, 116<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 111<br />
with ECI_STATE_ASYNC call type 119<br />
ECI_CLIENTSTATE_INAPPLICABLE 129<br />
ECI_CLIENTSTATE_UNKNOWN 129<br />
ECI_CLIENTSTATE_UP 129<br />
eci_commarea<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 109<br />
with ECI_GET_REPLY call type 121<br />
with ECI_GET_SPECIFIC_REPLY call type 125<br />
with ECI_STATE_ASYNC call type 117<br />
with ECI_STATE_SYNC call type 113<br />
with ECI_SYNC call type 101<br />
eci_commarea_length<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 109<br />
with ECI_GET_REPLY call type 121<br />
with ECI_GET_SPECIFIC_REPLY call type 125<br />
with ECI_STATE_ASYNC call type 117<br />
with ECI_STATE_SYNC call type 114<br />
with ECI_SYNC call type 102<br />
ECI_COMMIT 100, 103, 107, 110<br />
ECI_CONNECTED_NOWHERE 128<br />
ECI_CONNECTED_TO_CLIENT 128<br />
ECI_CONNECTED_TO_SEVER 128<br />
ECI_ERR_ALREADY_ACTIVE 106, 113<br />
ECI_ERR_CALL_FROM _CALLBACK 99, 130<br />
ECI_ERR_<strong>CICS</strong>_DIED 105, 122, 126<br />
ECI_ERR_INVALID_CALL_TYPE 99<br />
ECI_ERR_INVALID_DATA _LENGTH 105, 112, 116,<br />
120, 122, 126, 130<br />
ECI_ERR_INVALID_DATA_AREA 106, 113, 116, 120,<br />
123, 127<br />
ECI_ERR_INVALID_EXTEND _MODE 105, 113, 116,<br />
120<br />
ECI_ERR_INVALID_VERSION 99<br />
ECI_ERR_LUW_TOKEN 105, 113, 116, 120<br />
ECI_ERR_MAX_SESSIONS 106, 123, 127<br />
ECI_ERR_MAX_SYSTEMS 106, 123, 127<br />
ECI_ERR_MORE_SYSTEMS 130<br />
ECI_ERR_NO_<strong>CICS</strong> 105, 113, 122, 126, 130<br />
ECI_ERR_NO_REPLY 123, 126<br />
ECI_ERR_NO_SESSIONS 106, 113<br />
ECI_ERR_NO_SYSTEMS 130<br />
ECI_ERR_REQUEST_TIMEOUT 99<br />
ECI_ERR_RESOURCE_SHORTAGE 106, 113, 123, 127<br />
ECI_ERR_RESPONSE_TIMEOUT 99<br />
ECI_ERR_ROLLEDBACK 106, 123, 127<br />
ECI_ERR_SECURITY_ERROR 106, 123, 127<br />
ECI_ERR_SYSTEM_ERROR 99, 130<br />
ECI_ERR_THREAD_CREATE _ERROR 113, 123, 127<br />
ECI_ERR_TRANSACTION _ABEND 105, 123<br />
ECI_ERR_TRANSACTION_ABEND 126<br />
ECI_ERR_UNKNOWN_SERVER 106, 116, 123, 127<br />
eci_extend_mode 100, 101, 105, 107, 109, 112, 113, 114,<br />
115, 117, 119, 121, 125<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 109<br />
with ECI_STATE_ASYNC call type 118<br />
with ECI_STATE_SYNC call type 114<br />
with ECI_SYNC call type 102<br />
ECI_EXTENDED 103, 110<br />
ECI_GET_REPLY call type<br />
definition 120<br />
ECI_GET_REPLY_WAIT call type<br />
definition 124<br />
ECI_GET_SPECIFIC_REPLY call type<br />
definition 124<br />
ECI_GET_SPECIFIC_REPLY_WAIT call type<br />
definition 127<br />
eci_luw_token<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 110<br />
with ECI_STATE_ASYNC call type 119<br />
with ECI_STATE_SYNC call type 115<br />
with ECI_SYNC call type 103<br />
eci_message_qualifier<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 107, 110<br />
with ECI_GET_SPECIFIC_REPLY call type 124, 125<br />
with ECI_STATE_ASYNC call type 117, 118<br />
ECI_NO_ERROR 105, 112, 116, 120, 122, 126, 130<br />
ECI_NO_EXTEND 102, 110<br />
eci_password 100, 104, 108, 112<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 108<br />
with ECI_SYNC call type 101<br />
eci_password2 100, 101, 108<br />
Index 235
eci_password2 (continued)<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 112<br />
with ECI_SYNC call type 104<br />
eci_program_name<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 107<br />
with ECI_SYNC call type 100<br />
ECI_SERVERSTATE_DOWN 128<br />
ECI_SERVERSTATE_UNKNOWN 128<br />
ECI_SERVERSTATE_UP 128<br />
ECI_STATE_ASYNC call type<br />
definition 116<br />
ECI_STATE_CANCEL 113, 114, 115, 117, 118, 119, 121,<br />
125<br />
ECI_STATE_CHANGED 114, 115, 118, 119<br />
ECI_STATE_IMMEDIATE 114, 118<br />
ECI_STATE_SYNC call type<br />
definition 113<br />
ECI_STATUS 128<br />
ECI_SYNC call type<br />
definition 100<br />
eci_sysid<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 111<br />
with ECI_GET_REPLY call type 121<br />
with ECI_GET_SPECIFIC_REPLY call type 125<br />
with ECI_STATE_ASYNC call type 119<br />
with ECI_STATE_SYNC call type 115<br />
with ECI_SYNC call type 103<br />
eci_system_name<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 111<br />
with ECI_STATE_ASYNC call type 119<br />
with ECI_STATE_SYNC call type 115<br />
with ECI_SYNC call type 104<br />
eci_timeout<br />
field in ECI parameter block 98<br />
with ECI_SYNC call type 102, 109<br />
eci_tpn<br />
field in ECI parameter block 99<br />
with ECI_ASYNC call type 112<br />
with ECI_SYNC call type 104<br />
eci_transid<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 108<br />
with ECI_SYNC call type 101<br />
eci_userid 101, 104, 108, 112<br />
field in ECI parameter block 97<br />
with ECI_ASYNC call type 108<br />
with ECI_SYNC call type 100<br />
eci_userid2 100, 101, 108<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 112<br />
with ECI_SYNC call type 104<br />
236 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
eci_version<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 111<br />
with ECI_GET_REPLY call type 122<br />
with ECI_GET_SPECIFIC_REPLY call type 125<br />
with ECI_STATE_ASYNC call type 119<br />
with ECI_STATE_SYNC call type 115<br />
with ECI_SYNC call type 104<br />
ECI_VERSION_1 98, 104, 111, 115, 119, 122, 125<br />
ECI_VERSION_1A 98, 104, 111, 112, 115, 119, 122, 125<br />
enabled<br />
in ATIState 94<br />
in queryATI 91<br />
in setATI 92<br />
EndTerminalReason<br />
in CclTerminal class 95<br />
in Enumerations 95<br />
enter<br />
in AID 81<br />
Enumerations<br />
AID 81<br />
ATIState 94<br />
BaseInts 71<br />
BaseMDT 72<br />
BaseProt 72<br />
BaseType 72<br />
Bool 49<br />
CallType 76<br />
Color 72<br />
DataAreaOwner 55<br />
DataAreaType 55<br />
EndTerminalReason 95<br />
Highlight 72<br />
in Ccl class 49<br />
in CclBuf class 55<br />
in CclConn class 60<br />
in CclEPI class 65<br />
in CclField class 71<br />
in CclFlow class 76<br />
in CclScreen class 81<br />
in CclSession class 85<br />
in CclTerminal class 94<br />
ServerStatus 60<br />
signonType 94<br />
State 65, 85, 94<br />
Sync 49<br />
Transparency 72<br />
EPI<br />
constants 130<br />
data structures 131<br />
events 166<br />
functions 137<br />
in EPI COM Class 13
EPI COM class<br />
Methods<br />
Diagnose 13<br />
ErrorFormat 14<br />
ErrorOffset 14<br />
ErrorWindow 14<br />
ExCode 14<br />
ExCodeText 15<br />
ServerCount 15<br />
ServerDesc 15<br />
ServerName 16<br />
SetErrorFormat 16<br />
State 16<br />
Terminate 17<br />
error<br />
in state 65<br />
in State 66, 85, 94<br />
ErrorFormat<br />
in Methods<br />
in ECI COM Class 11<br />
in EPI COM Class 14<br />
ErrorOffset<br />
in Methods<br />
in ECI COM Class 11<br />
in EPI COM Class 14<br />
ErrorWindow<br />
in Methods<br />
in ECI COM Class 11<br />
in EPI COM Class 14<br />
ESI<br />
constants 169<br />
data structures 170<br />
functions 171<br />
Event parameter<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
except (parameter)<br />
in handleException 62, 64<br />
exCode<br />
in CclECI class 61<br />
in CclEPI class 63<br />
in CclException class 67<br />
in CclMap class 77<br />
in CclTerminal class 89<br />
in Public methods 61, 63, 67, 77, 89<br />
ExCode 11, 14<br />
in EPI COM Class 13<br />
in ErrorWindow 11, 14<br />
in Methods<br />
in ECI COM Class 11<br />
in EPI COM Class 14<br />
in Map COM Class 26<br />
in Terminal COM Class 38<br />
in State 16, 35<br />
exCodeText<br />
in CclECI class 61<br />
exCodeText (continued)<br />
in CclEPI class 64<br />
in CclException class 67<br />
in CclMap class 78<br />
in CclTerminal class 89<br />
in Public methods 61, 64, 67, 78, 89<br />
ExCodeText<br />
in ExCode 12<br />
in Methods<br />
in ECI COM Class 12<br />
in EPI COM Class 15<br />
in Terminal COM Class 38<br />
EXEC <strong>CICS</strong> CONVERSE 167<br />
EXEC <strong>CICS</strong> RECEIVE 158, 160, 167<br />
EXEC <strong>CICS</strong> RECEIVE BUFFER 167<br />
EXEC <strong>CICS</strong> SEND 166<br />
exObject<br />
in CclException class 67<br />
in Public methods 67<br />
ExpiryTime<br />
in SecAttr COM class 31<br />
extensible<br />
in CclBuf 50, 51<br />
in CclBuf class 50<br />
in dataAreaType 52<br />
in DataAreaType 55<br />
in setDataLength 55<br />
external<br />
in dataAreaOwner 52<br />
in DataAreaOwner 55<br />
ExtractString<br />
in Methods<br />
in Buffer COM Class 2<br />
F<br />
failed<br />
in EndTerminalReason 95<br />
false<br />
in ErrorWindow 11, 14<br />
False<br />
in Poll 24, 40<br />
FALSE<br />
in Validate 27<br />
field<br />
in CclMap class 78<br />
in CclScreen class 80<br />
in Public methods 78, 80<br />
Field<br />
in Field COM Class 17<br />
in Screen COM Class 28<br />
Field COM class<br />
Methods<br />
AppendText 17<br />
BackgroundColor 18<br />
BaseAttribute 18<br />
Index 237
Field COM class (continued)<br />
Methods (continued)<br />
Column 18<br />
DataTag 18<br />
ForegroundColor 19<br />
Highlight 19<br />
InputProt 19<br />
InputType 20<br />
Intensity 20<br />
Length 20<br />
Position 20<br />
ResetDataTag 21<br />
Row 21<br />
SetBaseAttribute 21<br />
SetExtAttribute 21<br />
SetText 21<br />
Text 22<br />
TextLength 22<br />
Transparency 22<br />
FieldByIndex<br />
in Methods<br />
in Screen COM Class 29<br />
FieldByName<br />
in Methods<br />
in Map COM Class 27<br />
in Validate 27<br />
FieldByPosition<br />
in Methods<br />
in Screen COM Class 29<br />
fieldCount<br />
in CclScreen class 80<br />
in Public methods 80<br />
FieldCount<br />
in Methods<br />
in Screen COM Class 29<br />
fields<br />
in validate 79<br />
fields (parameter)<br />
in validate 78, 79<br />
fixed<br />
in CclBuf 50, 51<br />
in CclBuf class 50<br />
in dataAreaType 52<br />
in DataAreaType 55<br />
Flow<br />
in Cancel 5<br />
in Changed 5<br />
in Commit 46<br />
in Connect COM Class 4<br />
in Flow COM class 22<br />
in Flow COM Class 22<br />
in Link 7<br />
in SetSyncType 24, 25<br />
in Status 9<br />
238 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
flow (parameter)<br />
in backout 95, 96<br />
in BackOut 45<br />
in cancel 57<br />
in Cancel 5<br />
in changed 57<br />
in Changed 5<br />
in commit 96<br />
in Commit 46<br />
in link 57, 58<br />
in Link 7<br />
in status 59<br />
in Status 9<br />
Flow COM class<br />
Methods<br />
AbendCode 23<br />
CallType 23<br />
CallTypeText 23<br />
Diagnose 23<br />
Flowid 24<br />
ForceReset 24<br />
Poll 24<br />
SetSyncType 24<br />
SetTimeout 25<br />
SyncType 25<br />
Timeout 25<br />
Wait 25<br />
flowId<br />
in CclFlow class 74<br />
in Public methods 74<br />
Flowid<br />
in Methods<br />
in Flow COM Class 24<br />
forceReset<br />
in CclFlow class 74<br />
in CclUOW class 96<br />
in Public methods 74, 96<br />
ForceReset<br />
in Methods<br />
in Flow COM Class 24<br />
in UOW COM Class 46<br />
foregroundColor<br />
in CclField class 69<br />
in Public methods 69<br />
ForegroundColor<br />
in Methods<br />
in Field COM Class 19<br />
format (parameter)<br />
in SetErrorFormat 13, 16<br />
G<br />
<strong>Gateway</strong> initialization file<br />
in Connect 37<br />
in Details 6<br />
in ServerCount 12, 15
<strong>Gateway</strong> initialization file (continued)<br />
in ServerDesc 15<br />
in ServerName 8, 16, 41<br />
GetDate<br />
in SecTime COM Class 32<br />
glossary of terms and abbreviations 213<br />
gray<br />
in Color 72<br />
green<br />
in Color 72<br />
H<br />
handleException<br />
in CclECI class 62<br />
in CclEPI class 64<br />
in Public methods 62, 64<br />
handleReply<br />
in CclFlow class 75<br />
in CclSession class 84<br />
in Public methods 75, 84<br />
highlight<br />
in CclField class 69<br />
in Public methods 69<br />
Highlight<br />
in CclField class 72<br />
in Enumerations 72<br />
in Methods<br />
in Field COM Class 19<br />
Hours<br />
in SecTime COM Class 32<br />
Hunderdths<br />
in SecTime COM Class 33<br />
I<br />
idle<br />
in send 92<br />
in State 85, 94<br />
in Buffer COM Class 1<br />
in Connect COM Class 4<br />
in ECI COM Class 11<br />
in EPI COM Class 13<br />
in field COM Class 23, 26, 34, 35, 45<br />
inactive<br />
in CallType 76<br />
index (parameter)<br />
in ExCode 15<br />
in field 78, 80<br />
in FieldByIndex 29<br />
in namedField 78<br />
in serverDesc 62, 63, 64<br />
in ServerDesc 12, 15<br />
in serverName 63, 65<br />
in ServerName 12, 13, 16<br />
in validate 78, 79<br />
initEPI<br />
in CclEPI constructor 63<br />
in CclTerminal constructor 86<br />
inputProt<br />
in CclField class 69<br />
in Public methods 69<br />
InputProt<br />
in Methods<br />
in Field COM Class 19<br />
inputType<br />
in CclField class 69<br />
in Public methods 69<br />
InputType<br />
in Methods<br />
in Field COM Class 20<br />
insert<br />
in CclBuf class 53<br />
in Public methods 53<br />
InsertString<br />
in Methods<br />
in Buffer COM Class 2<br />
install<br />
in CclTerminal class 90<br />
in Public methods 90<br />
Install<br />
in Methods<br />
in Terminal COM Class 39<br />
install_path vii<br />
installation<br />
path vii<br />
installation path vii<br />
instance<br />
in CclECI class 62<br />
in Public methods 62<br />
intense<br />
in BaseInts 71<br />
in intensity 69<br />
intenseHlt<br />
in Highlight 72<br />
intensity<br />
in CclField class 69<br />
in Public methods 69<br />
Intensity<br />
in Methods<br />
in Field COM Class 20<br />
internal<br />
in CclBuf 51<br />
in dataAreaOwner 52<br />
in DataAreaOwner 55<br />
invalidMap<br />
in CclMap constructor 77<br />
invalidState<br />
in poll 91<br />
in send 92<br />
Index 239
J<br />
Javadoc 47<br />
K<br />
key (parameter)<br />
in setAID 81<br />
in SetAID 30<br />
L<br />
labels<br />
in validate 79<br />
LastVerifiedTime<br />
in SecAttr COM class 31<br />
len<br />
in validate 79<br />
length<br />
in CclField class 69<br />
in Public methods 69<br />
Length<br />
in Methods<br />
in Buffer COM Class 3<br />
in Field COM Class 20<br />
length (parameter)<br />
in appendText 68<br />
in assign 51<br />
in CclBuf 50, 51<br />
in cut 51, 52<br />
in ExtractString 2<br />
in insert 53<br />
in replace 54<br />
in setDataLength 55<br />
in SetLength 3<br />
in setText 71<br />
link<br />
in CallType 77<br />
in CclConn class 57<br />
in Public methods 57<br />
in SetSyncType 25<br />
Link<br />
in Details 6<br />
in Methods<br />
in Connect COM Class 7<br />
in Poll 24<br />
in UOW COM class 45<br />
List parameter 130<br />
<strong>CICS</strong>_EciListSystems 129<br />
<strong>CICS</strong>_EpiListSystems function 143<br />
listState<br />
in CclBuf class 53<br />
in CclConn class 58<br />
in CclECI class 62<br />
in CclFlow class 75<br />
in CclUOW class 96<br />
in Public methods 53, 58, 62, 75, 96<br />
240 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
M<br />
makeSecurityDefault<br />
in CclConn class 58<br />
in CclTerminal class 90<br />
in Public methods 58, 90<br />
MakeSecurityDefault<br />
in Methods<br />
in Connect COM Class 7<br />
in Terminal COM Class 39<br />
Map<br />
in Map COM Class 26<br />
map (parameter)<br />
in validate 78, 79<br />
Map COM class<br />
Methods<br />
ExCode 26<br />
FieldByName 27<br />
Validate 27<br />
mapName<br />
in CclScreen class 80<br />
in Public methods 80<br />
MapName<br />
in Methods<br />
in Screen COM Class 29<br />
mapname (parameter)<br />
in Validate 27<br />
mapSetName<br />
in CclScreen class 80<br />
in Public methods 80<br />
MapSetName<br />
in Methods<br />
in Screen COM Class 29<br />
MaxBufferSize (parameter)<br />
in CclBuf class 50<br />
maxRequests<br />
in CclTerminal constructor 87<br />
maxServers<br />
in serverDesc 64<br />
in serverName 65<br />
methodName<br />
in CclException class 67<br />
in Public methods 67<br />
Methods<br />
AbendCode 23<br />
AlterSecurity 4, 36<br />
AppendString 2<br />
AppendText 17<br />
BackgroundColor 18<br />
BackOut 45<br />
BaseAttribute 18<br />
CallType 23<br />
CallTypeText 23<br />
Cancel 5<br />
CCSId 36<br />
Changed 5
Methods (continued)<br />
ChangePassword 5, 36<br />
Column 18<br />
Commit 46<br />
Connect 36<br />
CursorCol 28<br />
CursorRow 28<br />
Data 2<br />
DataTag 18<br />
Depth 28<br />
Details 6<br />
Devtype 37<br />
Diagnose 13, 23, 34, 37<br />
Disconnect 37<br />
DisconnectWithPurge 37<br />
DiscReason 38<br />
ErrorFormat 11, 14<br />
ErrorOffset 11, 14<br />
ErrorWindow 11, 14<br />
ExCode 11, 14, 26, 38<br />
ExCodeText 12, 15, 38<br />
ExtractString 2<br />
FieldByIndex 29<br />
FieldByName 27<br />
FieldByPosition 29<br />
FieldCount 29<br />
Flowid 24<br />
ForceReset 24, 46<br />
ForegroundColor 19<br />
Highlight 19<br />
in Buffer COM Class 2<br />
in Connect COM Class 4<br />
in ECI COM Class 11<br />
in EPI COM Class 13<br />
in Field COM Class 17<br />
in Flow COM Class 23<br />
in Map COM Class 26<br />
in Screen COM Class 28<br />
in Session COM Class 34<br />
in Terminal COM Class 36<br />
in UOW COM Class 45<br />
InputProt 19<br />
InputType 20<br />
InsertString 2<br />
Install 39<br />
Intensity 20<br />
Length 3, 20<br />
Link 7<br />
MakeSecurityDefault 7, 39<br />
MapName 29<br />
MapSetName 29<br />
NetName 39<br />
Overlay 3<br />
Password 7, 39<br />
Poll 24, 39<br />
Methods (continued)<br />
PollForReply 40<br />
Position 20<br />
QueryATI 40<br />
ReadTimeout 40<br />
ReceiveATI 40<br />
ResetDataTag 21<br />
Row 21<br />
Screen 41<br />
Send 41<br />
ServerCount 12, 15<br />
ServerDesc 12, 15<br />
ServerName 8, 12, 16, 41<br />
ServerStatus 8<br />
ServerStatusText 8<br />
SetAID 30<br />
SetATI 41<br />
SetBaseAttribute 21<br />
SetCursor 30<br />
SetData 3<br />
SetErrorFormat 13, 16<br />
SetExtAttribute 21<br />
SetLength 3<br />
SetString 3<br />
SetSyncType 24, 34<br />
SetTermDefns 42<br />
SetText 21<br />
SetTimeout 25<br />
SignonCapability 43<br />
Start 43<br />
State 16, 34, 44<br />
Status 8<br />
String 4<br />
SyncType 25<br />
TermId 44<br />
Terminate 17<br />
Text 22<br />
TextLength 22<br />
Timeout 25<br />
TranDetails 9<br />
TransId 35, 44<br />
Transparency 22<br />
UnpaddedPassword 9<br />
UnpaddedServerName 9<br />
UnpaddedUserid 9<br />
UowId 46<br />
Userid 44<br />
UserId 10<br />
Validate 27<br />
VerifyPassword 10, 44<br />
Wait 25<br />
Width 30<br />
Minutes<br />
in SecTime COM Class 33<br />
Index 241
modified<br />
in BaseMDT 72<br />
in dataTag 68<br />
Month<br />
in SecTime COM Class 33<br />
multipleInstance<br />
in CclECI class 61<br />
N<br />
n (parameter)<br />
in position 70<br />
name (parameter)<br />
in FieldByName 27<br />
namedField<br />
in CclMap class 78<br />
in Protected methods 78<br />
NameSpace parameter<br />
<strong>CICS</strong>_EciListSystems 129<br />
<strong>CICS</strong>_EpiAddTerminal function 145<br />
<strong>CICS</strong>_EpiListSystems function 143<br />
netName<br />
in CclTerminal class 90<br />
in Public methods 90<br />
NetName<br />
in Methods<br />
in Terminal COM Class 39<br />
netname (parameter)<br />
in CclTerminal constructor 86, 87<br />
NetName parameter<br />
<strong>CICS</strong>_EpiAddExTerminal function 149<br />
<strong>CICS</strong>_EpiAddTerminal function 145<br />
neutral<br />
in Color 72<br />
New<br />
in Buffer COM Class 1<br />
in Connect COM Class 4<br />
in ECI COM Class 11<br />
in EPI COM Class 13<br />
in Field COM Class 23, 26, 34, 35, 45<br />
newPassword (parameter)<br />
in alterSecurity 56, 57<br />
in AlterSecurity 4, 36<br />
in changed 57<br />
in ChangePassword 5<br />
in changePassword method 88<br />
NewPassword parameter<br />
<strong>CICS</strong>_ChangePassword function 175<br />
newstate (parameter)<br />
in setATI 92<br />
newUserid (parameter)<br />
in alterSecurity 57<br />
in AlterSecurity 4, 36<br />
no<br />
in Bool 49<br />
in operator!= 54<br />
242 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
no (continued)<br />
in operator== 54<br />
in poll 75<br />
normal<br />
in BaseInts 71<br />
in intensity 69<br />
normalHlt<br />
in Highlight 72<br />
notDiscon<br />
in EndTerminalReason 95<br />
Nothing<br />
in Poll 24<br />
NotifyFn parameter<br />
<strong>CICS</strong>_EpiAddExTerminal function 150<br />
<strong>CICS</strong>_EpiAddTerminal function 146<br />
numeric<br />
in BaseType 72<br />
in inputType 69<br />
nworkName (parameter)<br />
in Connect 36, 37<br />
in SetTermDefns 42<br />
O<br />
off<br />
in Bool 49<br />
offset (parameter)<br />
in cut 51, 52<br />
in dataArea 52<br />
in ExtractString 2<br />
in insert 53<br />
in InsertString 2<br />
in Overlay 3<br />
in replace 54<br />
OldPassword parameter<br />
<strong>CICS</strong>_ChangePassword function 175<br />
on<br />
in Bool 49<br />
opaqueTran<br />
in Transparency 73<br />
operator!=<br />
in CclBuf class 54<br />
in Public methods 54<br />
operator+=<br />
in CclBuf class 53, 54<br />
in Public methods 53, 54<br />
operator=<br />
in CclBuf class 53<br />
in Public methods 53<br />
operator==<br />
in CclBuf class 54<br />
in Public methods 54<br />
orange<br />
in Color 72<br />
orTran<br />
in Transparency 72
outofService<br />
in EndTerminalReason 95<br />
Overlay<br />
in Methods<br />
in Buffer COM Class 3<br />
P<br />
PA1<br />
in AID 81<br />
PA3<br />
in AID 81<br />
paleCyan<br />
in Color 72<br />
paleGreen<br />
in Color 72<br />
parameter<br />
in CclMap constructor 77<br />
in CclTerminal constructor 86<br />
in send 92<br />
in setCursor 81<br />
in setExtAttribute 70<br />
password 57<br />
in CclConn class 58, 59<br />
in CclTerminal class 90<br />
in Public methods 58, 59, 90<br />
in verifyPassword method 60<br />
Password<br />
in Methods<br />
in Connect COM Class 7<br />
in Terminal COM Class 39<br />
password (parameter)<br />
in alterSecurity method 88<br />
in CclConn constructor 56<br />
in CclTerminal constructor 87<br />
in ChangePassword 36<br />
in Details 6<br />
in SetTermDefns 42<br />
Password parameter<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 172<br />
PF1<br />
in AID 81<br />
PF24<br />
in AID 81<br />
pink<br />
in Color 72<br />
poll<br />
in CclFlow class 75<br />
in CclTerminal class 90<br />
in Public methods 75, 90<br />
Poll<br />
in Methods<br />
in Flow COM Class 24<br />
in Terminal COM Class 39<br />
Poll (continued)<br />
in SetSyncType 25, 34<br />
PollForReply<br />
in Methods<br />
in Terminal COM Class 40<br />
position<br />
in CclField class 70<br />
in Public methods 70<br />
Position<br />
in Methods<br />
in Field COM Class 20<br />
programming<br />
reference 47<br />
programName (parameter)<br />
in link 57, 58<br />
in Link 7<br />
protect<br />
in BaseProt 72<br />
in inputProt 69<br />
Protected methods<br />
in CclMap class 78<br />
namedField 78<br />
validate 78<br />
Public methods<br />
abendCode 66, 74<br />
alterSecurity 56, 88<br />
appendText 67, 68<br />
assign 51<br />
backgroundColor 68<br />
backout 95<br />
baseAttribute 68<br />
callType 74<br />
callTypeText 74<br />
cancel 57<br />
CCSid 88<br />
change password 57<br />
changed 57<br />
changePassword 88<br />
className 66<br />
column 68<br />
commit 96<br />
connection 74<br />
cursorCol 79<br />
cursorRow 79<br />
cut 51<br />
dataArea 52<br />
dataAreaLength 52<br />
dataAreaOwner 52<br />
dataAreaType 52<br />
dataLength 52<br />
dataTag 68<br />
depth 80<br />
diagnose 63, 66, 74, 84, 88<br />
disconnect 88, 89<br />
discReason 89<br />
Index 243
Public methods (continued)<br />
exCode 61, 63, 67, 77, 89<br />
exCodeText 61, 64, 67, 78, 89<br />
exObject 67<br />
field 78, 80<br />
fieldCount 80<br />
flowId 74<br />
forceReset 74, 96<br />
foregroundColor 69<br />
handleException 62, 64<br />
handleReply 75, 84<br />
highlight 69<br />
in CclBuf class 51<br />
in CclConn class 56<br />
in CclECI class 61<br />
in CclEPI class 63<br />
in CclException class 66<br />
in CclField class 67<br />
in CclFlow class 74<br />
in CclMap class 77<br />
in CclScreen class 79<br />
in CclSession class 84<br />
in CclTerminal class 88<br />
in CclUOW class 95<br />
inputProt 69<br />
inputType 69<br />
insert 53<br />
install 90<br />
instance 62<br />
intensity 69<br />
length 69<br />
link 57<br />
listState 53, 58, 62, 75, 96<br />
makeSecurityDefault 58, 90<br />
mapName 80<br />
mapSetName 80<br />
methodName 67<br />
netName 90<br />
operator!= 54<br />
operator+= 53, 54<br />
operator= 53<br />
operator== 54<br />
password 58, 59, 90<br />
poll 75, 90<br />
position 70<br />
queryATI 91<br />
readTimeout 91<br />
receiveATI 91<br />
replace 54<br />
resetDataTag 70<br />
row 70<br />
screen 92<br />
send 92<br />
serverCount 62, 64<br />
serverDesc 62, 64<br />
244 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Public methods (continued)<br />
serverName 59, 63, 65, 93<br />
serverStatus 59<br />
serverStatusText 60<br />
setAID 81<br />
setATI 92<br />
setBaseAttribute 70<br />
setCursor 81<br />
setDataLength 55<br />
setExtAttribute 70<br />
setText 71<br />
setTimeout 76<br />
signonCapability 93<br />
state 65, 85, 93<br />
status 59<br />
syncType 76<br />
termID 93<br />
terminal 85<br />
terminate 65<br />
text 71<br />
textLength 71<br />
timeout 76<br />
transID 85, 93<br />
transparency 71<br />
uow 76<br />
uowId 96<br />
userId 60, 93<br />
verifyPassword 60, 94<br />
wait 76<br />
width 81<br />
Public Methods<br />
in SecAttr COM class 31<br />
in SecTime COM Class 32<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 205<br />
purple<br />
in Color 72<br />
Q<br />
queryATI<br />
in CclTerminal class 91<br />
in Public methods 91<br />
QueryATI<br />
in Methods<br />
in Terminal COM Class 40<br />
R<br />
readTimeout<br />
in CclTerminal class 91<br />
in Public methods 91<br />
ReadTimeout<br />
in Methods<br />
in Terminal COM Class 40<br />
readTimeOut (parameter)<br />
in CclTerminal constructor 87
ReadTimeout (parameter)<br />
in SetTermDefns 42<br />
receiveATI<br />
in CclTerminal class 91<br />
in Public methods 91<br />
ReceiveATI<br />
in Methods<br />
in Terminal COM Class 40<br />
red<br />
in Color 72<br />
replace<br />
in CclBuf class 54<br />
in Public methods 54<br />
reserved1<br />
field in ECI parameter block 98<br />
with ECI_ASYNC call type 109<br />
with ECI_STATE_ASYNC call type 118<br />
with ECI_STATE_SYNC call type 114<br />
with ECI_SYNC call type 102<br />
resetDataTag<br />
in CclField class 70<br />
in Public methods 70<br />
ResetDataTag<br />
in Methods<br />
in Field COM Class 21<br />
in ResetDataTag 21<br />
reverseHlt<br />
in Highlight 72<br />
row<br />
in CclField class 70<br />
in Public methods 70<br />
in validate 79<br />
Row<br />
in Methods<br />
in Field COM Class 21<br />
row (parameter)<br />
in field 78, 80<br />
in setCursor 81<br />
rowPos (parameter)<br />
in FieldByPosition 29<br />
in SetCursor 30<br />
runTran (parameter)<br />
in CclConn constructor 56<br />
in TranDetails 9<br />
S<br />
screen<br />
in CclTerminal class 92<br />
in Public methods 92<br />
Screen<br />
in Field COM Class 17<br />
in Methods<br />
in Terminal COM Class 41<br />
in Screen 41<br />
in Screen COM class 28<br />
Screen (continued)<br />
in Validate 27<br />
screen (parameter)<br />
in CclMap constructor 77<br />
in handleReply 84<br />
Screen COM class<br />
Methods<br />
CursorCol 28<br />
CursorRow 28<br />
Depth 28<br />
FieldByIndex 29<br />
FieldByPosition 29<br />
FieldCount 29<br />
MapName 29<br />
MapSetName 29<br />
SetAID 30<br />
SetCursor 30<br />
Width 30<br />
Screen.fieldbyIndex method<br />
in Ccl Field COM class 17<br />
screenRef (parameter)<br />
in Validate 27<br />
Seconds<br />
in SecTime COM Class 33<br />
send<br />
in CclTerminal class 92<br />
in Public methods 92<br />
Send<br />
in Methods<br />
in Terminal COM Class 41<br />
in Poll 39<br />
in SetSyncType 34<br />
SenseCode parameter<br />
<strong>CICS</strong>_EpiSenseCode function 162<br />
server<br />
in poll 91<br />
in State 85, 94<br />
server (parameter)<br />
in CclTerminal constructor 86, 87<br />
serverCount<br />
in CclECI class 62<br />
in CclEPI class 64<br />
in Public methods 62, 64<br />
ServerCount<br />
in Methods<br />
in ECI COM Class 12<br />
in EPI COM Class 15<br />
serverDesc<br />
in CclECI class 62<br />
in CclEPI class 64<br />
in Public methods 62, 64<br />
ServerDesc<br />
in ExCode 15<br />
in Methods<br />
in ECI COM Class 12<br />
Index 245
ServerDesc (continued)<br />
in Methods (continued)<br />
in EPI COM Class 15<br />
serverName<br />
in CclConn class 59<br />
in CclECI class 63<br />
in CclEPI class 65<br />
in CclTerminal class 93<br />
in Public methods 59, 63, 65, 93<br />
ServerName<br />
in Details 6<br />
in ExCode 15<br />
in Methods<br />
in Connect COM Class 8<br />
in ECI COM Class 12<br />
in EPI COM Class 16<br />
in Terminal COM Class 41<br />
serverName (parameter)<br />
in CclConn constructor 56<br />
in Details 6<br />
serverStatus<br />
in CclConn class 59<br />
in Public methods 59<br />
ServerStatus<br />
in CclConn class 60<br />
in Enumerations 60<br />
in Methods<br />
in Connect COM Class 8<br />
serverStatusText<br />
in CclConn class 60<br />
in Public methods 60<br />
ServerStatusText<br />
in Methods<br />
in Connect COM Class 8<br />
servName (parameter)<br />
in Connect 36, 37<br />
in SetTermDefns 42<br />
Session<br />
in Send 41<br />
in Session COM Class 33<br />
in SetSyncType 34<br />
in Start 43<br />
in State 44<br />
session (parameter)<br />
in ReceiveATI 41<br />
in receiveATI method 91<br />
in send 92<br />
in Send 41<br />
in Start 43<br />
Session COM class<br />
Methods<br />
Diagnose 34<br />
SetSyncType 34<br />
State 34<br />
TransId 35<br />
246 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
setAID<br />
in CclScreen class 81<br />
in Public methods 81<br />
SetAID<br />
in Methods<br />
in Screen COM Class 30<br />
setATI<br />
in CclTerminal class 92<br />
in Public methods 92<br />
SetATI<br />
in Methods<br />
in Terminal COM Class 41<br />
setBaseAttribute<br />
in CclField class 70<br />
in Public methods 70<br />
SetBaseAttribute<br />
in Methods<br />
in Field COM Class 21<br />
setCursor<br />
in CclScreen class 81<br />
in Public methods 81<br />
SetCursor<br />
in Methods<br />
in Screen COM Class 30<br />
SetData<br />
in Methods<br />
in Buffer COM Class 3<br />
setDataLength<br />
in CclBuf class 55<br />
in Public methods 55<br />
SetErrorFormat<br />
in Methods<br />
in ECI COM Class 13<br />
in EPI COM Class 16<br />
setExtAttribute<br />
in CclField class 70<br />
in Public methods 70<br />
SetExtAttribute<br />
in Methods<br />
in Field COM Class 21<br />
SetLength<br />
in Buffer COM Class 1<br />
in Methods<br />
in Buffer COM Class 3<br />
SetString<br />
in Methods<br />
in Buffer COM Class 3<br />
SetSyncType<br />
in Methods<br />
in Flow COM Class 24<br />
in Session COM Class 34<br />
SetTermDefns<br />
in Methods<br />
in Terminal COM Class 42
setText<br />
in CclField class 71<br />
in Public methods 71<br />
SetText<br />
in Methods<br />
in Field COM Class 21<br />
setTimeout<br />
in CclFlow class 76<br />
in Public methods 76<br />
SetTimeout<br />
in Methods<br />
in Flow COM Class 25<br />
shutdown<br />
in EndTerminalReason 95<br />
signoff<br />
in EndTerminalReason 95<br />
signonCapability<br />
in CclTerminal class 93<br />
in Public methods 93<br />
SignonCapability<br />
in Methods<br />
in Terminal COM Class 43<br />
signonCapability (parameter)<br />
in CclTerminal constructor 87<br />
in SetTermDefns 42<br />
signonCapable<br />
in signonType 94<br />
signonIncapable<br />
in signonType 94<br />
signonType<br />
in CclTerminal class 94<br />
in Enumerations 94<br />
signonUnknown<br />
in signonType 94<br />
Size parameter<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiStartTran function 158<br />
stackPages (parameter)<br />
in CclFlow 73<br />
Start<br />
in Methods<br />
in Terminal COM Class 43<br />
in Poll 39<br />
in SetSyncType 34<br />
startdata (parameter)<br />
in send 92<br />
startData (parameter)<br />
in Start 43<br />
state<br />
in CclEPI class 65<br />
in CclSession class 85<br />
in CclTerminal class 93<br />
in Public methods 65, 85, 93<br />
State<br />
in CclEPI class 65<br />
State (continued)<br />
in CclSession class 85<br />
in CclTerminal class 94<br />
in Enumerations 65, 85, 94<br />
in EPI COM Class 13<br />
in Methods<br />
in EPI COM Class 16<br />
in Session COM Class 34<br />
in Terminal COM Class 44<br />
in State 44<br />
state (parameter)<br />
in handleReply 84<br />
stateVal (parameter)<br />
in SetATI 41, 42<br />
status<br />
in CallType 77<br />
in CclConn class 59<br />
in Public methods 59<br />
in ServerStatus 8<br />
in ServerStatusText 8<br />
in SetSyncType 25<br />
Status<br />
in Details 6<br />
in Methods<br />
in Connect COM Class 8<br />
in Poll 24<br />
String<br />
in Methods<br />
in Buffer COM Class 4<br />
string (parameter)<br />
in AppendString 2<br />
in InsertString 2<br />
in Overlay 3<br />
in SetString 3, 4<br />
sync<br />
in CclSession constructor 84<br />
in Sync 49<br />
Sync<br />
in Ccl class 49<br />
in Enumerations 49<br />
syncType<br />
in CclFlow class 76<br />
in poll 75, 91<br />
in Public methods 76<br />
in wait 76<br />
SyncType<br />
in Methods<br />
in Flow COM Class 25<br />
syncType (parameter)<br />
in CclFlow 73<br />
in CclSession constructor 84<br />
in SetSyncType 24, 34<br />
in SyncType 25<br />
SysErr parameter<br />
<strong>CICS</strong>_EpiGetSysError function 165<br />
Index 247
system information structure 129, 143<br />
System parameter<br />
<strong>CICS</strong>_ChangePassword function 175<br />
<strong>CICS</strong>_EpiAddExTerminal function 148<br />
<strong>CICS</strong>_EpiAddTerminal function 145<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 172<br />
SystemName parameter<br />
<strong>CICS</strong>_EciListSystems 129<br />
Systems parameter 130<br />
<strong>CICS</strong>_EciListSystems 129<br />
<strong>CICS</strong>_EpiListSystems function 143<br />
T<br />
termDefined<br />
in State 94<br />
termID<br />
in CclTerminal class 93<br />
in Public methods 93<br />
TermId<br />
in Methods<br />
in Terminal COM Class 44<br />
terminal<br />
in CclSession class 85<br />
in Public methods 85<br />
Terminal<br />
in EPI COM Class 13<br />
in Screen COM Class 28<br />
in ServerName 41<br />
Terminal COM class<br />
Methods<br />
AlterSecurity 36<br />
CCSId 36<br />
ChangePassword 36<br />
Connect 36<br />
Devtype 37<br />
Diagnose 37<br />
Disconnect 37<br />
DisconnectWithPurge 37<br />
DiscReason 38<br />
ExCode 38<br />
ExCodeText 38<br />
Install 39<br />
MakeSecurityDefault 39<br />
NetName 39<br />
Password 39<br />
Poll 39<br />
PollForReply 40<br />
QueryATI 40<br />
ReadTimeout 40<br />
ReceiveATI 40<br />
Screen 41<br />
Send 41<br />
ServerName 41<br />
SetATI 41<br />
248 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
Terminal COM class (continued)<br />
Methods (continued)<br />
SetTermDefns 42<br />
SignonCapability 43<br />
Start 43<br />
State 44<br />
TermId 44<br />
TransId 44<br />
Userid 44<br />
VerifyPassword 44<br />
terminal index 144, 148<br />
Terminal.Connect<br />
in Screen COM Class 28<br />
Terminal.Screen<br />
in Screen COM Class 28<br />
terminate<br />
in CclEPI class 65<br />
in Public methods 65<br />
Terminate<br />
in Methods<br />
in EPI COM Class 17<br />
in Terminate 17<br />
TermIndex parameter<br />
<strong>CICS</strong>_EpiAddExTerminal function 150<br />
<strong>CICS</strong>_EpiAddTerminal function 146<br />
<strong>CICS</strong>_EpiATIState function 161<br />
<strong>CICS</strong>_EpiDelTerminal function 154<br />
<strong>CICS</strong>_EpiGetEvent function 163<br />
<strong>CICS</strong>_EpiGetSysError function 165<br />
<strong>CICS</strong>_EpiInquireSystem function 153<br />
<strong>CICS</strong>_EpiPurgeTerminal function 155<br />
<strong>CICS</strong>_EpiReply function 160<br />
<strong>CICS</strong>_EpiSenseCode function 162<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_EpiStartTran function 157<br />
text<br />
in CclField class 71<br />
in Public methods 71<br />
Text<br />
in Methods<br />
in Field COM Class 22<br />
text (parameter)<br />
in appendText 68<br />
in CclBuf 51<br />
in operator+= 54<br />
in operator= 53<br />
in setText 71<br />
textLength<br />
in CclField class 71<br />
in Public methods 71<br />
TextLength<br />
in Methods<br />
in Field COM Class 22<br />
textString (parameter)<br />
in AppendText 17, 18
textString (parameter) (continued)<br />
in SetText 21, 22<br />
timeout<br />
in CclFlow class 76<br />
in Public methods 76<br />
Timeout<br />
in Methods<br />
in Flow COM Class 25<br />
timeout (parameter)<br />
in CclFlow 73<br />
in Install 39<br />
in setTimeout 76<br />
tranCode (parameter)<br />
in Start 43<br />
TranDetails<br />
in Connect COM Class 4<br />
in Methods<br />
in Connect COM Class 9<br />
transID<br />
in CclSession class 85<br />
in CclTerminal class 93<br />
in Public methods 85, 93<br />
TransId<br />
in Methods<br />
in Session COM Class 35<br />
in Terminal COM Class 44<br />
transid (parameter)<br />
in send 92<br />
TransId parameter<br />
<strong>CICS</strong>_EpiStartTran function 157<br />
transparency<br />
in CclField class 71<br />
in Public methods 71<br />
Transparency<br />
in CclField class 72<br />
in Enumerations 72<br />
in Methods<br />
in Field COM Class 22<br />
true<br />
in ErrorWindow 11, 14<br />
True<br />
in Poll 24, 39<br />
TRUE<br />
in Validate 27<br />
txnTimedOut<br />
in State 94<br />
type (parameter)<br />
in CclBuf 50, 51<br />
U<br />
unavailable<br />
in ServerStatus 61<br />
underscoreHlt<br />
in Highlight 72<br />
unit (parameter)<br />
in link 57, 58<br />
unitOfWork (parameter)<br />
in Link 7<br />
unknown<br />
in EndTerminalReason 95<br />
in ServerStatus 60<br />
unknownServer<br />
in CclTerminal constructor 86<br />
unmodified<br />
in BaseMDT 72<br />
in dataTag 68<br />
unmodified (parameter)<br />
in resetDataTag 70<br />
unpadded (parameter)<br />
in status 59, 60<br />
UnpaddedPassword<br />
in Methods<br />
in Connect COM Class 9<br />
UnpaddedServerName<br />
in Methods<br />
in Connect COM Class 9<br />
UnpaddedUserid<br />
in Methods<br />
in Connect COM Class 9<br />
unprotect<br />
in BaseProt 72<br />
in inputProt 69<br />
uow<br />
in CclFlow class 76<br />
in Public methods 76<br />
UOW<br />
in Link 7<br />
in UOW COM class 45<br />
UOW COM class<br />
Methods<br />
BackOut 45<br />
Commit 46<br />
ForceReset 46<br />
UowId 46<br />
uowId<br />
in CclUOW class 96<br />
in Public methods 96<br />
UowId<br />
in Methods<br />
in UOW COM Class 46<br />
userId<br />
in CclConn class 60<br />
in CclTerminal class 93<br />
in Public methods 60, 93<br />
Userid<br />
in Methods<br />
in Terminal COM Class 44<br />
Index 249
UserId<br />
in Methods<br />
in Connect COM Class 10<br />
userid (parameter)<br />
in alterSecurity method 88<br />
in CclTerminal constructor 87<br />
in SetTermDefns 42<br />
userId (parameter)<br />
in CclConn constructor 56<br />
in Details 6<br />
userID (parameter)<br />
in CclConn constructor 56<br />
in Details 6<br />
UserId parameter<br />
<strong>CICS</strong>_ChangePassword function 174<br />
<strong>CICS</strong>_EpiSetSecurity function 156<br />
<strong>CICS</strong>_SetDefaultSecurity function 178<br />
<strong>CICS</strong>_VerifyPassword function 172<br />
V<br />
validate<br />
in CclMap class 78<br />
in Protected methods 78<br />
Validate<br />
in Methods<br />
in Map COM Class 27<br />
value (parameter)<br />
in setExtAttribute 70<br />
Value (parameter)<br />
in SetExtAttribute 21<br />
verifyPassword<br />
in CclConn class 60<br />
in CclTerminal class 94<br />
in Public methods 60, 94<br />
VerifyPassword<br />
in Methods<br />
in Connect COM Class 10<br />
in Terminal COM Class 44<br />
<strong>Version</strong> parameter<br />
<strong>CICS</strong>_EpiInitialize function 141<br />
W<br />
wait<br />
in CclFlow class 76<br />
in Public methods 76<br />
Wait<br />
in Methods<br />
in Flow COM Class 25<br />
in Wait 25<br />
Wait parameter<br />
<strong>CICS</strong>_EpiGetEvent function 164<br />
white<br />
in Color 72<br />
width<br />
in CclScreen class 81<br />
250 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference<br />
width (continued)<br />
in Public methods 81<br />
in validate 79<br />
Width<br />
in Methods<br />
in Screen COM Class 30<br />
withPurge<br />
in disconnect method<br />
in CclTerminal class 89<br />
X<br />
xorTran<br />
in Transparency 72<br />
Y<br />
Year<br />
in SecTime COM Class 33<br />
yellow<br />
in Color 72<br />
yes<br />
in Bool 49<br />
in operator!= 54<br />
in operator== 54<br />
in poll 75
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 1989, 2002 251
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
COPYRIGHT LICENSE:<br />
This information contains sample application programs in source language,<br />
which illustrate programming techniques on various operating platforms. You<br />
may copy, modify, and distribute these sample programs in any form without<br />
payment to IBM for the purposes of developing, using, marketing, or<br />
distributing application programs conforming to IBM’s application<br />
programming interfaces for the operating platform for which the sample<br />
programs are written. These examples have not been thoroughly tested under<br />
all conditions. IBM, therefore, cannot guarantee or imply reliability,<br />
serviceability, or function of these programs.<br />
252 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Trademarks<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
AIX <strong>CICS</strong><br />
IBM OS/390<br />
VisualAge<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of<br />
Microsoft Corporation in the United States, other countries, or both.<br />
Java, and all Java-based trademarks and logos are trademarks of Sun<br />
Microsystems, Inc. in the United States, or other countries, or both.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
Notices 253
254 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 1989, 2002 255
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6140-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Programming Reference <strong>Version</strong> <strong>5.0</strong>
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Messages<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6193-00
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Messages<br />
<strong>Version</strong> <strong>5.0</strong><br />
���<br />
SC34-6193-00
Note!<br />
Before using this information and the product it supports, be sure to read the general information under<br />
“Notices” on page 143.<br />
First Edition (July 2002)<br />
This edition applies to <strong>Version</strong> <strong>5.0</strong> of IBM <strong>CICS</strong> ® <strong>Transaction</strong> <strong>Gateway</strong> program number 5724-D12.<br />
© Copyright International Business Machines Corporation 1994, 2002. All rights reserved.<br />
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract<br />
with IBM Corp.
Contents<br />
About this book. . . . . . . . . . . v<br />
Conventions and terminology used in this<br />
book . . . . . . . . . . . . . . . v<br />
Prerequisite and related information . . . . v<br />
How to send your comments . . . . . . v<br />
Obtaining books from IBM . . . . . . . vi<br />
Messages . . . . . . . . . . . . . 1<br />
The product library and related literature 123<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books . . . . 123<br />
Sample configuration documents. . . . . 124<br />
Redbooks . . . . . . . . . . . . 125<br />
Other Useful Books . . . . . . . . . 125<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications . . 125<br />
APPC-related publications . . . . . . 126<br />
|<br />
|<br />
TCP62–related publications . . . . . 126<br />
Obtaining books from IBM. . . . . . . 126<br />
Accessibility . . . . . . . . . . . 127<br />
Documentation . . . . . . . . . . 127<br />
Glossary . . . . . . . . . . . . 129<br />
Index . . . . . . . . . . . . . 141<br />
Notices . . . . . . . . . . . . . 143<br />
Trademarks . . . . . . . . . . . . 144<br />
Sending your comments to IBM . . . . 145<br />
© Copyright IBM Corp. 1994, 2002 iii
iv <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
About this book<br />
This book lists the error messages for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>Version</strong><br />
<strong>5.0</strong> and the <strong>CICS</strong> Universal Client products. Significant information messages<br />
are also listed.<br />
It is intended for use as a quick reference, with messages organized in<br />
alphanumeric sequence. Each message entry gives the message identifier,<br />
message text, and further diagnostic and explanatory information.<br />
Conventions and terminology used in this book<br />
The terminology in this book should be familiar to anyone who has used<br />
<strong>CICS</strong> and the supported operating systems.<br />
Prerequisite and related information<br />
The messages refer to several non-IBM books; these mainly relate to the<br />
platform on which the client is running and it is assumed that these books are<br />
available to you.<br />
How to send your comments<br />
Your feedback is important in helping to provide the most accurate and<br />
high-quality information. If you have any comments about this book, or any<br />
other <strong>CICS</strong> documentation:<br />
v Visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link to our feedback form.<br />
Here you will find the feedback page where you can enter and submit your<br />
comments.<br />
v Send your comments by e-mail to idrcf@hursley.ibm.com<br />
v Fax your comments to:<br />
+44 1962 842327 (if you are outside the UK)<br />
01962 842327 (if you are in the UK)<br />
v Mail your comments to:<br />
Information Development<br />
Mail Point 095<br />
© Copyright IBM Corp. 1994, 2002 v
IBM United Kingdom Laboratories<br />
Hursley Park<br />
Winchester<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
Whichever method you use, ensure that you include:<br />
v The name of the book<br />
v The form number of the book<br />
v If applicable, the version of the product<br />
v The specific location of the text you are commenting on, for example, a<br />
page number or table number.<br />
When you send information to IBM, you grant IBM a non-exclusive right to<br />
use or distribute the information in any way it believes appropriate without<br />
incurring any obligation to you.<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
vi <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Messages<br />
CCL0510E Command option option is invalid<br />
Explanation: An invalid command option was<br />
specified on the command line.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0511E Command option option must<br />
specify a value<br />
Explanation: A command line application was<br />
run with no value supplied for the named<br />
required option.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0512E Command option option cannot be<br />
used more than once<br />
Explanation: The named option was used more<br />
than once on the command line. This is invalid.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0513E Command option option1 cannot<br />
be used with option option2<br />
Explanation: The two named options, used on<br />
the command line, were incompatible.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0514E Command option option1 or<br />
option2 must be provided<br />
Explanation: The command line did not include<br />
one of the named required options.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0515E Command option option1 can only<br />
be used with option2<br />
Explanation: option1 was specified on the<br />
command line, but option2 was not also specified.<br />
This is invalid.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0516E Command option option is invalid<br />
Explanation: An invalid command option was<br />
specified on the command line.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0517E Command option option must<br />
specify a value<br />
Explanation: A command line application was<br />
run with no value supplied for the named<br />
required option.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
© Copyright IBM Corp. 1994, 2002 1
CCL0518E CCL1024E<br />
CCL0518E Command option option cannot be<br />
used more than once<br />
Explanation: The named option was used more<br />
than once on the command line. This is invalid.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0519E Command option option1 cannot<br />
be used with option option2<br />
Explanation: The two named options, used on<br />
the command line, were incompatible.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0520E Command option option1 or<br />
option2 must be provided<br />
Explanation: The command line did not include<br />
one of the named required options.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL0521E Command option option1 can only<br />
be used with option2<br />
Explanation: option1 was specified on the<br />
command line, but option2 was not also specified.<br />
This is invalid.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Retype the command using the<br />
correct options.<br />
CCL1021E Unable to write to text file filename<br />
Explanation: The binary trace formatter is<br />
unable to write any further information to the<br />
2 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
<strong>CICS</strong> client trace file during conversion of the<br />
binary trace.<br />
System Action: The binary trace formatter<br />
terminates.<br />
User Response: Determine the cause of the<br />
error. It may be that the disk which the binary<br />
trace formatter is writing to is full, or the disk<br />
might be write-protected.<br />
CCL1022E Unable to read from binary file<br />
filename<br />
Explanation: The binary trace formatter is<br />
unable to read from the binary trace file during<br />
conversion of the binary trace.<br />
System Action: The binary trace formatter<br />
terminates.<br />
User Response: Determine the cause of the<br />
error. It may be that the binary trace file has<br />
been removed during conversion, or the binary<br />
trace file might be read-protected.<br />
CCL1023E Unable to open file filename<br />
Explanation: The binary trace formatter is<br />
unable to open the specified file for reading or<br />
writing as required.<br />
System Action: The binary trace formatter<br />
terminates.<br />
User Response: Determine the cause of the<br />
error. If the file that is being opened is the binary<br />
trace file, check that the file exists and that it is<br />
not read-protected. If the file that is being<br />
opened is the output text file, make sure that the<br />
disk on to which the file is being written is not<br />
write-protected.<br />
CCL1024E Unable to correctly interpret all<br />
bytes of file filename<br />
Explanation: The binary trace formatter is<br />
unable to process the specified binary trace file.<br />
System Action: The binary trace formatter<br />
terminates.<br />
User Response: Determine the cause of the<br />
error. Make sure that the file being read is a
valid binary trace file, and that it was created<br />
with the version of the <strong>CICS</strong> client currently<br />
installed on your system. If after checking this<br />
you still receive the same error, you may need to<br />
remove the binary trace file before running the<br />
client trace again.<br />
CCL1025E Not enough memory to convert<br />
binary trace file<br />
Explanation: The binary trace formatter has run<br />
out of free memory whilst processing the binary<br />
trace.<br />
System Action: The binary trace formatter<br />
terminates.<br />
User Response: Increase the amount of<br />
available memory in the system by shutting<br />
down applications that are not needed, and then<br />
re-run the binary trace formatter. You can reduce<br />
the amount of memory that the binary trace<br />
formatter needs by specifying on the command<br />
line the maximum amount of data to convert at<br />
any one time (refer to the documentation for<br />
further information on how to do this).<br />
CCL1027E Invalid binary trace file filename<br />
(version number = number)<br />
Explanation: The binary trace formatter<br />
detected an invalid version number in the binary<br />
trace file.<br />
System Action: The binary trace formatter<br />
terminates without performing any further<br />
processing.<br />
User Response: Make sure that the file you are<br />
trying to convert is a valid binary trace file and<br />
that you are using the most recent version of the<br />
binary trace formatter that is available on your<br />
system.<br />
CCL1028E Unable to access the file filename<br />
Explanation: The binary trace formatter is<br />
unable to access the binary trace file.<br />
System Action: The binary trace formatter<br />
terminates.<br />
CCL1025E CCL1032I<br />
User Response: Check that the user has access<br />
to the binary trace file.<br />
CCL1030I Warning: component component<br />
was not found in the binary trace<br />
Explanation: The binary trace formatter was<br />
told to process trace points from a named<br />
component, but no trace points from that<br />
component were found in the binary trace file.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue to<br />
process the binary trace file.<br />
User Response: In order to stop this message<br />
being displayed, make sure that all the<br />
components you specify on the command line of<br />
the binary trace formatter exist in the binary<br />
trace.<br />
CCL1031I [Bytes Remaining - bytes<br />
(percentage)]<br />
Explanation: The binary trace formatter has<br />
been started and is in the process of converting<br />
the binary trace. The message shows the progress<br />
that the binary trace formatter has made so far.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue to<br />
process the binary trace file.<br />
User Response: No further action is required<br />
CCL1032I Do you want to overwrite filename<br />
[Y|N]?<br />
Explanation: The binary trace formatter has<br />
detected that the trace file you have told it to<br />
generate already exists. You are given the<br />
opportunity to erase it or terminate the formatter.<br />
System Action: If you enter Y at the command<br />
prompt, the binary trace formatter will continue<br />
and the old trace file will be overwritten. If you<br />
enter N at the command prompt, the binary trace<br />
formatter will terminate and the old trace file<br />
will remain unchanged.<br />
User Response: Select the appropriate option<br />
according to whether you want to overwrite the<br />
Messages 3
CCL1046 CCL1124I<br />
old trace file or terminate the binary trace<br />
formatter.<br />
CCL1046 Error in function function (Error<br />
code = error)<br />
Explanation: An system or internal client<br />
function failed.<br />
System Action: The message is written to the<br />
error log. The function name and error code are<br />
logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL1047 Error in the EPI (function, error,<br />
termid)<br />
Explanation: An internal EPI error has occurred.<br />
System Action: The message is written to the<br />
error log. The function name and error code are<br />
logged, together with the TermId.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL1100I The following list shows what<br />
components can be traced<br />
Explanation: A request to list all client<br />
components has been given.<br />
System Action: A list of all client components is<br />
displayed on the screen. An X is placed beside<br />
each component that is currently being traced.<br />
User Response: No further action is required<br />
CCL1120I Trace has not been started<br />
Explanation: A command that required tracing<br />
to be turned on was given, but at the moment<br />
tracing is disabled.<br />
System Action: Some client commands that<br />
require tracing to be turned on will fail, but most<br />
requests to the client will be unaffected.<br />
User Response: If you want to issue requests to<br />
the client that rely on tracing, tracing must be<br />
turned on.<br />
4 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL1121I Component trace started to:<br />
component list<br />
Explanation: A request to trace only those<br />
components specified on the command line was<br />
given.<br />
System Action: The client runs as normal,<br />
writing all trace points from the specified<br />
components to the binary trace file.<br />
User Response: No further action is required.<br />
CCL1122E Invalid list of components. Please<br />
re-type.<br />
Explanation: You have specified a list of<br />
components on the command line, but one or<br />
more of the components in the list is invalid.<br />
System Action: The request that required a list<br />
of components to be specified is ignored.<br />
User Response: Refer to the <strong>CICS</strong> client<br />
documentation for a list of valid components and<br />
retype the request.<br />
CCL1123I Reading binary trace file filename<br />
Explanation: The binary trace formatter is about<br />
to process the specified binary trace file.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue.<br />
User Response: No further action is required<br />
CCL1124I Reading binary trace file filename1<br />
and filename2<br />
Explanation: The binary trace formatter is about<br />
to process the specified binary trace files. The<br />
binary trace formatter is reading from two trace<br />
files because it is formatting a wrapping trace.<br />
Refer to the documentation for further<br />
information about wrapping traces.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue.<br />
User Response: No further action is required
CCL1125I Generating text trace file filename<br />
Explanation: The binary trace formatter will<br />
write all text formatted output to the specified<br />
file.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue.<br />
User Response: No further action is required<br />
CCL1126I Failed to make new trace<br />
component list persistent<br />
Explanation: When the list of trace components<br />
is changed, the new list is stored as the default.<br />
If there is a problem storing this new list then<br />
this message will be produced. Your current trace<br />
session will still use the components you<br />
specified but they will not become the default so<br />
if you turn trace off and on again, you will need<br />
to re-specify the component list.<br />
System Action: This message is for information<br />
only. The client will continue.<br />
User Response: No further action is required<br />
CCL1127I Updated trace component list to:<br />
list<br />
Explanation: The client has updated the list of<br />
components to trace and this list will be the<br />
default until the client is restarted (when the<br />
default will be refreshed from the initialisation<br />
file). For instance, if you stop and restart tracing,<br />
the components to trace will remain the same<br />
unless you make another change explicitly.<br />
System Action: This message is for information<br />
only. The client will continue.<br />
User Response: No further action is required<br />
CCL1128I Generating text summary trace<br />
file filename<br />
Explanation: The binary trace formatter will<br />
write all summary text formatted output to the<br />
specified file.<br />
System Action: This message is for information<br />
only. The binary trace formatter will continue.<br />
CCL1125I CCL1202<br />
User Response: No further action is required<br />
CCL1200 Unable to open binary trace file<br />
filename<br />
Explanation: The client cannot open the binary<br />
trace file for writing.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
User Response: Check that the directory into<br />
which the binary trace file is being written is not<br />
write-protected.<br />
CCL1200E TCP62 Trace Formatter: Network<br />
Protocol Format Syntax Error.<br />
Explanation: A syntax error was found while<br />
processing the NPF template files used to format<br />
TCP62 data flows.<br />
System Action: The trace formatter will not<br />
format any more TCP62 data flows, but will<br />
continue to format other parts of the trace.<br />
User Response: Contact your service<br />
organisation.<br />
CCL1201E TCP62 Trace Formatter: Network<br />
Protocol Format Run-time Error.<br />
Explanation: A run-time error was found while<br />
processing the NPF template files used to format<br />
TCP62 data flows.<br />
System Action: The trace formatter will stop<br />
formatting the current TCP62 data flow, but it<br />
will continue to format other TCP62 data flows<br />
and other parts of the trace.<br />
User Response: Contact your service<br />
organisation.<br />
CCL1202 Unable to write to binary trace<br />
file<br />
Explanation: Although the binary trace file was<br />
opened successfully, an error occurred whilst<br />
writing a trace point to the file.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
Messages 5
CCL1202E CCL1207<br />
User Response: Check that the permissions of<br />
the trace file have not changed.<br />
CCL1202E The remaining TCP62 data flows<br />
will not be formatted.<br />
Explanation: A severe error was found while<br />
processing the NPF template files used to format<br />
TCP62 data flows.<br />
System Action: The trace formatter will not<br />
format any more TCP62 data flows, but will<br />
continue to format other parts of the trace.<br />
User Response: Contact your service<br />
organisation.<br />
CCL1203 Out of memory whilst running<br />
with trace on<br />
Explanation: There is not enough available<br />
memory for tracing to continue.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
User Response: Make more memory available<br />
to the client and then try again.<br />
CCL1203E The remaining part of this TCP62<br />
data flow will not be formatted.<br />
Explanation: An error was found while<br />
processing the NPF template files used to format<br />
TCP62 data flows.<br />
System Action: The trace formatter will stop<br />
formatting the current TCP62 data flow, but it<br />
will continue to format other TCP62 data flows<br />
and other parts of the trace.<br />
User Response: Contact your service<br />
organisation.<br />
CCL1204 No memory buffer - unable to<br />
perform tracing operations<br />
Explanation: This is a serious internal error, and<br />
means that the client is unable to buffer its<br />
writes to the trace file.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
6 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: If the problem persists, contact<br />
your service organisation.<br />
CCL1204E Network Protocol Formatter Error:<br />
error description.<br />
Explanation: The error described here was<br />
found while processing the NPF template files<br />
used to format TCP62 data flows.<br />
System Action: The following CCL1202E or<br />
CCL1203E error message describes what will<br />
happen.<br />
User Response: Contact your service<br />
organisation.<br />
CCL1205 Invalid system return code<br />
(Function, Error code)<br />
Explanation: An internal system function has<br />
returned an error whilst tracing was turned on.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
User Response: If the problem persists, contact<br />
your service organisation.<br />
CCL1206 Internal error (Function, Error)<br />
Explanation: An internal function has returned<br />
an error whilst tracing was turned on.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
User Response: If the problem persists, contact<br />
your service organisation.<br />
CCL1207 Security failure - the owner of the<br />
binary trace file has changed<br />
Explanation: This message will appear in the<br />
log file on UNIX if the owner of the trace file<br />
changes. For security reasons, you may not<br />
change the owner of the trace file whilst trace is<br />
running.<br />
System Action: The client will continue, but<br />
tracing will be disabled.<br />
User Response: Restart trace and make sure
that the owner of the trace file does not change.<br />
CCL1208 Trace initialization failure.<br />
Explanation: An internal error prevented<br />
tracing from being turned on.<br />
System Action: The Client daemon will<br />
continue, but tracing is disabled.<br />
User Response: If the problem persists, contact<br />
your service organisation.<br />
CCL1209 Trace file deleted whilst tracing<br />
active.<br />
Explanation: The trace file was deleted whilst<br />
tracing was active.<br />
System Action: This message is written to the<br />
error log. Tracing will continue.<br />
User Response: Deleting the trace file whilst<br />
tracing is active is not recommended. To limit the<br />
size of the trace file, set the maximum client<br />
wrap size. See the administration guide for more<br />
details.<br />
CCL1210 Trace component component is<br />
invalid and will be ignored<br />
Explanation: You are trying to trace to a<br />
component that is not valid.<br />
System Action: Tracing will continue, but the<br />
component you have specified will be ignored.<br />
User Response: If you don’t want this message<br />
to appear in the log, remove the reference to the<br />
invalid component.<br />
CCL2001E Server server is undefined<br />
Explanation: The client received a request for a<br />
server, but the server is not defined in the client<br />
initialization file that was specified when the<br />
client first started up.<br />
System Action: The request fails but the client<br />
continues.<br />
User Response: Ensure the server name<br />
specified by the ECI or EPI application, or by the<br />
CCL1208 CCL2006I<br />
3270 Emulator is correct. If required, add the<br />
server name to the client initialization file, then<br />
stop and restart the client to activate the changes.<br />
CCL2003I Server server requires a security<br />
identification<br />
Explanation: The client received a request<br />
destined for a secure server. The server required<br />
a valid userid and password before it could<br />
accept the request, and was supplied either with<br />
an invalid one or none at all.<br />
System Action: The client displays a pop-up<br />
panel allowing a userid and password to be<br />
entered or the request to be cancelled.<br />
User Response: Enter a valid userid and<br />
password to allow the request to be processed by<br />
the server. This message can be avoided either by<br />
ensuring that an ECI application supplies a valid<br />
userid and password or by using the <strong>CICS</strong>CLI<br />
/C command to set the server security.<br />
CCL2004E The client cannot continue<br />
Explanation: An error was detected.<br />
System Action: The client terminates.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL2005I The client will continue<br />
Explanation: An error was detected.<br />
System Action: Client processing continues.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL2006I Refer to the client error log for<br />
more details<br />
Explanation: An error has occurred for which<br />
further useful diagnostic information has been<br />
written to the client error log.<br />
System Action: Error information is written to<br />
the client error log.<br />
Messages 7
CCL2007E CCL2014<br />
User Response: Examine the client error log to<br />
obtain the information.<br />
CCL2007E Free memory is exhausted<br />
Explanation: The client ran out of memory<br />
while processing a request.<br />
System Action: The request fails and the client<br />
attempts to continue processing.<br />
User Response: Try altering the values in the<br />
client initialization file to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL2008E An internal state error occurred<br />
Explanation: The client detected an unexpected<br />
internal error.<br />
System Action: Error information is written to<br />
the client error log.<br />
User Response: Obtain the client error log -<br />
and, if possible, trace information - and refer the<br />
problem to your support organization.<br />
CCL2009E An unexpected error has occurred<br />
Explanation: The client detected an unexpected<br />
error.<br />
System Action: Error information is written to<br />
the client error log.<br />
User Response: Obtain the client error log -<br />
and, if possible, trace information - and refer the<br />
problem to your support organization.<br />
CCL2010 Internal transport error (function,<br />
error)<br />
Explanation: An internal client function failed.<br />
System Action: The message is written to the<br />
error log and the client terminates. The function<br />
name and error code are logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
8 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL2011 Out of memory creating session<br />
control structure<br />
Explanation: The client was unable to allocate<br />
enough memory to create an internal control<br />
structure for a new server conversation.<br />
System Action: The message is written to the<br />
error log and processing continues. The<br />
conversation is not created.<br />
User Response: Try altering the values in the<br />
client initialization file to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL2012 Unable to find session entry<br />
(session id, slot number)<br />
Explanation: The client was unable to locate an<br />
internal control structure for an existing server<br />
conversation.<br />
System Action: The message is written to the<br />
error log and processing continues. The<br />
conversation is ended.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL2013 Out of memory creating terminal<br />
control structure<br />
Explanation: The client was unable to allocate<br />
enough memory to create an internal control<br />
structure associated with an emulator or EPI<br />
terminal.<br />
System Action: The message is written to the<br />
error log and processing continues. The control<br />
structure is not created.<br />
User Response: Try altering the values in the<br />
client initialization file to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL2014 Unable to find terminal entry<br />
(session id, index, name)<br />
Explanation: The client was unable to locate an<br />
internal control structure associated with a<br />
terminal or EPI program. This may occur if an
ATI request is received for a terminal that no<br />
longer exists because either the client or the<br />
terminal was shut while the ATI was in transit.<br />
System Action: The message is written to the<br />
error log and client processing continues but the<br />
emulator may be unable to continue.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL2015 Unable to find server entry (link<br />
id)<br />
Explanation: The client received an event<br />
associated with an unconnected server.<br />
System Action: The message is written to the<br />
error log and processing continues. The event is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL2016 Invalid communications event<br />
identifier (event id)<br />
Explanation: The client received an unknown<br />
event from one of the communications protocol<br />
drivers.<br />
System Action: The message is written to the<br />
error log and processing continues. The event is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL2018 Internal function error (function,<br />
error)<br />
Explanation: An internal function failed.<br />
System Action: The message is written to the<br />
error log and processing continues. The function<br />
name and error code are logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL2021 ECI request (SessId=session,<br />
Slot=slot, Type=type)<br />
Explanation: The client received an ECI request.<br />
The session value identifies the application and<br />
the slot value identifies the unit of work. The<br />
message is followed by the application’s ECI<br />
parameter block.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2022 ECI COMMAREA Data:<br />
Length=length Null Stripped<br />
Length=null stripped length<br />
Explanation: The client received an ECI request.<br />
The length value gives the length of the<br />
application’s COMMAREA. The null stripped<br />
length gives the length of the COMMAREA after<br />
some, or all, of the trailing nulls have been<br />
removed. The message is followed by the<br />
COMMAREA data.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2023 Client Response (SessId=session,<br />
Slot=slot, ReqRC=value1,<br />
AppRC=value2)<br />
Explanation: The client sent a response to an<br />
application. The session and slot values identify<br />
the application receiving the response. The value1<br />
and value2 values contain the response return<br />
codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2015 CCL2024<br />
CCL2024 Unknown application<br />
(SessId=session)<br />
Explanation: The client tried to send a response<br />
to an unknown application. Often this occurs if<br />
the application has ended before its response was<br />
Messages 9
CCL2025 CCL2031<br />
received. The session value identifies the<br />
application.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2025 ECI request held (SessId=session,<br />
Slot=slot)<br />
Explanation: The client held an ECI request<br />
while the connection to a server was established.<br />
The session and slot values identify the<br />
application.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2026 Server List request (SessId=session,<br />
Space=size)<br />
Explanation: The client received a request to<br />
supply a list of server names and descriptions.<br />
The session value identifies the application<br />
issuing the request and the size value indicates<br />
the amount of space provided to contain the<br />
result.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2027 Server Status request<br />
(SessId=session, Space=size)<br />
Explanation: The client received a request to<br />
supply a list of active server names, descriptions,<br />
and status. The session value identifies the<br />
application issuing the request and the size value<br />
indicates the amount of space provided to<br />
contain the result.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
10 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL2028 Server Start request<br />
(SessId=session)<br />
Explanation: The client received a request to<br />
start a connection to a server. The session value<br />
identifies the application issuing the request. The<br />
message is followed by the name of the required<br />
server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2029 Server Stop request<br />
(SessId=session, Type=type)<br />
Explanation: The client received a request to<br />
stop a connection to a server. The session value<br />
identifies the application issuing the request and<br />
type indicates if a stop or abort was requested.<br />
The message is followed by the name of the<br />
required server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2030 Server Security request<br />
(SessId=session)<br />
Explanation: The client received a request to set<br />
server security logon information. The session<br />
value identifies the application issuing the<br />
request. The message is followed by the new<br />
security details.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2031 Closedown request<br />
(SessId=session, Type=type)<br />
Explanation: The client received a request to<br />
terminate. The session value identifies the<br />
application issuing the request and type indicates<br />
if a stop or abort was requested.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.
User Response: None.<br />
CCL2032 Application terminated<br />
(SessId=session)<br />
Explanation: The client received a notification<br />
that an application has terminated. The session<br />
value identifies the terminating application.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2034 TR Install request (SessId=session,<br />
TermId=index, Type=type)<br />
Explanation: The client received a request to<br />
install a terminal from an emulator or EPI<br />
application. The session value identifies the<br />
application, the index value gives the EPI<br />
terminal index and the type value identifies an<br />
emulator or EPI request. The message is followed<br />
by the requested terminal install details.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2035 TR request (SessId=session,<br />
TermId=index, Type=type)<br />
Explanation: The client received a terminal<br />
request from an emulator or EPI application. The<br />
session value identifies the application, the index<br />
value gives the EPI terminal index and the type<br />
value identifies an emulator or EPI request.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2036 TR TIOA Data: Length=length<br />
Explanation: The client received a terminal<br />
request from an emulator or EPI application. The<br />
length value gives the length of the terminal or<br />
application’s TIOA data. The message is followed<br />
by the TIOA data.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2037 TR Install request held<br />
(SessId=session, TermId=index)<br />
Explanation: The client held an emulator or EPI<br />
request while the connection to a server was<br />
established. The session and index values identify<br />
the application and terminal.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2038 Service Trace Enable request<br />
(SessId=session)<br />
Explanation: The client received a request to<br />
enable service tracing. The session value identifies<br />
the application issuing the request.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2040 Service Trace Disable request<br />
(SessId=session)<br />
Explanation: The client received a request to<br />
disable service tracing. The session value<br />
identifies the application issuing the request.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2032 CCL2044<br />
CCL2044 Out of memory creating client<br />
control structure<br />
Explanation: The client was unable to allocate<br />
enough memory to create an internal control<br />
structure.<br />
System Action: The message is written to the<br />
error log and processing continues if possible.<br />
User Response: Try altering the values in the<br />
client initialization file to provide the client with<br />
a larger free memory pool or to reduce the<br />
Messages 11
CCL2045 CCL2055<br />
overall memory requirements.<br />
CCL2045 Request directed to server server<br />
Explanation: The client routed a request to the<br />
named server. The server value identifies the<br />
server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2048 Maximum trace data size set to<br />
size<br />
Explanation: The client set the maximum trace<br />
data size. The size value indicates the new<br />
maximum trace data size.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2050 Error and Logon prompt request<br />
(SessId=session, Type=type)<br />
Explanation: The client received a request to<br />
enable or suppress error and logon prompts. The<br />
session value identifies the application issuing the<br />
request and the type value indicates the request<br />
type.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2051 <strong>CICS</strong> system transaction tran<br />
failed on server server<br />
Explanation: A client system transaction failed<br />
to run on the named server. If connecting to a<br />
<strong>CICS</strong>/400 server, a failure of transaction CCIN<br />
indicates that the server is not available. The tran<br />
value indicates the name of the failed transaction<br />
and server indicates the failing server.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
12 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
your service organization.<br />
CCL2052E Cannot open error log file file<br />
name<br />
Explanation: The client could not open or write<br />
to the specified error log file.<br />
System Action: Log messages are lost.<br />
User Response: Check that the name specified<br />
in the LogFile parameter in the client<br />
initialization file is correct and accessible.<br />
CCL2053I Cannot open trace file file name -<br />
tracing has been disabled<br />
Explanation: The client could not open or write<br />
to the specified trace file.<br />
System Action: Trace information is lost.<br />
User Response: Check that the name specified<br />
in the TraceFile parameter in the client<br />
initialization file is correct and accessible.<br />
CCL2054I A <strong>CICS</strong> server error has occurred<br />
Explanation: An error occurred on a <strong>CICS</strong><br />
server with which the client was trying to<br />
communicate.<br />
System Action: Error information is written to<br />
the client error log; client processing continues.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL2055 Connection with server<br />
established (LinkId=link)<br />
Explanation: The client established a connection<br />
with a server. The link value identifies the server<br />
to which the connection was established.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.
CCL2056 Connection with server lost<br />
(LinkId=link)<br />
Explanation: The client lost a connection with a<br />
server. The link value identifies the server to<br />
which the connection was lost.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2057 Incoming conversation request<br />
(LinkId=link, ConvId=conv)<br />
Explanation: The client received an indication<br />
from a server that a new conversation should be<br />
established. The link value identifies the server<br />
requesting the conversation and the conv value<br />
identifies the new conversation.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2058 Incoming conversation data<br />
(ConvId=conv)<br />
Explanation: The client received an indication<br />
from a server that data had been received for an<br />
active conversation; conv identifies the<br />
conversation on which data was received.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2059 Request directed to unknown<br />
server server<br />
Explanation: The client received a requested<br />
routed to an unknown server; server identifies the<br />
unknown server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2060 Request directed to closing server<br />
server<br />
Explanation: The client received a request<br />
routed to a server which was closing down;<br />
server identifies the closing server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2061 MaxServers limit of number has<br />
been reached<br />
Explanation: The client received a request<br />
routed to a new server but was already<br />
connected to its MaxServers limit; number<br />
indicates the current MaxServers setting.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2062 TR Delete request (SessId=session,<br />
TermId=index, TermName=name)<br />
Explanation: The client received a request to<br />
delete a terminal from an emulator or EPI<br />
application. The session value identifies the<br />
application, the index value gives the EPI<br />
terminal index and the name gives the terminal<br />
name.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2063 TR EXIT detected (SessId=session,<br />
TermId=index, TermName=name)<br />
Explanation: The client detected the special<br />
terminal EXIT transaction code from an emulator<br />
or EPI application. The session value identifies<br />
the application, the index value gives the EPI<br />
terminal index, and the name gives the terminal<br />
name.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2056 CCL2063<br />
Messages 13
CCL2064 CCL2082<br />
CCL2064 TR issue ATI tran (SessId=session,<br />
TermId=index, TermName=name)<br />
Explanation: The client requested an emulator<br />
or EPI application terminal to start an ATI<br />
transaction. The tran value gives the name of the<br />
ATI, the session value identifies the application,<br />
the index value gives the EPI terminal index, and<br />
the name gives the terminal name.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2065 MaxRequests limit of number has<br />
been reached<br />
Explanation: The client received a request for a<br />
new conversation but was already at its<br />
MaxRequests limit; number indicates the current<br />
MaxRequests setting.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2070 MaxBufferSize limit of size<br />
exceeded by incoming data length<br />
length<br />
Explanation: The client received data from a<br />
server that exceeded the MaxBufferSize limit. The<br />
size value indicates the current MaxBufferSize<br />
setting and the length value indicates the length<br />
of the incoming data.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the value of<br />
MaxBufferSize in the client initialization file to at<br />
least the size of the incoming data.<br />
CCL2079 Failed to put transport message,<br />
retry number number<br />
Explanation: The client has attempted to put a<br />
transport message to a window owned by the<br />
client application. This has failed, the most likely<br />
reason for this is that the message queue<br />
14 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
associated with the windows client application is<br />
full.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled. The client allows<br />
windows to process messages in the queue and<br />
then tries posting the transport message again, a<br />
number of times.<br />
User Response: Try using SetMessageQueue to<br />
increase the size of the message queue.<br />
CCL2080 Extended request continued with<br />
server server<br />
Explanation: The client continued routing an<br />
extended unit of work request to the named<br />
server. The server value identifies the server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2081 CCIN install response: transaction<br />
not present<br />
Explanation: The server does not support the<br />
CCIN client install transation, this is a normal<br />
response from certain older host <strong>CICS</strong> servers.<br />
These servers cannot support client 3270 terminal<br />
emulation or user written EPI applications.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2082 CCIN install response: transaction<br />
requires security<br />
Explanation: The server requires a userid and<br />
password to be supplied before it will run the<br />
CCIN client install transaction. If no userid and<br />
password has been made available the client will<br />
prompt for one before retrying the connection to<br />
the server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.
CCL2087I Server server, User ID invalid,<br />
please re-enter<br />
Explanation: The userid entered in the previous<br />
security pop-up panel is not known to the<br />
receiving security system.<br />
System Action: The client displays a pop-up<br />
panel allowing a userid and password to be<br />
re-entered or the request to be cancelled.<br />
User Response: Enter a valid userid and<br />
password to allow the request to be processed by<br />
the server.<br />
CCL2088I Server server, Password invalid,<br />
please re-enter<br />
Explanation: The password entered in the<br />
previous security pop-up panel is incorrect.<br />
System Action: The client displays a pop-up<br />
panel allowing a userid and password to be<br />
re-entered or the request to be cancelled.<br />
User Response: Enter a valid userid and<br />
password to allow the request to be processed by<br />
the server.<br />
CCL2089I Server server, Password expired,<br />
please change<br />
Explanation: The password entered in the<br />
previous security pop-up panel has expired.<br />
System Action: The client displays a pop-up<br />
panel allowing the password to be changed or<br />
the request to be cancelled.<br />
User Response: Enter the expired password, a<br />
new password and confirm the new password to<br />
allow the request to be processed by the server.<br />
CCL2090I Server server, New Password<br />
unacceptable, please re-enter<br />
Explanation: The new password entered in the<br />
previous security pop-up panel is unacceptable<br />
to the receiving security system.<br />
System Action: The client displays a pop-up<br />
panel allowing a new password to be supplied<br />
or the request to be cancelled.<br />
User Response: Enter the expired password, a<br />
new password and confirm the new password to<br />
allow the request to be processed by the server.<br />
CCL2091I New and Confirm Passwords do<br />
not match, please re-enter<br />
Explanation: The new password and confirm<br />
passwords entered in the previous security<br />
pop-up panel do not match.<br />
System Action: The client displays a pop-up<br />
panel allowing a new password to be supplied<br />
or the request to be cancelled.<br />
User Response: Enter the expired password, a<br />
new password and confirm the new password to<br />
allow the request to be processed by the server.<br />
CCL2092 About to display a popup<br />
message<br />
Explanation: A popup message is about to be<br />
displayed on the Client daemon system.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2093 Returned from displaying a<br />
Popup Message<br />
Explanation: The popup message has been<br />
cleared, processing continues.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL2087I CCL2158<br />
CCL2158 Default userid has been set to<br />
spaces.<br />
Explanation: The default userid has been set to<br />
a value which contains only spaces.<br />
System Action: The message is logged, and<br />
processing continues.<br />
User Response: When using connection<br />
security, blank userids and passwords are valid<br />
Messages 15
CCL3001E CCL3009E<br />
only if Usedfltuser is set to YES in the <strong>CICS</strong><br />
connection definition.<br />
CCL3001E Errors detected at line number in<br />
file file name<br />
Explanation: Errors were detected at the<br />
specified line in the client initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
and restart the client.<br />
CCL3002E Cannot find client initialization<br />
file file name<br />
Explanation: The specified client initialization<br />
file could not be found.<br />
System Action: The client terminates.<br />
User Response: Ensure that the required<br />
initialization file exists and is correctly specified<br />
when starting the client.<br />
CCL3003E Missing = sign after parameter<br />
parameter<br />
Explanation: An = sign was expected after an<br />
initialization file parameter in the client<br />
initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3004E Parameter text not recognized<br />
Explanation: An unknown parameter starting<br />
with specified text was encountered in the client<br />
initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
16 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL3005E Parameter parameter repeated or<br />
misplaced<br />
Explanation: A valid parameter was<br />
encountered in the wrong position in the client<br />
initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3006E Parameter parameter has invalid<br />
value value<br />
Explanation: A valid parameter had an incorrect<br />
value specified in the client initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3007E Inconsistent values for parameters<br />
parameter 1 and parameter 2<br />
Explanation: The values of certain parameters<br />
specified in the client initialization file have<br />
dependencies on each other. The values for the<br />
two specified parameters are inconsistent.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3008E Required parameter parameter<br />
missing<br />
Explanation: The specified parameter is missing<br />
from the client initialization file and must be<br />
provided.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3009E Not enough memory for client<br />
initialization<br />
Explanation: There was not enough free<br />
memory to process the client initialization file.
System Action: The client terminates.<br />
User Response: Try altering the values in the<br />
client initialization file to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL3010E Missing driver definition for<br />
protocol protocol<br />
Explanation: The value of the protocol<br />
parameter in a Server section of the client<br />
initialization file must match with the name of a<br />
Driver section. No matching driver definition<br />
was found for the named protocol.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3011E Errors detected while reading file<br />
file name<br />
Explanation: Errors were encountered while<br />
reading the client initialization file.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3012E Duplicate section section<br />
definition<br />
Explanation: A Client, Server, or Driver section<br />
in the client initialization file had the same name<br />
as a previously specified section.<br />
System Action: The client terminates.<br />
User Response: Correct the initialization file<br />
error and restart the client.<br />
CCL3013E Unable to access file file name,<br />
rc=rc<br />
Explanation: Errors were encountered while<br />
accessing file file name.<br />
System Action: The client terminates.<br />
User Response: Change the file permissions<br />
and restart the client.<br />
CCL3010E CCL3105<br />
CCL3102 Inbound GDS data error (gds,<br />
length, size)<br />
Explanation: The client received invalid data<br />
from a server. The data does not have a valid<br />
<strong>CICS</strong> data stream header. The gds value should<br />
be either 0x12F2 or 0x12FF, the length value gives<br />
the expected data length, and size gives the true<br />
received length.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3103 Inbound SYNC/ROLL data error<br />
(length, data)<br />
Explanation: The client received invalid data<br />
from a server. The data was not part of a valid<br />
SYNC or ROLLBACK flow. The length values<br />
gives the length of the received data and data<br />
contains the first four bytes.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3104 Inbound FMH43 header error<br />
(length)<br />
Explanation: The client received invalid data<br />
from a server. The data was not a valid <strong>CICS</strong><br />
FMH43 header. The length values gives the<br />
length of the received data.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3105 Inbound <strong>CICS</strong> data stream error<br />
(type, value1, value2)<br />
Explanation: The client received invalid data<br />
from a server. The data was not a valid <strong>CICS</strong><br />
data stream. The type value indicates which part<br />
of the data contained errors, value1 and value2<br />
further identify the error. This message may be<br />
Messages 17
CCL3106 CCL3112E<br />
received if the server does not support signon<br />
capable terminals.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Use the option to request a<br />
non-signon capable terminal. If the problem<br />
persists, contact your service organization.<br />
CCL3106 Out of memory unpacking <strong>CICS</strong><br />
data stream<br />
Explanation: The client was unable to allocate<br />
enough memory to save data from a server.<br />
Normally such data is a COMMAREA associated<br />
with an emulator terminal.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL3107 Inbound FMH5 transaction name<br />
incorrect (data)<br />
Explanation: The client received an invalid<br />
transaction attach request from a server. The only<br />
valid transaction name is CRSR, used to start ATI<br />
requests to a terminal. The data value indicates<br />
the requested transaction name.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3108 Inbound FMH5 header error<br />
(length)<br />
Explanation: The client received invalid data<br />
from a server. The data was not a valid <strong>CICS</strong><br />
FHM5 header. The length value gives the length<br />
of the received data.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
18 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL3109E Cannot connect to server server -<br />
client is already installed<br />
Explanation: The client name specified in the<br />
Client section of the initialization file was already<br />
installed on the specified server.<br />
System Action: The server rejects the client’s<br />
installation request.<br />
User Response: Ensure all client names are<br />
unique within the network or specify the name<br />
as ″*″ to enable a suitable unique name to be<br />
generated automatically.<br />
CCL3110E Cannot connect to server server -<br />
server is busy<br />
Explanation: The specified server was busy and<br />
could not process the client installation request.<br />
System Action: The server rejects the client’s<br />
installation request.<br />
User Response: Retry the request sometime<br />
later when the server is not so busy. If the<br />
problem persists contact your server<br />
administrator.<br />
CCL3111E Cannot connect to server server -<br />
server rejected install request<br />
Explanation: The specified server could not<br />
process the client installation request.<br />
System Action: The server rejects the client’s<br />
installation request, server continues processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information on both the<br />
client and server to determine the cause of the<br />
error.<br />
CCL3112E Cannot connect to server server -<br />
request rejected by server exit<br />
Explanation: A user exit running on the<br />
specified server rejected the request to install the<br />
client definition.<br />
System Action: The server rejects the client’s<br />
installation request, the client continues<br />
processing.
User Response: Check with the server system<br />
administrator to determine why the client<br />
installation request was rejected.<br />
CCL3113 CCIN install request:<br />
ApplId=applid, Codepage=codepage<br />
Explanation: The client invoked the CCIN<br />
system install transaction on a server. The applid<br />
and codepage values indicate the requested client<br />
APPLID and codepage.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3114 CCIN install response:<br />
ApplId=applid, Codepage=codepage,<br />
RC=error<br />
Explanation: The client received the CCIN<br />
system install response from a server. The applid<br />
and codepage values indicate the returned client<br />
APPLID and codepage. The error values are<br />
non-zero if any errors occurred.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3115 CTIN install request:<br />
NetName=name, Model=model,<br />
Codepage=codepage<br />
Explanation: The client invoked the CTIN<br />
terminal install transaction on a server. The name,<br />
model and codepage values indicate the requested<br />
terminal name, model and codepage.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3116 CTIN install response:<br />
NetName=name, TermId=term,<br />
Rc=error<br />
Explanation: The client received the CTIN<br />
terminal install response from a server. The name<br />
and term values indicate the returned terminal<br />
NetName and TermName. The error values are<br />
non-zero if any errors occurred.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3117 PEM verify request: UserId=name<br />
Explanation: The client invoked the password<br />
expiry management (PEM) transaction on a<br />
server to verify a userid and password. The<br />
specified user id is indicated.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3118 PEM change request: UserId=name<br />
Explanation: The client invoked the password<br />
expiry management (PEM) transaction on a<br />
server to change the password of the specified<br />
user id.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3119 PEM response: Rc=error,<br />
CompStatus=value<br />
Explanation: The client received the password<br />
expiry management (PEM) transaction response<br />
from a server. The error value is non-zero if an<br />
error occured. The CompStatus value is set as<br />
follows: 1 = Unknown user id 2=Userid valid,<br />
passwordinvalid3=Useridvalid,password<br />
expired4=Newpasswordunacceptable 5 =<br />
Security function failure 6=Incorrectdata<br />
format<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3113 CCL3119<br />
Messages 19
CCL3120 CCL3228<br />
CCL3120 PEM response data error:<br />
ReqType=Request Type,<br />
ErrorValue=value<br />
Explanation: The client received the password<br />
expiry management (PEM) transaction response<br />
from a server. The data contained in the<br />
corresponding PEM request contained a data<br />
formatting error.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3121E Cannot connect to server server -<br />
invalid codepage specified<br />
Explanation: The codepage value sent to the<br />
server was rejected.<br />
System Action: The server rejects the client’s<br />
installation request, the client continues<br />
processing.<br />
User Response: If the CCSID parameter has<br />
been specified in CTG.INI, check that the value<br />
specified is valid. Otherwise, check with the<br />
server system administrator to determine why<br />
the codepage value was rejected.<br />
CCL3209 Link to server (link) is no longer<br />
available<br />
Explanation: The client tried to communicate<br />
with a server whose connection is currently<br />
unavailable.<br />
System Action: The message is written to the<br />
error log and processing continues. The server is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3221 Unable to find link control<br />
structure (link)<br />
Explanation: The client was unable to locate an<br />
internal control structure associated with a<br />
connection to a server.<br />
20 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: The message is written to the<br />
error log and processing continues. The server is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3222 Unable to find conversation<br />
control structure (conv)<br />
Explanation: The client was unable to locate an<br />
internal control structure associated with a server<br />
conversation.<br />
System Action: The message is written to the<br />
error log and processing continues. The<br />
conversation is ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3225 Invalid communications event<br />
identifier (event)<br />
Explanation: The client received an invalid<br />
internal event from a communications protocol<br />
driver.<br />
System Action: The message is written to the<br />
error log and processing continues. The event is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3227 Conversation (conv) isnotinstate<br />
state<br />
Explanation: The client detected a conversation<br />
to a server in an incorrect state.<br />
System Action: The message is written to the<br />
error log and processing continues. The request<br />
is ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3228 Unable to find protocol control<br />
structure (name, driver)<br />
Explanation: The client was unable to locate an<br />
internal control structure associated with a
communications protocol driver.<br />
System Action: The message is written to the<br />
error log and processing continues. The driver is<br />
ignored.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3229E Cannot load protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module could not be found or<br />
loaded.<br />
System Action: No communication can take<br />
place using the protocol, the client continues<br />
processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3230 Out of memory creating<br />
communications control structure<br />
Explanation: The client was unable to allocate<br />
enough memory to create an internal control<br />
structure associated with communications.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL3231 Comms Load request<br />
(Driver=name)<br />
Explanation: The client communications has<br />
received a request to load a new protocol driver.<br />
The name value indicates the required protocol<br />
driver DLL name.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3232 Comms Load completed<br />
(Driver=name, DrvId=driver,<br />
RC=error)<br />
Explanation: The client completed a request to<br />
load a new protocol driver. The name value<br />
indicates the required protocol driver DLL name,<br />
the driver value indicates the assigned driver<br />
identifier and error indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3233 Loading protocol driver<br />
(DLL=fullname)<br />
Explanation: The client wss loading a new<br />
communications protocol driver DLL; fullname<br />
gives the full file system name of the DLL to be<br />
loaded.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3234 Comms Unload completed<br />
(Driver=name, RC=error)<br />
Explanation: The client completed a request to<br />
unload a protocol driver. The name value<br />
indicates the protocol driver DLL name and error<br />
indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3235 Freeing protocol driver<br />
(DLL=fullname)<br />
Explanation: The client was freeing a<br />
communications protocol driver DLL; fullname<br />
gives the full file system name of the DLL to be<br />
freed.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3229E CCL3235<br />
Messages 21
CCL3236 CCL3243<br />
CCL3236 Comms Open completed<br />
(Server=name, LinkId=link,<br />
RC=error)<br />
Explanation: The client completed a request to<br />
try to establish a new connection with a server.<br />
The name value indicates the server, the link<br />
value contains the assigned link identifier, and<br />
error indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3237 Comms Close completed<br />
(LinkId=link, RC=error)<br />
Explanation: The client completed a request to<br />
close a connection with a server. The link value<br />
identifies the server connection to be closed and<br />
error indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3238 Comms Allocate completed<br />
(LinkId=link, ConvId=conv,<br />
RC=error)<br />
Explanation: The client completed a request to<br />
allocate a new conversation with a server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled. The link value<br />
identifies the server, the conv value contains the<br />
assigned conversation identifier, and error<br />
indicates any error codes.<br />
User Response: None.<br />
CCL3239 Comms Deallocate completed<br />
(ConvId=conv, Reason=reason,<br />
RC=error)<br />
Explanation: The client completed a request to<br />
deallocate a conversation with a server. The conv<br />
value identifies the conversation, the reason and<br />
error values indicate any errors.<br />
System Action: The message is written to the<br />
22 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3240 Comms Accept completed<br />
(ConvId=conv, RC=error)<br />
Explanation: The client completed a request to<br />
accept a new incoming conversation with a<br />
server. The conv value identifies the conversation<br />
and error indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3241 Comms Send completed<br />
(ConvId=conv, RC=error)<br />
Explanation: The client completed a request to<br />
send data over a conversation with a server. The<br />
conv value identifies the conversation and error<br />
indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3242 Comms Send request:<br />
Length=length (ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to send data over a<br />
conversation with a server. The conv value<br />
identifies the conversation and length indicates<br />
the length of data to be sent.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3243 Comms Wait completed<br />
(ConvId=conv, RC=error)<br />
Explanation: The client completed a request to<br />
wait for a response over a conversation with a<br />
server. The conv value identifies the conversation<br />
and error indicates any error codes.<br />
System Action: The message is written to the
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3244 Comms Receive request<br />
(ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to receive data from a<br />
conversation with a server; conv identifies the<br />
conversation.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3245 Comms Receive completed:<br />
Length=length (ConvId=conv,<br />
Reason=reason, RC=error)<br />
Explanation: The client completed a request to<br />
receive data from a conversation with a server.<br />
The conversation remains active. The conv value<br />
identifies the conversation, the length value<br />
contains the length of the data received, and<br />
reason and error indicate any error codes. The<br />
message is followed by the data received.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3246 Comms Complete completed<br />
(ConvId=conv, RC=error)<br />
Explanation: The client completed a request to<br />
finish with data received from a conversation<br />
with a server. The conv value identifies the<br />
conversation and error indicates any error codes.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3247 Error loading DLL fullname<br />
(function, error)<br />
Explanation: The client was unable to load a<br />
communications protocol driver DLL.<br />
System Action: The message is written to the<br />
error log and processing continues. The name of<br />
the failing DLL and the loading function and<br />
error codes are logged.<br />
User Response: Ensure the DLL is available and<br />
correctly named. If the problem persists contact<br />
your service organization.<br />
CCL3248 Comms Unload request<br />
(Driver=name)<br />
Explanation: The client communications has<br />
received a request to unload a protocol driver;<br />
name indicates the protocol driver DLL name.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3249 Comms Open request<br />
(Server=name, Driver=protocol)<br />
Explanation: The client communications has<br />
received a request to try to establish a new<br />
connection with a server. The name value<br />
indicates the server and protocol indicates the<br />
required communications protocol driver.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3250 Comms Close request<br />
(LinkId=link)<br />
Explanation: The client communications has<br />
received a request to close a connection with a<br />
server; link identifies the server connection.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3244 CCL3251<br />
CCL3251 Comms Allocate request<br />
(LinkId=link, Tran=tran)<br />
Explanation: The client communications has<br />
received a request to allocate a new conversation<br />
with a server. The link value identifies the server<br />
Messages 23
CCL3252 CCL3280E<br />
and the tran value gives the name of the<br />
transaction to be attached on the server.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3252 Comms Deallocate request<br />
(ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to deallocate a conversation<br />
with a server; conv identifies the conversation.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3253 Comms Accept request<br />
(ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to accept a new incoming<br />
conversation with a server; conv identifies the<br />
conversation.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3254 Comms Wait request<br />
(ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to wait for a response over a<br />
conversation with a server; conv identifies the<br />
conversation.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3255 Comms Complete request<br />
(ConvId=conv)<br />
Explanation: The client communications has<br />
received a request to finish with data received<br />
from a conversation with a server; conv identifies<br />
the conversation.<br />
24 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3256 Comms Receive completed (last):<br />
Length=length (ConvId=conv,<br />
Reason=reason, RC=error)<br />
Explanation: The client completed a request to<br />
receive data from a conversation with a server.<br />
The conversation has been ended. The conv value<br />
identifies the conversation, the length value<br />
contains the length of the data received, and<br />
reason and error indicate any error codes. The<br />
message is followed by the data received.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3257 Internal CcDrv.Notify returned<br />
return code<br />
Explanation: Data has been received by the<br />
tcpip protocol driver, and the protocol driver<br />
notifies the client of this data. If the notify<br />
completes with return code 3300, then the server<br />
supports conversational pings and a timeout has<br />
occurred. In this case the data received will be<br />
thrown away since the application request has<br />
already timed out.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL3280E Errors occurred while initializing<br />
protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors during<br />
startup.<br />
System Action: No communications can take<br />
place using the protocol, the client continues<br />
processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.
CCL3281E Errors occurred while terminating<br />
protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was closing down.<br />
System Action: The error is ignored and the<br />
client continues processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3282E Errors occurred while connecting<br />
to a server using protocol driver<br />
driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was trying to connect to a server.<br />
System Action: The client cannot communicate<br />
with the server, the client continues processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3283E Errors occurred while<br />
disconnecting from a server using<br />
protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was closing a connection with a server.<br />
System Action: The error is ignored and client<br />
continues processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3284E Errors occurred while starting a<br />
conversation with a server using<br />
protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was starting a new conversation with a<br />
connected server.<br />
CCL3281E CCL3287E<br />
System Action: The request to start the<br />
conversation fails and the client continues<br />
processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3285E Errors occurred while closing a<br />
conversation with a server using<br />
protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was closing a conversation with a connected<br />
server.<br />
System Action: The request to close the<br />
conversation fails and the client continues<br />
processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3286E Errors occurred while sending<br />
data to a server using protocol<br />
driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was sending data over a conversation with a<br />
connected server.<br />
System Action: The request that sent the data<br />
fails and the client continues processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3287E Errors occurred while receiving<br />
data from a server using protocol<br />
driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was receiving data from a conversation with a<br />
connected server.<br />
System Action: The request that required the<br />
data fails and the client continues processing.<br />
Messages 25
CCL3288E CCL3310<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3288E Errors occurred while<br />
communicating with a server<br />
using protocol driver driver<br />
Explanation: The specified communications<br />
protocol driver module reported errors while it<br />
was communicating or trying to communicate<br />
with a server.<br />
System Action: The request that initiated the<br />
communications fails and the client continues<br />
processing.<br />
User Response: Examine the client error log<br />
and, if possible, trace information to determine<br />
the cause of the error.<br />
CCL3299 Internal communications error<br />
(function, error)<br />
Explanation: An internal client communications<br />
function failed.<br />
System Action: The message is written to the<br />
error log and the client terminates. The function<br />
name and error code are logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3300 Before EPI Calltype:<br />
Explanation: The client EPI application is about<br />
to issue EPI call EPI Calltype<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3301 After EPI Calltype: Event: Event,<br />
rc=rc<br />
Explanation: The client EPI application has<br />
issued EPI call EPI Calltype which ended with<br />
return code rc. Event Event also occurred.<br />
System Action: The message is written to the<br />
26 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3302 EPI event information,Idx=Idx<br />
Explanation: This trace entry is issued for a<br />
number of reasons during EPI processing. The<br />
text of the message will describe the particular<br />
instance. Idx is the EPI terminal index.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3303 Before: extended call information<br />
Explanation: This trace entry contains more<br />
information relating to the EPI call detailed in a<br />
previous CCL3300 trace entry for this task.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace and<br />
ApiTraceLevel = 2 is specified in the client<br />
initialization file.<br />
User Response: None.<br />
CCL3304 After: extended call information<br />
Explanation: This trace entry contains more<br />
information relating to the EPI call detailed in a<br />
previous CCL3301 trace entry for this task.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace and<br />
ApiTraceLevel = 2 is specified in the client<br />
initialization file.<br />
User Response: None.<br />
CCL3310 Before ECI Calltype: UOW<br />
Token=UOW token<br />
Explanation: The client ECI application is about<br />
to issue ECI call ECI Calltype<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.
User Response: None.<br />
CCL3311 After ECI Calltype: rc=rc, UOW<br />
Token=UOW token<br />
Explanation: The client ECI application has<br />
issued ECI call ECI Calltype, which completed<br />
with return code rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3312 Notification type for call ECI<br />
Calltype<br />
Explanation: The client ECI application has<br />
been notified using notification type for ECI call<br />
ECI CallType.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3313 Before function name:<br />
Explanation: The client application is about to<br />
issue the call function name<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3314 After function name: rc=rc<br />
Explanation: The client application has issued<br />
the call function name, which completed with<br />
return code rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled and ApiTrace is<br />
specified in the client initialization file.<br />
User Response: None.<br />
CCL3311 CCL3402<br />
CCL3315 Unexpected comms error (internal<br />
return codes rc1 , rc2)<br />
Explanation: An network communications error<br />
occurred.<br />
System Action: The message is written to the<br />
error log and the client continues. The internal<br />
return codes provide information for use by IBM<br />
service groups.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL3400 Unable to find an LDAP server<br />
(rc=rc, Reason=reason)<br />
Explanation: Trying to find the LDAP server<br />
using DNS.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
User Response: To use LDAP contact your<br />
system administrator to set up their DNS<br />
correctly. Otherwise disable LDAP by using the<br />
environment variable or the /z optiononthe<br />
command line.<br />
CCL3401 Unable to retrieve user credentials<br />
Explanation: Trying to get the users credentials<br />
for use with LDAP.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
User Response: To rectify this problem it is<br />
recommended you reinstall the product.<br />
CCL3402 Unable to retrieve LDAP<br />
password (rc=rc, Reason=reason)<br />
Explanation: To retrieve encrypted LDAP<br />
password from the registry.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
User Response: The user must have a user ID<br />
Messages 27
CCL3403 CCL4401<br />
set up to talk to the LDAP server. Check that this<br />
has been done.<br />
CCL3403 Unknown LDAP error (rc=rc,<br />
Reason=reason)<br />
Explanation: An unknown error has occurred<br />
while using LDAP.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
Look at the reason for more guidance.<br />
User Response: None.<br />
CCL3404 Binding error to LDAP server<br />
(rc=rc, Reason=reason)<br />
Explanation: An error occured while trying to<br />
bind to the LDAP server.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
Look at the reason for more guidance.<br />
User Response: None.<br />
CCL3405 Unbinding error to LDAP server<br />
(rc=rc, Reason=reason)<br />
Explanation: An error occurred while trying to<br />
bind to the LDAP server.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the new configuration file.<br />
Look at the reason for more guidance.<br />
User Response: None.<br />
CCL3406 Trying to read LDAP entry error<br />
(rc=rc, Reason=reason,<br />
entry=baseDN)<br />
Explanation: The client tried to read an LDAP<br />
entry, but was unable too.<br />
System Action: This message is written to the<br />
trace file, if tracing is enabled. Look at the reason<br />
for more guidance.<br />
28 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: None.<br />
CCL3407 Entry does not exist (rc=rc,<br />
Reason=reason, entry=baseDN)<br />
Explanation: The client tried to test for<br />
existence of an LDAP entry.<br />
System Action: This message is written to the<br />
trace file, if tracing is enabled. Look at the reason<br />
for more guidance.<br />
User Response: None.<br />
CCL3408 Unable to find any configuration<br />
entry in LDAP server<br />
Explanation: An error occurred while trying to<br />
find a configuration entry on the LDAP server,<br />
but was unable to find any.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
User Response: None.<br />
CCL3409 Unable to write to file<br />
Explanation: An error occurred while trying to<br />
write the new configuration file.<br />
System Action: The message is written to the<br />
log file if the error occurs. The system will<br />
continue by using the existing configuration file.<br />
User Response: Check the security settings on<br />
the ctg.ini file.<br />
CCL4401 TCP/IP not available<br />
Explanation: The TCP/IP protocol driver cannot<br />
issue TCP/IP calls on this system. TCP/IP may<br />
not be installed or may not be active on the<br />
system.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Alter the system configuration<br />
to try to activate or install TCP/IP. If the<br />
problem persists, contact your service personnel.
CCL4402 TCP/IP out of memory for data<br />
buffers<br />
Explanation: The TCP/IP protocol driver could<br />
not allocate enough memory to create the<br />
internal data buffers.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL4403 TCP/IP (to server) no resources<br />
available: RC=error<br />
Explanation: The TCP/IP protocol driver could<br />
not create a TCP/IP socket. The server value<br />
identifies the server and the error value identifies<br />
the TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4404 TCP/IP (to server) unable to<br />
resolve name: RC=error<br />
Explanation: The TCP/IP protocol driver could<br />
not resolve a server host IP name. The server<br />
value identifies the server and the error value<br />
gives the TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Ensure the server IP name or<br />
address is correct and can be resolved by the<br />
local name server. If the problem persists contact<br />
your service organization.<br />
CCL4405 TCP/IP (to server) out of memory<br />
for control blocks<br />
Explanation: The TCP/IP protocol driver could<br />
not allocate enough memory to create the<br />
internal control structures; server identifies the<br />
server.<br />
CCL4402 CCL4408<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL4406 TCP/IP (to server) send failed:<br />
RC=error<br />
Explanation: The TCP/IP protocol driver could<br />
not send data to a server. The server value<br />
identifies the server and the error value gives the<br />
TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4407 TCP/IP (to server) connect failed:<br />
RC=error<br />
Explanation: The TCP/IP protocol driver could<br />
not connect to a server. The server value<br />
identifies the server and the error value gives the<br />
TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4408 TCP/IP (to server) recv failed:<br />
RC=error<br />
Explanation: The TCP/IP protocol driver could<br />
not receive data from a server. The server value<br />
identifies the server and the error value gives the<br />
TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
Messages 29
CCL4409 CCL4415<br />
CCL4409 TCP/IP (to server) error starting<br />
listener<br />
Explanation: The TCP/IP protocol driver could<br />
not start an internal listener function; server<br />
identifies the server.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4410 TCP/IP requires WINSOCK<br />
vrequired (vfound installed)<br />
Explanation: The TCP/IP protocol driver for<br />
Windows requires a WINSOCK DLL of at least<br />
version required, however version found was<br />
found to be installed. The required and found<br />
values indicate the version of WINSOCK<br />
required and found respectively.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Ensure your TCP/IP product<br />
provides a suitable level of the WINSOCK DLL<br />
and the system is correctly configured. If the<br />
problem persists contact your service<br />
organization.<br />
CCL4411 TCP/IP (to server) send data:<br />
Length=length<br />
Explanation: The TCP/IP protocol driver was<br />
about to send data to a server. The server value<br />
identifies the server and the length value contains<br />
the length of the data to be sent. This message is<br />
followed by the data to be sent, which consists of<br />
the client data and a TCP/IP protocol header.<br />
The total data flow may be sent in several pieces.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4412 TCP/IP (to server) receive data:<br />
Length=length<br />
Explanation: The TCP/IP protocol driver<br />
received data from a server. The server value<br />
30 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
identifies the server and the length value contains<br />
the length of the data received. This message is<br />
followed by the data received, which consists of<br />
the data returned to the client and a TCP/IP<br />
protocol header. The total data flow may be<br />
received in several pieces.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4413 TCP/IP (to server) address=ipaddr,<br />
port=port, socket=socket<br />
Explanation: The TCP/IP protocol driver has<br />
established a connection to a server. The server<br />
value identifies the server. The ipaddr, port, and<br />
socket values give the server’s IP address, the<br />
server’s port number, and the socket used,<br />
respectively.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4414 TCP/IP (to server) link failed:<br />
RC=error<br />
Explanation: The TCP/IP link failed. The server<br />
value identifies the server and the error value<br />
gives the TCP/IP error code.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4415 TCP/IP (to server) abend received:<br />
RC=sense code<br />
Explanation: The transaction failed. The server<br />
value identifies the server and the sense code<br />
value gives the FMH7 sense data.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: If the problem persists, contact<br />
your service organization.
CCL4416 TCP/IP (to server) Waiting for<br />
Connect Timer<br />
Explanation: The ConnectTimeOut value in the<br />
Server Section of the initialisation file has been<br />
set to a value other than 0 (the default), and the<br />
connection timer is running.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4417 TCP/IP (to server) TimeOut on<br />
Connect: Rc=error<br />
Explanation: The timer for ConnectTimeOut has<br />
expired and the attempt to connect to the Server<br />
is being terminated.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4418 TCP/IP (to server) Before Send<br />
data Length= length<br />
Explanation: A TCP/IP send is about to be<br />
performed.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4419 TCP/IP (to server) Before Wait<br />
CCB address = address<br />
Explanation: The TCP/IP wait routine has been<br />
entered.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4420 TCP/IP (to server) AfterWaitCCB<br />
address = address, rc= return code<br />
Explanation: The TCP/IP wait routine has been<br />
exitted.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4421 TCP/IP (to server) Need to receive<br />
data of length length, bytes bytes<br />
available<br />
Explanation: The TCP/IP receive processing<br />
information detailing how much data is to<br />
received.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4422 TCP/IP (to server) Before recv for<br />
length length<br />
Explanation: Before the TCP/IP recv is issued.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4423 TCP/IP (to server) After recv got<br />
length length<br />
Explanation: After the TCP/IP recv was issued<br />
and successfully completed.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4424 TCP/IP (to server) Bad recv error<br />
number error<br />
Explanation: The TCP/IP recv got a bad return<br />
code.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4416 CCL4425<br />
CCL4425 TCP/IP Allocation for memory<br />
block failed rc = rc<br />
Explanation: During TCP/IP processing a<br />
memory allocation failed.<br />
Messages 31
CCL4426 CCL4602<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4426 TCP/IP (to server) Errorwhen<br />
attempting to send good ping<br />
response, rc= rc<br />
Explanation: An error occurred when<br />
attempting to send a good ping response.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4427 TCP/IP (to server) Received<br />
unknown ping<br />
Explanation: Received a flow that looks like a<br />
ping but cannot be interpretted by the existing<br />
criteria.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4428 TCP/IP (to server) ErrorinTCP<br />
processing rc = rc<br />
Explanation: At the end of the receive<br />
processing loop, there is an error.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4429 TCP/IP Finished processing<br />
inbound data,rc=rc,<br />
available=bytes<br />
Explanation: This is the end of the processing<br />
loop. For the receive thread to be restarted, rc<br />
needs to be zero and bytes needstobezeroor<br />
positive. If the recv thread is not started, tcp<br />
receives will not occur.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
32 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL4430 TCP/IP (to server) Bad send error<br />
number error<br />
Explanation: The TCP/IP send got a bad return<br />
code.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL4499 TCP/IP (to server) datatobe<br />
received overflows buffer<br />
Explanation: The TCP/IP protocol driver<br />
received more data than its buffer space could<br />
hold. The server value identifies the server, the<br />
data is discarded.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL4601 Memory allocation of display<br />
buffer failed<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
retrieve LU 6.2 information from the APPC<br />
provider.<br />
System Action: The SNA protocol driver is not<br />
initialized.<br />
User Response: Free up some memory and<br />
retry.<br />
CCL4602 Memory allocation of receive<br />
buffer pool failed<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
receive data from any servers.<br />
System Action: The SNA protocol driver is not<br />
initialized.<br />
User Response: Free up some memory and<br />
retry.
CCL4603 Memory allocation of send buffer<br />
failed<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
send data to any servers.<br />
System Action: The SNA protocol driver is not<br />
initialized.<br />
User Response: Free up some memory and<br />
retry.<br />
CCL4605 Begin thread to handle inbound<br />
ATI requests failed<br />
Explanation: Creation of thread, to handle<br />
inbound allocate requests from ATI to client<br />
terminals, failed.<br />
System Action: The SNA protocol driver is not<br />
initialized.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4606 Netname partner LU name has<br />
invalid length for an alias name<br />
Explanation: The specified partner LU name in<br />
the NetName parameter in your client<br />
initialization file has an invalid length for this<br />
SNA protocol driver and LUAliasNames<br />
parameter setting. The maximum length of an<br />
alias name is 8 characters, the minimum length is<br />
1.<br />
System Action: The connection to the partner<br />
LU is not started.<br />
User Response: Refer to the Administration<br />
book to determine whether or not this SNA<br />
protocol driver requires the use of alias names.<br />
Correct the NetName and/or LUAliasNames<br />
parameters in the client initialization file and<br />
retry.<br />
CCL4607 Netname partner LU name has<br />
invalid length for a fully<br />
qualified name<br />
Explanation: The specified partner LU name in<br />
the NetName parameter in your client<br />
CCL4603 CCL4610<br />
initialization file has an invalid length for this<br />
SNA protocol driver and LUAliasNames<br />
parameter setting. The maximum length of a<br />
fully qualified name is 17 characters<br />
(********.********). The minimum length is 1.<br />
System Action: The connection to the partner<br />
LU is not started.<br />
User Response: Refer to the Administration<br />
book to determine whether or not this SNA<br />
protocol driver supports fully qualified names.<br />
Correct the NetName and/or LUAliasNames<br />
parameters in the client initialization file and<br />
retry.<br />
CCL4608 Memory allocation of link data<br />
block failed for server connection<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
open a link to the specified server.<br />
System Action: The client continues.<br />
User Response: Free up some memory and<br />
retry.<br />
CCL4609 Retrieval of LU 6.2 information<br />
for server connection failed, APPC<br />
return code primary RC, secondary<br />
RC<br />
Explanation: The client SNA protocol driver<br />
was unable to open a link to the specified server<br />
because retrieval of LU6.2 information from the<br />
APPC provider failed. The APPC DISPLAY verb<br />
failed with the specified return code.<br />
System Action: The client continues.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4610 LU 6.2 information for server<br />
connection not all returned on<br />
retrieval<br />
Explanation: The client SNA protocol driver<br />
was unable to open a link to the specified server<br />
because not all of the LU6.2 information could be<br />
obtained from the APPC provider.<br />
Messages 33
CCL4611 CCL4617<br />
System Action: The client continues.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4611 Local LU LU name is not defined<br />
Explanation: The client SNA protocol driver<br />
was unable to open any link using this LU<br />
because it is not defined to IBM Communications<br />
Manager/2.<br />
System Action: The client continues.<br />
User Response: Define the LU to IBM<br />
Communications Manager/2 or correct the<br />
LocalLUName parameter in your client<br />
initialization file and retry.<br />
CCL4612 Partner LU partner LU name is not<br />
defined<br />
Explanation: The client SNA protocol driver<br />
was unable to open any link using this partner<br />
LU because it is not defined to IBM<br />
Communications Manager/2.<br />
System Action: The client continues.<br />
User Response: Define the partner LU to IBM<br />
Communications Manager/2 or correct the<br />
NetName parameter in your client initialization<br />
file and retry.<br />
CCL4613 Communication Subsystem not<br />
loaded, APPC return code primary<br />
RC<br />
Explanation: APPC could not execute the verb<br />
because Communications Manager had not<br />
started APPC. Either Communications Manager<br />
has not been started or it has not been<br />
configured correctly for the application.<br />
System Action: The client continues.<br />
User Response: Start Communications Manager<br />
if it is not active. If the necessary APPC profiles<br />
are not configured, configure them and restart<br />
Communications Manager.<br />
34 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL4614 Open connection to server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb TP_STARTED<br />
failed with the specified return code. The<br />
connection to the specified server has not been<br />
started.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4615 Close connection to server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb TP_ENDED failed<br />
with the specified return code.<br />
System Action: The client connection to the<br />
specified server is closed.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4616 Memory allocation of<br />
conversation data block failed for<br />
server connection<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
start a conversation with the specified server.<br />
System Action: The client continues.<br />
User Response: Free up some memory and<br />
retry.<br />
CCL4617 No contention-winner sessions<br />
free<br />
Explanation: APPC could not allocate a<br />
conversation because no free sessions were<br />
available.<br />
System Action: The client continues.<br />
User Response: Wait until one or more existing
conversations have finished and retry.<br />
CCL4618 SNASVCMG or CPSVCMG is not<br />
a valid mode name, APPC return<br />
code primary RC, secondary RC<br />
Explanation: An attempt was made to allocate a<br />
client conversation in SNASVCMG or CPSVCMG<br />
sessions mode. These are not valid modes.<br />
System Action: The client continues.<br />
User Response: Change the Modename<br />
parameter in your client initialization file and<br />
retry.<br />
CCL4619 Mode name mode name is not<br />
configured, APPC return code<br />
primary RC, secondary RC<br />
Explanation: The specified mode has not been<br />
defined.<br />
System Action: The client continues.<br />
User Response: Check whether the mode has<br />
been configured, and the spelling of the<br />
ModeName parameter in your client initialization<br />
file.<br />
CCL4620 Allocate session to server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb ALLOCATE failed<br />
with the specified return code. A conversation<br />
with the specified server has not been started.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4621 Deallocate session to server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb DEALLOCATE<br />
failed with the specified return code.<br />
System Action: The client continues.<br />
CCL4618 CCL4625<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4622 Begin thread to receive data for<br />
ATI conversation with server<br />
failed<br />
Explanation: A client thread could not be<br />
created to process the queue holding inbound<br />
attach requests; _beginthread failed.<br />
System Action: The SNA protocol driver is not<br />
initialized.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4623 Begin thread to receive data for<br />
conversation with server failed<br />
Explanation: A client thread could not be<br />
created to receive data from the server for the<br />
current conversation; _beginthread failed.<br />
System Action: The conversation is deallocated.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4624 Inbound ATI initialisation failed<br />
with return code return code<br />
Explanation: An attempt to allocate resources<br />
for inbound allocate requests from ATI to client<br />
terminals has failed.<br />
System Action: The client continues but all<br />
inbound request processing is terminated.<br />
User Response: Check SNA configuration for<br />
ATI Side Information Profile entry.<br />
CCL4625 Error processing inbound ATI<br />
request, all ATI processing<br />
terminated<br />
Explanation: An error occurred during an<br />
inbound ATI request.<br />
System Action: The client continues but all<br />
inbound request processing is terminated.<br />
Messages 35
CCL4626 CCL4633<br />
User Response: Contact your system<br />
administrator.<br />
CCL4626 Attach Manager stopped, APPC<br />
return code primary RC, secondary<br />
RC<br />
Explanation: The client received an inbound<br />
ATI attach request but the receive allocate failed<br />
because the attach manager was stopped.<br />
System Action: The inbound allocate request is<br />
rejected.<br />
User Response: Start the attach manager.<br />
CCL4629 Receive_allocate for ATI request<br />
failed with APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb<br />
RECEIVE_ALLOCATE failed with the specified<br />
return code.<br />
System Action: The inbound allocate request is<br />
rejected.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4630 Send data to server failed with<br />
APPC return code primary RC,<br />
secondary RC<br />
Explanation: The APPC verb SEND_DATA<br />
failed with the specified return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
36 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL4631 Receive data from server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb<br />
RECEIVE_AND_POST failed with the specified<br />
return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4632 Error receiving data from server,<br />
APPC what_received return<br />
parameter is APPC return code<br />
Explanation: An APPC RECEIVE returned an<br />
unexpected data_received or conversation<br />
status_received indicator.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4633 Memory allocation of receive<br />
buffer failed<br />
Explanation: There was insufficient free<br />
memory for the client SNA protocol driver to<br />
receive data on the current conversation.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Free up some memory and<br />
retry the transaction.
CCL4634 Create semaphore for<br />
ReceiveAndPost failed, return<br />
code operating system return code<br />
Explanation: An attempt to set post semaphore<br />
for receiving conversation data failed.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4635 Allocate session to server failed,<br />
TP name TP name unknown,<br />
APPC return code primary RC,<br />
secondary RC<br />
Explanation: The server rejected the incoming<br />
attach because the client or client application<br />
specified a TP name that the server did not<br />
recognize.<br />
System Action: The client continues.<br />
User Response: Ensure that the specified TP is<br />
installed on the server.<br />
CCL4636 Allocate session to server failed<br />
with APPC return code primary<br />
RC, secondary RC. Retry<br />
Explanation: APPC could not allocate a<br />
conversation but retrying without intervention<br />
may succeed. APPC was probably unable to<br />
activate a link or a session.<br />
System Action: The client continues.<br />
User Response: Retry the operation. If retrying<br />
does not succeed, see your APPC Programming<br />
Reference information for further information or<br />
contact your system administrator.<br />
CCL4637 Allocate session to server failed<br />
with APPC return code primary<br />
RC, secondary RC; no retry<br />
Explanation: APPC could not allocate a<br />
conversation and intervention is required to<br />
correct the problem.<br />
CCL4634 CCL4640<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information or contact your system<br />
administrator.<br />
CCL4638 Prepare to receive data from server<br />
failed with APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb<br />
PREPARE_TO_RECEIVE failed with the specified<br />
return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4639 Receive data from server failed<br />
with APPC return code primary<br />
RC, secondary RC<br />
Explanation: The APPC verb<br />
RECEIVE_IMMEDIATE failed with the specified<br />
return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4640 Error receiving data from server,<br />
APPC what_received return<br />
parameter is APPC return code<br />
Explanation: An APPC RECEIVE returned an<br />
unexpected data_received or conversation<br />
status_received indicator.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
Messages 37
CCL4641 CCL4649<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4641 Send data and deallocate to server<br />
failed with APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb SEND_DATA with<br />
DEALLOCATE type failed with the specified<br />
return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4642 Invalid number of parameters<br />
defined for TP program EXE name<br />
Explanation: The TP program was invoked<br />
because of an inbound allocate request but the<br />
IBM Communications Manager definition for the<br />
TP program has an invalid number of<br />
parameters defined.<br />
System Action: The inbound allocate request is<br />
rejected.<br />
User Response: Refer to the Administration<br />
book, correct the TP definition, and retry.<br />
CCL4643 Invalid TP name parameter<br />
defined for TP program EXE name<br />
Explanation: The TP program was invoked<br />
because of an inbound allocate request but the<br />
IBM Communications Manager definition for the<br />
TP program has an invalid TP name parameter<br />
defined.<br />
System Action: The inbound allocate request is<br />
rejected.<br />
User Response: Refer to the Administration<br />
book, correct the TP definition, and retry.<br />
38 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL4646 APPC send data: Length=length<br />
Explanation: This is trace data sent to the server<br />
by the client SNA protocol driver.<br />
System Action: None.<br />
User Response: None.<br />
CCL4647 APPC receive data: Length=length<br />
Explanation: This is trace data received from<br />
the server by the client SNA protocol driver.<br />
System Action: None.<br />
User Response: None.<br />
CCL4648 Receive data from server<br />
unsuccessful after partial data<br />
received, APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb<br />
RECEIVE_IMMEDIATE failed with the specified<br />
return code after some data had already been<br />
received.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Try altering the SnaRetryCount<br />
parameter in the client initialization file and<br />
retry. Refer to the Administration book.<br />
CCL4649 Post on receipt of data from server<br />
failed with APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb<br />
POST_ON_RECEIPT failed with the specified<br />
return code.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.
CCL4650 Partner LU name netname is not<br />
fully qualified<br />
Explanation: The partner LU name specified in<br />
the NetName parameter in your client<br />
initialization file was not qualified by the SNA<br />
network name (NETID). The format is<br />
NETID.LU_NAME.<br />
System Action: The connection to the partner<br />
LU is not started.<br />
User Response: If using real LU names, correct<br />
the NetName parameter and retry. If using alias<br />
LU names, set the LUAliasNames parameter to Y<br />
and retry.<br />
CCL4651 Allocate session to server<br />
unsuccessful after number retry<br />
attempts, APPC return code<br />
primary RC, secondary_RC<br />
Explanation: The attempt to allocate a session<br />
to the specified server was unsuccessful after the<br />
number of retries specified in your client<br />
initialization file.<br />
System Action: The client continues.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4652 Conversation with server failed,<br />
APPC return code primary RC,<br />
retry<br />
Explanation: A temporary failure prematurely<br />
ended the conversation.<br />
System Action: The client continues.<br />
User Response: Retry the operation. If retrying<br />
does not succeed, see your APPC Programming<br />
Reference information for further information, or<br />
contact your system administrator.<br />
CCL4653 Conversation with server failed,<br />
APPC return code primary RC, no<br />
retry<br />
Explanation: A permanent failure prematurely<br />
ended the conversation. The link to the server<br />
has probably failed.<br />
CCL4650 CCL4656<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information or contact your system<br />
administrator.<br />
CCL4654 CNOS for mode mode sessions to<br />
server failed, APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb CNOS failed with<br />
the specified return code. The connection to the<br />
specified server has not been started.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information, or contact your system<br />
administrator.<br />
CCL4655 Partner LU server maximum<br />
session limit is zero, APPC return<br />
code primary RC, secondary RC<br />
Explanation: The APPC verb CNOS failed<br />
because the local maximum session limit of the<br />
partner LU is 0. The connection to the specified<br />
server has not been started.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
the particular error, or contact your system<br />
administrator.<br />
CCL4656 Mode mode not recognized by<br />
partner LU, APPC return code<br />
primary RC, secondary RC<br />
Explanation: The APPC verb CNOS failed as<br />
the partner LU does not recognize the specified<br />
mode name. The connection to the specified<br />
server has not been started.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
the particular error, or contact your system<br />
administrator.<br />
Messages 39
CCL4657 CCL4663<br />
CCL4657 SNA Server has no active services<br />
Explanation: The client SNA protocol driver<br />
was unable to open a link to the specified server<br />
because SNA server has no active services.<br />
System Action: The client continues.<br />
User Response: Activate the relevant service via<br />
SNA Server Administration or contact your<br />
system administrator.<br />
CCL4658 WinAPPCStartup failed with<br />
return code Windows APPC RC<br />
Explanation: The client SNA protocol driver<br />
was unable to open a link to the specified server<br />
because it failed to register itself with the<br />
currently installed Windows APPC<br />
implementation.<br />
System Action: The client continues.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4659 Local LU LU name is not defined<br />
on an active service/node<br />
Explanation: The client SNA protocol driver<br />
was unable to open any link using this LU<br />
because it is not defined on an active SNA<br />
service/node.<br />
System Action: The client continues.<br />
User Response: Activate the relevant service<br />
SNA service or define the LU to an active SNA<br />
service/node or correct the LocalLUName<br />
parameter in your client initialization file and<br />
retry.<br />
CCL4660 Partner LU partner LU name is not<br />
defined in a connection with local<br />
LU LU name<br />
Explanation: The client SNA protocol driver<br />
was unable to open any link using this partner<br />
LU because it is not defined in a connection with<br />
the specified local LU on an active SNA<br />
service/node.<br />
System Action: The client continues.<br />
40 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: Define a connection between<br />
the specified local and partner LUs on an active<br />
SNA service/node or correct the NetName<br />
parameter in your client initialization file and<br />
retry.<br />
CCL4661 SNA stack component not loaded<br />
or terminated, APPC return code<br />
primary RC<br />
Explanation: APPC could not execute the verb<br />
because a component of the product providing<br />
the SNA transport could not be loaded or<br />
terminated whilst processing the verb.<br />
System Action: The client continues.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4662 Load of SNA stack library DLL<br />
name failed, return code Windows<br />
return code<br />
Explanation: LoadLibrary failed, the client<br />
could not load the specified dynamic link library.<br />
System Action: The client SNA protocol driver<br />
is not loaded.<br />
User Response: Install and configure one of the<br />
supported products for SNA transport, if this has<br />
not already been done, and ensure that the DLL<br />
is in the LoadLibrary search path; then retry. Or<br />
contact your system administrator.<br />
CCL4663 Load of client driver DLL name by<br />
TP program EXE name failed with<br />
return code Windows return code<br />
Explanation: LoadLibrary failed, the client<br />
inbound ATI TP could not load the specified<br />
dynamic link library.<br />
System Action: The ATI request is rejected.<br />
User Response: Contact your system<br />
administrator.
CCL4664 TP program EXE name failed with<br />
an internal error, return code value<br />
Explanation: The client inbound ATI TP failed<br />
due to an internal error.<br />
System Action: The ATI request is rejected.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4665 TP program not available on<br />
server, APPC return code primary<br />
RC, secondary RC, retry<br />
Explanation: APPC could not start a remote TP<br />
program retrying without intervention may<br />
succeed.<br />
System Action: The client continues.<br />
User Response: Retry the operation. If retrying<br />
does not succeed, see your APPC Programming<br />
Reference information for further information or<br />
contact your system administrator.<br />
CCL4666 TP program not available on<br />
server, APPC return code primary<br />
RC, secondary RC, no retry<br />
Explanation: APPC could not start a remote TP<br />
program and intervention is required to correct<br />
the problem. The remote server is probably not<br />
available.<br />
System Action: The client continues.<br />
User Response: Ensure the remote server is<br />
available and if the problem persits ee your<br />
APPC Programming Reference information for<br />
further information or contact your system<br />
administrator.<br />
CCL4667 SNA Server not configured for<br />
inbound requests, APPC return<br />
code primary RC, secondary RC<br />
Explanation: The APPC verb<br />
RECEIVE_ALLOCATE failed as SNA Server has<br />
not been correctly configured to receive inbound<br />
ATI requests.<br />
System Action: The client continues.<br />
CCL4664 CCL4671<br />
User Response: If inbound ATI request<br />
processing is required, refer to the<br />
Administration book on how to configure SNA<br />
Server.<br />
CCL4668 SNA node not started, APPC<br />
return code primary RC<br />
Explanation: The SNA node has not been<br />
started.<br />
System Action: The client continues.<br />
User Response: Start the SNA node and retry<br />
the operation.<br />
CCL4669 Real LU names not supported by<br />
current client SNA driver.<br />
Explanation: The client SNA driver specified in<br />
the client initialization file does not support LU<br />
names specified as real names.<br />
System Action: The connection to the server is<br />
not started.<br />
User Response: Specify the local and partner<br />
LU names in the client initialization file as alias<br />
names, set the LUAliasNames parameter to Y and<br />
retry.<br />
CCL4670 Communications subsystem<br />
abended, APPC return code<br />
primary RC, secondary RC<br />
Explanation: Either the APPC provider has<br />
abended or has not been configured properly on<br />
the client machine.<br />
System Action: The connection to the server is<br />
not started.<br />
User Response: Check the configuration of the<br />
APPC provider on the <strong>CICS</strong> client machine. If<br />
using NWSAA v2.2, check that the NDS<br />
configuration for the NWSAA client is correct.<br />
CCL4671 LU alias LU alias name is not<br />
defined<br />
Explanation: The specified LU alias is not<br />
defined in the APPC provider.<br />
Messages 41
CCL4672 CCL4677<br />
System Action: The connection to the server is<br />
not started.<br />
User Response: If using alias LU names, define<br />
the LU alias and retry. If using real LU names,<br />
set the LUAliasNames parameter to N in the client<br />
initialisation file and retry.<br />
CCL4672 Partner LU alias LU alias name or<br />
mode mode name is unknown,<br />
APPC return code primary RC,<br />
secondary RC<br />
Explanation: If using real LU names, the<br />
specified mode is not defined. If using alias LU<br />
names, either the partner LU alias supplied in<br />
the Netname parameter in the client initialisation<br />
file is not defined, or the mode is not defined, in<br />
the APPC provider.<br />
System Action: The connection to the server is<br />
not started.<br />
User Response: Check that the parameters in<br />
the client initialisation match the definitions in<br />
the APPC provider.<br />
CCL4673 Conversation with server failed,<br />
APPC return code primary RC,<br />
secondary RC<br />
Explanation: There has been a failure to allocate<br />
a conversation or to receive data from the<br />
specified server. The link to the server has<br />
probably failed.<br />
System Action: The client continues.<br />
User Response: Refer to your APPC<br />
Programming Reference information for further<br />
information or contact your system<br />
administrator.<br />
CCL4674 TP program TP name abended on<br />
server server, APPC return code<br />
primary RC<br />
Explanation: The specified TP program abended<br />
on the given server. If the TP program is CTIN,<br />
then this may be because the server has been<br />
recycled since running CCIN.<br />
System Action: The client continues. If the TP<br />
42 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
program is CTIN, the client will attempt to<br />
reconnect to the server and retry the request.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4675 Wait on semaphore for<br />
ReceiveAndPost failed, return<br />
code operating system return code<br />
Explanation: An attempt to wait on a<br />
semaphore for conversation data, after successful<br />
completion of the receive verb, failed.<br />
System Action: The client sends a deallocate<br />
abend to the server to terminate the<br />
conversation.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4676 Protocol driver failed to notify<br />
client of a data event, return code<br />
internal return code<br />
Explanation: The protocol driver’s attempt to<br />
notify the client of a data event failed.<br />
System Action: The protocol driver sends a<br />
deallocate abend to the server to terminate the<br />
conversation.<br />
User Response: Contact your system<br />
administrator.<br />
CCL4677 Callback for<br />
RECEIVE_AND_POST for<br />
unknown convid APPC conv_id<br />
received<br />
Explanation: The protocol driver’s callback<br />
function was called for the specified<br />
conversation, but it was not in the list of<br />
conversations for which a RECEIVE_AND_POST<br />
call had been made.<br />
System Action: The event is ignored.<br />
User Response: Contact your system<br />
administrator.
CCL5800 TCP62: TCP/IP not available<br />
Explanation: TCP/IP is not started and may not<br />
have been configured or installed.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Make sure TCP/IP is active<br />
before starting the TCP62 protocol driver.<br />
CCL5801 TCP62: WINSOCK required or later<br />
required(found installed)<br />
Explanation: The TCP62 protocol driver for<br />
Windows requires a WINSOCK DLL of at least<br />
version required, however version found was<br />
found to be installed. The required and found<br />
values indicate the version of WINSOCK<br />
required and found respectively.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Ensure your TCP/IP product<br />
provides a suitable level of the WINSOCK DLL<br />
and the system is correctly configured. If the<br />
problem persists contact your service<br />
organization.<br />
CCL5802 TCP62: Out of memory for data<br />
buffers<br />
Explanation: The TCP62 protocol driver could<br />
not allocate enough memory to create the<br />
internal data buffers.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL5803 TCP62: Out of memory for control<br />
blocks<br />
Explanation: The TCP62 protocol driver could<br />
not allocate enough memory to create the<br />
internal control structures.<br />
CCL5800 CCL5807<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL5804 TCP62: Failure to create<br />
semaphores<br />
Explanation: An attempt to create a system<br />
semaphore failed.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Contact your system<br />
administrator.<br />
CCL5805 TCP62: Unexpected TCP/IP return<br />
code error on socket socknum<br />
Explanation: The TCP62 protocol driver<br />
detected an error return code from TCP/IP. The<br />
error value gives the TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL5806 TCP62: Failure to create threads<br />
Explanation: An attempt to begin a thread (or<br />
pthread) failed.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Contact your system<br />
administrator.<br />
CCL5807 TCP62: Invalid MODENAME<br />
modename<br />
Explanation: An attempt was made to allocate a<br />
client conversation in SNASVCMG or CPSVCMG<br />
sessions mode. These are not valid modes.<br />
Messages 43
CCL5808 CCL5814<br />
System Action: The client continues.<br />
User Response: Change the modename<br />
parameter in your client initialization file and<br />
retry.<br />
CCL5808 TCP62: Netname partner LU name<br />
has an invalid length for a fully<br />
qualified name<br />
Explanation: The specified partner LU name in<br />
the NetName parameter in your client<br />
initialization file has an invalid length for the<br />
TCP62 protocol driver. The maximum length of a<br />
fully qualified name is 17 characters<br />
(********.********). The minimum length is 1.<br />
System Action: The connection to the partner<br />
LU is not started.<br />
User Response: Correct the NetName parameter<br />
in your client initialization file and retry.<br />
CCL5809 TCP62: Partner LU name partner<br />
LU name is not fully qualified<br />
Explanation: The partner LU name specified in<br />
the NetName parameter in your client<br />
initialization file was not qualified by the SNA<br />
network name (NETID). The format is<br />
NETID.LU_NAME.<br />
System Action: The connection to the partner<br />
LU is not started.<br />
User Response: Correct the NetName parameter<br />
and retry.<br />
CCL5810 TCP62: No contention-winner<br />
sessions free<br />
Explanation: TCP62 could not allocate a<br />
conversation because no free sessions were<br />
available.<br />
System Action: The client continues.<br />
User Response: Wait until one or more existing<br />
conversations have finished and retry.<br />
44 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL5811 TCP62: Unresolved host name host<br />
IP name, TCP/IP Rc=error<br />
Explanation: The TCP62 protocol driver could<br />
not resolve a server host IP name. The error value<br />
gives the TCP/IP error code.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Ensure the server IP name or<br />
address is correct and can be resolved by the<br />
local name server. If the problem persists contact<br />
your service organization.<br />
CCL5812 TCP62: Server server name does not<br />
recognise mode mode name<br />
Explanation: The APPC verb CNOS failed as<br />
the partner LU does not recognize the specified<br />
mode name. The connection to the specified<br />
server has not been started.<br />
System Action: The client continues.<br />
User Response: Correct the ModeName<br />
parameter in your client initialization file and<br />
retry, or contact your system administrator.<br />
CCL5813 TCP62: Session session id failed to<br />
connect<br />
Explanation: The TCP62 protocol driver could<br />
not connect to a server. The session id value<br />
contains the server name.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Check that TCP62 is using the<br />
same TCP/IP port as the server. Check with your<br />
administrator that the server is available. If the<br />
problem persists, contact your service<br />
organization.<br />
CCL5814 TCP62: Session session id connect<br />
timed out<br />
Explanation: The TCP62 protocol driver could<br />
not connect to a server. The session id value<br />
contains the server name.<br />
System Action: The message is written to the
error log and processing continues.<br />
User Response: Check with your administrator<br />
that the server is available. If the problem<br />
persists, contact your service organization.<br />
CCL5815 TCP62: Session session id<br />
MPTNCONN rejected,<br />
Rc=primary,secondary, sense<br />
data=sense data<br />
Explanation: The TCP62 protocol driver could<br />
not connect to a server. The session id value<br />
contains the server name. There may be MPTN<br />
primary and secondary error codes or SNA sense<br />
data.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Look up the SNA sense data in<br />
the SNA Formats book for an explanation. Check<br />
with your administrator that the server is<br />
available. If the problem persists, contact your<br />
service organization.<br />
CCL5816 TCP62: The current user does not<br />
have the required permission<br />
Explanation: On UNIX systems the TCP62<br />
protocol driver must have root permissions to<br />
use TCP/IP port numbers less than 1024.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Contact your system<br />
administrator for guidance on whether to run<br />
with root permissions or to use an alternative<br />
TCP/IP port number.<br />
CCL5817 TCP62: Session session id remote<br />
node inactive<br />
Explanation: The TCP62 protocol driver lost<br />
contact with a server which did not respond to<br />
inactivity polling. The session id value contains<br />
the server name.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
CCL5815 CCL5820<br />
User Response: Check with your administrator<br />
that the server is available. If the problem<br />
persists, contact your service organization.<br />
CCL5818 TCP62: TCP/IP port port already in<br />
use<br />
Explanation: The TCP62 protocol driver can not<br />
be started because it is configured to use TCP/IP<br />
port number port which is in use by another<br />
program.<br />
System Action: The message is written to the<br />
error log and processing continues, but the<br />
TCP62 protocol is unavailable for use.<br />
User Response: Find the program (e.g.<br />
PCOMM) that is running and configured to use<br />
the same TCP/IP port number. Either stop that<br />
program, or configure it or the TCP62 protocol<br />
driver to use a different port.<br />
CCL5819 TCP62: Out of memory for<br />
peek-ahead buffer<br />
Explanation: The TCP62 protocol driver could<br />
not allocate enough memory to create the<br />
internal peek-ahead buffer.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Try altering the values in the<br />
client initialization file, to provide the client with<br />
a larger free memory pool or to reduce the<br />
overall memory requirements.<br />
CCL5820 TCP62: Attempt to open server<br />
server1 which is a duplicate of<br />
server2<br />
Explanation: Server definitions must differ in<br />
either local LU name, network name, or mode.<br />
System Action: The message is written to the<br />
error log and processing continues.<br />
User Response: Existing applications that use<br />
different server names to send requests to the<br />
same <strong>CICS</strong> region can continue to work if a user<br />
exit is coded to redirect requests. A sample user<br />
exit that does this is provided; see the samples<br />
documentation for more details.<br />
Messages 45
CCL5834 CCL6504I<br />
CCL5834 TCP62: Link close processing did<br />
not complete successfully<br />
Explanation: The processing to close the link to<br />
the server did not complete within the expected<br />
time.<br />
System Action: This message is written to the<br />
error log, and processing continues.<br />
User Response: It is recommended that you<br />
restart the client. This ensures that the previous<br />
connection has been terminated. If the problem<br />
persists, contact your service organization.<br />
CCL5835 TCP62: Socket closed with<br />
outstanding data<br />
Explanation: The processing to close the link to<br />
the server closed a TCPIP socket that had<br />
outstanding data to be sent.<br />
System Action: This message is written to the<br />
error log and processing continues.<br />
User Response: If the problem persists, contact<br />
your service organisation.<br />
CCL6500I No command line options have<br />
been specified.<br />
Explanation: The <strong>Gateway</strong> daemon is starting<br />
using either the default configuration settings, or<br />
those set with the configuration tool. Default<br />
settings are used when none have been set with<br />
the configuration tool.<br />
System Action: A <strong>Gateway</strong> console session is<br />
started.<br />
User Response: For help on the startup options,<br />
enter ctgstart -?<br />
CCL6501I Command line options have been<br />
specified.<br />
Explanation: The <strong>Gateway</strong> daemon is starting<br />
using options specified from the command<br />
prompt.<br />
System Action: Options specified on the<br />
command line will override those specified using<br />
the configuration tool.<br />
46 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: For help on the startup options,<br />
enter ctgstart -?<br />
CCL6502I Initial ConnectionManagers = n1,<br />
Maximum ConnectionManagers =<br />
n2, Initial Workers = n3,<br />
Maximum Workers = n4, tcp:<br />
Port= n5.<br />
Explanation: n1 ConnectionManager threads<br />
will be created initially. A maximum of n2<br />
ConnectionManager threads will be allowed. One<br />
ConnectionManager thread is needed for each<br />
connected client program. n3 Worker threads will<br />
be created initially. A maximum of n4 Worker<br />
threads will be allowed. One Worker thread is<br />
needed for each in progress request. The tcp/ip<br />
protocol handler will accept connections on port<br />
n5.<br />
System Action: The <strong>Gateway</strong> daemon has<br />
started using these values.<br />
User Response: For information only.<br />
CCL6503I Starting with tracing messages on.<br />
Explanation: Extra tracing messages have been<br />
enabled.<br />
System Action: Information passing between<br />
the <strong>Gateway</strong> daemon and the Java client will be<br />
recorded.<br />
User Response: For help on the startup options,<br />
enter ctgstart -?<br />
CCL6504I Starting with debugging messages<br />
on.<br />
Explanation: Debugging messages have been<br />
enabled.<br />
System Action: Debugging information passing<br />
between the <strong>Gateway</strong> and Java client will be<br />
recorded.<br />
User Response: For information only.
CCL6505I Successfully created the initial<br />
ConnectionManager and Worker<br />
threads.<br />
Explanation: ConnectionManager and Worker<br />
threads handle network connections and requests<br />
from or replies to Java clients.<br />
System Action: ConnectionManager will handle<br />
network connections from a particular Java<br />
client, the Worker thread will execute requests<br />
from it.<br />
User Response: For information only.<br />
CCL6506I Client connected. [{0}] - {1}<br />
Explanation: A client program connected. The<br />
connection is being handled by<br />
ConnectionManager {0}. The connection was<br />
made with protocol characteristics {1}.<br />
System Action: If an existing client program is<br />
in execute mode, put the connected client<br />
program in a queue. If there is no client program<br />
in execute mode, execute the connected client<br />
program.<br />
User Response: For information only.<br />
CCL6507I Client disconnected. [{0}] - {1}<br />
Explanation: A client program has<br />
disconnected. The connection was being handled<br />
by ConnectionManager {0}. The connection was<br />
made with protocol characteristics {1}.<br />
System Action: If there is still work in progress,<br />
the ConnectionManager waits for the length of<br />
the closetimeout period for in-progress requests<br />
to complete.<br />
User Response: For information only.<br />
CCL6508I Type Q or - to stop the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
Explanation: Type either character, followed by<br />
the Enter key.<br />
System Action: The <strong>Gateway</strong> daemon will stop.<br />
User Response: For information only.<br />
CCL6505I CCL6514I<br />
CCL6510I TCP/IP hostnames will not be<br />
shown.<br />
Explanation: The -nonames command line<br />
option was specified. This is useful in<br />
environments where a TCP/IP DNS is not<br />
available.<br />
System Action: Any displayed TCP/IP<br />
addresses will not be resolved to TCP/IP<br />
hostnames.<br />
User Response: For information only.<br />
CCL6511I ThreadManager created {0} {1}(s).<br />
Explanation: The ThreadManager created {0}<br />
thread(s) of type {1}<br />
System Action: Create {0} threads of type {1}<br />
User Response: Use the configuration tool to<br />
specify the number of threads that can be<br />
created.<br />
CCL6512I Waiting to receive a request. [{0}]<br />
Explanation: ConnectionManager {0} is waiting<br />
for an inbound request.<br />
System Action: When a request is received,<br />
ConnectionManager will allocate a worker<br />
thread.<br />
User Response: For information only.<br />
CCL6513I About to receive remainder of a<br />
request. [{0}]<br />
Explanation: A header has been received for a<br />
request of type {0}.<br />
System Action: Retrieve information on request<br />
to execute the remainder of request.<br />
User Response: For information only.<br />
CCL6514I Accepting work request. [{0}] [{1}]<br />
Explanation: Worker thread {0} has accepted a<br />
request from ConnectionManager {1}.<br />
System Action: Execute <strong>CICS</strong> request.<br />
Messages 47
CCL6515I CCL6522I<br />
User Response: For information only.<br />
CCL6515I Finished work request. [{0}]<br />
Explanation: Worker thread {0} has successfully<br />
completed a request.<br />
System Action: Send <strong>CICS</strong> reply to client.<br />
User Response: Check <strong>CICS</strong> reply from<br />
<strong>Gateway</strong>.<br />
CCL6516W Outstanding work in progress.<br />
[{0}] [{1}]<br />
Explanation: A client has disconnected from<br />
ConnectionManager {0}, but {1} work requests<br />
are still in progress.<br />
System Action: A ConnectionManager will not<br />
become available to handle another connection<br />
until the work has been finished.<br />
User Response: Wait for requests to finish.<br />
CCL6517I All outstanding work has been<br />
finished. [{0}]<br />
Explanation: Where {0} specifies the<br />
ConnectionManager.<br />
System Action: Wait for next client program<br />
connection or stop gateway.<br />
User Response: Either run a new client<br />
program or quit the gateway.<br />
CCL6518W Cleanups for previous requests<br />
are outstanding. [{0}] [{1}]<br />
Explanation: A client has disconnected from<br />
ConnectionManager {0}, but {1} requests which<br />
require completion are still outstanding.<br />
System Action: The ConnectionManager will<br />
attempt to clean up the allocated resources.<br />
User Response: For information only.<br />
48 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6519I Attempts have been made to clean<br />
up all unfinished requests.<br />
Explanation: The <strong>Gateway</strong> has finished trying<br />
to cleanup allocated resources for the<br />
disconnected client.<br />
System Action: None.<br />
User Response: For information only.<br />
CCL6520I This request has registered a<br />
cleanup object. [{0}]<br />
Explanation: A Request has been received<br />
which has provided an associated cleanup object.<br />
System Action: The ConnectionManager stores<br />
this cleanup object in case it needs to cleanup the<br />
resource on behalf of the client application.<br />
User Response: For information only.<br />
CCL6521I This request has updated an<br />
already registered cleanup object.<br />
[{0}]<br />
Explanation: A Request has been received<br />
which has provided an associated cleanup object,<br />
but one already exists for this allocated resource.<br />
System Action: The ConnectionManager<br />
replaces the stored cleanup object with this new<br />
one.<br />
User Response: For information only.<br />
CCL6522I This is a cleanup request,<br />
corresponding entry in the<br />
cleanup table removed. [{0}]<br />
Explanation: A request has been received from<br />
an application which cleans up an allocated<br />
resource.<br />
System Action: The ConnectionManager<br />
removes its stored cleanup object for that<br />
resource.<br />
User Response: For information only.
CCL6523I About to execute work request.<br />
[{0}]<br />
Explanation: Where {0} specifies the Worker<br />
thread.<br />
System Action: Executing request.<br />
User Response: For information only.<br />
CCL6524I Successfully started handler for<br />
the {0}: protocol.<br />
Explanation: Where {0} specifies the protocol<br />
type.<br />
System Action: <strong>Gateway</strong> started with {0}<br />
protocol handler.<br />
User Response: For information only.<br />
CCL6525E Unable to start handler for the {0}:<br />
protocol. [{1}]<br />
Explanation: Where {0} specifies the protocol<br />
type, and {1} specifies the cause of the error. The<br />
most likely cause is that the protocol handler is<br />
attempting to listen on a TCP/IP port that is<br />
already in use.<br />
System Action: <strong>Gateway</strong> forced to stop because<br />
of {0} protocol handler error.<br />
User Response: Check if protocol or port is<br />
available and supported by running gateway.<br />
CCL6526I Parameters passed to {0}: protocol<br />
handler = {1}.<br />
Explanation: The parameters, {1}, defined in the<br />
CTG initialization file have been passed to the {0}<br />
protocol handler.<br />
System Action: <strong>Gateway</strong> started with {0}<br />
protocol handler = {1}.<br />
User Response: For information only.<br />
CCL6527I Using {0} class to provide security<br />
to {1}.<br />
Explanation: The {0} ServerSecurity class is<br />
being used on connection {1}.<br />
CCL6523I CCL6531W<br />
System Action: <strong>Gateway</strong> is using secured<br />
connection.<br />
User Response: For information only.<br />
CCL6528W Outstanding work still in<br />
progress. [{0}] [{1}]<br />
Explanation: A client has disconnected from<br />
ConnectionManager {0}, with work requests in<br />
progress. {1} requests have failed to finish within<br />
a reasonable time.<br />
System Action: The ConnectionManager marks<br />
itself as available again.<br />
User Response: For information only.<br />
CCL6529W Unable to send reply to client.<br />
[{0}]<br />
Explanation: The <strong>Gateway</strong> worker thread {0}<br />
was unable to send the reply to the client. This<br />
could be because the client was disconnected.<br />
System Action: System action is not required.<br />
User Response: Check if client is still running.<br />
CCL6530I Disconnecting idle client. [{0}]-{1}<br />
Explanation: ConnectionManager disconnected<br />
the client at {1}, which had been idle for longer<br />
then the idletimeout value specified in the<br />
configuration file.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6531W Unable to disconnect idle client -<br />
work still in progress. [{0}]-{1}<br />
Explanation: The client at {1} has been idle for<br />
too long, but there are still work requests in<br />
progress on its behalf.<br />
System Action: ConnectionManager did not<br />
disconnect the client.<br />
User Response: For information only.<br />
Messages 49
CCL6532I CCL6547W<br />
CCL6532I Disconnecting non-responsive<br />
client. [{0}]-{1}<br />
Explanation: The client at {1} did not respond to<br />
a PING before the next was due to be sent.<br />
System Action: The client will be disconnected.<br />
User Response: For information only.<br />
CCL6533E Unable to read the ctg.ini file. [{0}]<br />
Explanation: Where {0} specifies the reason for<br />
the failure.<br />
System Action: The <strong>Gateway</strong> stops; it will not<br />
run without an ini file.<br />
User Response: Check that CTG.INI exists in<br />
the bin directory, or that the ini file specified<br />
through the <strong>CICS</strong>CLI environment variable<br />
exists. Run the configuration tool if necessary to<br />
create an ini file.<br />
CCL6534I Using a worker timeout of {0}<br />
milliseconds.<br />
Explanation: The worker thread timeout is set<br />
to {0} ms.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6535I Using a close timeout of {0}<br />
milliseconds.<br />
Explanation: The closedown timeout is set to {0}<br />
ms.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6536I Generic ECI reply calls will not<br />
be allowed.<br />
Explanation: Generic ECI reply calls will not be<br />
allowed.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
50 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6537I Security classes will be required<br />
for all connections on all<br />
protocols.<br />
Explanation: Security is set on all protocols for<br />
all connections.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6544E Port {0} is invalid.<br />
Explanation: The port number specified for the<br />
TCPIP protocol handler is outside the range 0 to<br />
65535.<br />
System Action: The TCPIP protocol handler<br />
does not start.<br />
User Response: Specify a valid TCPIP port<br />
number within the allowed range.<br />
CCL6545E [{0}] {1}:EXCI error. Function Call<br />
= {2}, Response = {3}, Reason = {4},<br />
Subreason field-1 = {5}, subreason<br />
field-2 = {6} CTG_Rc={7}<br />
Explanation: An EXCI call within a JNI native<br />
method failed. Where {0} = a number used<br />
internally by IBM service groups. {1} = name of<br />
the CTG function which issued the ECI call. {2} =<br />
a number representing EXCI call type.<br />
{3},{4},{5},{6} = error codes from the failing EXCI<br />
call. {7} = the return code that will be send to the<br />
CTG application.<br />
System Action: Check the EXCI documentation<br />
for source of error.<br />
User Response: For information only.<br />
CCL6547W The <strong>Gateway</strong> will display<br />
symbolic TCPIP hostnames in<br />
console messages<br />
Explanation: This might affect system<br />
performance.<br />
System Action: The <strong>Gateway</strong> will continue<br />
processing.<br />
User Response: Set NONAMES=ON in the<br />
CTG.INI file to avoid this. Refer to the <strong>CICS</strong>
<strong>Transaction</strong> <strong>Gateway</strong> Administration book for<br />
further details.<br />
CCL6550E Unable to listen on requested port<br />
Explanation: <strong>Gateway</strong> is unable to recognize<br />
port number.<br />
System Action: System action is not required.<br />
User Response: Check valid port number,<br />
protocol and server name.<br />
CCL6551E Unable to create requested<br />
ConnectionManager and worker<br />
threads.<br />
Explanation: Usually this means that the system<br />
is running low on resources.<br />
System Action: System action is not required.<br />
User Response: Reduce the number of<br />
ConnectionManager and worker threads initially<br />
created.<br />
CCL6552E Error whilst accepting a<br />
connection from {0}. Connection<br />
closed. [{1}]<br />
Explanation: A connection was accepted from<br />
{0}, but a problem of type {1} occurred.<br />
System Action: Unable to connect.<br />
User Response: Check error code.<br />
CCL6553E Error reading request. [{0}]<br />
Explanation: Where {0} specifies the<br />
ConnectionManager thread.<br />
System Action: Unable to execute request.<br />
User Response: Check if connection is still<br />
available.<br />
CCL6554E Error in native method. [{0}]<br />
Explanation: Where {0} specifies the Worker<br />
thread.<br />
System Action: System action is not required.<br />
CCL6550E CCL6559E<br />
User Response: For information only.<br />
CCL6555E Error writing reply [{0}]<br />
Explanation: Where {0} specifies the Worker<br />
thread.<br />
System Action: Unable to write reply.<br />
User Response: Check if connection is still<br />
available.<br />
CCL6556E Error copying request on local<br />
<strong>Gateway</strong>.<br />
Explanation: A problem has occurred in the<br />
local Java <strong>Gateway</strong> support.<br />
System Action: Unable to copy request on local<br />
<strong>Gateway</strong>.<br />
User Response: Check if <strong>Gateway</strong> is configured<br />
to use local protocol.<br />
CCL6557E Error whilst executing request.<br />
[{0}]<br />
Explanation: An error occurred while<br />
processing request with name [{0}]<br />
System Action: System action is not required.<br />
User Response: Check that request is valid.<br />
CCL6558E No protocol handlers started<br />
successfully.<br />
Explanation: <strong>Gateway</strong> cannot access any<br />
protocol handlers.<br />
System Action: If no protocol handlers can be<br />
started, the <strong>Gateway</strong> will exit.<br />
User Response: Check the CTG initialization<br />
file for protocol handlers; uncomment the<br />
protocol handle you want.<br />
CCL6559E Unexpected exception occurred<br />
[{0}]<br />
Explanation: An exception of type [{0}]<br />
occurred.<br />
System Action: System action is not required.<br />
Messages 51
CCL6560E CCL6581E<br />
User Response: For information only.<br />
CCL6560E Unable to accept request of type<br />
{0}. [{1}]<br />
Explanation: ConnectionManager {1} has<br />
received a request {0} but failed to load the<br />
required class file to execute the request.<br />
System Action: <strong>Gateway</strong> exits and displays<br />
error message.<br />
User Response: Make sure that the {0} class is<br />
in the CLASSPATH of the <strong>Gateway</strong> process.<br />
CCL6561E Unable to use {0} class to provide<br />
security to {1}.<br />
Explanation: The {0} class could not be<br />
successfully loaded to provide security to the<br />
connection from {1}.<br />
System Action: The connection will be closed.<br />
User Response: Make sure that the {0} class is<br />
in the CLASSPATH of the <strong>Gateway</strong> process.<br />
CCL6562E Connection to {0} rejected due to<br />
insufficient ConnectionManagers.<br />
Explanation: A connection was accepted from<br />
{0}, but a ConnectionManager did not become<br />
available in time.<br />
System Action: The connection was rejected.<br />
User Response: Increase the maximum number<br />
of ConnectionManagers.<br />
CCL6563E {0} protocol handler exited<br />
unexpectedly. [{1}]<br />
Explanation: The {0} protocol handler exited<br />
due to problem {1}.<br />
System Action: <strong>Gateway</strong> exits and displays<br />
error message.<br />
User Response: Check error code.<br />
52 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6569E Unable to open file {0}<br />
Explanation: File with name {0} could not be<br />
opened.<br />
System Action: System action is not required.<br />
User Response: Check that file is not in use or<br />
read-only.<br />
CCL6574I Connection logging has been<br />
disabled<br />
Explanation: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will not write messages to the log when a client<br />
application connects to, or disconnects from, the<br />
gateway daemon.<br />
System Action: System action is not required.<br />
User Response: To enable connection logging,<br />
select the Log client connections and disconnections<br />
check box in the configuration tool, or set<br />
CONNECTIONLOGGING=ON in the<br />
configuration file, CTG.INI.<br />
CCL6580E The parameter {0} in the ini file is<br />
unrecognized or invalid<br />
Explanation: An unknown parameter starting<br />
with specified text was encountered in the<br />
gateway initialization file.<br />
System Action: The gateway terminates.<br />
User Response: Correct the initialization file<br />
error and restart the gateway. The configuration<br />
tool can be used to correct a badly-formed<br />
initialization file.<br />
CCL6581E The <strong>Gateway</strong> cannot continue<br />
Explanation: An error was detected.<br />
System Action: The <strong>Gateway</strong> daemon<br />
terminates.<br />
User Response: Examine any other messages<br />
and the gateway error log to determine the cause<br />
of the error.
CCL6582E The command line option {0} is<br />
unrecognized or invalid<br />
Explanation: An unknown or invalid option<br />
starting with specified text was encountered on<br />
the command line.<br />
System Action: The gateway terminates and<br />
displays help.<br />
User Response: Restart the gateway with a<br />
correct command line option.<br />
CCL65XXW Unable to find message. [{0}]<br />
Explanation: The message appropriate for this<br />
error code cannot be found.<br />
System Action: Display the number of the<br />
message.<br />
User Response: Find the appropriate message<br />
by searching for its number in this message file.<br />
CCL6601I Request specific trace {0}.<br />
Explanation: A historical message.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6602I <strong>Gateway</strong>Request type = {0}, flow<br />
version = {1}, flow type = {2},<br />
<strong>Gateway</strong> return code = {3}, length<br />
of data following the header = {4}.<br />
Explanation: Information from current request.<br />
System Action: Execute request.<br />
User Response: For information only.<br />
CCL6650E Unable to connect to the <strong>Gateway</strong>.<br />
Explanation: Client application unable to<br />
connect to gateway.<br />
System Action: Client request unable to start.<br />
User Response: Check if <strong>Gateway</strong> is running; if<br />
client application has specified the correct<br />
parameters to connect to the gateway.<br />
CCL6582E CCL6655E<br />
CCL6651E Unable to connect to the <strong>Gateway</strong><br />
[address={0}, port={1}] [{2}]<br />
Explanation: Where {0} specifies the <strong>Gateway</strong><br />
TCP/IP address, {1} specifies the TCP/IP port<br />
and {2} specifies the cause of the error.<br />
System Action: Client request unable to start.<br />
User Response: Check error code.<br />
CCL6652E Unable to start the <strong>Gateway</strong><br />
listener.<br />
Explanation: Client application could not start<br />
the <strong>Gateway</strong> listener.<br />
System Action: Close this Java<strong>Gateway</strong><br />
instance.<br />
User Response: Check that <strong>Gateway</strong> is correctly<br />
configured.<br />
CCL6653E Unable to flow request to the<br />
<strong>Gateway</strong>; this Java<strong>Gateway</strong><br />
instance has been closed.<br />
Explanation: The <strong>Gateway</strong> is unreachable.<br />
System Action: Close this Java<strong>Gateway</strong><br />
instance.<br />
User Response: Check if the connections to the<br />
<strong>Gateway</strong> still exist.<br />
CCL6654E An error occurred while the<br />
<strong>Gateway</strong> was closing. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: Close the <strong>Gateway</strong>.<br />
User Response: Check error code.<br />
CCL6655E There was an error reading the<br />
reply. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: Unable to read the reply.<br />
User Response: Check error code.<br />
Messages 53
CCL6656E CCL6664E<br />
CCL6656E Flow did not contain the correct<br />
eyecatcher. Fatal Error.<br />
Explanation: Network connection did not<br />
contain the correct identifier.<br />
System Action: Connection closed.<br />
User Response: For information only.<br />
CCL6657E Invalid <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
address specified.<br />
Explanation: The <strong>Gateway</strong> URL was incorrectly<br />
specified.<br />
System Action: Unable to connect to <strong>Gateway</strong><br />
at this address.<br />
User Response: Check <strong>Gateway</strong> is running and<br />
address is right.<br />
CCL6658E Local <strong>Gateway</strong> support has been<br />
terminated.<br />
Explanation: Attempts have been made to use<br />
the local <strong>Gateway</strong> support after the<br />
LocalJava<strong>Gateway</strong>.terminate method has been<br />
called.<br />
System Action: Unable to make further requests<br />
to this gateway.<br />
User Response: For information only.<br />
CCL6659E In use Local <strong>Gateway</strong>s currently<br />
exist.<br />
Explanation: The LocalJava<strong>Gateway</strong>.terminate<br />
method has been called while local <strong>Gateway</strong>s are<br />
still in use.<br />
System Action: Wait for requests to finish.<br />
User Response: For information only.<br />
CCL6660E Error copying reply. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: Unable to copy reply.<br />
User Response: Check error code.<br />
54 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6661E Cannot change Java<strong>Gateway</strong><br />
properties when the Java<strong>Gateway</strong><br />
instance is open.<br />
Explanation: A call to a Java<strong>Gateway</strong>.set<br />
method has been made, after the Java<strong>Gateway</strong><br />
has been opened.<br />
System Action: System action is not required.<br />
User Response: Close Java<strong>Gateway</strong> instance.<br />
CCL6662E This Java<strong>Gateway</strong> instance is still<br />
open.<br />
Explanation: This Java<strong>Gateway</strong> instance is still<br />
open in the client application.<br />
System Action: System action is not required.<br />
User Response: Close this Java<strong>Gateway</strong><br />
instance.<br />
CCL6663E Cannot open a Java<strong>Gateway</strong><br />
instance when no protocol has<br />
been specified.<br />
Explanation: No protocol classes have been<br />
requested by the client application.<br />
System Action: Unable to make further requests<br />
to this instance.<br />
User Response: Check if client application<br />
specifies a valid protocol parameter.<br />
CCL6664E Unable to load relevant class to<br />
support the {0} protocol.<br />
Explanation: The relevant class could not be<br />
found.<br />
System Action: Unable to create Java<strong>Gateway</strong><br />
instance.<br />
User Response: If the protocol {0} is xyz, then<br />
the required class is called xyzJava<strong>Gateway</strong>.<br />
Ensure that this can be found by your client<br />
program.
CCL6665E This Java<strong>Gateway</strong> instance has<br />
been closed.<br />
Explanation: The Java<strong>Gateway</strong> instance was<br />
closed by the client application.<br />
System Action: Unable to make a further<br />
request to this instance.<br />
User Response: Start new Java<strong>Gateway</strong><br />
instance.<br />
CCL6666E Unable to flow request to the<br />
<strong>Gateway</strong>. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: Unable to make further request<br />
to this instance.<br />
User Response: Check error code.<br />
CCL6667E Error writing request. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: Unable to write further requests<br />
to this instance.<br />
User Response: Check error code.<br />
CCL6668E Initial handshake flow failed. [{0}]<br />
Explanation: Caused by {0}<br />
System Action: Unable to make initial<br />
handshake; hence unable to make requests.<br />
User Response: Check error code.<br />
CCL6669E Cannot open Java<strong>Gateway</strong>. Must<br />
specify both client-side and<br />
server-side security classes.<br />
Explanation: Server application needs security.<br />
System Action: Unable to make requests<br />
because of lack of security.<br />
User Response: Specify both client and server<br />
sides security classes.<br />
CCL6665E CCL6687E<br />
CCL6670E Exception occurred in the<br />
<strong>Gateway</strong>. [{0}]<br />
Explanation: Where {0} specifies the cause of<br />
the error.<br />
System Action: System action is not required.<br />
User Response: Check error code.<br />
CCL6671E This Java<strong>Gateway</strong> instance has yet<br />
to be opened.<br />
Explanation: The client application has not<br />
opened a new Java<strong>Gateway</strong> instance yet.<br />
System Action: System action is not required.<br />
User Response: Open Java<strong>Gateway</strong> instance<br />
before making requests.<br />
CCL6686E Keyring specified but case does<br />
not match, or cfwk.zip not on<br />
classpath<br />
Explanation: the SSLight implementation for<br />
SSL was selected, but either cfwk.zip was not on<br />
the class path, or a keyring was specified and the<br />
name of the class was correct and it was found,<br />
but the case did not match, so the class cannot be<br />
loaded.<br />
System Action: Either the SSL or HTTPS<br />
protocol will fail to start on the server or the<br />
client application will fail to open a Java<br />
<strong>Gateway</strong> using SSL<br />
User Response: Ensure cfwk.zip is specified on<br />
the classpath or that you have entered the<br />
keyring class correctly ensuring the case is<br />
identical to the keyring class filename.<br />
CCL6687E Keyring was tampered with, or<br />
password was incorrect.<br />
Explanation: Unable to import keyring.<br />
System Action: System action is not required.<br />
User Response: Ensure correct keyring class<br />
and password has been provided.<br />
Messages 55
CCL6688I CCL6696I<br />
CCL6688I Unknown JSSE <strong>Version</strong>.<br />
Explanation: Unable to detect JSSE version<br />
strings.<br />
System Action: System action is not required.<br />
User Response: Information only no action<br />
required.<br />
CCL6689I JSSE Package information.<br />
Explanation: <strong>Version</strong> information relating to<br />
JSSE Libraries.<br />
System Action: System action is not required.<br />
User Response: Information only no action<br />
required.<br />
CCL6690I After JNI {0}<br />
Explanation: A JNI native method call has just<br />
completed. Where {0} is the name of the JNI call.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6691I Before JNI {0} : TermIndex={1}<br />
Explanation: The CTG is about to call a JNI<br />
native method. Where {0} is the name of the JNI<br />
call and {1} is the terminal index number<br />
parameter passed to the call.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6692I Before JNI {0} : TermIndex={1},<br />
Transid={2}<br />
Explanation: The CTG is about to call a JNI<br />
native method. Where {0} is the name of the JNI<br />
call, {1) is the terminal index number to be<br />
passed to the call and {2} is the transaction id.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
56 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6693I After JNI {0} : Rc={1},<br />
LUW/TermIndex={2}<br />
Explanation: A JNI native method call has just<br />
completed. Where {0} is the name of the JNI call<br />
and {1} is the return code from the call. {2} may<br />
either represent a LUW token or a terminal index<br />
returned by the call depending on what type of<br />
call was made.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6694I Before JNI {0} : Server={1}<br />
NetName={2}<br />
Explanation: The CTG is about to call a JNI<br />
native method. Where {0} is the name of the JNI<br />
call,{1} is the name of the server and {2} is the<br />
NetName to be passed to the JNI call.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6695I Before JNI {0} : Server={1},<br />
Program={2},<br />
Commarea.Length={3},<br />
ExtendMode={4}, LUW={5}.<br />
Explanation: The CTG is about to call a JNI<br />
native method. Where {0} is the name of the JNI<br />
call and parameters {1} to {5} are ECI parameters<br />
to be passed to the JNI call.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6696I After JNI {0} : Rc={1}<br />
Explanation: A JNI native method call has just<br />
completed. Where {0} is the name of the JNI call<br />
and {1} is the return code from the call.<br />
System Action: System action is not required.<br />
User Response: For information only.
CCL6697I Before JNI {0}<br />
Explanation: The CTG is about to call a JNI<br />
native method. Where {0} is the name of the JNI<br />
call.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6702I <strong>CICS</strong> Request: Successfully<br />
loaded native library.<br />
Explanation: Native library for environment<br />
loaded successfully.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6703E <strong>CICS</strong> Request: Load of native<br />
library failed {0}.<br />
Explanation: Where {0} specifies the Java error.<br />
System Action: Unable to load native library.<br />
User Response: Check if native library is<br />
available.<br />
CCL6704I BMS Map Converter<br />
Explanation: The BMS Map Converter is a<br />
utility that generates Java Map classes from BMS<br />
definition files.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6705E {0} is not a valid AID key<br />
Explanation: The exit key parameter indicated<br />
was not a valid AID value. Valid AID keys are<br />
enter, clear, PF1 - 24, and PA1 - 3.<br />
System Action: Unable to execute command.<br />
User Response: Check if AID key is valid.<br />
CCL6706I Classes will be created in package<br />
{0}.<br />
Explanation: When the BMS Map Converter<br />
generates classes, a package statement will be<br />
included, where the name of the package is {0}.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6707I ScreenHandler will be generated.<br />
Explanation: A ScreenHandler bean will be<br />
generated for this screen.<br />
System Action: Generating ScreenHandler for<br />
screen.<br />
User Response: For information only.<br />
CCL6708I Use this command to generate<br />
Map classes from BMS Map files.<br />
Explanation: This command generates Map<br />
classes from BMS Map files.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6709I Arguments: <br />
bmsfile1<br />
bmsfile2 ..<br />
Explanation: This help will be displayed if the<br />
BMS Map Converter is invoked without<br />
arguments.<br />
System Action: Exit BMS Map Converter and<br />
display arguments accepted.<br />
User Response: Enter valid arguments.<br />
CCL6710I Processing file {0} ...<br />
CCL6697I CCL6710I<br />
Explanation: The BMS Map Converter has<br />
begun processing the file {0}.<br />
System Action: BMS Map Converter is<br />
processing this BMS Map.<br />
User Response: For information only.<br />
Messages 57
CCL6714W CCL6732I<br />
CCL6714W <strong>CICS</strong> Request: Cics_Rc {0} not<br />
recognised.<br />
Explanation: <strong>CICS</strong> Server return code {0} is not<br />
valid.<br />
System Action: System action is not required.<br />
User Response: Check if Cics_Rc is valid.<br />
CCL6716E <strong>CICS</strong> Request: Error in<br />
initialization. [{0}]<br />
Explanation: Where {0} specifies the Java error.<br />
System Action: <strong>CICS</strong> Request revolted.<br />
User Response: Check the Java error.<br />
CCL6717E <strong>CICS</strong> Request: An attempt to<br />
convert from a C byte array to a<br />
Java String failed.<br />
Explanation: The codepage specified for the<br />
conversion was {0}.<br />
System Action: A <strong>CICS</strong> Request attempted to<br />
convert between a C byte array and a Java<br />
String. The codepage being used for the<br />
conversion was {0}.<br />
User Response: Check user codepage.<br />
CCL6718E <strong>CICS</strong> Request: Error. [{0}]<br />
Explanation: Where {0} specifies the error.<br />
System Action: <strong>CICS</strong> Request revolted.<br />
User Response: Check error.<br />
CCL6719E <strong>CICS</strong> Request: Java default<br />
character encoding not obtained.<br />
[{0}]<br />
Explanation: An attempt was made to obtain<br />
the Java default character encoding. {0} specifies<br />
the Java error.<br />
System Action: System action is not required.<br />
User Response: Check the return Java error.<br />
58 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6726I ECIRequest: ECI_BACKOUT<br />
request, Cics_Rc = {0}, Luw_Token<br />
={1}.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> back out.<br />
System Action: <strong>CICS</strong> Server returns to the<br />
status it was before the last request.<br />
User Response: Check Cics_Rc, if it is not 0<br />
then check <strong>CICS</strong> Server and <strong>CICS</strong> Client.<br />
CCL6730I ECIRequest: Commarea_Length<br />
limited to length of Commarea.<br />
Explanation: Commarea_Length set to the<br />
length of Commarea specified; usually this is<br />
caused by user-defined Commarea being larger<br />
than the Commarea specified.<br />
System Action: Set Commarea_Length to length<br />
of specified Commarea.<br />
User Response: Reduce User-defined<br />
Commarea.<br />
CCL6731W ECIRequest: This call type may<br />
return a reply intended for<br />
another Java client.<br />
Explanation: Either Call_Type ECI_GET_REPLY<br />
or Call_Type ECI_GET_REPLY_WAIT have been<br />
used. These types of call should be used with<br />
caution since they will return the next reply,<br />
which may be intended for another Java client.<br />
System Action: System action is not required.<br />
User Response: Use ECI_GET_REPLY and<br />
ECI_GET_REPLY_WAIT call types with caution.<br />
CCL6732I ECIRequest: The array containing<br />
the status bytes is null. The<br />
ConnectionType, CicsServerStatus<br />
and CicsClientStatus will be set to<br />
their defaults.<br />
Explanation: No status information has been<br />
returned, so the status fields will be set to their<br />
defaults.<br />
System Action: System action is not required.<br />
User Response: For information only.
CCL6733W ECIRequest: The Commarea<br />
outbound length is greater than<br />
Commarea_Length.<br />
Explanation: The amount of data sent from the<br />
Java client to the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, is<br />
greater than the size of the Commarea given to<br />
<strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: Specify Larger Commarea.<br />
CCL6734W ECIRequest: The Commarea<br />
inbound length is greater than<br />
Commarea_Length.<br />
Explanation: The amount of data sent to the<br />
Java client from the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, is<br />
greater than the size of the Commarea given to<br />
<strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: Specify larger Commarea.<br />
CCL6735I ECIRequest: Call_Type = {0},<br />
Server = {1}, Extend_Mode =<br />
ECI_STATE_IMMEDIATE.<br />
Explanation: Trace message for ECIRequest.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6736E ECIRequest: Message Qualifier is<br />
invalid, outside of range -32767 to<br />
32767<br />
Explanation: An invalid message qualifier<br />
parameter has been provided.<br />
System Action: None.<br />
User Response: Correct the value passed for<br />
message qualifier in the method invocation.<br />
CCL6749E ESIRequest: Userid, Password or<br />
Server Name too long<br />
Explanation: Either the Userid, Password or<br />
Server Name entered is longer than required.<br />
System Action: System action is not required.<br />
User Response: Re-enter the correct Userid,<br />
Password or Server name.<br />
CCL6755E EPIRequest: size field limited to<br />
data.length.<br />
Explanation: The size field may not exceed the<br />
length of the data array.<br />
System Action: System action is not required.<br />
User Response: Specify larger data array.<br />
CCL6762W termIndex: 0xFFFF is invalid for<br />
calls that are not to a local<br />
<strong>Gateway</strong>.<br />
Explanation: Unless using a local <strong>Gateway</strong>, it is<br />
invalid to attempt to get an event without<br />
specifying a termIndex, since you may obtain<br />
events intended for other terminal resources.<br />
System Action: System action is not required.<br />
User Response: Specify a termIndex.<br />
CCL6770E ECIRequest: Invalid Call_Type.<br />
Explanation: Invalid call type passed to<br />
ECIRequest<br />
System Action: System action is not required.<br />
User Response: Check call type.<br />
CCL6733W CCL6772E<br />
CCL6771E ECIRequest: Commarea outbound<br />
length is negative.<br />
Explanation: Commarea outbound length must<br />
always be a positive integer.<br />
System Action: Could not create a Commarea<br />
outbound length of this size; default length is set.<br />
User Response: Check if Commarea outbound<br />
length is a positive integer.<br />
CCL6772E ECIRequest: eci_timeout value is<br />
negative.<br />
Explanation: eci_timeout can only be 0 or a<br />
positive integer.<br />
Messages 59
CCL6774E CCL6782E<br />
System Action: Could not set ECI timeout;<br />
default timeout is set.<br />
User Response: Check if eci_time is a positive<br />
integer.<br />
CCL6774E No Java<strong>Gateway</strong> or EPI<strong>Gateway</strong><br />
instance has been associated with<br />
this terminal<br />
Explanation: An attempt to connect a terminal<br />
failed as no Java<strong>Gateway</strong> or EPI<strong>Gateway</strong><br />
instance has been associated with that terminal<br />
instance.<br />
System Action: None.<br />
User Response: Create and Configure a<br />
Java<strong>Gateway</strong> or EPI<strong>Gateway</strong> instance and use<br />
the appropriate methods or constructors to<br />
associate this instance with the instance of the<br />
terminal.<br />
CCL6775E Your created terminal cannot use<br />
these extended connect methods,<br />
as it is not an extended terminal<br />
Explanation: An attempt to use the extended<br />
Connect Methods on a terminal has failed. The<br />
Extended Connect methods can only be used on<br />
extended terminal instances.<br />
System Action: None.<br />
User Response: Use the standard connect<br />
method or create an extended terminal instance<br />
if you wish to use the extended connect<br />
methods.<br />
CCL6776E CicsCpRequest: Unable to convert<br />
the <strong>CICS</strong> code page to a Java<br />
Encoding. [{0}]<br />
Explanation: An attempt to convert a <strong>CICS</strong> code<br />
page to a Java format, (for example, 850 to<br />
Cp850), failed. {0} is the Java error.<br />
System Action: System action is not required.<br />
User Response: Check the Java error and the<br />
<strong>CICS</strong> Code page.<br />
60 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6777E Security Exception. Return code<br />
{1} from {0} call.<br />
Explanation: Return code {1} was received<br />
when attempting to invoke a security type<br />
method {0}<br />
System Action: None.<br />
User Response: Look up the return code to<br />
determine the cause of failure.<br />
CCL6779E Cannot find equivalent CSid for<br />
Encoding<br />
Explanation: A Java encoding was specified for<br />
a terminal, but no equivalent host CCSid is<br />
known for this encoding.<br />
System Action: None.<br />
User Response: Check the documentation for<br />
the list of allowed Java encodings that have<br />
equivalent CCSid values.<br />
CCL6780E EPIRequest: Invalid Call_Type.<br />
Explanation: Invalid call type passed to<br />
EPIRequest.<br />
System Action: System action is not required.<br />
User Response: Check call type.<br />
CCL6781E EPIRequest: Invalid event.<br />
Explanation: Invalid event passed.<br />
System Action: System action is not required.<br />
User Response: Check event.<br />
CCL6782E EPIRequest: Invalid termIndex:<br />
0xFFFF.<br />
Explanation: It is invalid to attempt to get an<br />
event without specifying a termIndex, since you<br />
may obtain events intended for other terminal<br />
resources.<br />
System Action: System action is not required.<br />
User Response: Specify a termIndex.
CCL6783E EPIRequest: termIndex {0} does<br />
not exist.<br />
Explanation: Where {0} is the invalid termIndex.<br />
System Action: System action is not required.<br />
User Response: Check that termIndex is<br />
available and unique to this connection.<br />
CCL6784E EPIRequest: termIndex {0} belongs<br />
to another connection.<br />
Explanation: Where {0} is the invalid termIndex.<br />
System Action: System action is not required.<br />
User Response: Check that termIndex is unique<br />
to this connection.<br />
CCL6785E EPIRequest: EPI Initialization<br />
failed. [{0}]<br />
Explanation: Where {0} is the error.<br />
System Action: Exit application.<br />
User Response: For information only.<br />
CCL6786I There are no free terminals<br />
available.<br />
Explanation: The maximum number of<br />
terminals for this application has been reached.<br />
System Action: Stop starting new transactions.<br />
User Response: Wait for free terminal.<br />
CCL6787E Exception [{0}] occurred while<br />
attempting to load classes from<br />
the path: {1}″<br />
Explanation: An exception occurred while<br />
screen handler beans where being loaded from<br />
the path specified. Possible causes are: the<br />
classpath is incorrect, a screen handler bean did<br />
not have a public constructor , a file or directory<br />
could not be accessed.<br />
System Action: System action is not required.<br />
User Response: Check if classpath exist and<br />
classes are available.<br />
CCL6783E CCL6792E<br />
CCL6788E Exception [{0}] occurred while<br />
attempting to load the class: {1}<br />
Explanation: An exception occurred while the<br />
specified class was being loaded. Possible causes<br />
are: the class could not be found, the class did<br />
not have a public constructor.<br />
System Action: System action is not required.<br />
User Response: Check exception and that class<br />
is available and has a public constructor.<br />
CCL6789E An exception has occurred: {0}<br />
Explanation: Where {0} is the exception.<br />
System Action: System action is not required.<br />
User Response: Check where exception has<br />
occurred.<br />
CCL6790E Too much data received from<br />
<strong>CICS</strong>.<br />
Explanation: More data was returned by <strong>CICS</strong><br />
than could be handled.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6791E Internal error - terminal state<br />
invalid.<br />
Explanation: An internal error has occurred.<br />
The terminal state is incorrect.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6792E Null transaction ID parameter<br />
passed to Terminal.send.<br />
Explanation: If a transaction ID parameter is<br />
passed to send, it must be a valid string.<br />
System Action: System action is not required.<br />
User Response: Check if a valid transaction ID<br />
is given.<br />
Messages 61
CCL6793E CCL6801I<br />
CCL6793E The terminal is in the wrong state<br />
for the requested action.<br />
Explanation: An action was requested when the<br />
terminal was in the wrong state, for example:<br />
disconnect while the terminal was not idle.<br />
System Action: Wait and try again after a fixed<br />
period of time.<br />
User Response: Wait and try again after a<br />
period of time.<br />
CCL6794E Cursor could not be set to row {0},<br />
column {1} - out of range.<br />
Explanation: Either the row {0} or the column<br />
(1} are off the screen.<br />
System Action: System action is not required.<br />
User Response: Check if either the row or the<br />
column are out of range.<br />
CCL6795E Unsupported datastream received<br />
from <strong>CICS</strong> - command is {0}.<br />
Explanation: The datastream received from<br />
<strong>CICS</strong> could not be parsed.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6796E <strong>Transaction</strong> {0} failed, return code<br />
{1}.<br />
Explanation: <strong>Transaction</strong> {0} failed to start, did<br />
not complete, or timed out.<br />
System Action: None.<br />
User Response: Check the Read Timeout value<br />
for the terminal if the transaction timed out.<br />
Check the Client and <strong>CICS</strong> server logs for more<br />
information on why the transaction failed.<br />
CCL6797E Failed to delete terminal.<br />
Explanation: Terminal could not be deleted.<br />
System Action: Wait, then try again.<br />
User Response: Check if terminal is still in use.<br />
62 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6798E Unknown attribute type {0}.<br />
Explanation: The attribute type {0} is not<br />
supported.<br />
System Action: System action is not required.<br />
User Response: Check attribute type.<br />
CCL6799I Return code {1} from {0} call.<br />
Explanation: The EPI call {0} returned the<br />
return code {1}.<br />
System Action: System action is not required.<br />
User Response: Check return code; if it is not 0<br />
than check for error.<br />
CCL6800I ECI parameters on entry.<br />
Call_Type = Call Type,<br />
Extend_Mode = Extend Mode,<br />
Luw_Token = Luw Token,<br />
Commarea_Length = Commarea<br />
Length, Cics_Rc = Cics Rc,<br />
Message_Qualifier = Message<br />
Qualifier outbound Commarea<br />
length = outbound data length.<br />
Explanation: These are the parameters passed<br />
to the CTG JNI layer. The ECI call specified will<br />
be called with the parameters set here. Outbound<br />
data length can be specifed using the<br />
setCommareaOutboundLength API call.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6801I CcicsECI: Performed parameter<br />
conversion. parameter name =<br />
name, parameter value = value<br />
Explanation: The CTG has converted the<br />
specified parameter to the correct format and<br />
will use this for the ECI call.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.
CCL6802I CcicsECI: Input commarea<br />
information. commarea length =<br />
length, commarea address =<br />
address.<br />
Explanation: The CTG will pass the commarea<br />
described in the message on the ECI call.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6803I CcicsInit: Userid password<br />
authentication enabled.<br />
Explanation: The AUTH_USERID_PASSWORD<br />
environment variable has been set, and Userids<br />
and Passwords will be authenticated against the<br />
appropriate security mechanisms.<br />
System Action: The CTG will start with userid<br />
and password authentication enabled.<br />
User Response: Valid user ids and passwords<br />
should be used when making calls to <strong>CICS</strong> If<br />
authentication is not required, the<br />
AUTH_USERID_PASSWORD environment<br />
variable should be unset. Note: Setting<br />
AUTH_USERID_PASSWORD=NO still makes the<br />
environment variable set. Use unset<br />
AUTH_USERID_PASSWORD to ensure it is not<br />
set.<br />
CCL6804I CcicsECI: Returned commarea<br />
information. commarea length =<br />
length, commarea address =<br />
address, inbound commarea data<br />
length = inbound data length<br />
Explanation: The CTG returned the commarea<br />
decribed after a call to <strong>CICS</strong>. Inbound data<br />
length refers to the length after null stripping has<br />
occurred.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6802I CCL6807I<br />
CCL6805I ECI parameters on exit. Call_Type<br />
= Call Type, Extend_Mode = Extend<br />
Mode, Luw_Token = Luw Token,<br />
Commarea_Length = Commarea<br />
Length, Cics_Rc = Cics Rc,<br />
Message_Qualifier = Message<br />
Qualifier<br />
Explanation: The ECI parameters specified were<br />
set as displayed just before exit from the CTG<br />
JNI interface.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6806I CcicsInit: Register with RRS.<br />
Return code = rc<br />
Explanation: This displays the return code from<br />
the RRS registration call (crggrm) which registers<br />
the CTG as a resource manager.<br />
System Action: CTG processing will continue.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis, or see the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616), section 5.1 -<br />
Register_Resource_Manager, for details of the<br />
return code and any corrective action which<br />
should be taken.<br />
CCL6807I CcicsInit: Set exitcode with RRS.<br />
Return code = rc<br />
Explanation: This displays the return code from<br />
the RRS set exit information call (crgseif).<br />
System Action: CTG processing will continue.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis.<br />
Messages 63
CCL6808I CCL6814I<br />
CCL6808I CcicsECI: Authorise<br />
userid/password with RACF.<br />
Return code = rc, errno = error<br />
number, errno2 = reason code.<br />
Explanation: This displays the return code from<br />
the __passwd call used to authenticate the<br />
username and password, and the system error<br />
number. Please refer to the problem<br />
determination section of the z/OS<br />
Administration Guide for further details of<br />
security errors.<br />
System Action: If the return code is non-zero,<br />
the CTG will return an ECI_SECURITY_ERROR,<br />
otherwise it will continue processing.<br />
User Response: If the return code is non-zero,<br />
see the C/C++ Run-Time Library Reference book<br />
(SC28-1663), and refer to the section describing<br />
the __passwd() call. More detail on the reason<br />
code can be found in UNIX System Services<br />
Messages and Codes (SC28-1908-10)<br />
CCL6809I getRACFUID: Map X.509<br />
certificate to RACF userid. Return<br />
code = rc, errno = error number,<br />
errno2 = reason code.<br />
Explanation: This displays the return code from<br />
the authorisation call, and the system error<br />
number.<br />
System Action: CTG processing will continue.<br />
User Response: If the return code is non-zero,<br />
see the C/C++ Run-Time Library Reference book<br />
(SC28-1663), and refer to the section describing<br />
the pthread_security_np() call. More detail on the<br />
reason code can be found in UNIX System<br />
Services Messages and Codes (SC28-1908-10)<br />
CCL6810I connopen: First request on TCB<br />
address = address.<br />
Explanation: The address specified is the<br />
address of the TCB used by this connection. The<br />
first ECI request on the specified TCB has been<br />
received. A pipe has not yet been allocated.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
64 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL6811I connclean: Cleanup routine entry,<br />
TCB address = address.<br />
Explanation: The CTG is performing routine<br />
cleanup. This will close and deallocate the pipe,<br />
and is called on thread cleanup by the system.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6812I CcicsECI: EXCI version 2 not<br />
supported on server = server<br />
Explanation: The server specified does not<br />
support the use of EXCI version 2.<br />
System Action: The CTG will retry the request<br />
using an EXCI version 1 parameter block.<br />
User Response: Support for EXCI v2 on <strong>CICS</strong><br />
<strong>Transaction</strong> Server for OS/390 v1.3 is provided<br />
by APAR PQ38644.<br />
CCL6813I CcicsInit: Running under<br />
Websphere z/OS.<br />
Explanation: The CTG is running under<br />
Websphere z/OS platform v4 or later.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6814I CcicsECI: Global transaction<br />
mode detected.<br />
Explanation: The CTG has detected a Global<br />
<strong>Transaction</strong> running on this thread This will only<br />
occur if running under WebSphere Application<br />
Server for z/OS v4 or later, and when using the<br />
J2EE ECI connector.<br />
System Action: The ECI request will join the<br />
Global <strong>Transaction</strong>. The CTG will not set the<br />
EXCI SYNCONRETURN option.<br />
User Response: No further action is required.
CCL6815E CcicsECI: Retrieve Side<br />
Information Fast failed. RRM<br />
Return code = rc.<br />
Explanation: The call to Retrieve Side<br />
Information Fast (atrrusf) failed with the<br />
specified return code.<br />
System Action: The CTG will return a system<br />
error on the associated ECI request.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis, or see the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616), section 7.25 -<br />
Retrieve_Side_Information_Fast, for details of the<br />
return code and any corrective action which<br />
should be taken.<br />
CCL6816E CcicsECI: Retrieve Current<br />
Context Token failed. RRM<br />
Return code = rc.<br />
Explanation: The call to Retrieve Current<br />
Context Token (ctxrcc) failed with the specified<br />
return code.<br />
System Action: The CTG will return a system<br />
error on the associated ECI request.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis, or refer to the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616-01), section 6.7 -<br />
Retrieve_Current_Context_Token, for details of<br />
the return code and any corrective action which<br />
should be taken.<br />
CCL6817E CcicsECI: Switch Context failed.<br />
RRM Return code = rc.<br />
Explanation: The call to Switch Context<br />
(ctxswch) failed with the specified return code.<br />
System Action: The CTG will return a system<br />
error on the associated ECI request.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
CCL6815E CCL6820E<br />
representative for more information and<br />
diagnosis, or refer to the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616-01), section 6.10 - Switch_Context, for<br />
details of the return code and any corrective<br />
action which should be taken.<br />
CCL6818E CcicsECI: Begin Context failed.<br />
RRM Return code = rc.<br />
Explanation: The call to Begin Context (ctxbegc)<br />
failed with the specified return code.<br />
System Action: The CTG will return a system<br />
error on the associated ECI request.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis, or refer to the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616-01), section 6.1 - Begin_Context, for<br />
details of the return code and any corrective<br />
action which should be taken.<br />
CCL6819I CcicsECI: End Context failed.<br />
RRM Return code = rc.<br />
Explanation: The call to End Context (ctxendc)<br />
failed with the specified return code.<br />
System Action: The CTG will return a system<br />
error on the associated ECI request.<br />
User Response: If the return code is non-zero,<br />
the user should contact their support<br />
representative for more information and<br />
diagnosis, or refer to the z/OS v1r2 MVS<br />
Programming: Resource Recovery book<br />
(sa22-7616-01), section 6.3 - End_Context, for<br />
details of the return code and any corrective<br />
action which should be taken.<br />
CCL6820E CcicsECI: Error in<br />
GetStringPlatform function.<br />
Return code = rc, dataarea=data<br />
area, length = length.<br />
Explanation: The call to GetStringPlatform has<br />
failed with the specified return code and<br />
information.<br />
Messages 65
CCL6821E CCL6827E<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6821E CcicsECI: Error in<br />
GetStringPlatformLength<br />
function. Return code = rc.<br />
Explanation: The call to<br />
GetStringPlatformlength has failed with the<br />
specified return code and information.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6822E CcicsECI: EXCI function error.<br />
Function Call = function call,<br />
Response = response code, Reason =<br />
reason code, Subreason field-1 =<br />
subreason field 1, subreason field-2<br />
= subreason field 2, Cics_Rc = rc.<br />
Explanation: The EXCI call failed with the error<br />
codes displayed.<br />
System Action: The CTG will return an<br />
appropriate error to the application and will<br />
continue processing.<br />
User Response: The user should refer to the<br />
<strong>CICS</strong> External Interfaces Guide (sc33-1944), to<br />
determine the cause. The EXCI function being<br />
performed is specified by the Function Call data<br />
in the message, which maps to the EXCI calls as<br />
follows; 1=Initialize_User, 2=Allocate_Pipe,<br />
3=Open_Pipe, 4=Close_Pipe, 5=Deallocate_Pipe,<br />
6=DPL_Request.<br />
CCL6823E CcicsECI: EXCI DPL_REQUEST<br />
specific error. RESP value =<br />
response code, RESP2 value =<br />
response code 2, Abend Code =<br />
abend code, Cics_Rc = rc.<br />
Explanation: A request failed with a DPL<br />
specific error. The error codes returned by the<br />
DPL_REQUEST are displayed.<br />
System Action: The CTG will return an<br />
appropriate error to the application and will<br />
continue processing.<br />
66 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: The user should refer to the<br />
<strong>CICS</strong> External Interfaces Guide (sc33-1944), to<br />
determine the cause of the error.<br />
CCL6825E CcicsECI: Unsupported call type.<br />
Call_Type = call type, Cics_Rc =<br />
cics rc.<br />
Explanation: This message is issued when an<br />
invalid EXCI call is being attempted. The only<br />
valid call types for use with EXCI are<br />
ECI_SYNC, ECI_STATE_SYNC and<br />
ECI_SYNC_TPN.<br />
System Action: The CTG will return an<br />
appropriate error to the application and will<br />
continue processing.<br />
User Response: The user should only use valid<br />
call types on the z/OS platform.<br />
CCL6826E CcicsECI: Invalid commarea<br />
length. Commarea_Length =<br />
commarea length, Size of Commarea<br />
=commarea size, Cics_Rc = rc.<br />
Explanation: The commarea length defined, or<br />
the actual length of the commarea is too large,<br />
and is therefore invalid. The maximum length<br />
supported is 32659 bytes.<br />
System Action: The CTG will return an<br />
appropriate error to the application and will<br />
continue processing.<br />
User Response: The user should ensure the<br />
maximum length of commarea used does not<br />
exceed 32659 bytes.<br />
CCL6827E CcicsECI: Error message from<br />
<strong>CICS</strong>: cics_error.<br />
Explanation: An error message has been<br />
returned directly from the <strong>CICS</strong> region, and is<br />
displayed.<br />
System Action: CTG processing will continue.<br />
User Response: The user should refer to the<br />
<strong>CICS</strong> Messages and Codes book (gc33-1694-35),<br />
for details of the error.
CCL6828I ECI Entry parameters. Call_Type =<br />
Call Type, Extend_Mode = Extend<br />
Mode, Luw Token = Luw Token,<br />
Commarea_Length = Commarea<br />
Length, Message_Qualifier =<br />
Message Qualifier, Timeout =<br />
Timeout.<br />
Explanation: The ECI request will be executed<br />
with the displayed parameters.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6829I ECI Server Name= server_name,<br />
Program Name = program_name,<br />
Transid = transid.<br />
Explanation: The ECI Request will be executed<br />
using the displayed parameters.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6830I ECI Commarea set in ECI block =<br />
commarea length.<br />
Explanation: commarea length is the length of the<br />
commarea specified on the ECI Request.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6831I CcicsECI: Memory Allocation<br />
Failure Cics_RC set to cics_rc.<br />
Explanation: cics_rc will be set to<br />
ECI_ERR_RESOURCE_SHORTAGE. This<br />
message applies to the Solaris platform only, and<br />
indicates a malloc() failure.<br />
System Action: CTG processing will continue.<br />
User Response: The user should refer to the<br />
Solaris documentation to determine what<br />
corrective action is necessary to provide adequate<br />
memory to the CTG process.<br />
CCL6828I CCL6835I<br />
CCL6832I ECI Return values. Luw_Token =<br />
luw token, Cics_RC = cics rc,<br />
Message_Qualifier = message<br />
qualifier, Abend code = abend code<br />
Explanation: The specified parameters were<br />
returned to the CTG after an ECI request.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6833I EPI Get Sys Error Doesn’t call the<br />
client fixed values are Cics_RC =<br />
cics rc, Cause = cause, Value =<br />
value.<br />
Explanation: The message provides details of<br />
the last system error and is triggered by an API<br />
call.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6834I EPI Event Exit Parameters . Size =<br />
size, Event = event, EndReason =<br />
endreason, Cics_RC = rc.<br />
Explanation: The message details what the<br />
specified data is set to after an EPI_GET_EVENT.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6835I EPI Sense Code Exit Parameters.<br />
SenseCode = sense code, Cics_RC =<br />
rc.<br />
Explanation: The CTG is about to exit from the<br />
EPI Sense Code call with a sense code and return<br />
code as indicated.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
Messages 67
CCL6836I CCL6844I<br />
CCL6836I EPI ATI State Exit Parameters.<br />
ATIState = ati state, Cics_RC = rc.<br />
Explanation: The CTG is about to exit from the<br />
EPI ATI State call with an ATI state and return<br />
code as indicated.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6837I EPI Reply Entry Parameters.<br />
Terminal Index = terminal index,<br />
Size = size.<br />
Explanation: This message shows that the CTG<br />
is about to send an EPI Reply call, using the<br />
specified parameters.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6838I EPI Start <strong>Transaction</strong> Entry<br />
Parameters. Terminal Index =<br />
terminal index, TransId = transaction<br />
id, Size=size.<br />
Explanation: This messages shows the CTG is<br />
about to start a transaction on the specified<br />
terminal with the specified transaction id.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6839I EPI Delete Terminal Entry<br />
Parameters. Terminal Index =<br />
terminal index.<br />
Explanation: The CTG is about to delete the<br />
terminal with the specified terminal index.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6840I EPI Inquire System Entry<br />
Parameters. Terminal Index =<br />
terminal index.<br />
Explanation: The CTG is about to inquire which<br />
system the terminal specified is connected to.<br />
68 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6841I EPI Add Terminal Entry<br />
Parameters. Server = server,<br />
NetName = netname, DeviceType =<br />
device type.<br />
Explanation: The CTG is about to install or<br />
reserve a terminal resouce to the specified server,<br />
with the specified netname, and of the specified<br />
device type.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6842I EPI Server List Entry Parameters.<br />
Number of Systems = number of<br />
systems.<br />
Explanation: The CTG is about to list the <strong>CICS</strong><br />
Systems available to be used by the EPI API.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6843I EPI Initialise/Terminate Entry<br />
Parameters. Call_Type = call type.<br />
Explanation: The CTG is about to initialize or<br />
terminate the EPI interface. A call type of 1<br />
indicates initialization, all other values indicate<br />
termination.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6844I ESI verifyPassword Exit results<br />
Server = server, Cics_RC = return<br />
code.<br />
Explanation: The specified return code was<br />
received from the specified server following an<br />
ESI verifyPassword request.<br />
System Action: CTG processing will continue.<br />
User Response: If the return code is non-zero,<br />
the user can reference the cics_esi.h file supplied<br />
with the CTG for information on the return code.
CCL6845I EPI Purge Terminal Entry<br />
Parameters. Terminal Index =<br />
terminal index.<br />
Explanation: The CTG is about to purge the<br />
terminal specified by the terminal index.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6846I EPI Purge Terminal Exit<br />
Parameters. Cics_RC = rc.<br />
Explanation: The CTG has completed the purge<br />
terminal request, and is exiting the function with<br />
the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6847I EPI Add Extended Terminal Entry<br />
Parameters. Server = server,<br />
NetName = netname, DeviceType =<br />
device type, add type = add type,<br />
Install Timeout = install timeout,<br />
Read Timeout = read timeout,<br />
CCSid = ccs id, Signon Type =<br />
signon type.<br />
Explanation: The CTG is about to install or<br />
reserve an extended mode terminal resouce to<br />
the specified server, with the specified netname,<br />
and of the specified device type. Other<br />
parameters specified are as displayed.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6848I EPI Add Extended Terminal Exit<br />
Parameters. Server = server,<br />
NetName = netname, Termid=<br />
termid, Termindex = terminal index,<br />
signon Type = signon type, max<br />
data = max data, Cics_RC = return<br />
code.<br />
Explanation: The attempt to install or reserve<br />
an extended mode terminal resouce to the<br />
specified server has completed with the return<br />
CCL6845I CCL6852I<br />
code specified. Other parameters retured are as<br />
specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6849I EPI Set Security Entry Parameters.<br />
Terminal Index = terminal index.<br />
Explanation: The CTG will set security on the<br />
terminal resource specified by the terminal index.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6850I EPI Delete Terminal Exit<br />
Parameters. Cics_RC = return code.<br />
Explanation: The CTG completed the Delete<br />
Terminal request with the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6851I EPI Set Security Exit Parameters.<br />
Cics_RC = return code.<br />
Explanation: The CTG completed the Set<br />
Security call with the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6852I EPI Add Terminal Exit<br />
Parameters. Server = server,<br />
NetName = netname, Termid=<br />
termid, Termindex = terminal index,<br />
signon Type = signon type, max<br />
data = max data, Cics_RC = return<br />
code.<br />
Explanation: The CTG completed the EPI Add<br />
Terminal request with the specified return code.<br />
Other parameters returned are as specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
Messages 69
CCL6853I CCL6861I<br />
CCL6853I ESI verifyPassword Entry<br />
Parameters Server = server.<br />
Explanation: The CTG is about to perform a<br />
verifyPassword request to the server specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6854I ESI changePassword Entry<br />
Parameters Server = server.<br />
Explanation: The CTG is about to perform a<br />
changePassword request to the server specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6855I ESI changePassword Exit results<br />
Server = server, Cics_RC = return<br />
code.<br />
Explanation: The CTG completed the change<br />
password request to the specified server with the<br />
displayed return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6856I EPI ATI State Entry Parameters.<br />
Terminal Index = terminal index,<br />
ATIState = ATI state.<br />
Explanation: The CTG is about to alter or query<br />
the ATI state on the server specified. If ATI state<br />
is specified, the ATI state will be changed.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6857I EPI Event Entry Parameters.<br />
Terminal Index = terminal index,<br />
Wait State = wait state.<br />
Explanation: The CTG is about to process a<br />
GET_EVENT on the terminal specified, with a<br />
wait state as shown.<br />
System Action: CTG processing will continue.<br />
70 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: No further action is required.<br />
CCL6858I EPI Event Add Terminal Exit<br />
Parameters. Server = server,<br />
NetName = netname, Termid=<br />
terminal id, Termindex = terminal<br />
index, signon Type = signon type,<br />
max data = max data, Cics_RC =<br />
return code.<br />
Explanation: The CTG has completed the Add<br />
Terminal request with the specified return code.<br />
Other parameters returned are as specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6859I EPI Initialise/Terminate Exit<br />
Parameters. Cics_RC = return code.<br />
Explanation: The CTG has completed<br />
initialising or terminating the EPI interface. The<br />
return code from this operation is as specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6860I EPI Inquire System Exit<br />
Parameters. System = system,<br />
Cics_RC = return code.<br />
Explanation: The CTG has completed the<br />
Inquire System call. The system returned is the<br />
one connected to the terminal resource specified<br />
on the call. The return code for the call is as<br />
specified.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6861I EPI Reply Exit Parameters.<br />
Cics_RC = return code.<br />
Explanation: The CTG has completed the EPI<br />
Reply requested with the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.
CCL6862I EPI Sense Code Entry Parameters.<br />
Terminal Index = teminal index.<br />
Explanation: The CTG is about to perform an<br />
EPI Sense Code call for the terminal resource<br />
specified by the terminal index.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6863I EPI Start <strong>Transaction</strong> Exit<br />
Parameters. Cics_RC = return code.<br />
Explanation: The CTG has completed the EPI<br />
Start <strong>Transaction</strong> call with the specified return<br />
code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6864I EPI Server List Exit Parameters.<br />
Cics_RC = return code.<br />
Explanation: The CTG has completed the EPI<br />
Server List call with the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6865I ECI Server List Entry Parameters.<br />
Number of Systems = number of<br />
systems.<br />
Explanation: The CTG is about to request a list<br />
of the servers that are available for ECI<br />
connections. The maximum number of systems<br />
to be returned is displayed.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6866I ECI Server List Exit Parameters.<br />
Cics_RC = return code.<br />
Explanation: The CTG has completed the ECI<br />
Server List call with the specified return code.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6862I CCL6873E<br />
CCL6867I <strong>CICS</strong> CP Request Entry<br />
Parameters. length in = length.<br />
Explanation: The CTG is about to obtain the<br />
codepage details from the system This message<br />
should not be displayed when using the MVS<br />
platform.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6868I <strong>CICS</strong> CP Request Exit Parameters.<br />
data = data, length out = length out,<br />
Rc = return code.<br />
Explanation: The CTG has completed the CP<br />
request call with the specified return code. This<br />
message should not be displayed when using the<br />
MVS platform.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6869E Change trace file name failed.<br />
filename = file name.<br />
Explanation: An attempt to change the JNI<br />
Trace file name to file name has failed.<br />
System Action: CTG will throw an<br />
TFileException. CTG processing will continue.<br />
JNI Tracing continues using the existing file<br />
name.<br />
User Response: User code should handle the<br />
exception. Check that the file name is valid and<br />
can be written to.<br />
CCL6873E conninit: Already initialized.<br />
Explanation: EXCI connection reuse has already<br />
been initialized.<br />
System Action: The CTG will return an<br />
ECI_ERR_SYSTEM_ERROR error.<br />
User Response: The user should contact their<br />
support representative for more information and<br />
diagnosis.<br />
Messages 71
CCL6874E CCL6901E<br />
CCL6874E conninit: Memory allocation<br />
failure for TCB table for number<br />
TCB entries.<br />
Explanation: The CTG was unable to allocate<br />
memory for the number of TCB entries specified.<br />
System Action: The CTG will return an<br />
ECI_ERR_RESOURCE_SHORTAGE error.<br />
User Response: The user should ensure the<br />
CTG has enough memory available to it to<br />
operate correctly.<br />
CCL6875I CcicsECI: EXCI warning. EXCI<br />
Reason = %lu, Subreason field-1<br />
= %lu, subreason field-2 =<br />
199105866″<br />
Explanation: A warning has occurred in EXCI -<br />
See the <strong>CICS</strong> External Interfaces Guide for<br />
explanation.<br />
System Action: The Server has issued an EXCI<br />
warning; refer to the EXCI documentation for<br />
details.<br />
User Response: Diagnose the warning by<br />
refering to the <strong>CICS</strong> External Interfaces Guide<br />
and try again.<br />
CCL6876E CcicsECI: EXCI error. EXCI<br />
Reason = return code, Subreason<br />
field-1 = return code, subreason<br />
field-2 = return code<br />
Explanation: An error has occurred in EXCI -<br />
See the <strong>CICS</strong> External Interfaces Guide for<br />
explanation.<br />
System Action: The Server has issued an EXCI<br />
error; refer to the EXCI documentation for<br />
details.<br />
User Response: Diagnose the error by refering<br />
to the <strong>CICS</strong> External Interfaces Guide and try<br />
again.<br />
CCL6877E Internal: Unknown Tracepoint!<br />
num = number.<br />
Explanation: JNI Tracing has sent an unknown<br />
trace point to the formatter.<br />
72 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: Cannot be sure what will<br />
happen as we do not know this trace point.<br />
User Response: Route this trace to service to<br />
identify the undefined trace point.<br />
CCL6878E Surrogate check failed.<br />
SURROGCHK=yes set in<br />
DFHXCOPT. EXCI Reason =<br />
return code, Subreason field-1 =<br />
return code, subreason field-2 =<br />
return code<br />
Explanation: The surrogate user check has<br />
failed.<br />
System Action: The DPL call is rejected. The<br />
MVS External Security Manager’s return code<br />
and reason code are subreason codes 1 and 2.<br />
User Response: Check whether SURROGCHK<br />
has been set to YES in DFHXCOPT, and that the<br />
credentials are accurate.<br />
CCL6879I Generic pipe used.<br />
Explanation: A generic pipe has been used for<br />
the connection.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6880I Specific pipe used.<br />
NETNAME=name<br />
Explanation: A specific pipe, named name has<br />
been used.<br />
System Action: CTG processing will continue.<br />
User Response: No further action is required.<br />
CCL6901E Exception occurred [{0}]<br />
Explanation: This message is added to the<br />
servlet log when an unexpected error occurs.<br />
System Action: System action is not required.<br />
User Response: Reset TerminalServlet and<br />
restart application.
CCL6902I Initialization: loading property<br />
file {0}<br />
Explanation: This message is added to the<br />
servlet log when the servlet loads a properties<br />
file.<br />
System Action: Servlet opens properties file.<br />
User Response: For information only.<br />
CCL6903E Initialization failed. Property file<br />
{0} not found<br />
Explanation: This message is added to the<br />
servlet log if the servlet cannot find the property<br />
file {0}.<br />
System Action: The servlet will not start.<br />
User Response: Check if property file exists and<br />
the location is correct.<br />
CCL6904E Initialization failed. Error reading<br />
property file {0}<br />
Explanation: The servlet could not read the<br />
property file {0}.<br />
System Action: The servlet will not start.<br />
User Response: Ensure that the servlet property<br />
file is in the correct format.<br />
CCL6905W Initialization: property {0}={1} is<br />
invalid and has been ignored.<br />
Explanation: This message is added to the<br />
servlet log if, during initialization, the servlet<br />
finds that an initialization parameter or property<br />
file entry is not valid. This could mean either<br />
that the property name is incorrect, or that the<br />
value specified is not a valid setting for the<br />
property.<br />
System Action: The servlet continues running.<br />
User Response: Check if property is valid.<br />
CCL6902I CCL6911W<br />
CCL6906I Initialization completed<br />
successfully.<br />
Explanation: This message is added to the<br />
servlet log when the servlet has started.<br />
System Action: Servlet ready to start.<br />
User Response: For information only.<br />
CCL6907I The servlet is shutting down. In<br />
progress sessions will be<br />
terminated.<br />
Explanation: This message is added to the<br />
servlet log when the servlet begins shutting<br />
down.<br />
System Action: The servlet will shut down.<br />
User Response: For information only.<br />
CCL6908I The servlet has now stopped.<br />
Explanation: This message is added to the<br />
servlet log when the servlet has been unloaded.<br />
System Action: Unloading servlet.<br />
User Response: For information only.<br />
CCL6910W The requested action: {0} is<br />
unrecognized.<br />
Explanation: This message is added to the<br />
servlet log if the value of the ″request″ parameter<br />
is unrecognized. The only supported values of<br />
″request″ are ″send″ and ″disconnect″.<br />
System Action: The request is not completed.<br />
User Response: Check that request is send or<br />
disconnect.<br />
CCL6911W Failed to allocate a terminal for<br />
this request.<br />
Explanation: A terminal could not be allocated<br />
for a user. This could be because a terminal<br />
could not be connected to <strong>CICS</strong> (for example, if<br />
the server is down), or the maximum number of<br />
terminals are in use.<br />
System Action: Unable to allocate a terminal.<br />
Messages 73
CCL6913W CCL6923I<br />
User Response: Check server is running and<br />
maximum number of terminals has not been<br />
exceeded.<br />
CCL6913W File {0} not found<br />
Explanation: The file indicated could not be<br />
loaded by the servlet.<br />
System Action: System unable to load file.<br />
User Response: Check if file is available and is<br />
in the correct location.<br />
CCL6914I Setting property {0} to the value:<br />
{1}<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when the<br />
servlet is requested to set a property value.<br />
System Action: Set property value.<br />
User Response: For information only.<br />
CCL6915I Initialization: reading parameters<br />
Explanation: This message is added to the<br />
servlet log when the servlet begins processing its<br />
initialization parameters.<br />
System Action: Initialization reading<br />
parameters.<br />
User Response: For information only.<br />
CCL6916E Failed to initialize terminal pool.<br />
The error message is: {0}<br />
Explanation: This message is added to the<br />
servlet log if an error occurs while creating the<br />
terminal pool. The servlet will not start.<br />
System Action: Servlet exit.<br />
User Response: Check error message.<br />
CCL6917I Creating screen handler bean {0}<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when the<br />
servlet has loaded a screen handler bean.<br />
74 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: Servlet loading screen handler<br />
bean.<br />
User Response: For information only.<br />
CCL6918I Getting the property named {0}<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when the<br />
servlet is requested to display a property value.<br />
System Action: Servlet displays a property<br />
value.<br />
User Response: For information only.<br />
CCL6919W The property named {0} does not<br />
exist<br />
Explanation: This message is added to the<br />
servlet log when the servlet is requested to set or<br />
to display a property which it does not<br />
recognize.<br />
System Action: Servlet cannot find property.<br />
User Response: Check property name is correct<br />
and exists.<br />
CCL6920I Setting screen wrapper class to {0}<br />
Explanation: Screen wrapper is being set to a<br />
different class.<br />
System Action: System action is not required.<br />
User Response: For information only.<br />
CCL6921I Handling a request<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when a<br />
request is processed.<br />
System Action: Execute request.<br />
User Response: For information only.<br />
CCL6923I Redirecting to page: {0}<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when the<br />
next page to display to the user has been<br />
determined.
System Action: Redirect to a loaded page.<br />
User Response: For information only.<br />
CCL6924E An error occurred while<br />
processing the request.<br />
Explanation: An error occurred while a request<br />
was being processed. Further messages should<br />
indicate the cause of the problem.<br />
System Action: Terminate request.<br />
User Response: Check further messages for<br />
cause of problem.<br />
CCL6925I Request processing has<br />
completed.<br />
Explanation: If extended logging is on, this<br />
message is added to the servlet log when a<br />
request has been processed.<br />
System Action: Request has been completed.<br />
User Response: For information only.<br />
CCL6999E Unable to open ini file {0}<br />
Explanation: The <strong>Gateway</strong> cannot find CTG.INI,<br />
or the ini file specified by the user.<br />
System Action: The <strong>Gateway</strong> stops; it will not<br />
run without an ini file.<br />
User Response: Check that CTG.INI exists in<br />
the bin directory, or that the ini file specified<br />
through the <strong>CICS</strong>CLI environment variable<br />
exists. Run the configuration tool if necessary to<br />
create an ini file.<br />
CCL7023E Command option option is invalid<br />
Explanation: An invalid command option was<br />
specified when starting the <strong>CICS</strong>TERM or<br />
<strong>CICS</strong>PRNT 3270 emulator.<br />
System Action: The emulator terminates.<br />
User Response: Restart the emulator with the<br />
correct option.<br />
CCL6924E CCL7028E<br />
CCL7024E Command option option must<br />
specify a value<br />
Explanation: A <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT<br />
command was issued with no value supplied for<br />
the named required option.<br />
System Action: The emulator terminates.<br />
User Response: Restart the emulator using a<br />
valid value for the option.<br />
CCL7025E Command option option cannot be<br />
used more than once<br />
Explanation: On a <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT<br />
command, the named option was used more<br />
than once. This is invalid.<br />
System Action: The emulator terminates.<br />
User Response: Restart the emulator using the<br />
correct options.<br />
CCL7026E Command option option1 cannot<br />
be used with option option2<br />
Explanation: The two named options, used on a<br />
<strong>CICS</strong>TERM or <strong>CICS</strong>PRNT command, were<br />
incompatible.<br />
System Action: The emulator terminates.<br />
User Response: Restart the emulator using the<br />
correct options.<br />
CCL7027E Command option option1 or<br />
option2 must be provided<br />
Explanation: A <strong>CICS</strong>PRNT command did not<br />
include one of the named required options.<br />
System Action: The emulator terminates.<br />
User Response: Restart the emulator using the<br />
correct options.<br />
CCL7028E Cannot open binding file file name<br />
Explanation: <strong>CICS</strong>TERM could not find or open<br />
the specified color, or keyboard, binding file.<br />
System Action: The emulator terminates.<br />
Messages 75
CCL7029E CCL7036E<br />
User Response: Ensure the required binding<br />
files exist and are correctly specified, then restart<br />
the emulator.<br />
CCL7029E Out of memory processing<br />
binding file file name<br />
Explanation: <strong>CICS</strong>TERM ran out of memory<br />
while processing a color, or keyboard, binding<br />
file.<br />
System Action: The emulator terminates.<br />
User Response: Reduce the number of bindings<br />
specified in the file or try to provide more<br />
system free memory; then restart the emulator.<br />
CCL7030E Error detected at line number in<br />
binding file file name - duplicate<br />
bind for item item<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
color, or keyboard, binding file. Only one<br />
binding is allowed for the specified item.<br />
System Action: The emulator terminates.<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7031E Error detected at line number in<br />
binding file file name - unknown<br />
command command<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
color, or keyboard, binding file. The specified<br />
command was not a valid binding command.<br />
System Action: The emulator terminates.<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7032E Error detected at line number in<br />
binding file file name - invalid<br />
function function<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
keyboard binding file. The specified item was not<br />
a valid 3270 keyboard function.<br />
System Action: The emulator terminates.<br />
76 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7033E Error detected at line number in<br />
binding file file name - invalid<br />
modifier modifier<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
keyboard binding file. The specified item was not<br />
a valid workstation keyboard modifier value.<br />
System Action: The emulator terminates.<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7034E Error detected at line number in<br />
binding file file name - invalid key<br />
key<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
keyboard binding file. The specified item was not<br />
a valid workstation key name.<br />
System Action: The emulator terminates.<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7035E Error detected at line number in<br />
binding file file name - invalid<br />
attribute attribute<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
color binding file. The specified item was not a<br />
valid 3270 screen field attribute.<br />
System Action: The emulator terminates.<br />
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7036E Error detected at line number in<br />
binding file file name - invalid<br />
color color<br />
Explanation: <strong>CICS</strong>TERM detected an error in a<br />
color binding file. The specified item was not a<br />
valid workstation display color.<br />
System Action: The emulator terminates.
User Response: Correct the binding file and<br />
restart the emulator.<br />
CCL7037E Unable to communicate with the<br />
<strong>CICS</strong> Client<br />
Explanation: <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT could<br />
not communicate with the client process. This<br />
probably means the client was unable to start.<br />
System Action: The emulator terminates.<br />
User Response: Try to start the client using the<br />
<strong>CICS</strong>CLI /S command.<br />
CCL7038E The <strong>CICS</strong> Client has not been<br />
started<br />
Explanation: <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT did not<br />
start because the client was not, or could not be,<br />
started.<br />
System Action: The emulator terminates.<br />
User Response: Try to start the client using the<br />
<strong>CICS</strong>CLI /S command.<br />
CCL7039I EMULATOR - <strong>CICS</strong> server<br />
selection<br />
Explanation: The emulator was started with the<br />
/R or /S option and a server name was not<br />
specified to connect <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT to.<br />
System Action: A list of available server names<br />
is provided.<br />
User Response: Choose the required server<br />
from the list or CANCEL to terminate the<br />
emulator.<br />
CCL7043E Terminal screen width is invalid -<br />
reset to 80 columns<br />
Explanation: The server returned a terminal<br />
definition that contained an invalid screen width<br />
for the terminal emulator. (Screen widths are<br />
normally 40, 80, or 132 columns.)<br />
System Action: The emulator resets the screen<br />
width to a standard 80 columns. Output may<br />
appear corrupted because the client and server<br />
terminal definitions may not match.<br />
CCL7037E CCL7046E<br />
User Response: Check with the server system<br />
administrator to determine why the terminal<br />
definition is incorrect.<br />
CCL7044E Terminal screen size is too large -<br />
reset to maximum<br />
Explanation: The server returned a terminal<br />
definition that contained a screen size too large<br />
for the terminal emulator. The product of screen<br />
width and screen depth cannot exceed 4096.<br />
System Action: The emulator resets the screen<br />
depth to the maximum number of rows. Output<br />
may appear corrupted because the client and<br />
server terminal definitions may not match.<br />
User Response: Check with the server system<br />
administrator to determine why the terminal<br />
definition is incorrect.<br />
CCL7045E Connection lost with server server<br />
Explanation: The connection with the specified<br />
server has been lost. This would normally<br />
indicate that the server is no longer available.<br />
System Action: The emulator waits until the<br />
server is available again and tries to reconnect.<br />
User Response: Wait for the connection to be<br />
reestablished or clear the error message and<br />
terminate the emulator.<br />
CCL7046E The <strong>CICS</strong> Client reported a<br />
resource shortage<br />
Explanation: The client returned a resource<br />
shortage error. This would normally indicate that<br />
the client ran out of free memory. If SNA<br />
communications are being used, it may indicate<br />
that there are insufficient LU6.2 sessions<br />
available.<br />
System Action: The emulator attempts to<br />
continue, although further requests to the client<br />
may receive the same error response.<br />
User Response: If the client is very busy the<br />
resource shortage may disappear when the client<br />
becomes less loaded. Otherwise, examine the<br />
client error log and, if possible, trace information<br />
to determine the cause of the error. Then, stop<br />
Messages 77
CCL7047E CCL7054I<br />
the client and reconfigure it to provide more of<br />
the particular resource causing the problem.<br />
CCL7047E The <strong>CICS</strong> Client is closing down<br />
Explanation: <strong>CICS</strong>TERM or <strong>CICS</strong>PRNT could<br />
not be started because the client was closing<br />
down.<br />
System Action: The emulator terminates.<br />
User Response: Wait for the client to close<br />
down, then restart the emulator.<br />
CCL7048E Server server is undefined<br />
Explanation: The client indicated that the<br />
specified server name is unknown.<br />
System Action: The emulator terminates.<br />
User Response: Ensure the required server<br />
name is one of those listed in the client<br />
initialization file, or use the /S option to select<br />
from a list of valid names.<br />
CCL7049E Unable to connect to server server<br />
Explanation: The client was unable to connect<br />
to the specified server.<br />
System Action: The emulator terminates.<br />
User Response: Check for other messages and<br />
examine the client error log to determine the<br />
cause of the error.<br />
CCL7050E The MaxBufferSize setting is too<br />
small for this terminal<br />
Explanation: The emulator tried to send more<br />
data than the client could accept.<br />
System Action: The data is ignored and the<br />
emulator continues.<br />
User Response: Increase the MaxBufferSize<br />
value in the Client section of the client<br />
initialization file and stop, then restart, the client.<br />
78 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL7051E Server server does not support<br />
client terminals<br />
Explanation: Client 3270 emulator terminals are<br />
not supported by all <strong>CICS</strong> servers. The specified<br />
server is one of those that does not provide this<br />
support. If this is a <strong>CICS</strong>/400 server this message<br />
can also be generated if <strong>CICS</strong> is unavailable.<br />
System Action: The emulator terminates.<br />
User Response: Select a server that does<br />
support client terminals or check with the server<br />
system administrator to determine why client<br />
terminals are not supported.<br />
CCL7052E Server server rejected this terminal<br />
with a security error<br />
Explanation: The specified server is secure and<br />
required a valid userid and password before it<br />
could install a client terminal.<br />
System Action: The emulator terminates.<br />
User Response: Enter a valid userid and<br />
password when prompted by the client.<br />
Alternatively, to avoid the prompt use the<br />
<strong>CICS</strong>CLI /C command to set the userid and<br />
password.<br />
CCL7053E Errors found while<br />
communicating with server server<br />
Explanation: The client encountered errors<br />
while communicating with the specified server.<br />
System Action: The emulator ignores the errors<br />
and tries to continue.<br />
User Response: Check for other messages and<br />
examine the client error log to determine the<br />
cause of the error.<br />
CCL7054I Server server is currently<br />
unavailable<br />
Explanation: The client found that the specified<br />
server was currently unavailable.<br />
System Action: The emulator waits until the<br />
server becomes available and then tries to<br />
connect.
User Response: Wait for the connection to be<br />
established or clear the error message and<br />
terminate the emulator.<br />
CCL7055E Terminal install failed - NetName<br />
name is invalid<br />
Explanation: The server rejected the terminal<br />
because the specified NetName was invalid.<br />
System Action: The emulator terminates.<br />
User Response: Ensure the requested terminal<br />
NetName is correct and defined at the server. If<br />
the error persists, check with the server system<br />
administrator for the cause of the error.<br />
CCL7056E Terminal install failed - Model<br />
model is invalid<br />
Explanation: The server rejected the terminal<br />
because the specified Model was invalid.<br />
System Action: The emulator terminates.<br />
User Response: Ensure the requested terminal<br />
Model is correct and defined at the server. If the<br />
error persists, check with the server system<br />
administrator for the cause of the error.<br />
CCL7057E Terminal install failed - NetName<br />
name is already installed<br />
Explanation: The server rejected the request<br />
because another terminal was already installed<br />
with the same NetName.<br />
System Action: The emulator terminates.<br />
User Response: Ensure the requested terminal<br />
NetName is correct. If the error persists, check<br />
with the server system administrator for the<br />
cause of the error.<br />
CCL7058E Terminal install failed - rejected<br />
by the server<br />
Explanation: The server was unable to accept<br />
the terminal and rejected the installation request.<br />
System Action: The emulator terminates.<br />
User Response: Check with the server system<br />
CCL7055E CCL7062E<br />
administrator to determine why the terminal was<br />
rejected.<br />
CCL7059E Terminal install failed - reason<br />
unknown<br />
Explanation: The server rejected the terminal.<br />
System Action: The emulator terminates.<br />
User Response: Check with the server system<br />
administrator to determine why the terminal was<br />
rejected.<br />
CCL7060I DBCS datastream errors detected<br />
Explanation: The terminal emulator detected<br />
errors in the DBCS datastream.<br />
System Action: The terminal emulator ignores<br />
the errors and tries to continue.<br />
User Response: Check with the server system<br />
administrator to determine why incorrect data is<br />
being generated. Client trace information may be<br />
helpful when trying to find these errors.<br />
CCL7061E Unable to open or create print<br />
output file<br />
Explanation: The terminal emulator was unable<br />
to open or create the local print file specified by<br />
the PrintFile option in the client initialization file.<br />
System Action: The print request is ignored and<br />
the terminal emulator continues.<br />
User Response: Ensure the name of the print<br />
file you specified in the client initialization file is<br />
correct and accessible.<br />
CCL7062E Unable to write to the print<br />
output file<br />
Explanation: The terminal was unable to write<br />
to the local print file specified by the PrintFile<br />
option in the client initialization file.<br />
System Action: The print request is ignored and<br />
the emulator continues.<br />
User Response: Ensure the name of the print<br />
Messages 79
CCL7063E CCL7074E<br />
file you specified in the client initialization file is<br />
correct and accessible.<br />
CCL7063E Unable to execute print command<br />
Explanation: The terminal emulator is unable to<br />
execute the local print command specified by the<br />
PrintCommand option in the client initialization<br />
file.<br />
System Action: The print request is ignored and<br />
the emulator continues.<br />
User Response: Ensure the print command you<br />
specified in the client initialization file is correct.<br />
CCL7069E Server server has reported a<br />
transaction ABEND<br />
Explanation: The specified server reported an<br />
ABEND while trying to run the current<br />
transaction. This may have been caused by a<br />
communications failure between the client and<br />
server.<br />
System Action: The terminal emulator ignores<br />
the errors and tries to continue.<br />
User Response: Examine any other messages<br />
and the client error log and server error log to<br />
determine the cause of the error.<br />
CCL7070E Terminal screen depth is invalid -<br />
reset to 24 rows<br />
Explanation: The server returned a terminal<br />
definition that contained an invalid screen depth<br />
for the terminal emulator. (Screen depths are<br />
normally between 10 and 60 rows).<br />
System Action: The terminal emulator has reset<br />
the screen depth to a standard 24 rows. Output<br />
may appear corrupted because the terminal<br />
emulator and server terminal definitions may not<br />
match.<br />
User Response: Check with the server system<br />
administrator to determine why the terminal<br />
definition is incorrect.<br />
80 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL7071E Screen data exceeds the display<br />
space available<br />
Explanation: The server returned more data<br />
than the terminal emulator can accept.<br />
System Action: The excess data is ignored and<br />
the terminal emulator tries to continue.<br />
User Response: Check with the server system<br />
administrator to determine why such a large<br />
amount of data is being generated. Client trace<br />
information may be helpful when trying to find<br />
these errors.<br />
CCL7072E The <strong>CICS</strong> Client has reached its<br />
MaxServers limit of number<br />
Explanation: The client can only communicate<br />
simultaneously with the number of servers<br />
specified by the MaxServers option in the Client<br />
section of the client initialization file. This limit<br />
has been reached.<br />
System Action: The emulator terminates.<br />
User Response: Use the <strong>CICS</strong>CLI /X command<br />
to close connections to servers that are no longer<br />
required, or increase the ″MaxServers″ setting in<br />
the client initialization file; then stop and restart<br />
the client.<br />
CCL7073E Terminal install failed - requested<br />
terminal is not a 3270 device<br />
Explanation: The server rejected the terminal<br />
because the server terminal definition does not<br />
represent a 3270 device.<br />
System Action: The emulator terminates.<br />
User Response: Ensure the requested terminal<br />
Model or NetName is correct and correctly<br />
defined at the server. If the error persists, check<br />
with the server system administrator for the<br />
cause of the error.<br />
CCL7074E Terminal install failed - server is<br />
busy<br />
Explanation: The server rejected the terminal<br />
emulator because the server was too busy.
System Action: The emulator terminates.<br />
User Response: Retry the request sometime<br />
later when the server is not so busy.<br />
CCL7098E An internal processing error has<br />
occurred<br />
Explanation: The terminal emulator detected an<br />
unexpected internal error.<br />
System Action: Error information is written to<br />
the client error log.<br />
User Response: Obtain the client error log -<br />
and, if possible, trace information - and refer the<br />
problem to your support organization.<br />
CCL7099I Refer to the error log for more<br />
details<br />
Explanation: An error has occurred for which<br />
further useful diagnostic information has been<br />
written to the client error log.<br />
System Action: Client processing continues.<br />
User Response: Examine the client error log to<br />
obtain the information.<br />
CCL7101 Internal transport error (function,<br />
error)<br />
Explanation: An internal emulator function<br />
failed.<br />
System Action: The message is written to the<br />
error log and the emulator terminates. The<br />
function name and error code are logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL7103 Internal Windows function error<br />
(function)<br />
Explanation: An internal Windows function<br />
failed.<br />
System Action: The message is written to the<br />
error log and the emulator terminates. The<br />
function name is logged.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL7098E CCL7108E<br />
CCL7104 Emulator has insufficient memory<br />
to create an internal control<br />
structure<br />
Explanation: The emulator is unable to allocate<br />
enough memory to create an internal control<br />
structure.<br />
System Action: The message is written to the<br />
error log and the emulator terminates.<br />
User Response: Try altering the system<br />
configuration to provide more free memory<br />
when the emulator is started, then restart the<br />
emulator.<br />
CCL7105 Emulator received incorrect sized<br />
data block(s) (size1, size2)<br />
Explanation: The emulator has received<br />
incorrect data from the Client daemon.<br />
System Action: The message is written to the<br />
error log and the emulator continues.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL7106 Emulator ATI table error<br />
Explanation: The emulator has received too<br />
many outstanding ATI requests from the server.<br />
System Action: The message is written to the<br />
error log and the emulator continues.<br />
User Response: Try to establish why the<br />
emulator is receiving large numbers of ATI<br />
requests while being unable to initiate them. If<br />
the problem persists contact your service<br />
organization.<br />
CCL7108E No <strong>CICS</strong> servers are available<br />
Explanation: There no <strong>CICS</strong> servers available<br />
for the emulator to use.<br />
System Action: The emulator terminates.<br />
User Response: Check that there are one or<br />
more valid <strong>CICS</strong> servers in either the <strong>CICS</strong> Client<br />
Messages 81
CCL7109E CCL7116<br />
initialization file. If load management exits are<br />
active then check that at least one of the servers<br />
the emulator tried to connect to is available.<br />
Examine the Client trace to see which servers the<br />
load management attempted to connect to.<br />
CCL7109E <strong>CICS</strong>_EpiAddTerminal rejected by<br />
the EPI user exit<br />
Explanation: The EPI user exit (<strong>CICS</strong>EPIX)<br />
returned <strong>CICS</strong>_EXIT_DONT_ADD_TERMINAL<br />
and rejected the <strong>CICS</strong>_EpiAddTerminal request.<br />
System Action: The EPI terminal is not added.<br />
User Response: Check with the server system<br />
administrator to determine why the terminal was<br />
rejected.<br />
CCL7110 <strong>CICS</strong>_EciInitializeExit returned rc<br />
= rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciInitializeExit was called and returned a<br />
return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7111 <strong>CICS</strong>_EciTerminateExit returned<br />
rc = rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciTerminateExit was called and returned a<br />
return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7112 <strong>CICS</strong>_EciExternalCallExit1<br />
returned rc = rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciExternalCallExit1 was called and<br />
returned a return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
82 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: None.<br />
CCL7113 <strong>CICS</strong>_EciExternalCallExit2<br />
returned rc = rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciExternalCallExit2 was called and<br />
returned a return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7114 <strong>CICS</strong>_EciSystemIdExit returned rc<br />
= rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciSystemIdExit was called and returned a<br />
return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7115 <strong>CICS</strong>_EciDataSendExit returned rc<br />
= rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciDataSendExit was called and returned a<br />
return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7116 <strong>CICS</strong>_EciDataReturnExit returned<br />
rc = rc<br />
Explanation: The ECI user exit function<br />
<strong>CICS</strong>_EciDataReturnExit was called and returned<br />
a return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.
CCL7117 <strong>CICS</strong> ECI user exit loaded,<br />
DLLPathName<br />
Explanation: The ECI user exit <strong>CICS</strong>ECIX.DLL<br />
has been successfully loaded, the full path name<br />
being DLLPathName.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7118 About to call <strong>CICS</strong>_ECIEXITINIT<br />
Explanation: The ECI user exit initialization<br />
function <strong>CICS</strong>_ECIEXITINIT is about to be<br />
called.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7119 <strong>CICS</strong> ECI user exit active flag =<br />
flag<br />
Explanation: The ECI user exit initialization has<br />
completed and the boolean ECI exit active flag is<br />
0 for inactive and 1 for active.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7120 About to call ECI user exit<br />
Explanation: An ECI user exit function is about<br />
to be called.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7121 <strong>CICS</strong> EPI user exit loaded,<br />
DLLPathName<br />
Explanation: The EPI user exit <strong>CICS</strong>EPIX.DLL<br />
has been successfully loaded, the full path name<br />
being DLLPathName.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7122 About to call <strong>CICS</strong>_EPIEXITINIT<br />
Explanation: The EPI user exit initialization<br />
function <strong>CICS</strong>_EPIEXITINIT is about to be called.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7123 <strong>CICS</strong> EPI user exit active flag =<br />
flag<br />
Explanation: The EPI user exit initialization has<br />
completed and the boolean EPI exit active flag is<br />
0 for inactive and 1 for active.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7124 <strong>CICS</strong> EPI user exit unloaded,<br />
DLLPathName<br />
Explanation: The EPI user exit <strong>CICS</strong>EPIX.DLL<br />
has been successfully unloaded, the full path<br />
name being DLLPathName.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7125 <strong>CICS</strong>_EpiInitializeExit returned rc<br />
= rc<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiInitializeExit was called and returned a<br />
return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7117 CCL7125<br />
Messages 83
CCL7126 CCL7133<br />
CCL7126 <strong>CICS</strong>_EpiTerminateExit returned<br />
rc = rc<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiTerminateExit was called and returned<br />
a return code of rc.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7127 <strong>CICS</strong>_EpiAddTerminalExit<br />
returned rc = rc, System system,<br />
NetName netname, DevType<br />
devtype<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiAddTerminalExit was called and<br />
returned a return code of rc. The output values<br />
of System, NetName and DevType are provided.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7128 <strong>CICS</strong>_EpiTermIdExit returned rc =<br />
rc, TermIndex termindex, System<br />
system<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiTermIdExit was called and returned a<br />
return code of rc. The values of TermIndex and<br />
System are provided.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7129 <strong>CICS</strong>_EpiStartTranExit returned rc<br />
= rc, TranId tranid, Data size size:<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiStartTranExit was called and returned a<br />
return code of rc. The values of TranId and Data<br />
Size are provided, along with a dump of the data<br />
itself.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
84 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL7130 <strong>CICS</strong>_EpiReplyExit returned rc =<br />
rc, TermIndex termindex, Data size<br />
size:<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiReplyExit was called and returned a<br />
return code of rc. The values of TermIndex and<br />
Data Size are provided, along with a dump of<br />
the data itself.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7131 <strong>CICS</strong>_EpiDelTerminalExit<br />
returned rc = rc, TermIndex<br />
termindex<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiDelTerminalExit was called and<br />
returned a return code of rc. The value of<br />
TermIndex is provided.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7132 <strong>CICS</strong>_EpiGetEventExit returned rc<br />
= rc, TermIndex termindex,<br />
EventData:<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiGetEventExit was called and returned a<br />
return code of rc. The value of TermIndex is<br />
provided, along with a dump of the EventData.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7133 <strong>CICS</strong>_EpiTranFailExit returned rc<br />
= rc, TermIndex termindex,<br />
EventData:<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiTranFailExit was called and returned a<br />
return code of rc. The value of TermIndex is<br />
provided, along with a dump of the EventData.<br />
System Action: The message is written to the
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7134 <strong>CICS</strong>_EpiSystemIdExit returned rc<br />
= rc, System system, NetName<br />
netname, DevType devtype<br />
Explanation: The EPI user exit function<br />
<strong>CICS</strong>_EpiSystemIdExit was called and returned a<br />
return code of rc. The output values of System,<br />
NetName and DevType are provided.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7135 About to call EPI user exit<br />
Explanation: An EPI user exit function is about<br />
to be called.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL7136E A minimum screen size of number<br />
rows by number columns is<br />
required<br />
Explanation: The screen size available is too<br />
small for cicsterm. The minimum size is 25 rows<br />
by 80 columns.<br />
System Action: The terminal emulator has not<br />
been started.<br />
User Response: Change the screen size of your<br />
terminal before starting cicsterm and retry.<br />
CCL7629 Unable to read Load Manager INI<br />
file filename (reason = error)<br />
Explanation: The client is unable to read the<br />
Load Manager INI configuration file.<br />
System Action: The message is written to the<br />
log and the Load Manager is disabled.<br />
User Response: Make sure that the INI file<br />
being read exists on the disk, and that it is not<br />
read-protected. If the problem persists, contact<br />
your service organisation.<br />
CCL7134 CCL7644<br />
CCL7639 Duplicate parameter parameter<br />
found - ignored<br />
Explanation: This is a warning. A duplicate<br />
parameter heading has been detected in your<br />
Load Manager INI file.<br />
System Action: The client will continue to read<br />
the Load Manager INI file, but will ignore all<br />
duplicate parameters will be ignored.<br />
User Response: If you do not want this<br />
warning to appear in the log, make sure that<br />
there are no duplicate parameters in your Load<br />
Manager INI file.<br />
CCL7640 Duplicate section section found -<br />
ignored<br />
Explanation: This is a warning. A duplicate<br />
section heading has been detected in your Load<br />
Manager INI file.<br />
System Action: The client will continue to read<br />
the Load Manager INI file, but will ignore all<br />
duplicate sections will be ignored.<br />
User Response: If you do not want this<br />
warning to appear in the log, make sure that<br />
there are no duplicate sections in your Load<br />
Manager INI file.<br />
CCL7643 Incomplete or missing section<br />
section - error<br />
Explanation: Your Load Manager INI file is<br />
invalid, and the client could not read the<br />
specified section.<br />
System Action: The Load Manager will be<br />
disabled.<br />
User Response: Make sure that the Load<br />
Manager INI file is valid.<br />
CCL7644 Cannot find parameter parameter -<br />
error<br />
Explanation: A mandatory parameter could not<br />
be found in the Load Manager INI file.<br />
Messages 85
CCL7645 CCL8031E<br />
System Action: The Load Manager will be<br />
disabled.<br />
User Response: Make sure that the Load<br />
Manager INI file is valid.<br />
CCL7645 Paramater parameter has invalid<br />
value value<br />
Explanation: The specified parameter has an<br />
invalid value.<br />
System Action: The Load Manager will be<br />
disabled.<br />
User Response: Make sure that the Load<br />
Manager INI file is valid.<br />
CCL7646 Value for parameter parameter is<br />
too large<br />
Explanation: The value of the specified<br />
parameter is too large.<br />
System Action: The Load Manager will be<br />
disabled.<br />
User Response: Make sure that the value<br />
specified is within the required range.<br />
CCL8024E Unable to communicate with the<br />
<strong>CICS</strong> Client<br />
Explanation: <strong>CICS</strong>CLI could not communicate<br />
with the client process. This probably means the<br />
client was unable to start.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Try starting the client using the<br />
<strong>CICS</strong>CLI /S command.<br />
CCL8025I The <strong>CICS</strong> Client has not been<br />
started<br />
Explanation: No attempt has been made to start<br />
the <strong>CICS</strong> Client or the <strong>CICS</strong> Client had not been<br />
started.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Start the client using the<br />
<strong>CICS</strong>CLI /S command.<br />
86 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL8026I Client trace is enabled<br />
Explanation: The <strong>CICS</strong>CLI /D command was<br />
issued to start client tracing.<br />
System Action: Trace information is appended<br />
to the client trace file specified by the TraceFile<br />
parameter in the client initialization file.<br />
User Response: You can examine the trace file<br />
by using a standard ASCII text editor.<br />
CCL8027I Client trace is disabled<br />
Explanation: The <strong>CICS</strong>CLI /O command was<br />
issued to stop client tracing.<br />
System Action: No further trace information is<br />
written to the client trace file or to the trace<br />
memory buffer.<br />
User Response: You can examine the trace<br />
and/or dump files by using a standard ASCII<br />
text editor.<br />
CCL8030E Unable to change client trace state<br />
Explanation: The client was unable to set the<br />
requested trace state.<br />
System Action: Service tracing remains<br />
unchanged.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8031E Server server is unknown<br />
Explanation: The specified server name was not<br />
defined in the client initialization file that was<br />
specified when the client first started up.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Correct the server name and<br />
reissue the command. If required add the server<br />
to the client initialization file, then stop and<br />
restart the client to activate the changes.
CCL8032E Unable to complete stop request<br />
Explanation: The client was unable to<br />
disconnect from the server.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Try using <strong>CICS</strong>CLI /I; if this<br />
fails examine any other messages and the client<br />
error log to determine the cause of the error.<br />
CCL8033I Connection to server server is<br />
stopping<br />
Explanation: The client accepted the request to<br />
close a connection with a server and is<br />
processing that request.<br />
System Action: It may take some time for the<br />
close request to complete because all active<br />
conversations with the server must complete<br />
first.<br />
User Response: Wait for the connection to close;<br />
if the connection does not close you may have to<br />
force it to close using the <strong>CICS</strong>CLI /I command.<br />
This forces any open conversations to end.<br />
CCL8034I The <strong>CICS</strong> Client is stopping<br />
Explanation: The client accepted a request to<br />
close all server connections and to terminate.<br />
System Action: It may take some time for the<br />
close request to complete because all active<br />
conversations with the server must complete<br />
first.<br />
User Response: Wait for the client to stop; if the<br />
client does not stop you may have to force it to<br />
close using the <strong>CICS</strong>CLI /I command. This forces<br />
any open conversations to end.<br />
CCL8035I The <strong>CICS</strong> Client is already started<br />
Explanation: A request to start the client was<br />
ignored because it was already started.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: No further action is required.<br />
CCL8032E CCL8039I<br />
CCL8036E Unable to perform start request,<br />
see Client error log<br />
Explanation: The client was unable to complete<br />
the request to start the connection to a server.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Examine any other messages<br />
and the Client error log to determine the cause of<br />
the error.<br />
CCL8037I Connection to server server is<br />
being started<br />
Explanation: The client accepted a request to<br />
start a connection with a server and is processing<br />
that request.<br />
System Action: It may take some time for the<br />
start request to complete because<br />
communications with the server must be<br />
established.<br />
User Response: Wait for the connection to<br />
complete; you can use the <strong>CICS</strong>CLI /L command<br />
to check connection status.<br />
CCL8038I The <strong>CICS</strong> Client is starting<br />
Explanation: The client has accepted a request<br />
to start.<br />
System Action: It may take a few moments for<br />
the start request to complete.<br />
User Response: Wait for the client to start; you<br />
can use the <strong>CICS</strong>CLI /L command to check client<br />
status.<br />
CCL8039I The <strong>CICS</strong> Client is stopping<br />
Explanation: The client was requested to<br />
perform a function but first had to wait to<br />
terminate following an earlier <strong>CICS</strong>CLI /X<br />
command.<br />
System Action: The termination processing<br />
continues.<br />
User Response: Wait for the client to terminate.<br />
If the client does not close you may need to force<br />
it close using the <strong>CICS</strong>CLI /I command. This<br />
forces any open conversations to end.<br />
Messages 87
CCL8040I CCL8051E<br />
CCL8040I No servers are being used by the<br />
<strong>CICS</strong> Client<br />
Explanation: The client is active but is not<br />
connected to any servers.<br />
System Action: No further action is performed.<br />
User Response: No further action is required.<br />
CCL8042I Server server (using protocol to<br />
netname) is available<br />
Explanation: The client is connected to the<br />
server and the server is available. The client is<br />
connected using the specified protocol to the<br />
system known on the network by the specified<br />
netname.<br />
System Action: Processing continues.<br />
User Response: No further action is required.<br />
CCL8043I Server server (using protocol to<br />
netname) is unavailable<br />
Explanation: The client is connected to the<br />
server but the server is unavailable. The client is<br />
connected using the specified protocol to the<br />
system known on the network by the specified<br />
netname.<br />
System Action: No further action is performed.<br />
User Response: Wait for the server to become<br />
available, or close the connection using the<br />
<strong>CICS</strong>CLI /X command if the server is no longer<br />
required.<br />
CCL8044I Server server (using protocol to<br />
netname) is connecting<br />
Explanation: The client is waiting to connect to<br />
the server, the state of the server is not yet<br />
known. The client is connecting using the<br />
specified protocol to the system known on the<br />
network by the specified netname.<br />
System Action: The connection processing<br />
continues.<br />
User Response: Wait for the connection to<br />
complete. After completion the status of the<br />
88 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
server - either available or unavailable - is<br />
known.<br />
CCL8045I Server server (using protocol to<br />
netname) is stopping<br />
Explanation: The connection with the server is<br />
currently waiting to be closed.<br />
System Action: The termination processing<br />
continues.<br />
User Response: Wait for the connection to close.<br />
If the connection does not close you may need to<br />
force it to close using the <strong>CICS</strong>CLI /I command.<br />
This forces any open conversations to end.<br />
CCL8046E Unable to perform list request<br />
Explanation: The client was unable to perform a<br />
request to list the current server connection<br />
details.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8050I Requested security information<br />
has been updated<br />
Explanation: The client completed a request to<br />
set the userid and password information for a<br />
secure server.<br />
System Action: Secure server information is<br />
updated.<br />
User Response: No further action is required.<br />
CCL8051E Invalid request to change security<br />
information<br />
Explanation: A <strong>CICS</strong>CLI command was issued<br />
with the /U or /P options but without the /C<br />
option specifying a server name.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Reissue the command with the<br />
correct options.
CCL8052E Unable to make the requested<br />
security information changes<br />
Explanation: The client was unable to perform<br />
the request to change the userid and password<br />
information for a secure server.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8053E Connection to server server is<br />
already started<br />
Explanation: The client was unable to perform a<br />
request to connect to the named server, because a<br />
connection with the server already exists.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: If the connection is no longer<br />
required, use the <strong>CICS</strong>CLI /X command to close<br />
it.<br />
CCL8054E Connection to server server has not<br />
been started<br />
Explanation: The client was unable to perform<br />
the request to start a connection with the<br />
specified server.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8055E The <strong>CICS</strong> Client has reached its<br />
MaxServers limit<br />
Explanation: The client can only communicate<br />
simultaneously with the number of servers<br />
specified by the MaxServers option in the Client<br />
section of the client initialization file. This limit<br />
has been reached.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Use the <strong>CICS</strong>CLI /X command<br />
to close connections to servers that are no longer<br />
required. Alternatively, increase the MaxServers<br />
CCL8052E CCL8059I<br />
setting in the client initialization file; then stop<br />
and restart the client.<br />
CCL8056E Size is an incorrect trace size limit<br />
value<br />
Explanation: The <strong>CICS</strong>CLI /D or <strong>CICS</strong>CLI /T<br />
command to start client tracing can include an<br />
optional numeric value specifying the maximum<br />
size of data to be traced. The specified size is<br />
either not a numeric value or is outside the<br />
permitted range of 1 - 32767.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Reissue the command with the<br />
correct value.<br />
CCL8057I Client error and security pop-ups<br />
have been enabled<br />
Explanation: The <strong>CICS</strong>CLI /E command was<br />
used to enable presentation of messages in<br />
pop-ups.<br />
System Action: Any client errors and secure<br />
server requests are presented via a pop-up.<br />
User Response: Any pop-ups have to be<br />
acknowledged by the user before further<br />
processing can continue.<br />
CCL8058I Client error and security pop-ups<br />
have been disabled<br />
Explanation: The <strong>CICS</strong>CLI /N command was<br />
used to disable presentation of messages in<br />
pop-ups. This allows the client to run without<br />
any user interaction.<br />
System Action: Client error messages will be<br />
written to the client error log and secure server<br />
logon requests will fail.<br />
User Response: No further action is required.<br />
CCL8059I Error and security pop-ups were<br />
already enabled<br />
Explanation: The <strong>CICS</strong>CLI /E command was<br />
used to enable error and security pop-ups but<br />
they were already enabled.<br />
Messages 89
CCL8060I CCL806IE<br />
System Action: Error and security pop-ups<br />
remain enabled.<br />
User Response: No further action is required.<br />
CCL8060I Error and security pop-ups were<br />
already disabled<br />
Explanation: The <strong>CICS</strong>CLI /N command was<br />
used to disable error and security pop-ups but<br />
they were already disabled.<br />
System Action: Error and security pop-ups<br />
remain disabled.<br />
User Response: No further action is required.<br />
CCL8062I Option option ignored because the<br />
<strong>CICS</strong> Client is already started<br />
Explanation: The /F option to specify a client<br />
initialization file was included on a <strong>CICS</strong>CLI<br />
command but this option can be specified only<br />
when the client is first started with the <strong>CICS</strong>CLI<br />
/S command.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: If a different client initialization<br />
file is required, the client must be stopped and<br />
restarted.<br />
CCL8063E Option option cannot be used<br />
unless starting the <strong>CICS</strong> Client<br />
Explanation: The /F option to specify a client<br />
initialization file was included on a <strong>CICS</strong>CLI<br />
command, but this option can be specified only<br />
when starting the client with the <strong>CICS</strong>CLI /S<br />
command.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: If a different client initialization<br />
file is required, the client must be stopped and<br />
restarted.<br />
CCL8065E Unable to change status of client<br />
trace to memory buffer<br />
Explanation: The client was unable to set the<br />
requested trace state.<br />
90 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: Service tracing to the memory<br />
buffer remains unchanged.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8066E Unable to start client trace to<br />
memory buffer<br />
Explanation: The client was unable to start the<br />
trace to the memory buffer. This is probably<br />
because sufficient storage could not be allocated.<br />
System Action: Service tracing to the memory<br />
buffer was not started.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8068E Error dumping trace file in<br />
memory buffer to file<br />
Explanation: The client was unable to dump the<br />
trace memory buffer to the dump file. Ensure the<br />
dump file name (in CTG.INI) is valid and the<br />
disk is not full.<br />
System Action: Service tracing to the memory<br />
buffer is not dumped.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8069E Userid userid exceeds the<br />
maximum supported length<br />
Explanation: The length of the userid string<br />
supplied exceeds the maximum supported by the<br />
<strong>CICS</strong> Client.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Reissue the command with a<br />
valid string.<br />
CCL806IE Unable to set error and security<br />
pop-up state<br />
Explanation: The client was unable to set the<br />
security and error pop-up state requested by a
<strong>CICS</strong>CLI /E or <strong>CICS</strong>CLI /N command.<br />
System Action: Error and security pop-ups<br />
remain unchanged.<br />
User Response: Examine any other messages<br />
and the client error log to determine the cause of<br />
the error.<br />
CCL8070E Password password exceeds the<br />
maximum supported length<br />
Explanation: The length of the password string<br />
supplied exceeds the maximum supported by the<br />
<strong>CICS</strong> Client.<br />
System Action: <strong>CICS</strong>CLI performs no action.<br />
User Response: Reissue the command with a<br />
valid string.<br />
CCL8400I Using ini file {0}<br />
Explanation: You can now specify the ini file to<br />
be used. The <strong>Gateway</strong> is using either CTG.INI or<br />
the ini file specified by the <strong>CICS</strong>CLI environment<br />
variable.<br />
System Action: Display the ini file in use, and<br />
write it to the log.<br />
User Response: User response not required.<br />
CCL8401I The Following Ciphers are<br />
Enabled<br />
Explanation: Information following this<br />
message describes the names of the enabled<br />
ciphers.<br />
System Action: System action is not required.<br />
User Response: Information only, no response is<br />
required.<br />
CCL8402I JSSE libraries selected for use.<br />
Explanation: Information detailing security<br />
implementation providing encryption services.<br />
System Action: System action is not required.<br />
User Response: Information only, no response is<br />
required.<br />
CCL8403I SSLIGHT libraries selected for<br />
use.<br />
Explanation: Information detailing security<br />
implementation providing encryption services.<br />
System Action: System action is not required.<br />
User Response: Information only, no response is<br />
required.<br />
CCL8404I JSSE <strong>Version</strong> unknown<br />
Explanation: <strong>Version</strong> information for the JSSE<br />
security provider is unavailable.<br />
System Action: System action is not required.<br />
User Response: Information only. no response is<br />
required<br />
CCL8405I {0}<br />
CCL8070E CCL8522E<br />
Explanation: JSSE provider information.<br />
System Action: System action is not required.<br />
User Response: Information only, no response is<br />
required.<br />
CCL8521E Unknown option option<br />
Explanation: An invalid command option was<br />
specified when using the <strong>CICS</strong>BMSC command.<br />
System Action: <strong>CICS</strong>BMSC performs no action.<br />
User Response: Reissue the command with the<br />
correct option.<br />
CCL8522E Input file filename must have .bms<br />
or .BMS suffix<br />
Explanation: The <strong>CICS</strong>BMSC command requires<br />
a BMS source file as input.<br />
System Action: <strong>CICS</strong>BMSC performs no action.<br />
User Response: Reissue the command with the<br />
correct BMS source file name.<br />
Messages 91
CCL8523E CCL8605<br />
CCL8523E Unable to open BMS input file<br />
filename<br />
Explanation: The <strong>CICS</strong>BMSC command could<br />
not find, or could not read the supplied BMS<br />
source file.<br />
System Action: <strong>CICS</strong>BMSC performs no action.<br />
User Response: Check that the BMS source file<br />
name is correct, that the file is available and can<br />
be read.<br />
CCL8524E Unable to open output files<br />
Explanation: The <strong>CICS</strong>BMSC command is<br />
unable to create output files.<br />
System Action: <strong>CICS</strong>BMSC processing ends.<br />
User Response: Check that there is sufficient<br />
disk space available for the <strong>CICS</strong>BMSC output<br />
files.<br />
CCL8526E Error in BMS source file filename<br />
line number<br />
Explanation: The <strong>CICS</strong>BMSC command has<br />
found an error in an input BMS source file.<br />
System Action: <strong>CICS</strong>BMSC processing ends.<br />
User Response: Check the BMS macro source at<br />
the line indicated.<br />
CCL8601 Exception exception raised in<br />
class:method [during call request]<br />
Explanation: The exception named, one of the<br />
Ccl:ExCode enumeration values, was raised<br />
during the execution of the class:method method<br />
during the server request indicated by the call<br />
value. An exception object encapsulating details<br />
of the exception is passed to<br />
CclECI:handleException or<br />
CclEPI:handleException and/or thrown via the<br />
C++ exception mechanism.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
92 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL8602 Sending call request to server<br />
Explanation: The client class library is about to<br />
make a server call. The call value indicates the<br />
request type.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled, followed by a<br />
dump of the flow object state.<br />
User Response: None.<br />
CCL8603 Received call reply from server<br />
Explanation: The client class library has<br />
received a reply from the server. The call value<br />
indicates the request type.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled, followed by a<br />
dump of the flow object state.<br />
User Response: None.<br />
CCL8604 EPI call calltype: RC=error,<br />
Event=event<br />
Explanation: The client class library completed<br />
an EPI call. The error value indicates any errors,<br />
the event value indicates the EPI event returned<br />
on GetEvent calls.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL8605 Method class:method invoked:<br />
State=state, ExCode=exception<br />
Explanation: The client class library method<br />
indicated by the class and method values has been<br />
invoked. The state and exception values indicate<br />
the current object state and exception code.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.
CCL8707E Unable to open file filename<br />
Explanation: The <strong>CICS</strong>CONV utility is unable<br />
to access the file.<br />
System Action: <strong>CICS</strong>CONV processing ends.<br />
User Response: Check that the file specified is<br />
accessible.<br />
CCL8708I Process file filename<br />
Explanation: The <strong>CICS</strong>CONV utility is<br />
processing the file.<br />
System Action: <strong>CICS</strong>CONV processing<br />
continues.<br />
User Response: No further action is required.<br />
CCL8709I Creating file filename<br />
Explanation: The <strong>CICS</strong>CONV utility is<br />
generating the file.<br />
System Action: <strong>CICS</strong>CONV processing<br />
continues.<br />
User Response: No further action is required.<br />
CCL8710I Renaming file filename to file<br />
filename<br />
Explanation: The <strong>CICS</strong>CONV utility is changing<br />
the name of a file that already exists.<br />
System Action: <strong>CICS</strong>CONV processing<br />
continues.<br />
User Response: No further action is required.<br />
CCL8711I Processing complete<br />
Explanation: The <strong>CICS</strong>CONV utility has<br />
finished conversion.<br />
System Action: <strong>CICS</strong>CONV terminates without<br />
error.<br />
User Response: No further action is required.<br />
CCL8707E CCL8807E<br />
CCL8804E The <strong>CICS</strong> Client/<strong>Gateway</strong> is not<br />
installed properly<br />
Explanation: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or<br />
<strong>CICS</strong> Univseral Client is not installed correctly.<br />
Registry keys are created at install time.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Reinstall the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> or <strong>CICS</strong> Universal Client.<br />
CCL8805E Unable to read from the registry<br />
Explanation: The program tried to read from<br />
the registry but cannot read the appropiate<br />
registry key. This is normally caused by security<br />
settings in the registry.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Get your system administrator<br />
to give read permission to the registry key<br />
HKEY_LOCAL_MACHINE\SOFTWARE\<br />
IBM\<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or<br />
HKEY_LOCAL_MACHINE\SOFTWARE\<br />
IBM\<strong>CICS</strong> Universal Client.<br />
CCL8806E Unable to write to the registry<br />
Explanation: The program tried to write to the<br />
registry but cannot write the appropiate registry<br />
key. This is normally caused by security settings<br />
in the registry.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Logon as a user who has<br />
permissions to write to either<br />
HKEY_LOCAL_MACHINE\SOFTWARE\<br />
IBM\<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> or<br />
HKEY_LOCAL_MACHINE\SOFTWARE\<br />
IBM\<strong>CICS</strong> Universal Client. Then repeat the<br />
command line option.<br />
CCL8807E Unable to find a JVM<br />
Explanation: When trying to run a Java<br />
application, the application launcher tries to find<br />
a JVM, it does this by querying the registry.<br />
Messages 93
CCL8808E CCL9303<br />
System Action: The command line application<br />
terminates.<br />
User Response: Install a JVM, or use the<br />
CTGJAVA command to point to the Java Virtual<br />
Machine to run.<br />
CCL8808E Unable to find Java runtime<br />
classes<br />
Explanation: When trying to run a Java<br />
application, the Java runtime classes could not be<br />
found.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Install the Java Virtual Machine<br />
(JVM) correctly.<br />
CCL8815E File does not exist<br />
Explanation: The file specified does not exist.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Specify the fully qualified path<br />
to a Java Virtual Machine.<br />
CCL8818E The JVM specified is unsupported<br />
Explanation: When trying to point to a Java<br />
Virtual Machine using the CTGJAVA command,<br />
the specified JVM is tested and determined to be<br />
at an unsupported level.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Specify a supported Java<br />
Virtual Machine to CTGJAVA.<br />
CCL8819E The currently set JVM is<br />
unsupported<br />
Explanation: When trying to run a Java<br />
application, the application launcher tests the<br />
currently set JVM. It is determined to be at an<br />
unsupported level.<br />
System Action: The command line application<br />
terminates.<br />
94 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: Use the CTGJAVA command to<br />
point to a supported Java Virtual Machine to<br />
run.<br />
CCL8820W Old IKeyman found in the JRE at<br />
path. Unexpected errors may occur<br />
Explanation: When launching IKeyman, the<br />
application launcher found an old version of<br />
IKeyman installed in the JRE. Unexpected errors<br />
may occur within the IKeyman tool.<br />
System Action: The command line application<br />
continues.<br />
User Response: If errors occur in the IKeyman<br />
tool, delete the specified jar file and rerun the<br />
launcher.<br />
CCL9119 Attempt to get addressability to<br />
an IPC queue element failed with<br />
rc = value1<br />
Explanation: On a Windows platform an<br />
attempt to get addressability to a shared memory<br />
element has failed for some operating system<br />
reason.<br />
System Action: The message is written to the<br />
error log and the client tries to continue,<br />
although attempts to reference this shared<br />
memory element will result in a trap.<br />
User Response: If the problem persists, contact<br />
your service organization.<br />
CCL9303 Memory allocation failed.<br />
DosAllocMem return code: error<br />
Explanation: The client was unable to allocate<br />
the amount of memory required to hold the<br />
returned data. The error value indicates the<br />
failing return code.<br />
System Action: The message is written to the<br />
error log and the call fails.<br />
User Response: Try reducing the amount of<br />
data requested and try again. If the problem<br />
persists contact your support organization.
CCL9304 Invalid call type (call_type)<br />
Explanation: An invalid value (as indicated by<br />
call_type) was specified for the ECI call type.<br />
System Action: The message is written to the<br />
error log and the call fails.<br />
User Response: Correct the program so that a<br />
supported value is specified for the ECI call type.<br />
CCL9305 The commarea size specified<br />
exceeds the length of data<br />
supplied<br />
Explanation: The value specified for the length<br />
of the commarea is larger than the amount of<br />
data supplied.<br />
System Action: The message is written to the<br />
error log and the call fails.<br />
User Response: Correct the program so that the<br />
specified length of the commarea is equal to, or<br />
exceeds, the amount of data being passed to the<br />
ECI.<br />
CCL9306 The value specified for Extended<br />
Mode (value) isinvalid<br />
Explanation: An invalid value (as indicated by<br />
value) has been specified for the ECI extended<br />
mode parameter.<br />
System Action: The message is written to the<br />
error log and the call fails.<br />
User Response: Correct the program so that a<br />
supported value is specified for the extended<br />
mode parameter.<br />
CCL9307 The ECI version specified (version)<br />
is not valid<br />
Explanation: An invalid value (as indicated by<br />
value) has been specified for the ECI version<br />
parameter.<br />
System Action: The message is written to the<br />
error log and the call fails.<br />
User Response: Correct the program so that a<br />
supported value is specified for the ECI version<br />
parameter.<br />
CCL9313 Base address for returned<br />
commarea allocated by<br />
DosAllocMem is addr<br />
Explanation: The client has successfully<br />
allocated a buffer in memory to hold the data<br />
returned in the commarea by the call to the ECI.<br />
The value of addr indicates the address at which<br />
the buffer has been allocated.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9314 eci_call_type = type<br />
Explanation: The value type identifies the type<br />
of call which has been requested.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9315 eci_program_name = progname<br />
Explanation: The value progname identifies the<br />
name of the program which is to be invoked by<br />
this ECI call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9316 eci_userid = userid<br />
Explanation: The value userid identifies the<br />
userid to be used for security checking.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9304 CCL9317<br />
CCL9317 eci_password = password<br />
Explanation: The value password identifies the<br />
password to be used for security checking.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
Messages 95
CCL9318 CCL9326<br />
User Response: None.<br />
CCL9318 eci_transid = tid<br />
Explanation: The value tid identifies the TranID<br />
specified for this call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9319 User specified commarea length<br />
was length<br />
Explanation: The value length indicates an<br />
explicit length for the commarea, as set by the<br />
caller. A value of -1 indicates that no specific<br />
value was provided and so the length of the user<br />
supplied commarea will be used instead.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9320 eci_commarea_length = len<br />
Explanation: A commarea length of len will be<br />
used on the ECI call. It was either set explicitly<br />
by the caller or else is taken as the length of the<br />
commarea passed as input to the call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9321 eci_timeout = seconds<br />
Explanation: The value seconds specifies the<br />
maximum time that the request from the<br />
application should be allowed to take. This<br />
parameter is provided for backwards<br />
compatibility only and should normally be set to<br />
0.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
96 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL9322 eci_extend_mode = mode<br />
Explanation: The value mode specifies the<br />
extended mode for this ECI call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9323 eci_message_id = msgid<br />
Explanation: The value msgid is a user-provided<br />
reference to an asynchronous call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9324 eci_luw_token = luwid<br />
Explanation: The value luwid is an identifier for<br />
a logical unit of work.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9325 eci_sysid = sysid<br />
Explanation: The value sysid is reserved for<br />
future use and should generally be left null.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9326 eci_version = version<br />
Explanation: The value version specified the<br />
version of the ECI for which the application is<br />
coded. This should be set to the value<br />
ECI_VERSION_1 or ECI_VERSION_1A.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.
CCL9327 eci_system_name = name<br />
Explanation: The value name specifies the name<br />
of the system to which the ECI call should be<br />
directed.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9328 eci_userid2 = userid<br />
Explanation: The value userid specifies a userid<br />
to be used for security checking.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9329 eci_password2 = password<br />
Explanation: The value password specifies a<br />
password to be used for security checking.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9330 eci_tpn = tpn<br />
Explanation: The value tpn specifies a<br />
transaction name under which this program<br />
should execute in the target system.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9331 Returned eci_return_code = rc<br />
Explanation: The value rc is the return code<br />
from the ECI call.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: Refer to the <strong>CICS</strong> Client/Server<br />
Programming book for an explanation of the<br />
error codes.<br />
CCL9332 Returned eci_abend_code = abend<br />
Explanation: The value abend is the abend code<br />
for a failed program.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: Refer to the <strong>CICS</strong> Client/Server<br />
Programming book for an explanation of the<br />
error codes.<br />
CCL9334 Returned eci_luw_token = luwid<br />
Explanation: The value luwid is an identifier for<br />
a logical unit of work. This is the value which<br />
was returned by the call to the ECI.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9335 Returned eci_commarea_length =<br />
length<br />
Explanation: The value length specifies the<br />
amount of data returned in the commarea after<br />
the call to the ECI.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9336 Cammarea base address = addr,<br />
length = length<br />
Explanation: The call to the ECI has completed<br />
successfully. The value of addr indicates the<br />
location in memory of the returned commarea<br />
and the value of length indicates the amount of<br />
data returned in the commarea.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9327 CCL9336<br />
Messages 97
CCL9337 CCL9500E<br />
CCL9337 Error during ECI call. Commarea<br />
not returned.<br />
Explanation: The call to the ECI has completed<br />
but an error was detected. No data is returned to<br />
the calling application in the commarea.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: Information on the type of error<br />
can be determined from earlier entries in the<br />
trace log.<br />
CCL9339 System count variable is name<br />
Explanation: The value name indicates the<br />
variable into which the number of systems found<br />
will be written.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9340 List stem name is stemname<br />
Explanation: The value stemname specifies the<br />
stem of the variable into which the returned<br />
system information is to be written.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9341 Number of systems found is count<br />
Explanation: The value of count specifies the<br />
number of systems found. Data can only be<br />
returned for a number of systems up to the<br />
implementation maximum (currently 100). If the<br />
value of count is larger than the maximum<br />
number specified then some data will have been<br />
lost.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
98 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL9342 System name = sysname<br />
(Description = desc)<br />
Explanation: For each system returned to the<br />
caller, the value sysname indicates the name of<br />
the system and the value desc its associated<br />
description.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9343 <strong>CICS</strong>_EciListSystems call<br />
completed successfully<br />
Explanation: The call has completed<br />
successfully and control is being returned to the<br />
calling program.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: None.<br />
CCL9344 Error during <strong>CICS</strong>_EciListSystems<br />
call. Return code: rc<br />
Explanation: An error was encountered during<br />
execution of the code. The value of rc indicates<br />
the failing error code.<br />
System Action: The message is written to the<br />
trace file if tracing is enabled.<br />
User Response: Refer to the <strong>CICS</strong> Client/Server<br />
Programming book for an explanation of the<br />
error codes.<br />
CCL9500E Maximum number of Java<br />
arguments exceeded<br />
Explanation: The maximum number of<br />
parameters that can be passed to the CTG has<br />
been exceded.<br />
System Action: The CTG service terminates.<br />
User Response: Reduce the number of<br />
arguments and try again.
CCL9501E Cannot load JNI dll: jvm.dll<br />
Explanation: The service cannot find the Java<br />
native runtime dll and is unable to start the<br />
CTG.<br />
System Action: The CTG service terminates.<br />
User Response: Reinstall your Java Virtual<br />
Machine<br />
CCL9502E Service could not allocate memory<br />
Explanation: Upon starting the CTG service<br />
enough resources could not be allocated.<br />
System Action: The CTG service terminates.<br />
User Response: Free up some memory and try<br />
again<br />
CCL9503E Service could not create Java<br />
Virtual Machine<br />
Explanation: An error occured whilst trying to<br />
start the Java Virtual Machine for the <strong>Gateway</strong><br />
service to run under. The options used when<br />
trying to creat the JVM will be output when this<br />
condition occurs.<br />
System Action: The CTG service terminates.<br />
User Response: Check the options supplied and<br />
try again with different parameters<br />
CCL9505E Cannot find class<br />
com.ibm.ctg.server.JGate<br />
Explanation: When attempting to start the CTG<br />
service the required Java class could not be<br />
found. This class can be found in the supplied<br />
CTGSERVER.JAR.<br />
System Action: The CTG service terminates.<br />
User Response: Update your classpath and try<br />
again.<br />
CCL9506E No main() method found in class<br />
com.ibm.ctg.server.JGate<br />
Explanation: When attempting to start the CTG<br />
service the main() method cannot be found<br />
within the JGate class.<br />
System Action: The CTG service terminates.<br />
User Response: Reinstall the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
CCL9507E Out of memory<br />
CCL9501E CCL9511E<br />
Explanation: Whilst running the CTG service no<br />
free memory was available for new resources.<br />
System Action: The CTG service terminates.<br />
User Response: If this occurs under expected<br />
load then more memory may be needed to<br />
satisfy the performance needs for the specific<br />
CTG installation.<br />
CCL9508E StartServiceControlDispatcher<br />
failed<br />
Explanation: An attempt to start the Windows<br />
service control dispatcher failed.<br />
System Action: The CTG service terminates.<br />
User Response: Restart the machine and try to<br />
start the service again.<br />
CCL9510I Calling<br />
StartServiceCtrlDispatcher.....<br />
Explanation: The CTG service is attempting to<br />
start the Windows Service control dispatcher.<br />
System Action: This message is for information<br />
only.<br />
User Response: No further action is required<br />
CCL9511E Unrecognized option: option<br />
Explanation: The option specified is not<br />
supported by the CTGSERVICE command line<br />
executable.<br />
System Action: The usage statement is<br />
displayed<br />
Messages 99
CCL9528E CCL9538E<br />
User Response: Adjust the parameters you pass<br />
to CTGSERVICE.EXE<br />
CCL9528E Unable to install service name,<br />
error: error message text<br />
Explanation: Installation of the CTG service<br />
failed. An error code describing why failure<br />
occured is supplied.<br />
System Action: The command line application<br />
terminates<br />
User Response: Check that the service isn’t<br />
already installed and try again.<br />
CCL9532E Service service name failed to stop<br />
Explanation: When trying to stop the CTG<br />
service before uninstallation an error occured.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Try to stop the service<br />
manually and try the uninstall again.<br />
CCL9533E OpenService failed: error message<br />
text<br />
Explanation: During an uninstall of the CTG<br />
service the service could not be opened.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Check to see if the service is<br />
installed and try again.<br />
CCL9534E DeleteService failed: error message<br />
text<br />
Explanation: During an uninstall of the CTG<br />
service the service could not be deleted.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Check to see if the service is<br />
installed and try again.<br />
100 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CCL9535E Failed to create AppParameters<br />
sub-key<br />
Explanation: Whilst attempting to create the<br />
specified subkey to be used by the CTG in the<br />
registry an error occured.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Restart the machine and try<br />
again.<br />
CCL9536E Failed to create AppParameters<br />
string<br />
Explanation: Whilst attempting to create the<br />
specified string to be used by the CTG in the<br />
registry an error occured.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Restart the machine and try<br />
again.<br />
CCL9537E Failed to save value of<br />
AppParameters<br />
Explanation: Whilst attempting to store the<br />
parameters to be used by the CTG in the registry<br />
an error occured.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Restart the machine and try<br />
again.<br />
CCL9538E Failed to create service: error<br />
message text<br />
Explanation: During an install of the CTG<br />
service the service could not be created.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Check to see if the service is<br />
already installed.
CCL9539E OpenSCManager failed: error<br />
message text<br />
Explanation: During an install of the CTG<br />
service the Service Control Manager could not be<br />
opened.<br />
System Action: The command line application<br />
terminates.<br />
User Response: Restart the machine and try<br />
again.<br />
CTG6000I CTGARM - CTG Automatic<br />
Restart Manager Batch Utility<br />
Explanation: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) is starting. This message is the first of a<br />
series of messages generated by the utility.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6001I End of CTGARM - CTG<br />
Automatic Restart Manager Batch<br />
Utility<br />
Explanation: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) has completed. This message marks the<br />
end of a series of messages generated by the<br />
utility.<br />
System Action: The utility ends.<br />
User Response: For information only.<br />
CTG6002I Parameters processed:<br />
Explanation: This is a header line before a list<br />
of parameters read by the utility. There will<br />
follow three messages, one for each parameter<br />
passed.<br />
System Action: If all the parameters are valid,<br />
the utility will continue, otherwise an error<br />
message will be issued and the utility will end.<br />
User Response: For information only.<br />
CTG6003I COMMAND: [value]<br />
Explanation: This is first parameter passed to<br />
ctgarm, and is evaluated from the first letter of<br />
the parameter. Valid values are: Register and<br />
Deregister.<br />
System Action: If the parameter is valid, the<br />
utility will continue, otherwise an error message<br />
will be issued and the utility will end.<br />
User Response: For information only.<br />
CTG6004I ARM_ID: [value]<br />
Explanation: This is second parameter passed to<br />
ctgarm. Valid values are between 1 and 16<br />
characters. Valid characters are the uppercase<br />
alphabetic characters, the numbers 0 through 9<br />
and the special characters: $, #, @, and<br />
underscore (_).<br />
System Action: If the parameter is valid, the<br />
utility will continue, otherwise an error message<br />
will be issued and the utility will end.<br />
User Response: For information only.<br />
CTG6005I ARM_TYPE: [value]<br />
Explanation: This is the optional third<br />
parameter passed to ctgarm. Valid values are<br />
between 1 and 8 characters. Valid characters are<br />
the uppercase alphabetic characters, the numbers<br />
0 through 9 and the special characters: $, #, @,<br />
and underscore (_). If the parameter was absent,<br />
then it will default to the value SYSLVL2. See the<br />
Administration book for details.<br />
System Action: If the parameter is valid, the<br />
utility will continue, otherwise an error message<br />
will be issued and the utility will end.<br />
User Response: For information only.<br />
CTG6006I Results are:<br />
CCL9539E CTG6006I<br />
Explanation: This is a header line following a<br />
message describing the call to Automatic Restart<br />
Manager. There will follow two messages,<br />
specifying the return code and reason code<br />
values from the call. A further message will<br />
indicate the outcome of the call.<br />
Messages 101
CTG6007I CTG6015E<br />
System Action: If the results are acceptable, the<br />
utility will continue, otherwise it will end.<br />
User Response: Refer to the z/OS MVS<br />
Programming: Sysplex Services Reference manual for<br />
information on unexplained return and reason<br />
codes.<br />
CTG6007I Return code: [value]<br />
Explanation: The return code is given as a<br />
hexadecimal value. Generally a successful return<br />
code is 00 or 04.<br />
System Action: If the results are acceptable, the<br />
utility will continue, otherwise it will end.<br />
User Response: Refer to the z/OS MVS<br />
Programming: Sysplex Services Reference manual for<br />
explanations of return code values.<br />
CTG6008I Reason code: [value]<br />
Explanation: The reason code is given as a<br />
hexadecimal value.<br />
System Action: If the results a acceptable, the<br />
utility will continue, otherwise it will end.<br />
User Response: Refer to the z/OS MVS<br />
Programming: Sysplex Services Reference manual for<br />
explanations of reason code values.<br />
CTG6010S Severe Error - Cannot read<br />
parameters<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) has an internal error reading the passed<br />
parameters.<br />
System Action: The utility will not run.<br />
User Response: Contact your service<br />
organisation.<br />
CTG6011E Error - Too many parameters<br />
passed<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) takes either 1,2 or 3 parameters. See<br />
other messages for the command format.<br />
102 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
System Action: The parameters were incorrect,<br />
and the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6012E Error - Empty parameter passed<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) takes either 1,2 or 3 parameters. See<br />
other messages for the command format.<br />
System Action: The parameters were incorrect,<br />
and the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6013E Error - missing parameters<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) takes either 1,2 or 3 parameters. See<br />
other messages for the command format.<br />
System Action: The parameters were incorrect,<br />
and the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6014E Bad command, only ″Register″<br />
and ″Deregister″ supported<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) takes either R or D as its first<br />
parameter. See other messages for the command<br />
format.<br />
System Action: The parameters were incorrect,<br />
and the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6015E Ready not accepted by ARM - see<br />
reason codes<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Ready function of Automatic
Restart Manager (ARM) as one of the last phases<br />
of registering with ARM. ARM rejected the call.<br />
System Action: The utility will terminate.<br />
User Response: An explanation of the reason<br />
code returned by the Ready request to ARM can<br />
be found in the z/OS MVS Programming: Sysplex<br />
Services Reference manual.<br />
CTG6016E Registration failed - see reason<br />
codes<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM rejected the<br />
call.<br />
System Action: The utility will terminate.<br />
User Response: An explanation of the reason<br />
code returned by the Registration request to ARM<br />
can be found in the z/OS MVS Programming:<br />
Sysplex Services Reference manual.<br />
CTG6017E Wait for predecessors failed - see<br />
reason codes<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Wait function of Automatic<br />
Restart Manager (ARM) as the Register request to<br />
ARM indicated that this was a restart. ARM<br />
rejected the call.<br />
System Action: The utility will terminate.<br />
User Response: An explanation of the reason<br />
code returned by the Wait request to ARM can be<br />
found in the z/OS MVS Programming: Sysplex<br />
Services Reference manual.<br />
CTG6018E Deregistration failed - see reason<br />
codes<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Deregistration function of<br />
Automatic Restart Manager (ARM) to deregister<br />
with ARM. ARM rejected the call. This is a<br />
non-fatal error.<br />
CTG6016E CTG6022E<br />
System Action: The utility will terminate.<br />
User Response: An explanation of the reason<br />
code returned by the Deregister request to ARM<br />
can be found in the z/OS MVS Programming:<br />
Sysplex Services Reference manual.<br />
CTG6020E Deregistration failed - was not<br />
registered<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Deregistration function of<br />
Automatic Restart Manager (ARM) to deregister<br />
with ARM. ARM rejected the call because this job<br />
was not registered with ARM.<br />
System Action: The utility will terminate.<br />
User Response: No further action is required.<br />
CTG6021E Registration failed - ARM_ID<br />
already in use<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM rejected the<br />
call because the ARM_ID was not unique in the<br />
sysplex.<br />
System Action: The utility will terminate.<br />
User Response: Choose a sysplex unique id and<br />
re-run the utility.<br />
CTG6022E Registration failed - ARM_ID is<br />
invalid<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM rejected the<br />
call because the ARM_ID did not conform to the<br />
character restrictions.<br />
System Action: The utility will terminate.<br />
User Response: Check the value in the ARM_ID<br />
parameter against the restrictions given by other<br />
messages.<br />
Messages 103
CTG6023E CTG6032I<br />
CTG6023E Registration / Deregistration<br />
failed - ARM is not running<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. The call to ARM<br />
failed because ARM was not active on the<br />
sysplex.<br />
System Action: The utility will terminate.<br />
User Response: Investigate why ARM is not<br />
running.<br />
CTG6024E Registration / Deregistration<br />
failed - This is not a started job<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM rejected the<br />
call because only started jobs can register.<br />
System Action: The utility will terminate.<br />
User Response: The utility may have been<br />
called from the USS command line or as part of<br />
a USS script. The utility can run successfully<br />
only when called from BPXBATCH with a PGM=<br />
parameter. Refer to the CTG Administration book<br />
for JCL examples.<br />
CTG6025E Registration failed - ARM_TYPE<br />
is invalid<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM rejected the<br />
call because the ARM_TYPE did not conform to<br />
the character restrictions.<br />
System Action: The utility will terminate.<br />
User Response: Check the value in the<br />
ARM_TYPE parameter against the restrictions<br />
given by messages.<br />
104 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG6026E Error - ARM_ID is too long -<br />
maximum of 16 characters.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) Registration command takes a required<br />
parameter (ARM_ID) that is up to 16 characters<br />
long. See other messages for the command<br />
format.<br />
System Action: The parameter is incorrect, and<br />
the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6027E Error - ARM_TYPE is too long -<br />
maximum of 8 characters.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) Registration command takes an optional<br />
parameter (ARM_TYPE) that is up to 8<br />
characters long. See other messages for the<br />
command format.<br />
System Action: The parameter is incorrect, and<br />
the utility will not run.<br />
User Response: Check the format of the<br />
command used and retry.<br />
CTG6031I This is first time register with<br />
ARM<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM has<br />
accepted the registration, and this is not a<br />
restarted job.<br />
System Action: The utility completes<br />
successfully.<br />
User Response: For information only.<br />
CTG6032I This is a re-started job, so wait for<br />
any predecessors<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM. ARM has<br />
accepted the registration, but this is a restarted<br />
job. The utility must now call ARM with the Wait<br />
function to allow any predecessor jobs to restart<br />
before continuing.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6033I Deregistering from ARM<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) will call the Deregistration function of<br />
Automatic Restart Manager (ARM) to deregister<br />
with ARM.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6034I Registering with ARM<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) will call the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6035I Telling ARM we are ready<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) will call the Ready function of<br />
Automatic Restart Manager (ARM) as the last<br />
phase of registering with ARM as a restarted job.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6036I Successfully deregistered with<br />
ARM<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
CTG6033I CTG6052E<br />
(ctgarm) called the Deregistration function of<br />
Automatic Restart Manager (ARM) to deregister<br />
with ARM.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6037I Successfully registered with ARM<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) called the Registration function of<br />
Automatic Restart Manager (ARM) as the first<br />
phase of registering with ARM.<br />
System Action: The utility continues.<br />
User Response: For information only.<br />
CTG6051S System Error with CSVQUERY,<br />
RC=[value]<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) uses the CSVQUERY macro to check if<br />
it has been APF authorized. The call to do this<br />
has failed with the return code [value].<br />
System Action: The utility terminates.<br />
User Response: This is a severe error and<br />
should be reported to the service team.<br />
CTG6052E Error - ctgarm is not APF<br />
Authorized.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
Automatic Restart Manager Batch Utility<br />
(ctgarm) must be APF authorized in order to<br />
register with ARM. This should happen during<br />
installation.<br />
System Action: The utility terminates.<br />
User Response: See the installation instructions<br />
in the Administration book for details of how to<br />
APF authorize ctgarm.<br />
Messages 105
CTG6100E CTG6106E<br />
CTG6100E The installation cannot continue<br />
as the operating system of this<br />
machine (machine OS <strong>Version</strong>) does<br />
not reach the pre-requisite level<br />
(minimum OS <strong>Version</strong>).<br />
Explanation: The operating system level is not<br />
supported.<br />
System Action: The install terminates.<br />
User Response: Refer to the CTG<br />
Administration book for your system to<br />
determine the supported levels of operating<br />
system.<br />
CTG6101W Not enough primary allocation<br />
space in directory directory name to<br />
install the product. If you have<br />
enough secondary allocation<br />
space, the installation may still<br />
succeed.<br />
Explanation: On the z/OS operating system, the<br />
size of directory space can be expanded<br />
automatically as disk space is used up. The space<br />
currently allocated to directory name is insufficient<br />
to continue the installation, but may be able to<br />
expand as required.<br />
System Action: The script will prompt the user<br />
with the option to continue or terminate.<br />
User Response: Either expand the disk space<br />
allocation for the given directory, or continue<br />
with the installation and check for other possible<br />
errors due to the limited space.<br />
CTG6102E Not enough space in directory<br />
directory name to unpack the<br />
product.<br />
Explanation: The space currently allocated to<br />
directory name is insufficient to continue the<br />
installation.<br />
System Action: The install will terminate.<br />
User Response: Expand the disk space<br />
allocation for directory name and retry the install.<br />
106 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG6103E Command command name cannot<br />
be found in your PATH.<br />
Explanation: The install requires the use of the<br />
command: command name, but this is not in the<br />
current PATH.<br />
System Action: The install will terminate.<br />
User Response: Identify where this command is<br />
on your system. Add its location to your PATH<br />
and retry the install. See the Problem<br />
Determination section in the CTG Administration<br />
book for your system for further information.<br />
CTG6104E You must be logged in as root to<br />
install this product. Log in as root<br />
and try again.<br />
Explanation: On most platforms you will<br />
require super user or root authority to complete<br />
the installation.<br />
System Action: The install will terminate.<br />
User Response: Log in as root or su to superuser<br />
and retry the install.<br />
CTG6105W Install could not change to<br />
codepage %s1 - the installation<br />
may not be valid.<br />
Explanation: When installing in non-US locales,<br />
the installation will attempt to convert scripts to<br />
a codepage suitable for the current locale. This<br />
has failed.<br />
System Action: The install continues, but the<br />
scripts will be left in the default codepage.<br />
User Response: Check the following message to<br />
determine the reason for failure, for example,<br />
unsupported language and code set combination.<br />
Try running the ctgmsgs command to set the<br />
language and code set you require.<br />
CTG6106E Language language code is not<br />
recognized. Use command ctgmsgs<br />
to list the recognized languages.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
supports a number of language and code set<br />
combinations, but the specified language code is
not supported on this platform.<br />
System Action: The message language will not<br />
be changed.<br />
User Response: Run the ctgmsgs command with<br />
the -? parameter to get a list of supported<br />
language and code set combinations. Choose the<br />
combination that best meets your requirements<br />
and retry with that combination.<br />
CTG6107E Code set code set is not recognized.<br />
Use command ctgmsgs to list the<br />
recognized code sets.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
supports a number of language and code set<br />
combinations, but the specified code set is not<br />
supported on this platform.<br />
System Action: The message language will not<br />
be changed.<br />
User Response: Run the ctgmsgs command with<br />
the -? parameter to get a list of supported<br />
language and code set combinations. Choose the<br />
combination that best meets your requirements<br />
and retry with that combination.<br />
CTG6108E Adobe Acrobat Reader not found.<br />
Explanation: The documentation for <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong> is provided in a PDF file,<br />
and Adobe Acrobat reader was not found on the<br />
system.<br />
System Action: The ctgdoc utility terminates.<br />
User Response: Either install Adobe Acrobat<br />
reader, if it is available for this platform, or<br />
identify a reader for PDF files and use this to<br />
view the documentation which is available in the<br />
/docs directory, or copy the PDF file<br />
to a platform that supports Adobe Acrobat<br />
reader.<br />
CTG6109E The JVM is not at the required<br />
level to run this application.<br />
Explanation: The Java applications supplied<br />
with <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> require a<br />
minimum level of JVM.<br />
CTG6107E CTG6112W<br />
System Action: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will not start.<br />
User Response: See the Administration book for<br />
details of the versions of Java supported. Install<br />
the correct level of Java and add access to it from<br />
the PATH.<br />
CTG6110E File ctgenvvar not found. Create it<br />
by copying ctgenvvarsamp and<br />
editing it to match your<br />
environment<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS uses the ctgenvvar script to initialize<br />
environment variables before executing its Java<br />
component.<br />
System Action: The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
will not start.<br />
User Response: See the Administration book for<br />
details on configuring the <strong>Gateway</strong> and creating<br />
ctgenvvar.<br />
CTG6111I File ctgenvvar found. Using the<br />
configuration in script ctgenvvar to<br />
start up the application.<br />
Explanation: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on zOS<br />
uses the ctgenvvar script to initialize environment<br />
variables before executing its Java component.<br />
System Action: The script will continue, using<br />
the ctgenvvar values.<br />
User Response: For information only.<br />
CTG6112W To configure <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for use with RACF<br />
userid and password<br />
authentication, a user with READ<br />
access to the<br />
BPX.FILEATTR.PROGCTL<br />
FACILITY class will need to run<br />
the command [unix command].<br />
Explanation: The install script attempts to set<br />
extended attributes required to run with RACF<br />
userid and password authentication. If the user<br />
does not have authority to do this the message is<br />
issued as a warning.<br />
Messages 107
CTG6113W CTG8202E<br />
System Action: The script continues without<br />
setting the extended attributes.<br />
User Response: If you wish to configure CTG<br />
for RACF authentication, then an authorized user<br />
will need to enter this [unix command],<br />
otherwise no further action is necessary. See the<br />
Administration book or the z/OS UNIX System<br />
Services Planning book for more information.<br />
CTG6113W To configure <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> for use with z/OS<br />
Automatic Restart Manager, a user<br />
with authority to update RACF<br />
group BPX.FILEATTR.APF will<br />
need to run the command [unix<br />
command].<br />
Explanation: The install script attempts to set<br />
extended attributes required to run the ctgarm<br />
command. If the user does not have authority to<br />
do this the message is issued as a warning.<br />
System Action: The script continues without<br />
setting the extended attributes.<br />
User Response: If you wish to use ARM, then<br />
an authorized user will need to enter this [unix<br />
command], otherwise no further action is<br />
necessary. See the Administration book or the<br />
z/OS UNIX System Services Planning book for<br />
more information.<br />
CTG6114E <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has<br />
not been fully installed. Run the<br />
command setup command to<br />
complete the installation.<br />
Explanation: Part of the installation process is<br />
to run the setup command, but this has not been<br />
completed satisfactorily.<br />
System Action: The script terminates.<br />
User Response: Refer to the CTG<br />
Administration book for more information on<br />
installing the product.<br />
108 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG6115S There is an internal problem<br />
installing the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
Explanation: The ctgsetup command has failed<br />
to unlock this installation of the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>. The messages following<br />
may indicate why it failed.<br />
System Action: The script terminates.<br />
User Response: Refer to the problem<br />
determination section of CTG Administration<br />
book. If this does not resolve the problem,<br />
contact your service representative with the<br />
information.<br />
CTG8200E No message available for message<br />
id {0}<br />
Explanation: The message id indicated could<br />
not be located within the message file.<br />
System Action: No action has been taken.<br />
User Response: Contact your service<br />
representative with the information.<br />
CTG8201E Unable to open a connection to<br />
gateway {0}. Exception<br />
message={1}<br />
Explanation: An exception was thrown when<br />
trying to open a connection to the CTG Server at<br />
the specified URL. The exception message is<br />
provided.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The exception may provide<br />
more information into the problem.<br />
CTG8202E Exception occurred trying to<br />
authenticate with gateway {0}.<br />
Exception message={1}<br />
Explanation: An exception was thrown when<br />
trying to authenticate the client with the CTG<br />
Server at the specified URL. The exception<br />
message is provided.
System Action: The requested action cannot be<br />
completed.<br />
User Response: The exception may provide<br />
more information into the problem.<br />
CTG8203E Unexpected gateway rc={0} trying<br />
to authenticate with gateway {1}<br />
Explanation: An unexpected return code was<br />
received when trying to authenticate the client<br />
with the CTG server at the specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The return code may provide<br />
more information into the problem.<br />
CTG8204E <strong>Gateway</strong> {0} has security protocols<br />
in place not recognized by this<br />
program<br />
Explanation: CTGAdmin cannot handle the<br />
security protocols in place on the CTG Server at<br />
the specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Obtain a later version of<br />
ctgadmin.jar, or disable the protocols at <strong>Gateway</strong><br />
{0}.<br />
CTG8205E Unknown security protocol {0} in<br />
<strong>Gateway</strong> {1} reported a failure<br />
rc={2}<br />
Explanation: The indicated security protocol,<br />
unknown to CTGAdmin, reported a failure of the<br />
specified return code.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Obtain a later version of<br />
ctgadmin.jar, or disable the protocols at <strong>Gateway</strong><br />
{0}.<br />
CTG8203E CTG8209E<br />
CTG8206E Unexpected gateway rc={0} trying<br />
to send request to gateway {1}<br />
Explanation: An unexpected return code was<br />
received trying to send the request from the<br />
authenticated client.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The return code may provide<br />
more information into the problem.<br />
CTG8207E Unable to initialize with<br />
authenticated gateway {0}. rc={1}<br />
Explanation: An unexpected return code was<br />
received trying to initialize with the CTG server<br />
from an authenticated client at the specified<br />
URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The return code may provide<br />
more information into the problem.<br />
CTG8208E Exception occurred trying to send<br />
request to gateway {0}. Exception<br />
message={1}<br />
Explanation: An exception was thrown when<br />
trying to send a request from an authenticated<br />
client to the CTG Server at the specified URL.<br />
The exception message is provided.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The exception may provide<br />
more information into the problem.<br />
CTG8209E Unexpected rc={0} sending request<br />
to gateway {1}<br />
Explanation: An unexpected return code was<br />
received trying to send a request to the CTG<br />
server from an authenticated client at the<br />
specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The return code may provide<br />
Messages 109
CTG8210E CTG8218E<br />
more information into the problem.<br />
CTG8210E The gateway {0} reports no<br />
management server located<br />
Explanation: The CTG server at the specified<br />
URL was unable to locate its management server.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Obtain a trace from the CTG<br />
Server and contact your service representative.<br />
CTG8211E The gateway {0} sent back<br />
information which this client<br />
cannot read<br />
Explanation: CTGAdmin cannot handle<br />
information sent by the CTG server at the<br />
specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Ensure that the Java level on<br />
the client is at least as high as that on the server.<br />
Also check that you have the latest version of<br />
ctgadmin.jar installed.<br />
CTG8212E Tag ″{0}″ must be specified<br />
Explanation: The mandatory tag was not<br />
specified.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Reissue the command,<br />
specifying the tag.<br />
CTG8213E An unexpected error occurred<br />
processing tag ″{0}″<br />
Explanation: An unexpected error occurred<br />
when processing the specified tag.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Contact your service<br />
representative.<br />
110 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG8214E Tag ″{0}″ cannot be specified more<br />
than once<br />
Explanation: The specified tag appears more<br />
than once in the request; this is not allowed.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8215E Tag ″{0}″ is not valid<br />
Explanation: The specified tag is not<br />
recognized.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8216E Tag ″{0}″ must be prefixed with -<br />
Explanation: A parameter was provided but did<br />
not start with a minus sign<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8217E URL ″{0}″ for tag ctg is not valid<br />
Explanation: The URL specified in the ctg tag is<br />
not a valid URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8218E URL ″{0}″ did not specify the TCP<br />
protocol<br />
Explanation: The URL given in the ctg tag did<br />
not specify the TCP protocol. Currently<br />
CTGAdmin supports only the TCP protocol.<br />
System Action: The requested action cannot be<br />
completed.
User Response: Correct the request and try<br />
again. The form of the ctg tag is<br />
-ctg=tcp://mygateway.com:2810<br />
CTG8219E Action ″{0}″ specified is not valid<br />
Explanation: CTGAdmin did not recognize the<br />
specified action.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again. Refer to help for a list of valid actions.<br />
CTG8220E No recognized tags for action ″{0}″<br />
specified<br />
Explanation: This action requires tags, but no<br />
valid ones were specified.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8221E Value for tag ″{0}″ must be<br />
numeric<br />
Explanation: The value for the specified tag was<br />
not a number and is required to be a number.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8222E Tag ″{0}″, value {1} outside range<br />
of {2}-{3}<br />
Explanation: The value for the specified tag was<br />
not within the range specified by {2}-{3}.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8219E CTG8226E<br />
CTG8223E Cannot specify the tag<br />
fulldatadump with dumpoffset or<br />
truncationsize<br />
Explanation: For the setgwtrace action you<br />
cannot specify the fulldatadump tag with the<br />
dumpoffset tag or the truncationsize tag.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again. Specify fulldatadump if you want the<br />
complete contents of the dump. Specify<br />
dumpoffset, or truncationsize, or both, if you<br />
want a partial dump.<br />
CTG8224E IP address or hostname not<br />
authorized for gateway {0}<br />
Explanation: The client machine is not<br />
authorized to perform administrative commands<br />
on the specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Check that the host from which<br />
you are issuing the command appears in the list<br />
of authorized hosts at the <strong>Gateway</strong> that you are<br />
attempting to administer (configuration tool,<br />
TCPAdmin panel).<br />
CTG8225E Tag ″{0}″, value {1} is below<br />
minimum value of {2}<br />
Explanation: The value for the specified tag was<br />
too low and cannot be used.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8226E <strong>Gateway</strong> {0} is not restricted. URL<br />
cannot be used<br />
Explanation: The specified URL does not refer<br />
to the TCPAdmin protocol handler but refers to a<br />
standard TCP protocol handler.<br />
Messages 111
CTG8227E CTG9602I<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: specify the URL for the<br />
TCPAdmin handler and reissue the request.<br />
CTG8227E Exception returned from gateway<br />
{0}. Exception message={1}<br />
Explanation: An exception was returned from<br />
the CTG Server at the specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The exception message will<br />
provide more information on the problem.<br />
CTG8228E Specified tag(s) ″{0}″ unknown for<br />
requested action<br />
Explanation: The specified tag is not<br />
recognized.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG8229E Unexpected rc={0} trying to<br />
authenticate with gateway {1}<br />
Explanation: An unexpected return code was<br />
received when trying to authenticate the client<br />
with the CTG server at the specified URL.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: The return code may provide<br />
more information into the problem.<br />
CTG8230E The gateway {0} sent back an<br />
exception that this client cannot<br />
read<br />
Explanation: The CTG Server at the URL<br />
specified tried to send an exception back which<br />
cannot be handled by CTGAdmin.<br />
System Action: The requested action cannot be<br />
completed.<br />
112 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
User Response: Ensure that the Java level on<br />
the client is at least as high as that on the server.<br />
Also check that you have the latest version of<br />
ctgadmin.jar installed.<br />
CTG8231E JNI Trace file name must be<br />
specified<br />
Explanation: For the setjnitrace action, the tfile<br />
tag was specified but no value was given. A<br />
value must be specified.<br />
System Action: The requested action cannot be<br />
completed.<br />
User Response: Correct the request and try<br />
again.<br />
CTG9600I ResultSet not supported<br />
Explanation: The ResultSet Record type is not<br />
supported by the <strong>CICS</strong> resource adapters.<br />
System Action: System action is not required.<br />
User Response: You are attempting to get a<br />
ResultSet, which is not supported by the <strong>CICS</strong><br />
resource adapters.<br />
CTG9601E This connection is already closed<br />
Explanation: The connection has already been<br />
closed and so cannot be closed again.<br />
System Action: System action is not required.<br />
User Response: You are attempting to close a<br />
connection that has already been closed.<br />
CTG9602I RecordFactory not supported<br />
Explanation: The <strong>CICS</strong> resource adapters do not<br />
provide or support the use of a RecordFactory<br />
object as defined within the J2EE/CA<br />
Specification.<br />
System Action: System action is not required.<br />
User Response: You are attempting to get a<br />
reference to a RecordFactory, which is not<br />
supported by the <strong>CICS</strong> resource adapters.
CTG9603E ConnectionManager has returned<br />
an invalid connection<br />
Explanation: The connection returned by the<br />
ConnectionManager is not of the correct type for<br />
use with the <strong>CICS</strong> resource adapters. This is an<br />
internal error.<br />
System Action: System action is not required.<br />
User Response: The <strong>CICS</strong> Resource Adapter<br />
was returned a connection that was either null,<br />
or not of the correct type.<br />
CTG9604I This form of execute is not<br />
supported<br />
Explanation: The <strong>CICS</strong> resource adapters only<br />
support the two parameter version of execute()<br />
as prior knowledge of the output Record object is<br />
needed in order to store the reply from <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: Please recode the application to<br />
use the two parameter variant of execute() as<br />
defined in the javadoc.<br />
CTG9605E ManagedConnection cannot be<br />
used, it is in an unrecoverable<br />
state<br />
Explanation: Due to an unrecoverable error the<br />
ManagedConnection object your application is<br />
using has become corrupted and cannot be used<br />
for any further interactions with <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9606I Feature not supported by ECI<br />
resource adapter.<br />
Explanation: The method being called is not<br />
supported by the ECI resource adapter.<br />
System Action: System action is not required.<br />
User Response: Please adjust the application, as<br />
this feature of the Connector specification is not<br />
supported by the ECI resource adapter.<br />
CTG9603E CTG9616E<br />
CTG9607E <strong>Transaction</strong> failed to commit,<br />
rolled back instead.<br />
Explanation: Due to some error the transaction<br />
failed to commit on <strong>CICS</strong> and so a rollback was<br />
carried out to back out any work done within<br />
the transaction.<br />
System Action: The system has attempted to<br />
commit the transaction but cannot do so. The<br />
transaction has therefore been rolled back.<br />
User Response: User action above.<br />
CTG9610E <strong>Transaction</strong> already started on<br />
ECIManagedConnection.<br />
Explanation: A local transaction has already<br />
been started on the ECIManagedConnection so<br />
you may not start another. Only one local<br />
transaction per ECIManagedConnection at any<br />
one time is supported by the ECI resource<br />
adapter.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9611E <strong>Transaction</strong> not started on<br />
ECIManagedConnection.<br />
Explanation: A local transaction has not been<br />
started on the ECIManagedConnection so any<br />
calls to commit() or rollback() will fail.<br />
System Action: System action is not required.<br />
User Response: The local transaction has not<br />
been started, so cannot commit.<br />
CTG9616E <strong>Transaction</strong> failed to commit or<br />
roll back.<br />
Explanation: A request was made, but failed,<br />
possibly due to a communications error.<br />
System Action: System action is not required.<br />
User Response: Due to an error, this transaction<br />
cannot be committed or rolled back.<br />
Messages 113
CTG9617E CTG9624E<br />
CTG9617E ECI connection closed.<br />
Explanation: Access to this ECIConnection is no<br />
longer allowed as it has been closed. A new<br />
ECIConnection must be acquired for any further<br />
interaction to occur with <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: This connection is closed, no<br />
further work through this handle is allowed.<br />
CTG9618E Cannot associate connection with<br />
ECIManagedConnection. Supplied<br />
Connection is null.<br />
Explanation: When trying to associate a<br />
connection with an ECIManagedConnection the<br />
connection type must be ECIConnection. This is<br />
an internal error.<br />
System Action: System action is not required.<br />
User Response: Connection handle supplied is<br />
null.<br />
CTG9619E Cannot associate connection with<br />
ECIManagedConnection. Not of<br />
type ECIConnection.<br />
Explanation: When trying to associate a<br />
connection with an ECIManagedConnection the<br />
connection type must be ECIConnection. This is<br />
an internal error.<br />
System Action: System action is not required.<br />
User Response: The Connection handle is not of<br />
the correct type.<br />
CTG9620E Connection returned by<br />
ConnectionManager not of type<br />
ECIConnection.<br />
Explanation: The ConnectionManager has not<br />
returned an ECIConnection object from the<br />
allocateConnection() method.<br />
System Action: System action is not required.<br />
User Response: The Connection handle<br />
returned is not of the correct type.<br />
114 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG9621E ConnectionSpec supplied is not of<br />
type ECIConnectionSpec.<br />
Explanation: The ECI resource adapter only<br />
supports ConnectionSpec objects of the type<br />
ECIConnectionSpec.<br />
System Action: System action is not required.<br />
User Response: The ConnectionSpec handle is<br />
not of the correct type.<br />
CTG9622E ConnectionRequestInfo object is<br />
not of type<br />
ECIConnectionRequestInfo.<br />
Explanation: The ConnectionRequestInfo object<br />
being supplied to the ECI resource adapter is not<br />
of the correct type. This is an internal error.<br />
System Action: System action is not required.<br />
User Response: The ConnectionRequestInfo<br />
handle is not of the correct type.<br />
CTG9623E ConnectionManager supplied is<br />
null.<br />
Explanation: The ConnectionManager supplied<br />
to the ECIConnectionFactory is null. In a<br />
managed environment this is a internal error to<br />
the environment. In a nonmanaged environment<br />
you must not supply a null ConnectionManager<br />
to the ECIConnectionFactory constructor.<br />
System Action: System action is not required.<br />
User Response: The ConnectionManager handle<br />
is null.<br />
CTG9624E ECIInteraction closed.<br />
Explanation: You cannot do any further work<br />
with this ECIInteraction object as it has been<br />
closed.<br />
System Action: System action is not required.<br />
User Response: The ECIInteraction has been<br />
closed, further work is not allowed.
CTG9625E ECIConnection used during<br />
interaction is null.<br />
Explanation: The ECIConnection object<br />
associated with the current ECIInteraction object<br />
is null so the interaction cannot continue. This is<br />
an internal error.<br />
System Action: System action is not required.<br />
User Response: The Connection handle is null<br />
for this interaction.<br />
CTG9626E Connection associated with<br />
ECIInteraction not of type<br />
ECIConnection.<br />
Explanation: The ECIConnection that is being<br />
used by your ECIInteraction is not of the correct<br />
type. This is an internal error.<br />
System Action: System action is not required.<br />
User Response: The Connection handle for this<br />
interaction is not of the correct type.<br />
CTG9627E IOException occurred when<br />
writing to the Output Record.<br />
Explanation: An I/O exception was thrown by<br />
the record when the resource adapter attempted<br />
to populate it with the relevant information. The<br />
record exception is linked to this one.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9628E InteractionSpec passed to<br />
execute() not of type<br />
ECIInteractionSpec.<br />
Explanation: Only InteractionSpec objects of the<br />
type ECIInteractionSpec can passed to the<br />
ECIInteraction.execute() method.<br />
System Action: System action is not required.<br />
User Response: InteractionSpec passed in to the<br />
execute method is not of the correct type.<br />
CTG9625E CTG9632E<br />
CTG9629E InteractionSpec passed to<br />
execute() is null.<br />
Explanation: When calling<br />
ECIInteraction.execute() a non null<br />
ECIInteractionSpec must be supplied at all times.<br />
System Action: System action is not required.<br />
User Response: Null was passed to the<br />
ECIInteractionSpec.execute method.<br />
CTG9630E IOException occurred in<br />
communication with <strong>CICS</strong>.<br />
Explanation: During an interaction an<br />
IOException has occurred when communicating<br />
with a <strong>CICS</strong> server.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9631E Error occurred during interaction<br />
with <strong>CICS</strong>. Error Code=<br />
Explanation: During an interaction with a <strong>CICS</strong><br />
server a known error has occurred in the<br />
underlying <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> runtime.<br />
The supplied error code can be referenced in the<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> documentation. This<br />
is an internal error.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9632E SYNC_SEND<br />
/SYNC_SEND_RECEIVE not<br />
supported when reply to previous<br />
SYNC_SEND is pending.<br />
Explanation: If a SYNC_SEND interaction has<br />
been executed and no matching SYNC_RECEIVE<br />
has been carried out the a reply is pending so no<br />
further SYNC_SEND/ SYNC_SEND_RECEIVE<br />
interactions are allowed until a SYNC_RECEIVE<br />
is executed.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
Messages 115
CTG9633E CTG9641E<br />
CTG9633E SYNC_RECEIVE attempted<br />
without corresponding<br />
SYNC_SEND.<br />
Explanation: In order to receive a reply from<br />
<strong>CICS</strong> using a SYNC_RECEIVE Interaction a<br />
SYNC_SEND Interaction must first be executed.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9634E Input record does not implement<br />
javax.resource.spi.Streamable<br />
interface.<br />
Explanation: Input record objects supplied to<br />
the ECIInteraction.execute() method must<br />
support the javax.resource.spi.Streamable<br />
interface.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9635E Input record is null.<br />
Explanation: When specifying an<br />
InteractionVerb of SYNC_SEND or<br />
SYNC_SEND_RECEIVE a non null input Record<br />
object must be supplied as input to <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9636E Output record does not<br />
implement<br />
javax.resource.spi.Streamable<br />
interface.<br />
Explanation: Output record objects supplied to<br />
the ECIInteraction.execute() method must<br />
support the javax.resource.spi.Streamable<br />
interface.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
116 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG9637E Output record is null.<br />
Explanation: When specifying an<br />
InteractionVerb of SYNC_RECEIVE or<br />
SYNC_SEND_RECEIVE a non null output<br />
Record object must be supplied to hold the reply<br />
from <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9638E <strong>Transaction</strong> Abend occurred in<br />
<strong>CICS</strong>. Abend Code=<br />
Explanation: During the Interaction with <strong>CICS</strong><br />
a <strong>Transaction</strong> Abend occurred on the server. The<br />
supplied code is that which is returned by <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9639E Unable to perform action,<br />
connection is closed<br />
Explanation: The EPIConnection has been<br />
closed and can no longer be used.<br />
System Action: System action is not required.<br />
User Response: Connection is closed, no further<br />
work possible.<br />
CTG9640E No connection was returned by<br />
ConnectionManager<br />
Explanation: The ConnectionManager did not<br />
return an EPIConnection for use by the<br />
application.<br />
System Action: System action is not required.<br />
User Response: No connection returned by the<br />
ConnectionManager.<br />
CTG9641E Invalid connection was returned<br />
by ConnectionManager<br />
Explanation: An unusable Connection object<br />
was returned by the ConnectionManager.<br />
System Action: System action is not required.
User Response: Invalid connection was<br />
returned by ConnectionManager.<br />
CTG9642E Invalid ConnectionSpec was<br />
supplied, must be an<br />
EPIConnectionSpec instance<br />
Explanation: Only ConnectionSpecs of the type<br />
EPIConnectionSpec are accepted in the<br />
getConnection() method of<br />
EPIConnectionFactory.<br />
System Action: System action is not required.<br />
User Response: Invalid ConnectionSpec was<br />
supplied, must be an EPIConnectionSpec<br />
instance.<br />
CTG9643E Unable to perform action,<br />
interaction is closed<br />
Explanation: The EPIInteraction is closed so no<br />
further work can be carried out on it.<br />
System Action: System action is not required.<br />
User Response: Connection is closed, no further<br />
work possible.<br />
CTG9644E No EPIInteractionSpec supplied<br />
Explanation: An EPIInteractionSpec must be<br />
supplied when EPIConnection.execute() is called.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9645E Invalid InteractionSpec was<br />
supplied, must be an<br />
EPIInteractionSpec instance<br />
Explanation: An EPIInteractionSpec must be<br />
supplied when EPIConnection.execute() is called.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9642E CTG9649I<br />
CTG9646E Invalid connection passed to<br />
associate connection method by<br />
application server<br />
Explanation: When attempting to associate a<br />
Connection object with an<br />
EPIManagedConnection the incorrect type was<br />
used. The EPI resource adapter only supports<br />
EPIConnection objects being passed to the<br />
associateConnection() method.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9647E A null connection was passed to<br />
associate connection method by<br />
application server<br />
Explanation: When attempting to associate a<br />
Connection object with an<br />
EPIManagedConnection the incorrect type was<br />
used. The EPI resource adapter only supports<br />
EPIConnection objects being passed to the<br />
associateConnection() method.<br />
System Action: System action is not required.<br />
User Response: A null connection was passed<br />
to associateConnection() method by the<br />
application server.<br />
CTG9648I Local transactions not supported<br />
Explanation: The EPI resource adapter does not<br />
support any transactional interfaces. Any attempt<br />
to use them will throw an exception.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9649I XAResource not supported<br />
Explanation: The EPI resource adapter does not<br />
support any transactional interfaces. Any attempt<br />
to use them will throw an exception.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
Messages 117
CTG9650E CTG9658E<br />
CTG9650E Streamable input record<br />
information does not contain the<br />
correct amount of data<br />
Explanation: The amount of data stored in the<br />
input Record object does not correspond to the<br />
amount required for the currently defined screen<br />
size.<br />
System Action: System action is not required.<br />
User Response: Streamable input record<br />
information does not contain the correct amount<br />
of data.<br />
CTG9651E Input record is of unknown type<br />
and cannot be used<br />
Explanation: Input record objects supplied to<br />
EPIInteraction.execute() must implement the<br />
javax.resource.spi.Streamable interface in order to<br />
be used by the EPI resource adapter.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9652E Output record is of unknown type<br />
and cannot be used<br />
Explanation: Output record objects supplied to<br />
EPIInteraction.execute() must implement the<br />
javax.resource.spi.Streamable interface in order to<br />
be used by the EPI resource adapter.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9653E No output record was given and<br />
one was expected<br />
Explanation: When executing a<br />
SYNC_RECEIVE or SYNC_SEND_RECEIVE an<br />
output record must be supplied to hold the reply<br />
from <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
118 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG9654E No input record was given and<br />
one was expected<br />
Explanation: When executing a SYNC_SEND or<br />
SYNC_SEND_RECEIVE an input record must be<br />
supplied to hold the data to be sent to <strong>CICS</strong>.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9655E LogonLogoff class threw an<br />
exception which is linked to this<br />
one<br />
Explanation: An exception was thrown whilst<br />
accessing the LogonLogoff class specified. The<br />
original exception can be accessed using the<br />
getLinkedException method.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9656E LogonLogoff class could not be<br />
found<br />
Explanation: The LogonLogoff class specified<br />
could not be found in the current CLASSPATH.<br />
Check that any required files are in your systems<br />
CLASSPATH.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9657E LogonLogoff class found but<br />
could not be instantiated<br />
Explanation: An error occurred whilst trying to<br />
instantiate the LogonLogoff class specified.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9658E No authority to create<br />
LogonLogoff Class<br />
Explanation: Your application does not have the<br />
required authorization to create the specified<br />
LogonLogoff class.<br />
System Action: System action is not required.
User Response: User action above.<br />
CTG9659E Unable to build security<br />
information to pass to<br />
LogonLogoff class<br />
Explanation: The resource adapter was unable<br />
to create a Subject object required to be passed to<br />
the registered LogonLogoff class. This could be<br />
because the required Java Security permissions<br />
are not available.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9660E No Connection Manager passed to<br />
resource adapter. Adapter unable<br />
to function<br />
Explanation: A Request to create a connection<br />
factory has failed because a null connection<br />
manager was passed to the<br />
createConnectionFactory method.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9661I EPI is not transactional, so this<br />
action is not supported<br />
Explanation: The EPI resource adapter does not<br />
support any transactional interfaces. Any attempt<br />
to use them will throw an exception.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9662I You can only have one interaction<br />
per connection<br />
Explanation: The EPI resource adapter only<br />
supports a single EPIInteraction instance per<br />
EPIConnection instance.<br />
System Action: System action is not required.<br />
User Response: Because a connection represents<br />
a 3270 conversation, only one interaction per<br />
connection is allowed.<br />
CTG9659E CTG9666E<br />
CTG9663E A connection which is not the<br />
active connection attempted to<br />
execute on the resource adapter.<br />
Explanation: The EPIConnection that your<br />
component is trying to use is not the current<br />
Connection being processed by the EPI resource<br />
adapter. The current working Connection must<br />
be closed before work can continue. This is an<br />
internal error.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9664E <strong>Transaction</strong> ended. Unable to<br />
determine server state.<br />
Explanation: The <strong>CICS</strong> transaction has ended,<br />
but it is not possible to determine if resources<br />
were committed or rolled back.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9665E ExecuteTimeout property cannot<br />
be negative.<br />
Explanation: The ExecuteTimeout property on<br />
the ECIInteractionSpec must be a positive value.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9666E Value of InteractionVerb is not<br />
one of SYNC_SEND,<br />
SYNC_RECEIVE,<br />
SYNC_SEND_RECEIVE.<br />
Explanation: You have not passed a valid value<br />
for InteractionVerb within your<br />
ECIInteractionSpec.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
Messages 119
CTG9667E CTG9801E<br />
CTG9667E FunctionName is empty, cannot<br />
send request.<br />
Explanation: In order to carry out an Interaction<br />
with <strong>CICS</strong> a FunctionName must be provided in<br />
the ECIInteractionSpec. This FunctionName maps<br />
to the program that is to be executed on the<br />
<strong>CICS</strong> server.<br />
System Action: System action is not required.<br />
User Response: The function name in the<br />
ECIInteractionSpec is empty, request not valid.<br />
CTG9671E Screenable input record doesn’t<br />
match the current screen<br />
definition<br />
Explanation: The input record provided does<br />
not match the EPI resource adapter’s<br />
representation of the screen.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9673E SYNC_RECEIVE required<br />
Commarea length, reply length or<br />
both to be defined.<br />
Explanation: A SYNC_RECEIVE interaction<br />
requires the COMMAREA length or reply length<br />
to be specified in the InteractionSpec, and neither<br />
have been specified.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9674E No SSL keyring class was<br />
provided for SSL protocol<br />
Explanation: The SSL protocol was specified for<br />
the connectionURL, but no keyring has been<br />
specified.<br />
System Action: System action is not required.<br />
User Response: No SSL keyring class was<br />
provided for SSL protocol.<br />
120 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
CTG9675E EPI resource adapter failed trying<br />
to populate Screenable record<br />
Explanation: An exception was thrown by the<br />
screenable record when the EPI resource adapter<br />
attempted to populate it with the relevant<br />
information. The record exception is linked to<br />
this one.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9676E IOException occurred when<br />
reading the Input Record.<br />
Explanation: An I/O exception was thrown by<br />
the record when the resource adapter attempted<br />
to read the information. The record exception is<br />
linked to this one.<br />
System Action: System action is not required.<br />
User Response: User action above.<br />
CTG9800E No message for id {0} could be<br />
located<br />
Explanation: The message id indicated could<br />
not be located within the message file.<br />
System Action: No action taken.<br />
User Response: Contact your service<br />
representative with the information.<br />
CTG9801E A request to get or set an attribute<br />
was unknown to MBean {0}<br />
Explanation: A Management Bean received a<br />
request to get or set an attribute but this attribute<br />
is unknown to it.<br />
System Action: No action taken.<br />
User Response: Ensure the management bean<br />
being invoked supports this attribute.
CTG9802E An invalid value was given for an<br />
attribute for MBean {0}<br />
Explanation: A request to set an attribute on a<br />
management bean failed because the value<br />
provided was not valid.<br />
System Action: The attribute doesn’t change.<br />
User Response: Ensure the value provided is<br />
valid for the attribute.<br />
CTG9803E An unexpected exception was<br />
received from MBean {0}<br />
Explanation: A management bean throw an<br />
exception which was not expected by the system.<br />
System Action: No action taken.<br />
User Response: The linked exception may<br />
provide more information on the problem.<br />
CTG9804E An unknown exception occurred<br />
whilst trying to set the trace file<br />
to {0}<br />
Explanation: An exception occurred whilst<br />
trying to set the <strong>Gateway</strong> trace file to the<br />
specified file. This might be because the specified<br />
file is a directory, is not writeable or cannot be<br />
opened for another reason.<br />
System Action: The <strong>Gateway</strong> trace file is not<br />
changed.<br />
User Response: Check that the file specified is a<br />
valid file and is in a writeable location.<br />
CTG9805E An unknown exception occurred<br />
whilst trying to set the jni trace<br />
file to {0}<br />
Explanation: An exception occurred whilst<br />
trying to set the JNI trace file to the specified file.<br />
This might be because the specified file is a<br />
directory, is not writeable or cannot be opened<br />
for another reason.<br />
System Action: The JNI trace file is not<br />
changed.<br />
User Response: Check that the file specified is a<br />
valid file and is in a writeable location.<br />
CTG9802E CTG9809E<br />
CTG9806E An error occurred when setting {0}<br />
Explanation: When trying to make multiple<br />
changes to the <strong>Gateway</strong> server {0} failed.<br />
System Action: The <strong>Gateway</strong> server settings are<br />
not changed.<br />
User Response: Check that the parameters used<br />
in the change are correct.<br />
CTG9807E Attempted to Rollback due to<br />
error setting {0}. Error occurred<br />
during rollback because of setting<br />
{1}<br />
Explanation: When trying to make multiple<br />
changes to the <strong>Gateway</strong> server {0} failed. Then<br />
when trying to undo the changes already made,<br />
a further change {1} failed.<br />
System Action: The <strong>Gateway</strong> server settings are<br />
left in an undefined state.<br />
User Response: Check that the parameters used<br />
in the change are correct.<br />
CTG9808E The value of {1} is not valid for {0}<br />
Explanation: When trying to change a <strong>Gateway</strong><br />
trace setting, the value provided was not valid.<br />
System Action: The <strong>Gateway</strong> server setting is<br />
not changed.<br />
User Response: Check that the value used for<br />
the setting is correct.<br />
CTG9809E The value of {1} is not valid for {0}<br />
Explanation: When trying to change a <strong>Gateway</strong><br />
JNI trace setting, the value provided was not<br />
valid.<br />
System Action: The <strong>Gateway</strong> server setting is<br />
not changed.<br />
User Response: Check that the value used for<br />
the setting is correct.<br />
Messages 121
CTG9810E CTG9815E<br />
CTG9810E The trace file {0} specified a<br />
directory<br />
Explanation: When trying to set the <strong>Gateway</strong><br />
trace file, the value specified a directory.<br />
System Action: The trace file is not changed.<br />
User Response: Specify a trace file that is not a<br />
directory.<br />
CTG9811E The trace file {0} specified an<br />
invalid path<br />
Explanation: When trying to set the <strong>Gateway</strong><br />
trace file, the value specified an invalid path.<br />
System Action: The trace file is not changed.<br />
User Response: Specify a trace file using a valid<br />
path for the platform.<br />
CTG9812E The trace file {0} specified an<br />
unwriteable file<br />
Explanation: When trying to set the <strong>Gateway</strong><br />
trace file, the value specified a file on which the<br />
<strong>Gateway</strong> does not have write permissions, or a<br />
directory in which the <strong>Gateway</strong> cannot create or<br />
write a file.<br />
System Action: The trace file is not changed.<br />
User Response: Specify a trace file which is<br />
writeable by the <strong>Gateway</strong> or in a location which<br />
is writeable by the <strong>Gateway</strong>.<br />
CTG9814E The jni trace file {0} specified an<br />
invalid path<br />
Explanation: When trying to set the jni trace<br />
file, the value specified an invalid path.<br />
System Action: The jni trace file is not changed.<br />
User Response: Specify a jni trace file using a<br />
valid path for the platform.<br />
CTG9815E The jni trace file {0} specified an<br />
unwriteable file<br />
Explanation: When trying to set the jni trace<br />
file, the value specified a file on which the CTG<br />
122 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
does not have write permissions, or a directory<br />
in which the CTG cannot create or write a file.<br />
System Action: The jni trace file is not changed.<br />
User Response: Specify a trace file which is<br />
writeable by the CTG or in a location which is<br />
writeable by the CTG.
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The product library and related literature<br />
This chapter lists books on the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, and related topics.<br />
It also discusses how you can view the online library supplied with the<br />
product.<br />
It consists of the following topics:<br />
“<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books” Read this for a list of all books provided<br />
with the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Sample configuration documents” on<br />
page 124<br />
Read this for information about a series of<br />
PDF documents that provide step-by-step<br />
guidance on configuring the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
“Redbooks ” on page 125 Read this for details of other publications<br />
that contain examples of client/server<br />
configurations.<br />
“Other Useful Books” on page 125 Read this for details of other relevant<br />
publications.<br />
“Obtaining books from IBM” on page 126 Read this for information on downloading<br />
books and ordering hardcopy versions.<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> books<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Windows ® Administration, SC34-6190<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
Windows.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: UNIX ® Administration, SC34-6139<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
UNIX operating systems.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: z/OS ® Administration, SC34-6191<br />
This book describes the administration of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for<br />
z/OS.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>Gateway</strong> Messages<br />
This online book lists and explains the error messages that can be generated<br />
by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
You cannot order this book.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Reference, SC34-6140<br />
© Copyright IBM Corp. 1994, 2002 123
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
The <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
This book provides information on the APIs of the programming languages<br />
supported by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
There are also additional HTML pages that contain JAVA programming<br />
reference information.<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: Programming Guide, SC34-6141<br />
This introduction to programming for the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
provides the information that you need to allow non-<strong>CICS</strong> applications to<br />
use <strong>CICS</strong> facilities in a client/server environment.<br />
Sample configuration documents<br />
Several sample configuration documents are available in portable document<br />
format (PDF). These documents give step-by-step guidance for configuring<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for communication with <strong>CICS</strong> servers, using<br />
various protocols. They provide detailed instructions that extend the<br />
information in the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library. .<br />
The following scenarios are currently covered:<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Microsoft ® SNA<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for eNetwork Personal<br />
Communications<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for TCP62<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for AIX ® for IBM ® eNetwork<br />
Communications Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Windows for Communications<br />
Server<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for Terminal Servlets using<br />
WebSphere ® Application Server for Windows<br />
v Client security configuration<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> for WebSphere 4.01 using J2EE<br />
v Configuring <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 4.02 for WebSphere Application<br />
Server on z/OS using J2EE<br />
As more sample configuration documents become available, you can<br />
download them from our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Download link.<br />
124 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Redbooks <br />
Other Useful Books<br />
The following International Technical Support Organization (ITSO) Redbook<br />
publication contains many examples of client/server configurations:<br />
v <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> V3.1 The WebSphere Connector for <strong>CICS</strong>, SG24-6133<br />
This book supersedes the following book:<br />
v Revealed! <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> with more <strong>CICS</strong> Clients Unmasked,<br />
SG24-5277.<br />
v Java Connectors for <strong>CICS</strong>: Featuring the J2EE Connector Architecture, SG24-6401.<br />
This book provides information on developing J2EE applications.<br />
See also:<br />
v Securing Web Access to <strong>CICS</strong>, SG24–5756.<br />
v Workload Management for Web Access to <strong>CICS</strong>, SG24–6118.<br />
You can obtain ITSO Redbooks from a number of sources. For the latest<br />
information, see:<br />
www.ibm.com/redbooks/<br />
<strong>CICS</strong> <strong>Transaction</strong> Server publications<br />
Other publications<br />
<strong>CICS</strong> interproduct communication<br />
The following books describe the intercommunication facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>CICS</strong> Family: Interproduct Communication, SC34-6030<br />
<strong>Transaction</strong> Server for Windows NT ® : Intercommunication, SC33-1882<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS: Intercommunication Guide, SC34-6005<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA : Intercommunication Guide, SC33-1665<br />
<strong>CICS</strong> for OS/400 ® : Intercommunication, SC33-1388<br />
TXSeries: <strong>CICS</strong> Intercommunication Guide, SC09-3900<br />
<strong>CICS</strong> for OS/2: Intercommunication, SC33-1583<br />
The first book above is a <strong>CICS</strong> family book containing a platform-independent<br />
overview of <strong>CICS</strong> interproduct communication.<br />
<strong>CICS</strong> problem determination books<br />
The following books describe the problem determination facilities of the <strong>CICS</strong><br />
server products:<br />
<strong>Transaction</strong> Server for Windows NT: Problem Determination, GC33-1883<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for z/OS ® Problem Determination Guide, SC34-6002<br />
The product library and related literature 125
Other publications<br />
<strong>CICS</strong> <strong>Transaction</strong> Server for VSE/ESA Problem Determination Guide,<br />
GC33-1663<br />
<strong>CICS</strong> for OS/400 ® : Problem Determination, SC33-1384<br />
TXSeries: <strong>CICS</strong> Problem Determination Guide, SC33-1565.<br />
You can find information on <strong>CICS</strong> products at the following Web site:<br />
www.ibm.com/software/ts/cics/<br />
APPC-related publications<br />
The following books are concerned with products providing APPC support:<br />
IBM products<br />
IBM Communications Server for AIX for AIX:<br />
IBM Communications Server for AIX: Quick Beginnings, GC31-8583<br />
IBM Communications Server for AIX: General Information, GC31-8584<br />
IBM Communications Server for AIX: Administration, SC31-8586<br />
IBM Communications Server for AIX: Administration Command Reference,<br />
SC31-8587<br />
Systems Network Architecture (SNA)<br />
SNA Formats, GA27-3136<br />
Systems Network Architecture Technical Overview, GC30-3073<br />
TCP62–related publications<br />
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,<br />
GC31–7073<br />
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074<br />
Obtaining books from IBM<br />
For information on books you can download, visit our Web site at:<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
You can order hardcopy books:<br />
v Through your IBM representative or the IBM branch office serving your<br />
locality.<br />
v By calling 1-800-879-2755 in the United States.<br />
v From the Web site at:<br />
www.ibm.com/shop/publications/order<br />
126 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
|<br />
Accessibility<br />
The English version of the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> has been tested for<br />
accessibility on the Windows operating system. The product is accessible.<br />
Documentation<br />
Download the <strong>CICS</strong> Information Center for an html version of the<br />
documentation. Go to this Web page<br />
www.ibm.com/software/ts/cics/<br />
and follow the Library link.<br />
© Copyright IBM Corp. 1994, 2002 127
128 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Glossary<br />
This glossary defines special terms used in<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> library.<br />
3270 emulation. The use of software that<br />
enables a client to emulate an IBM 3270 display<br />
station or printer, and to use the functions of an<br />
IBM host system.<br />
A<br />
abend. The termination of a task, job, or<br />
subsystem because of an error condition that<br />
recovery facilities cannot resolve.<br />
APAR. (Authorized program analysis report.) A<br />
report on the basis of which IBM supplies a fix<br />
of a temporary corrective nature to elements of<br />
function SYSMODs. APAR fixes are called<br />
″corrective″ service because they are installed to<br />
cure problems currently being experienced by an<br />
installation. The APAR fix is usually in the form<br />
of either a modification to a load module or an<br />
update to card-image data. It is intended as a<br />
temporary arrangement until a preventive service<br />
(PTF) is issued to fix the problem permanently.<br />
This PTF supersedes the APAR fix, and indeed<br />
specifies this relationship on its ++VER<br />
statement.<br />
API. Application programming interface.<br />
APING. A command used to verify an APPC<br />
link.<br />
APPC. Advanced program-to-program<br />
communication. An implementation of the<br />
SNA/SDLC LU 6.2 protocol that allows<br />
interconnected systems to communicate and<br />
share the processing of programs. The Client<br />
daemon uses APPC to communicate with <strong>CICS</strong><br />
server systems.<br />
applet. A Java program that is downloaded to,<br />
and executed on, a Web browser or network<br />
computer. See also servlet.<br />
applid. In <strong>CICS</strong>, a system initialization and<br />
terminal control parameter that identifies the<br />
<strong>CICS</strong> system to other remote systems.<br />
ATI. See automatic transaction initiation.<br />
Attach. In SNA, the request unit that flows on a<br />
session to initiate a conversation.<br />
Attach Manager. The component of APPC that<br />
matches Attaches received from remote<br />
computers to accepts issued by local programs.<br />
autoinstall. A facility that enables terminal<br />
definitions to be created automatically in a <strong>CICS</strong><br />
server on request. The definition is deleted when<br />
the client terminal is logged off.<br />
automatic transaction initiation (ATI). The<br />
process whereby a transaction request made<br />
internally within a <strong>CICS</strong> system or network leads<br />
to the scheduling of the transaction. An ATI<br />
request from a <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> can<br />
cause the initiation of a transaction in a <strong>CICS</strong><br />
server system.<br />
B<br />
beans. See JavaBeans .<br />
BIND. In SNA, a request to activate a session<br />
between two logical units (LUs).<br />
business logic. The part of a distributed<br />
application that is concerned with the application<br />
logic rather than the user interface of the<br />
application. Compare with presentation logic.<br />
C<br />
CA. See certification authority.<br />
CEDA. A <strong>CICS</strong> transaction that defines<br />
resources online.<br />
© Copyright IBM Corp. 1994, 2002 129
Glossary<br />
certification authority. In computer security, an<br />
organization that issues certificates. The<br />
certification authority authenticates the certificate<br />
owner’s identity and the services that the owner<br />
is authorized to use. It issues new certificates<br />
and revokes certificates from users who are no<br />
longer authorized to use them.<br />
Change-Number-of-Sessions (CNOS). An<br />
internal transaction program that regulates the<br />
number of parallel sessions between the partner<br />
LUs with specific characteristics.<br />
<strong>CICS</strong> External Call Interface (EXCI). An<br />
application programming interface that enables a<br />
program running on Z/OS, such as <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>, to call a program running<br />
in a <strong>CICS</strong> region. The programs can transfer data<br />
between each other using a communication area.<br />
Compare with External Call Interface (ECI).<br />
<strong>CICS</strong> <strong>Gateway</strong> for Java. In <strong>CICS</strong> Universal<br />
Clients <strong>Version</strong> 2, an interface between a Java<br />
program and <strong>CICS</strong> that allows a Java-enabled<br />
browser to dynamically download a Java Applet<br />
and transparently access <strong>CICS</strong> data. This has<br />
been replaced by the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
<strong>CICS</strong> on open systems. A term used to refer<br />
generically to the products: <strong>CICS</strong> for HP-UX,<br />
<strong>CICS</strong> for Sun Solaris, TXSeries for AIX,<br />
TXSeries for HP-UX, and TXSeries for Solaris.<br />
<strong>CICS</strong> on System/390 ® . A term used to refer<br />
generically to the products <strong>CICS</strong> <strong>Transaction</strong><br />
Server for z/OS , <strong>CICS</strong> for MVS/ESA ,<strong>CICS</strong><br />
<strong>Transaction</strong> Server for z/OS, <strong>CICS</strong> <strong>Transaction</strong><br />
Server for VSE/ESA, and <strong>CICS</strong>/VSE ® .<br />
cicscli. A command that starts and stops the<br />
Client daemon, checks the availability of servers,<br />
and sets other options.<br />
cicsprnt. A command that allows you to define<br />
a printer terminal on the Client daemon<br />
workstation. The command enables <strong>CICS</strong><br />
applications running on the server to direct<br />
output to the client-attached printer.<br />
cicsterm. A command that provides 3270<br />
emulation and enables connection to a <strong>CICS</strong><br />
region.<br />
130 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
class. In object-oriented programming, a model<br />
or template that can be instantiated to create<br />
objects with a common definition and therefore,<br />
common properties, operations, and behavior. An<br />
object is an instance of a class.<br />
classpath. An environment variable that tells<br />
the JVM and other Java applications where to<br />
find the class libraries, including user-defined<br />
class libraries.<br />
Client API. On distributed platforms running<br />
non-Java applications, the interface between the<br />
Client application and the Client daemon.<br />
client application. A user application, written in<br />
a supported programming language other than<br />
Java, that communicates directly with the Client<br />
daemon.<br />
Client daemon. The Client daemon (process<br />
cclclnt) exists only on distributed platforms. It<br />
manages network connections to <strong>CICS</strong> servers. It<br />
processes ECI, EPI, and ESI requests, sending<br />
and receiving the appropriate flows from the<br />
<strong>CICS</strong> server to satisfy the application requests. It<br />
uses the CLIENT section of CTG.INI for its<br />
configuration.<br />
client/server. A distributed application design<br />
model, in which the client sends a request to its<br />
partner, the server, which executes the request<br />
and returns the results to the client. This design<br />
model is associated typically with cooperative<br />
processing.<br />
CNOS. See Change-Number-of-Sessions.<br />
code page. An assignment of hexadecimal<br />
identifiers (code points) to graphic characters.<br />
Within a given code page, a code point can have<br />
only one meaning.<br />
color mapping file. File <strong>CICS</strong>COL.INI used by<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> to customize the<br />
3270 screen color attributes on client<br />
workstations.<br />
COMMAREA. A communication area that is<br />
used for passing data both between programs<br />
within a transaction and between transactions.
Common Object Request Broker Architecture<br />
(CORBA). An industry standard for an interface<br />
definition language that enables different object<br />
request brokers to interoperate.<br />
configuration file. The file CTG.INI containing<br />
information telling <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong><br />
about the <strong>CICS</strong> servers that it can connect to, and<br />
the communication protocols to use.<br />
configuration tool. A graphical user interface<br />
that allows you to configure the <strong>CICS</strong><br />
<strong>Transaction</strong> <strong>Gateway</strong>.<br />
connection. In data communication, an<br />
association established between functional units<br />
for conveying information. In Open Systems<br />
Interconnection architecture, an association<br />
established by a given layer between two or<br />
more entities of the next higher layer for the<br />
purpose of data transfer. In TCP/IP, the path<br />
between two protocol application that provides<br />
reliable data stream delivery service. In Internet,<br />
a connection extends from a TCP application on<br />
one system to a TCP application on another<br />
system.<br />
control table. In <strong>CICS</strong>, a storage area used to<br />
describe or define the configuration or operation<br />
of the system.<br />
conversation. The communication between a<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> and a <strong>CICS</strong> server. In<br />
APPC, a connection between two transaction<br />
programs over an LU-LU session that allows<br />
them to communicate with each other while<br />
processing a transaction. See also session.<br />
conversation security. In APPC, a process that<br />
allows validation of a user ID or group ID and<br />
password before establishing a connection.<br />
cooperative processing. A subset of distributed<br />
processing, in which at least the user interface<br />
(presentation) aspect of the application runs on a<br />
programmable workstation.<br />
CORBA. See Common Object Request Broker<br />
Architecture.<br />
ctgstart. A command that starts the gateway<br />
daemon.<br />
D<br />
daemon. A program that runs unattended to<br />
perform continuous or periodic systemwide<br />
functions, such as network control. A daemon<br />
may be launched automatically, such as when the<br />
operating system is started, or manually.<br />
data link control (DLC). A set of rules used by<br />
nodes on a data link (such as an SDLC link or a<br />
token ring) to accomplish an orderly exchange of<br />
information.<br />
DBCS. See double-byte character set.<br />
Glossary<br />
dependent LU. A logical unit (LU) that can<br />
receive, but not send a BIND, and which<br />
supports only single sessions. See BIND.<br />
digital certificate. A form of personal<br />
identification that can be verified electronically.<br />
Only the certificate owner who holds the<br />
corresponding private key can present a<br />
certificate for authentication through a Web<br />
browser session. Anyone can verify that the<br />
certificate is valid by using a readily available<br />
public key.<br />
digital signature. Information that is encrypted<br />
with an entity’s private key and is appended to a<br />
message to assure the recipient of the<br />
authenticity and integrity of the message. The<br />
digital signature proves that the message was<br />
signed by the entity that owns, or has access to,<br />
the private key or shared secret symmetric key.<br />
distributed application. An application for<br />
which the component application programs are<br />
distributed between two or more interconnected<br />
processors.<br />
distributed processing. The processing of<br />
different parts of the same application in<br />
different systems, on one or more processors.<br />
distributed program link. A link that enables<br />
an application program running on one <strong>CICS</strong><br />
system to link to another application program<br />
running in another <strong>CICS</strong> system.<br />
Glossary 131
Glossary<br />
domain. In the Internet, a part of a naming<br />
hierarchy in which the domain name consists of<br />
a sequence of names (labels) separated by<br />
periods (dots).<br />
domain name. In TCP/IP, a name of a host<br />
system in a network.<br />
Domain Name Server. In TCP/IP, a server<br />
program that supplies name-to-address<br />
translation by mapping domain names to<br />
internet addresses. Synonymous with name<br />
server.<br />
dotted decimal notation. The syntactical<br />
representation for a 32-bit integer that consists of<br />
four 8-bit numbers written in base 10 with<br />
periods (dots) separating them. It is used to<br />
represent IP addresses.<br />
double-byte character set (DBCS). A set of<br />
characters in which each character is represented<br />
by 2 bytes. Languages such as Japanese, Chinese<br />
and Korean, which contain more symbols than<br />
can be represented by 256 code points, require<br />
double-byte character sets. Because each<br />
character requires 2 bytes, the typing, display,<br />
and printing of DBCS characters requires<br />
hardware and programs that support DBCS.<br />
Contrast with single-byte character set.<br />
DPL. See distributed program link.<br />
E<br />
EBCDIC. Extended binary-coded decimal<br />
interchange code. A coded character set of 256<br />
8-bit characters developed for the representation<br />
of textual data.<br />
ECI. See external call interface.<br />
emulator, emulation program. A program that<br />
allows a host system to communicate with a<br />
workstation in the same way as it would with<br />
the emulated terminal. In the <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong> the terminal emulation function allows<br />
client workstations to run <strong>CICS</strong> transactions that<br />
use 3270 data flows.<br />
132 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
encryption. The process of transforming data<br />
into an unintelligible form in such a way that the<br />
original data can be obtained only by using a<br />
decryption process.<br />
environment variable. A variable that specifies<br />
the operating environment for a process. For<br />
example, environment variables can describe the<br />
home directory, the command search path, the<br />
terminal in use, and the current time zone.<br />
EPI. See external presentation interface.<br />
ESI. See external security interface.<br />
Ethernet. A 10–megabit or 100–megabit<br />
baseband local area network that allows multiple<br />
stations to access the transmission medium at<br />
will without prior coordination, avoids<br />
contention by using carrier sense and deference,<br />
and resolves contention by using collision<br />
detection and transmission. Ethernet uses carrier<br />
sense multiple access with collision detection<br />
(CSMA/CD).<br />
EXCI. See <strong>CICS</strong> External Call Interface.<br />
external call interface (ECI). A facility that<br />
allows a non-<strong>CICS</strong> program to run a <strong>CICS</strong><br />
program. Data is exchanged in a COMMAREA<br />
as for normal <strong>CICS</strong> interprogram communication.<br />
external presentation interface (EPI). A facility<br />
that allows a non-<strong>CICS</strong> program to appear to<br />
<strong>CICS</strong> as one or more standard 3270 terminals.<br />
3270 data can be presented to the user by<br />
emulating a 3270 terminal or by using a<br />
graphical user interface.<br />
external security interface (ESI). A facility that<br />
enables client applications to verify and change<br />
passwords for user IDs on <strong>CICS</strong> servers.<br />
F<br />
firewall. A configuration of software that<br />
prevents unauthorized traffic between a trusted<br />
network and an untrusted network.
G<br />
gateway. A device that connects two dissimilar<br />
LANs, or that connects a LAN to a wide area<br />
network (WAN), midrange computer, or<br />
mainframe computer. A gateway device has its<br />
own processor and memory and may perform<br />
protocol conversion. A gateway handles multiple<br />
communication sessions simultaneously.<br />
gateway classes. The interface for Java Client<br />
applications to connect to the <strong>Gateway</strong> daemon.<br />
The <strong>Gateway</strong> classes, which are supplied with<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>, must be in the<br />
classpath for Java Client applications to run.<br />
gateway daemon. Used only in remote mode,<br />
the <strong>Gateway</strong> daemon listens on protocols defined<br />
in CTG.INI for gateway requests from remote<br />
Java client applications. It issues these requests to<br />
the Client daemon on distributed platforms, and<br />
directly to <strong>CICS</strong> over the EXCI on z/OS. The<br />
<strong>Gateway</strong> daemon runs the protocol listener<br />
threads, the worker threads and the connection<br />
manager threads. It uses the GATEWAY section<br />
of CTG.INI (and on z/OS the ctgenvvar script)<br />
for its configuration.<br />
H<br />
host. A computer that is connected to a network<br />
(such as the Internet or an SNA network) and<br />
provides an access point to that network. The<br />
host can be any system; it does not have to be a<br />
mainframe.<br />
host address. An IP address that is used to<br />
identify a host in an internet.<br />
host ID. In TCP/IP, that part of the Internet<br />
address that defines the host on the network. The<br />
length of the host ID depends on the type of<br />
network or network class (A, B, or C).<br />
host name. In the Internet suite of protocols, the<br />
domain name of a host.<br />
HTTP. In the Internet suite of protocols, the<br />
protocol that is used to transfer and display<br />
hypertext and XML documents.<br />
HTTPS. A TCP/IP protocol that World Wide<br />
Web servers and Web browsers use to transfer<br />
and display documents secured by SSL.<br />
I<br />
iKeyman. A tool supplied with the <strong>Gateway</strong> for<br />
maintaining digital certificates for SSLight and<br />
JSSE.<br />
independent LU. A logical unit (LU) that can<br />
both send and receive a BIND, and which<br />
supports single, parallel, and multiple sessions.<br />
See BIND.<br />
internet. A collection of networks<br />
interconnected by a set of routers that allow<br />
them to function as a single, large network.<br />
Contrast with Internet.<br />
Internet. The internet administered by the<br />
Internet Architecture Board (IAB), consisting of<br />
large national backbone networks and many<br />
regional and campus networks all over the<br />
world. The Internet uses the Internet suite of<br />
protocols.<br />
Internet address. See IP address.<br />
Glossary<br />
Internet Architecture Board. The technical body<br />
that oversees the development of the internet<br />
suite of protocols known as TCP/IP.<br />
Internet Packet Exchange (IPX). In Novell<br />
NetWare LANs, a communication protocol that<br />
sends data packets to requested destinations.<br />
Internet Protocol (IP). In TCP/IP, a protocol<br />
that routes data from its source to its destination<br />
in an Internet environment.<br />
Interoperability. The capability to communicate,<br />
execute programs, or transfer data among<br />
various functional units in a way that requires<br />
the user to have little or no knowledge of the<br />
unique characteristics of those units.<br />
intranet. A private network that integrates<br />
Internet standards and applications (such as Web<br />
browsers) with an organization’s existing<br />
Glossary 133
Glossary<br />
computer networking infrastructure. Compare<br />
with Internet and internet.<br />
IP. Internet Protocol.<br />
IPX. Internet Packet Exchange.<br />
J<br />
J2EE. (Java 2 Platform, Enterprise Edition.) An<br />
environment for developing and deploying<br />
enterprise applications, defined by Sun<br />
Microsystems Inc. The J2EE platform consists of<br />
a set of services, application programming<br />
interfaces (APIs), and protocols that allow<br />
multitiered, Web-based applications to be<br />
developed.<br />
Java. An object-oriented programming language<br />
for portable interpretive code that supports<br />
interaction among remote objects.<br />
JavaBeans. A platform-independent, software<br />
component technology for building reusable Java<br />
components called beans. Once built, these beans<br />
can be made available for use by other software<br />
engineers or they can be used in Java<br />
applications. Also, using JavaBeans, software<br />
engineers can manipulate and assemble beans in<br />
a graphical drag-and-drop development<br />
environment.<br />
Java client application. A Java application,<br />
servlet or applet that communicates with the<br />
<strong>Gateway</strong> classes.<br />
Java development kit (JDK). A software<br />
package that can be used to write, compile,<br />
debug, and run Java applets and applications.<br />
Java Native Interface (JNI). A programming<br />
interface that allows Java code running in a Java<br />
virtual machine to work with functions that are<br />
written in other programming languages.<br />
Java Secure Socket Extension (JSSE). An<br />
implementation of SSL, written in Java, and<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>.<br />
134 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
Java Virtual Machine (JVM). A software<br />
implementation of a processor that runs<br />
compiled Java code (applets and applications).<br />
JDK. See Java development kit (JDK).<br />
JNI. See Java Native Interface (JNI).<br />
JSSE. See Java Secure Socket Extension (JSSE).<br />
JVM. See Java Virtual Machine (JVM).<br />
K<br />
keyboard mapping. A list that establishes a<br />
correspondence between keys on the keyboard<br />
and characters displayed on a display screen, or<br />
action taken by a program, when that key is<br />
pressed. The default keyboard mapping file for<br />
the <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> is <strong>CICS</strong>KEY.INI.<br />
KeyRing or KeyStore. In computer security, a<br />
file that contains public keys, private keys,<br />
trusted roots, and certificates.<br />
L<br />
LAN. See local area network.<br />
local area network (LAN). A network of<br />
workstations, or terminals, or both, where all the<br />
connected systems are relatively near to each<br />
other. See wide area network.<br />
local mode. Describes a Java Client application<br />
using the <strong>Gateway</strong> local protocol. The <strong>Gateway</strong><br />
daemon is not used in local mode; on distributed<br />
platforms, the <strong>Gateway</strong> classes interface directly<br />
with the Client daemon API, and with the EXCI<br />
on z/OS. See remote mode.<br />
logical unit (LU). In SNA, a port through which<br />
an end user accesses the SNA network in order<br />
to communicate with another end user and<br />
through which the end user accesses the<br />
functions provided by system services control<br />
points (SSCP). An LU can support at least two<br />
sessions, one with an SSCP and one with another<br />
LU, and may be capable of supporting many
sessions with other logical units. See network<br />
addressable unit, primary logical unit, secondary<br />
logical unit.<br />
LU-LU session. In SNA, a session between two<br />
logical units (LUs) in an SNA network. It<br />
provides communication between two end users,<br />
or between an end user and an LU services<br />
component.<br />
LU-LU session type 6.2. In SNA, a type of<br />
session for communication between peer<br />
systems. Synonymous with APPC protocol.<br />
LU 6.2. See APPC.<br />
M<br />
MAC. Medium access control.<br />
medium access control (MAC) sublayer. One of<br />
two sublayers of the ISO Open Systems<br />
Interconnection data link layer proposed for local<br />
area networks by the IEEE Project 802 Committee<br />
on Local Area Networks and the European<br />
Computer Manufacturers Association (ECMA). It<br />
provides functions that depend on the topology<br />
of the network and uses services of the physical<br />
layer to provide services to the logical link<br />
control (LLC) sublayer. The OSI data link layer<br />
corresponds to the SNA data link control layer.<br />
method. In object-oriented programming, an<br />
operation that an object can perform. An object<br />
can have many methods.<br />
mode. In SNA, a set of parameters that defines<br />
the characteristics of a session between two LUs.<br />
N<br />
name server. In TCP/IP, synonym for Domain<br />
Name Server In Internet communications, the<br />
host that translates host names into their<br />
respective internet addresses when requested by<br />
the hosts on the network A physical device, and<br />
its associated software, that enables a processor<br />
or controller to be connected to a network.<br />
network address. In SNA, an address,<br />
consisting of subarea and element fields, that<br />
identifies a link, link station, or network<br />
addressable unit (NAU). Subarea nodes use<br />
network addresses; peripheral nodes use local<br />
addresses. The boundary function in the subarea<br />
node to which a peripheral node is attached<br />
transforms local addresses to network addresses<br />
and vice versa. See also network name.<br />
network addressable unit (NAU). In SNA, a<br />
logical unit, a physical unit, or a system services<br />
control point. The NAU is the origin or the<br />
destination of information transmitted by the<br />
path control network. See also logical unit,<br />
network address, network name.<br />
network name. In SNA, the symbolic identifier<br />
by which end users refer to a network<br />
addressable unit (NAU), link station, or link. See<br />
also network address.<br />
node type. In SNA, a designation of a node<br />
according to the protocols it supports and the<br />
network addressable units (NAUs) it can contain.<br />
Four types are defined: 1, 2, 4, and 5. Type 1 and<br />
type 2 nodes are peripheral nodes; type 4 and<br />
type 5 nodes are subarea nodes.<br />
O<br />
object. In object-oriented programming, a<br />
concrete realization of a class that consists of<br />
data and the operations associated with that<br />
data.<br />
object request broker (ORB). Software that<br />
serves as an intermediary by transparently<br />
enabling objects to exchange requests and<br />
responses.<br />
OO. Object-oriented.<br />
P<br />
Glossary<br />
pacing. A technique by which a receiving<br />
station controls the rate of transmission of a<br />
sending station to prevent overrun.<br />
packet internet groper (PING). In Internet<br />
communications, a program used in TCP/IP<br />
networks to test the ability to reach destinations<br />
Glossary 135
Glossary<br />
by sending the destinations an Internet Control<br />
Message Protocol (ICMP) echo request and<br />
waiting for a reply.<br />
parallel session. In SNA, two or more<br />
concurrently active sessions between the same<br />
two LUs using different pairs of network<br />
addresses. Each session can have independent<br />
session parameters.<br />
PING. Packet internet groper. The command<br />
that sends an ICMP Echo Request packet to a<br />
gateway, router, or host with the expectation of<br />
receiving a reply.<br />
partner logical unit (PLU). In SNA, the remote<br />
participant in a session.<br />
partner transaction program. The transaction<br />
program engaged in an APPC conversation with<br />
a local transaction program.<br />
PLU. Primary logical unit. Partner logical unit.<br />
port. An endpoint for communication between<br />
devices, generally referring to a logical<br />
connection. A 16-bit number identifying a<br />
particular Transmission Control Protocol (TCP)<br />
or User Datagram Protocol (UDP) resource<br />
within a given TCP/IP node.<br />
presentation logic. The part of a distributed<br />
application that is concerned with the user<br />
interface of the application. Compare with<br />
business logic.<br />
primary logical unit (PLU). In SNA, the logical<br />
unit (LU) that contains the primary half-session<br />
for a particular LU-LU session. Contrast with<br />
secondary logical unit. See also logical unit.<br />
Note: A particular logical unit may contain<br />
primary and secondary half-sessions for<br />
different active LU-LU sessions.<br />
protocol boundary. The signals and rules<br />
governing interactions between two components<br />
within a node.<br />
136 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
R<br />
RACF ® . Resource Access Control Facility. An<br />
IBM licensed program that provides access<br />
control by identifying users to the system;<br />
verifying users of the system; authorizing access<br />
to protected resources; logging detected,<br />
unauthorized attempts to enter the system; and<br />
logging detected accesses to protected resources.<br />
region. A physical instance of a <strong>CICS</strong> server.<br />
remote mode. Describes a Java Client<br />
application using a <strong>Gateway</strong> network protocol to<br />
connect to the <strong>Gateway</strong> daemon. See local mode.<br />
remote procedure call (RPC). Remote procedure<br />
calls are analogous to the standard procedure<br />
calls used in modern programming, providing<br />
modularity and reducing code size. The main<br />
difference between standard procedure calls and<br />
remote procedure calls is that in a remote<br />
procedure call, the called procedure is being<br />
executed by a different process than the caller. To<br />
the calling procedure, a remote procedure call<br />
looks the same as a call to a local procedure.<br />
When a program makes a remote procedure call<br />
to a remote application, the procedure’s<br />
parameters are automatically bundled into a<br />
request message, which is then sent to the<br />
remote program or system.<br />
request unit (RU). In SNA, a message unit that<br />
contains control information such as a request<br />
code, or function management (FM) headers,<br />
end-user data, or both.<br />
request/response unit. A generic term for a<br />
request unit or a response unit. See also request<br />
unit and response unit.<br />
response file. A file that contains a set of<br />
predefined answers to questions asked by a<br />
program and that is used in place of a user<br />
dialog. See CID methodology.<br />
response unit (RU). A message unit that<br />
acknowledges a request unit; it may contain<br />
prefix information received in a request unit.<br />
RU. Request unit. Response unit.
RPC. See remote procedure call.<br />
S<br />
SBCS. See single-byte character set.<br />
secondary logical unit (SLU). In SNA, the<br />
logical unit (LU) that contains the secondary<br />
half-session for a particular LU-LU session.<br />
Contrast with primary logical unit. See also<br />
logical unit.<br />
Secure Sockets Layer (SSL). A security protocol<br />
that provides communication privacy. SSL<br />
enables client/server applications to<br />
communicate in a way that is designed to<br />
prevent eavesdropping, tampering, and message<br />
forgery.<br />
servlet. A Java servlets program that run on a<br />
Web server machine, unlike Java applets, which<br />
are downloaded to a Web browser. Java servlets<br />
have become popular as a replacement for CGI<br />
(Common <strong>Gateway</strong> Interface) programs.<br />
session. In SNA, a logical connection between<br />
two network addressable units (NAUs) that can<br />
be activated, tailored to provide various<br />
protocols, and deactivated as requested. The<br />
session activation request and response can<br />
determine options for such things as rate and<br />
concurrency of data exchange, control of<br />
contention and error recovery, and characteristics<br />
of the data stream. Sessions compete for network<br />
resources, such as links within the path control<br />
network. For routing purposes, each session is<br />
identified by the network or local addresses of<br />
the session partners. See LU-LU session, LU-LU<br />
session type.<br />
session limit. In SNA, the maximum number of<br />
concurrently active LU-LU sessions that a<br />
particular logical unit (LU) can support.<br />
single-byte character set (SBCS). A character<br />
set in which each character is represented by 1<br />
byte. Contrast with double-byte character set.<br />
signon capable terminal. A signon capable<br />
terminal allows signon transactions, either<br />
<strong>CICS</strong>-supplied (CESN) or user-written, to be run.<br />
Contrast with signon incapable terminal.<br />
SIT (system initialization table). A table<br />
containing parameters used to start a <strong>CICS</strong><br />
control region.<br />
SNA gateway. A gateway that handles multiple<br />
APPC communication sessions simultaneously.<br />
See gateway.<br />
SNA sense data. An SNA-defined encoding of<br />
error information In SNA, the data sent with a<br />
negative response, indicating the reason for the<br />
response.<br />
SNASVCMG mode name. The SNA service<br />
manager mode name. This is the<br />
architecturally-defined mode name identifying<br />
sessions on which CNOS is exchanged. Most<br />
APPC-providing products predefine SNASVCMG<br />
sessions.<br />
SSL. See Secure Sockets Layer (SSL).<br />
Glossary<br />
SSLight. An implementation of SSL, written in<br />
Java, and supported by <strong>CICS</strong> <strong>Transaction</strong><br />
<strong>Gateway</strong>.<br />
System Management Interface Tool (SMIT). In<br />
the AIX operating system, a set of menu-driven<br />
services that facilitate the performance of system<br />
tasks such as installation, management,<br />
configuration, and diagnosis.<br />
standard error. In many workstation-based<br />
operating systems, the output stream to which<br />
error messages or diagnostic messages are sent.<br />
subnet. In TCP/IP, a part of a network that is<br />
identified by a portion of the Internet address.<br />
Synonym for subnetwork.<br />
subnet address. In Internet communications, an<br />
extension to the basic IP addressing scheme<br />
where a portion of the host address is interpreted<br />
as the local network address.<br />
Systems Network Architecture (SNA). The<br />
description of the logical structure, formats,<br />
protocols, and operational sequences for<br />
Glossary 137
Glossary<br />
transmitting information units through, and<br />
controlling the configuration and operation of,<br />
networks.<br />
System SSL. An implementation of SSL,<br />
supported by <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> on<br />
z/OS. Written in native code, it supports<br />
hardware encryption technology available to<br />
z/OS, and can be used only for SSL servers on<br />
that operating system.<br />
T<br />
Taskguide. A function of the configuration tool<br />
that provides step-by-step guidance to<br />
configuring your <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>. .<br />
TCP62. SNA logical unit type 62 (LU62)<br />
protocol encapsulated in TCP/IP. This allows<br />
APPC applications to communicate over a<br />
TCP/IP Network without changes to the<br />
applications.<br />
TCP/IP. Transmission Control Protocol/Internet<br />
Protocol.<br />
TCP/IP address. An address that uniquely<br />
identifies a machine on a network. A machine<br />
can have several threads of execution running at<br />
the same time; a TCP/IP port uniquely identifies<br />
a particular thread.<br />
terminal emulation. The capability of a<br />
microcomputer or personal computer to operate<br />
as if it were a particular type of terminal linked<br />
to a processing unit and to access data. See also<br />
emulator, emulation program.<br />
Terminal Servlet. A Java program that allows<br />
you to use a Web browser as an emulator for a<br />
3270 <strong>CICS</strong> application running on any <strong>CICS</strong><br />
server.<br />
thread. A stream of computer instructions that<br />
is in control of a process. A multithread process<br />
begins with one stream of instructions (one<br />
thread) and may later create other instruction<br />
streams to perform tasks.<br />
138 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages<br />
token ring. A network with a ring topology that<br />
passes tokens from one attaching device to<br />
another; for example, the IBM Token-Ring<br />
network.<br />
trace. A record of data that provides a history of<br />
events that occurred in a system. The process of<br />
recording the sequence in which the statements<br />
in a program are executed and, optionally, are<br />
the values of the program variables used in the<br />
statements.<br />
transaction program. A program that uses the<br />
APPC application program interface (API) to<br />
communicate with a partner application program<br />
in the same node or at a partner node.<br />
Transmission Control Protocol/Internet Protocol<br />
(TCP/IP). A set of communications protocols<br />
that support peer-to-peer connectivity functions<br />
for both local and wide area networks. TCP/IP<br />
can be used for client/server links between the<br />
Client daemon and, for example, <strong>CICS</strong> for<br />
OS/2 ® , <strong>CICS</strong> for Windows NT.<br />
type 2.0 node. An SNA node that attaches to a<br />
subarea network as a peripheral node and<br />
provides full end-user services but no<br />
intermediate routing services.<br />
type 2.1 node. An SNA node that can be<br />
configured as an endpoint or intermediate<br />
routing node in a network, or as a peripheral<br />
node attached to a subarea network.<br />
U<br />
URL. (Uniform Resource Locator.) A sequence<br />
of characters that represent information resources<br />
on a computer or in a network such as the<br />
Internet. This sequence of characters includes (a)<br />
the abbreviated name of the protocol used to<br />
access the information resource and (b) the<br />
information used by the protocol to locate the<br />
information resource.<br />
user session. Any APPC session other than a<br />
SNASVCMG session.
V<br />
verb. A reserved word that expresses an action<br />
to be taken by an application programming<br />
interface (API), a compiler, or an object program.<br />
In SNA, the general name for a transaction<br />
program’s request for communication services.<br />
W<br />
Web browser. A software program that sends<br />
requests to a Web server and displays the<br />
information that the server returns.<br />
Web server. A software program that responds<br />
to information requests generated by Web<br />
browsers.<br />
wide area network (WAN). A network that<br />
provides communication services to a geographic<br />
area larger than that served by a local area<br />
network or a metropolitan area network, and<br />
that may use or provide public communication<br />
facilities.<br />
Glossary<br />
Glossary 139
Glossary<br />
140 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Index<br />
A<br />
accessibility 127<br />
B<br />
books 123<br />
<strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 123<br />
D<br />
disability 127<br />
documentation 123<br />
G<br />
glossary of terms and abbreviations 129<br />
P<br />
publications, <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> 123<br />
© Copyright IBM Corp. 1994, 2002 141
142 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Notices<br />
This information was developed for products and services offered in the<br />
U.S.A. IBM may not offer the products, services, or features discussed in this<br />
document in other countries. Consult your local IBM representative for<br />
information on the products and services currently available in your area. Any<br />
reference to an IBM product, program, or service is not intended to state or<br />
imply that only that IBM product, program, or service may be used. Any<br />
functionally equivalent product, program, or service that does not infringe<br />
any IBM intellectual property right may be used instead. However, it is the<br />
user’s responsibility to evaluate and verify the operation of any non-IBM<br />
product, program, or service.<br />
IBM may have patents or pending patent applications covering subject matter<br />
described in this document. The furnishing of this document does not give<br />
you any license to these patents. You can send license inquiries, in writing, to:<br />
IBM Director of Licensing<br />
IBM Corporation<br />
North Castle Drive<br />
Armonk, NY 10504-1785<br />
U.S.A.<br />
For license inquiries regarding double-byte (DBCS) information, contact the<br />
IBM Intellectual Property Department in your country or send inquiries, in<br />
writing, to:<br />
IBM World Trade Asia Corporation<br />
Licensing<br />
2-31 Roppongi 3-chome, Minato-ku<br />
Tokyo 106, Japan<br />
The following paragraph does not apply in the United Kingdom or any<br />
other country where such provisions are inconsistent with local law:<br />
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS<br />
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER<br />
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,<br />
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow<br />
disclaimer of express or implied warranties in certain transactions, therefore<br />
this statement may not apply to you.<br />
© Copyright IBM Corp. 1994, 2002 143
Trademarks<br />
This information could include technical inaccuracies or typographical errors.<br />
Changes are periodically made to the information herein; these changes will<br />
be incorporated in new editions of the information. IBM may make<br />
improvements and/or changes in the product(s) and/or the program(s)<br />
described in this information at any time without notice.<br />
Any references in this information to non-IBM Web sites are provided for<br />
convenience only and do not in any manner serve as an endorsement of those<br />
Web sites. The materials at those Web sites are not part of the materials for<br />
this IBM product and use of those Web sites is at your own risk.<br />
Licensees of this program who wish to have information about it for the<br />
purpose of enabling: (i) the exchange of information between independently<br />
created programs and other programs (including this one) and (ii) the mutual<br />
use of the information which has been exchanged, should contact IBM United<br />
Kingdom Laboratories, MP151, Hursley Park, Winchester, Hampshire,<br />
England, SO21 2JN. Such information may be available, subject to appropriate<br />
terms and conditions, including in some cases, payment of a fee.<br />
The licensed program described in this information and all licensed material<br />
available for it are provided by IBM under terms of the IBM Customer<br />
Agreement, IBM International Programming License Agreement, or any<br />
equivalent agreement between us.<br />
Information concerning non-IBM products was obtained from the suppliers of<br />
those products, their published announcements or other publicly available<br />
sources. IBM has not tested those products and cannot confirm the accuracy<br />
of performance, compatibility or any other claims related to non-IBM<br />
products. Questions on the capabilities of non-IBM products should be<br />
addressed to the suppliers of those products.<br />
The following terms are trademarks of International Business Machines<br />
Corporation in the United States, or other countries, or both:<br />
<strong>CICS</strong> IBM<br />
Java and all Java-based trademarks and logos are trademarks of Sun<br />
Microsystems, Inc. in the United States, or other countries, or both.<br />
Other company, product or service names may be trademarks or service<br />
marks of others.<br />
144 <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong>: <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages
Sending your comments to IBM<br />
If you especially like or dislike anything about this book, use one of the<br />
methods listed below to send your comments to IBM.<br />
Feel free to comment on what you regard as specific errors or omissions, and<br />
on the accuracy, organization, subject matter, or completeness of this book.<br />
Limit your comments to the information in this book and the way in which<br />
the information is presented.<br />
To ask questions, make comments about the functions of IBM products or<br />
systems, or to request additional publications, contact your IBM representative<br />
or your IBM authorized remarketer.<br />
When you send comments to IBM, you grant IBM a nonexclusive right to use<br />
or distribute your comments in any way it believes appropriate, without<br />
incurring any obligation to you.<br />
You can send your comments to IBM in any of the following ways:<br />
v By mail, to this address:<br />
User Technologies Department (MP095)<br />
IBM United Kingdom Laboratories<br />
Hursley Park<br />
WINCHESTER,<br />
Hampshire<br />
SO21 2JN<br />
United Kingdom<br />
v By fax:<br />
– +44 1962 842327 (if you are outside the UK)<br />
– 01962 842327 (if you are in the UK)<br />
v Electronically, use the appropriate network ID:<br />
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL<br />
– IBMLink <br />
: HURSLEY(IDRCF)<br />
– Internet: idrcf@hursley.ibm.com<br />
Whichever you use, ensure that you include:<br />
v The publication title and order number<br />
v The topic to which your comment applies<br />
v Your name and address/telephone number/fax number/network ID.<br />
© Copyright IBM Corp. 1994, 2002 145
����<br />
Program Number: 5724-D12<br />
Printed in U.S.A.<br />
SC34-6193-00
Spine information:<br />
��� <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> <strong>CICS</strong> <strong>Transaction</strong> <strong>Gateway</strong> Messages <strong>Version</strong> <strong>5.0</strong>