UNIX And Linux Administration

Performance considerations for heavy IPICworkloads . . . . . . . . . . . . .Performance considerations with large containersTracing and performance . . . . . . . .Performance monitoring tools . . . . . . .Statistics and performance assessment . . . .Investigating poor response times . . . .Avoiding out of memory conditions . . . . . 182182. 183. 183. 184. 184. 187Chapter 9. High availability . . . . . 189CICS request exit . 189Chapter 10. Operating. . . . . . . . 191Starting CICS Transaction Gateway . . . . . .Stopping CICS Transaction Gateway. . . . . .Changing the system time . . . . . . . . .Operating the Gateway daemon . . . . . . .Starting and stopping the Gateway daemon . .Running the Gateway daemon as a backgroundprocess . . . . . . . . . . . . . .Gateway daemon administration . . . . . .ctgadmin command reference . . . . . . .Operating the Client daemon . . . . . . . .Administering the Client daemon . . . . .cicscli command reference . . . . . . . .191191192193193196197203204204210Chapter 11. 3270 terminal emulationand printing . . . . . . . . . . . . 213 cicsterm emulator . . . . . . . . . . .Using cicsterm . . . . . . . . . . .cicsterm options . . . . . . . . . .Stopping a terminal emulator . . . . . .cicsterm and user exits . . . . . . . .cicsterm and RETURN TRANSID IMMEDIATEUsing clients for X-Window System . . . .Keyboard mapping in cicsterm . . . . .cicsterm restrictions . . . . . . . . .cicsterm command reference . . . . . . .cicsprnt emulator . . . . . . . . . . .Using cicsprnt . . . . . . . . . . .cicsprnt options . . . . . . . . . .cicsprnt and user exits . . . . . . . .cicsprnt and RETURN TRANSID IMMEDIATEcicsprnt restrictions . . . . . . . . .cicsprnt command reference . . . . . . 22Chapter 12. Resolving problems . . . 225Introduction to problem determination .Preliminary checks . . . . . . .What to do next . . . . . . . .Problem determination tools . . . .Java debug tools . . . . . . .JVM dump and system dump . . .VTAM buffer trace . . . . . .APING utility . . . . . . . .TCP/IP diagnostic commands . . .Dealing with problems . . . . . .Installation problems . . . . . .Startup and shutdown problems . .Configuration problems . . . . .225225227227227227228228228229229230233CICS connection problems . . . . . .Security problems . . . . . . . . .Memory problems . . . . . . . . .Performance problems . . . . . . .Resource problems . . . . . . . .Java problems . . . . . . . . . .General information about messages . . .Telnet clients . . . . . . . . . .SNA error log . . . . . . . . . .Tracing . . . . . . . . . . . . .Gateway daemon tracing . . . . . .Client daemon tracing . . . . . . .JNI tracing . . . . . . . . . . .Tracing Java Client applications . . . .JEE Tracing . . . . . . . . . . .Tracing issues when serializing ConnectionFactories . . . . . . . . . . . .Problem solving and support . . . . . .Searching knowledge bases . . . . . .Contacting IBM Software Support . . 254255255.Chapter 13. Monitoring and statisticsRequest monitoring exits . . . . . .Request monitoring exits configuration .Statistics . . . . . . . . . . . .Statistics configuration . . . . . .Displaying statistics . . . . . . .Statistics resource groups . . . . .Using the statistics . . . . . . .CICS TG plug-in for CICS Explorer . . .257257258259261265267279283Appendix. Data conversion . . . . . 285Supported conversionsArabic . . . . .Baltic Rim . . .Cyrillic . . . .Estonian . . . .Greek . . . . .Hebrew . . . .Japanese . . . .Korean . . . .Latin-1 and Latin-9Latin-2 . . . .Latin-5 . . . .Simplified ChineseTraditional ChineseVietnamese . . .Unicode data . .Product library and related literatureCICS Transaction Gateway books . . .Sample configuration documents . . .IBM Redbooks publications. . . . .Other useful information . . . . .CICS Transaction Server publicationsAPPC-related publications . . . 95295295296296296297Accessibility . . . . . . . . . . . . 299Installation . . . . . . . .Configuration Tool accessibility . 299. 299Contentsv

Components. . . . . .Keys . . . . . . . .Customizing colors and fontsStarting the Gateway daemon .cicsterm . . . . . . . .300300302302303Index . . . . . . . . . . . . . . . 327Notices . . . . . . . . . . . . . . 333Trademarks .Glossary . . . . . . . . . . . . . 305viCICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration. 334

About this informationThis information describes the planning, installation, configuration, and operationof the IBM CICS Transaction Gateway and the IBM CICS Transaction GatewayDesktop Edition products.You should be familiar with the operating system on which CICS TransactionGateway runs and also with Internet terminology.This information is organized as shown in the following table:TopicContents“What's new in CICS TransactionGateway V8.1” on page ixFunctional changes made in this version of the product./common/ctg int.ditaOverview of the product and the functions it provides.Chapter 2, “Planning,” on page 9Planning your installation, including the hardware and software you need torun the product.Chapter 3, “Installing,” on page21How to install the product.“Configuring CICS serverconnections” on page 48How to set up communication between CICS Transaction Gateway and CICS.How to configure the product.Chapter 7, “Security,” on page157How to set up the product to use the SSL network security protocol.“Client security overview” onpage 166How to provide a user ID and password when connecting to a CICS server.Chapter 8, “Performance,” onpage 173How to tune the product, and other system components, to achieve the bestpossible performance.“Operating the Gateway daemon” How to operate the product.on page 193Chapter 10, “Operating,” on page191How to operate the Gateway daemon.“Operating the Client daemon”on page 204How to operate the Client daemon.Chapter 11, “3270 terminalemulation and printing,” on page213How to use the cicsterm and cicsprnt programs.Chapter 12, “Resolvingproblems,” on page 225How to perform problem determination and problem solving.Chapter 4, “Upgrading,” on page27How to upgrade from an earlier version of the product.Chapter 13, “Monitoring andstatistics,” on page 257How to use the statistics and request monitoring exits provided by the product. Copyright IBM Corp. 1998, 2011vii

viiiCICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration

What's new in CICS Transaction Gateway V8.1CICS Transaction Gateway includes enhancements in the areas of open integration,security and high availability.Open integrationv Interoperability with 32-bit or 64-bit compilers and runtime environments isprovided on Microsoft Windows using a pure .NET DLL. For more informationsee Programming using the .NET Framework.v On Microsoft Windows, the .NET API is extended to provide CICS channels andcontainers support. For more information see Using channels and containers in.NET programs.v The JCA 1.6 architecture is supported, enabling the use of JEE 6 certifiedapplications servers, such as WebSphere Application Server V8. For moreinformation see Supported JEE application servers.v AIX V7 and Red Hat Enterprise Linux (RHEL) V6 platforms are nowsupported, along with CICS Transaction Server V4.2.v An enhanced CICS Transaction Gateway plug-in is provided for the CICSExplorer which supports user-defined connection groups, connection importand export capability, and column sorting. For more information see the CICSTransaction Server V4.2 Information Center at: pts/Explorer.html.Securityv Security is enhanced through the use of password phrases with ECI and ESIrequests over IPIC connections to CICS TS V4.2. For more information see IPICconnection security.v Password management is now available from .NET applications and remote Capplications using the ESI API. For more information see Making ESI calls from.NET programs and Making ESI V2 calls in remote mode.High availabilityv Dynamic server selection is available through a user exit in the Gatewaydaemon. The exit typically decides which CICS server to select based on theCICS server name, user ID, and transaction ID that accompany the request. Formore information see High availability.Additional featuresv Transaction tracking is supported for ECI V2 and .NET client applicationsthrough their APPLID and APPLID qualifier. For more information seeMonitoring and statistics.v Origin data is available for remote Java client applications. For more informationsee Monitoring and statistics.User informationv Message help is provided for the CICS Transaction Gateway administrationprogram ctgadmin. For more information see Viewing message help. Copyright IBM Corp. 1998, 2011ix

v Reference tables “Which API can be used?” on page 17 and “Which protocol canbe used?” on page 16 are included in the CICS Transaction Gateway informationcenter.v An improved message search capability is included in the CICS TransactionGateway information center.Removed and changed functionv The named pipe protocol for Windows is no longer supported. For moreinformation see Upgrading from Version 8 Release 0.v The JAR file cicsj2ee.jar file has been renamed to cicsjee.jar.v The CICS Transaction Gateway .NET API has been upgraded. For moreinformation see CICS Transaction Gateway .NET applications.v The logical server has been deprecated and is superseded by policy-baseddynamic server selection. For more information see Logical CICS server definitions.xCICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration

Chapter 1. OverviewCICS Transaction Gateway for MultiplatformsCICS Transaction Gateway for Multiplatforms is a high-performing, secure, andscalable connector that enables client applications in different runtimeenvironments to access CICS servers.Using standards-based interfaces, CICS Transaction Gateway delivers access to newand existing CICS applications. CICS Transaction Gateway also provides flexibledeployment options for different architectures. An example is shown in Figure 1.Figure 1. Access to CICS using CICS Transaction Gateway for MultiplatformsOn all operating platforms, CICS Transaction Gateway provides a gateway to CICSfor remote clients, and complements IBM WebSphere Application Server on arange of different platforms. CICS Transaction Gateway for Multiplatforms alsoprovides these features and benefits:v A simple programming model requiring minimal change to CICS programsv Access to CICS COMMAREA, channel and 3270 applicationsv A rich set of client application programming interfaces (APIs) for differentruntime environmentsvvvvvSupport for standard network protocolsSupport for different operating platformsManaged qualities of service and, on z/OS , high availabilityAccess to statistics and request monitoring informationSupport for two-phase commit transactions from a JEE application server Copyright IBM Corp. 1998, 20111

CICS Transaction Gateway Desktop EditionCICS Transaction Gateway Desktop Edition provides single user desktopconnectivity to CICS applications from a wide variety of client environments.Figure 2. Access to CICS using CICS Transaction Gateway Desktop EditionClient applications can be written in Java, .NET, C, C , COM, or COBOL, andcommunicate with CICS Transaction Gateway Desktop Edition using either thelocal TCP/IP stack or interprocess communication. CICS Transaction GatewayDesktop Edition offers these features and benefits:v A simple programming model requiring minimal change to CICS programsv Access to CICS COMMAREA, channel and 3270 applicationsv A rich set of client application programming interfaces (APIs) for differentruntime environmentsv Support for standard network protocolsv Support for different operating platformsv Access to statistics and request monitoring informationCICS Transaction Gateway Desktop Edition does not include Java ConnectorArchitecture (JCA) resource adapter support, and some parameters haverestrictions. For more information about the parameter restrictions see:v “Maximum requests” on page 85v “Maximum number of worker threads” on page 71v “Maximum number of connection manager threads” on page 70v “IPIC send sessions” on page 532CICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration

Related information:Chapter 2, “Planning,” on page 9When planning a CICS Transaction Gateway installation, you must ensure that therequisite system hardware is available for running the product. You must alsocheck that you have the correct software (for example, the correct operatingsystem, web browser, CICS system and JEE application server). Finally, you mustensure that you use the correct communications protocols and interfaces forconnecting to CICS on the platform on which CICS has been installed.Application programming interfaces (APIs)The application programming interfaces provide access to CICS COMMAREAprograms, CICS channels and containers programs, and 3270 programs. APIs areincluded for the Java, C, C , and COBOL programming languages. JCA resourceadapters, are also included.External Call Interface (ECI)The ECI enables client applications to send requests to CICS COMMAREA andchannel programs.The ECI is available in all supported runtime environments. ECI is the mostcommonly used mechanism for providing client access to CICS. An ECI requestresults in a CICS distributed program link (DPL) call to the target program andmust follow the CICS rules of the DPL subset.JEE applications using the ECI resource adapter can access CICS resources as partof a two-phase commit transaction.External Presentation Interface (EPI)The EPI enables client applications to access CICS 3270-based programs. Clientapplications can install and delete virtual 3270 terminals in CICS through thisinterface. The EPI can be used in all supported runtime environments.Basic mapping support (BMS) and non-BMS based terminal transactions aresupported. Automatic transaction initiation (ATI) is supported.External Security Interface (ESI)The ESI enables client applications to call CICS password expiry management(PEM) functions. Client applications can access information about user IDs that areheld in the CICS External Security Manager (ESM) through this interface.Statistics APIThe statistics API enables applications to obtain dynamic, real-time statisticalinformation about the runtime performance of CICS Transaction Gateway.Applications can be written in C or Java.Sample applications written in the supported programming languages areprovided for all programming interfaces. For more information about workingwith the APIs, see the CICS Transaction Gateway: Application Programming Guide.Chapter 1. Overview3

Programming GuideProgramming information for CICS Transaction Gateway including information onAPIs, ancillary functions, user applications, and supported programminglanguages.ProgrammingDeployment topologiesCICS Transaction Gateway can be deployed in a local mode (two-tier) topology ora remote mode (three-tier) topology. Each topology provides different qualities ofservice.Connectivity options to CICSThere is a choice of network protocols for connecting to CICS.All protocols support ECI COMMAREA requests.IPICThis protocol is required for ECI channel requests and supports ESIrequests. The protocol also supports two-phase commit transactions inlocal mode. SSL can be configured on IPIC connections in a local modeconfiguration.SNAThis protocol is required for sending EPI to CICS TS servers and supportsESI requests.TCP/IPThis protocol is required for sending EPI requests to TXSeries servers.Related information:“Configuring CICS server connections” on page 48After you have installed the CICS Transaction Gateway and set up your CICSservers for communication, your next step is to set up the communication linksbetween the CICS Transaction Gateway and your CICS servers.“Which protocol can be used?” on page 16This table shows what support is available for connecting to different version CICSservers over IPIC, TCP/IP and SNA.Remote modeThe client application and CICS Transaction Gateway are on different machinesand the Gateway daemon listens on a specific port for incoming client requests.The Gateway daemon runs as a standalone process, handles the management ofconnections and threads, and forwards client requests to CICS.In a remote mode configuration, the CICS Transaction Gateway runs a processknown as a Gateway daemon which receives requests from client applications andforwards those requests to CICS servers. Client applications send requests to aGateway daemon using either TCP/IP or SSL.4CICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration

Figure 3. An example of CICS Transaction Gateway for Multiplatforms in remote modeFeatures of remote modeRemote mode is best suited to large-scale systems and has the following features:v A common point of access to CICS for different applications and operatingsystemsv A common point of configuration and administration for connections to CICSv A lightweight client footprintv Access to statistical informationv Support for 64-bit JEE application serversv Supports the use of applets to connect to a Gateway daemonLocal modeIn a local mode configuration, the CICS Transaction Gateway runs within the clientapplication. Client applications send requests directly to CICS without using aGateway daemon.Figure 4. An example of CICS Transaction Gateway for Multiplatforms in local modeChapter 1. Overview5

Features of local modeLocal mode is best suited to environments where a small number of JEEapplication servers are connected to CICS, and has the following features:v Fewer components to manage than in remote modev Network topology is simplifiedHigh availabilityHigh availability ensures that a single point of failure does not cause failure of thetotal solution. High availability also allows increased capacity to be provided bythe addition of more components.A high availability scenario can be implemented using dynamic server selectionfrom within a user exit program.SecurityCICS Transaction Gateway provides a secure way of connecting to CICS usingstandard security mechanisms. These mechanisms integrate with security providedby the JEE application server and with security provided by CICS.Network securityNetwork security is the ability to provide authentication and encryption over anetwork connection using these security technologies:v Secure Sockets Layer (SSL) or Transport Layer Security (TLS) from a Java clientapplication to CICS Transaction Gatewayv SSL or TLS from a Java client application to a CICS server using IPICv Security exitsUnderlying security technologies such as Internet Protocol Security (IPSec) are alsosupported.User authenticationUser authentication is the process by which a service verifies a user's authenticity.Verification is through the use of credentials, usually a password or a certificate.User auth

UNIX and Linux Administration SC34-7216-00. CICS Transaction Gateway Version 8 Release 1 UNIX and Linux Administration . Other system factors .180 iv CICS Transaction Gateway for Multiplatforms V8.1: UNIX and Linux Administration. Performance considerations for heavy IPIC