Intelidata Technologies

InteliData Technologies

Interpose Transaction Engine V. 4.1

IP Socket Gateway Guide

Software Version4.1

Document Revision1.0

Document NumberIP41-SK.102.1

InteliData Technologies Corporation

April 2001

Printed in U.S.A.

Interpose is a trademark of InteliData Technologies Corporation.

Whenever such names, or registered trademarks and trademarks of companies other than InteliData Technologies Corporation appear in this document, such names shall be deemed to refer to the corresponding registered trademarks or trademarks.

Comments regarding this publication, or any matter related to the Interpose Transaction Engine IP Socket Gateway manual should be directed to:

InteliData Technologies Corporation
1946 N. 13Street
Suite 392
Toledo, OH 43624

Software Version:4.1

Document Revision:1.0

Document NumberIP41-SK.102.1

Contents

1INTRODUCTION

1.1Requirements......

2The IP Socket Gateway......

2.1.1System Architecture......

2.2Comparison of the APPC Gateway and the IP Socket Gateway......

2.2.1Gateway Comparisons......

2.3How the IP Socket Gateway Operates......

3INSTALLATION OF THE IP SOCKET GATEWAY

3.1Pre-installation Requirements......

3.2Installation Procedures For CICS TCP/IP Socket Interfaces......

3.2.1Step 1: TCP/IP Software......

3.2.2Step 2: Define SEZATCP library......

3.2.3Step 3: CICS Startup Configuration......

3.2.4Step 4: Define CICS Resources......

3.2.5Step 5: Create VSAM Files......

3.2.6Step 6: Define the OMVS Segment......

3.3Method for Linking Programs Using the Socket Interface......

3.4Getting the Source To the Mainframe......

4Compiling, Linking, and Assembling the System......

4.1The Compilation Process......

4.1.1STEP 1 – STEP1IP – Assembling the Listener Program......

4.1.2STEP 2 – STEP2IP – Compiling the Message Adapter......

4.2Preparing CICS......

4.2.1File Control Table (FCT)......

4.2.2Program Processing Table (PPT)......

4.2.3Program Control Table (PCT)......

4.2.4Delete/Define the VSAM Files......

4.3Configure the IP Socket Gateway......

4.3.1IBM CICS Socket Service Configuration......

4.4Startup/Shutdown of the IP Socket Gateway......

4.4.1Known Problems in Startup/Shutdown of the IP Socket Gateway......

4.5Logging Messages in the Socket Processor......

4.6Routing Messages To Remote Regions......

4.7Security Exit Processing......

5APPENDIX A

5.1Sample JCL......

5.1.1Sample JCL To Build the EZACONFG File......

5.1.2Sample JCL To Build the EZACACHE File......

6APPENDIX B

6.1CICS DFHCSD Definitions......

6.1.1File Control Table (FCT)......

6.1.2Program Processing Table (PPT)......

6.1.3Program Control Table (PCT)......

7APPENDIX C

7.1Tape Creation JCL......

7.2Tape Unload JCL......

8APPENDIX D

8.1Assembly and Compilation JCL......

8.1.1STEP1IP: Assembling the Listener Program......

8.1.2STEP2IP: Compiling the Message Adapter......

9APPENDIX E

9.1Glossary......

Interpose Transaction Engine V. 4.1

IP Socket Gateway IP41-SK.102.1

InteliData Technologies

Interpose Transaction Engine V. 4.1

IP Socket Gateway Guide

1INTRODUCTION

The IP Socket Gateway is designed to allow a direct IP connection between the components of Interpose (as well as other InteliData products) to the back-end Interpose Transaction Engine. This socket gateway does not eliminate the existing APPC-based gateway, but it can either replace or co-exist with any existing connectivity services, as required.

WhoThis Manual Is For

This manual is intended for the Interpose installers, as well as customer CICS systems programmers.

What’s In This Manual

This manual provides information regarding system requirements and instructions for installation. It also discusses the architecture and functionality of the IP Gateway and compares the differences between the APPC Gateway and the IP Socket Gateway. The appendices provide sample JCL, CSD definitions, and JCL for tape creation and unload as well as assembly and compilation.

All abbreviations used in this manual are listed in the glossary in Section 9 “Appendix E.”

Navigation

If viewing the manual electronically (online), there are clickable “links” next to each in-text reference to a “Section” (e.g., “see Section x for more information” – where the x is the clickable link) located in this manual. These links make it easier to navigate between the sections that describe program functions and the sections having the hardcopy JCL for those functions (which are located near the back of the manual). However, references to sections in the CICS TCP/IP Socket Interface Guide (which will be shortened to ‘TCP/IP socket guide’ throughout the manual) are not clickable (see under Requirements below).

1.1Requirements

In order to install and configure the TCP/IP services, the installer must have access to the following IBM document: CICS TCP/IP Socket Interface Guide (IBM # SC31-7131-03). This document can be viewed or downloaded from the Web at this link: http:\\ . (If you click on this link and it doesn’t work, you may need to cut and paste the entire link into your browser’s URL address window.)

This document is based primarily upon information in section 1.0 through section 4.0 of the TCP/IP socket guide.

Your operating environment should have the following software levels installed and active on the systems you wish to run this Gateway:

1)TCP/IP Version 3 Release 2 or above (available from IBM)

2)MVS/ESA Version 4.3 or higher

3)CICS 3.3 or later

4)Transaction Server 1.1 or higher preferred

The Interpose Transaction Engine requires a PTF. This PTF changes each of the message processing programs to properly handle an internal processing architecture that is synchronous. ITE Version 4.1 (and above) already has this PTF applied. Previous releases would have to be upgraded. The PTF is a stand-alone feature and has no pre-requisites.

Interpose Transaction Engine V. 4.1

IP Socket Gateway IP41-SK.102.1

InteliData Technologies

2The IP Socket Gateway

The IP Socket Gateway acts as an interface gateway, allowing any client using AFMS to attach directly to the CICS Transaction Server, thereby eliminating the necessity of using a protocol translation server. The design of the gateway also allows configuration of a user-defined number of concurrent transactions (up to 1000) within the CICS environment. The limitations on the number of transactions is based upon allocated resources.

2.1.1System Architecture

2.2Comparison of the APPC Gateway and the IP Socket Gateway

There are two primary differences between the APPC gateway and the IP Socket Gateway. The first, as mentioned previously, is the elimination of the necessity for protocol conversion when using the IP gateway. The APPC gateway requires an external server running Microsoft NT Server and using Microsoft SNA Gateway software. For this arrangement, a custom-coded server application provides the connectivity between the TCP/IP and SNA protocols. However, by implementing the IP socket gateway, the external server (or multiple servers, if a multi-channel solution has been set up), along with its corresponding software products, is eliminated. The resulting reduction in components eliminates points of failure, and reduces network latency and instruction paths as well, thereby yielding some improvement in overall response.

The second difference involves the method by which conversations are managed. In the APPC gateway, an Interpose session is made up of a series of asynchronous conversations between the OFX server and Interpose. From a Transaction Server (CICS) perspective, each message from the OFX server is viewed as a series of separate transactions. However, with the IP gateway, the entire transaction set is treated as a single transaction. The IP gateway issues “sync points” at appropriate times, which ensure that “held resources” are limited and response-time is reduced.

2.2.1Gateway Comparisons

2.3How the IP Socket Gateway Operates

The IP socket gateway is made up of two primary components: a Listener task and a Worker task.

Listener Task

A Listener task is a long-running CICS task that has the following responsibilities: (1) to determine which IP port it will listen on (as well as several other configuration parameters), (2) to establish the IP environment, (3) to listen for incoming connections, (4) to give up the incoming socket to a Worker task (a socket processor that is essentially a new, detached CICS transaction), and (5) to close the incoming socket so that the Worker task can take ownership and begin processing the message.

Each Listener task must have an entry in the EZACONFG file (see Section 5 “Appendix A” for sample JCL that can be modified to create this file). This entry enables the Listener tasks to determine the necessary initialization parameters. CICS transaction ‘EZAC’ can be used to establish the necessary Listener task entry, or the entry can be created during TCP/IP configuration (see the installation procedures in Section 3 “Installation of the IP Socket Gateway” for further details).

The Listener uses the ACCTIME value from the configuration file to determine how often it checks for a shutdown function. Every time the Listener regains control, it checks to see whether or not it should shut itself down. The ACCTIME value is used in a SELECTX IP call to establish a timer “pop,” in the event that no incoming socket calls are being received. A small timer value (e.g., one second) means that the Listener will be dispatched every second to check for a shutdown. A larger value (e.g., 60 seconds) means that the Listener will wait up to 60 seconds before checking for a shutdown. A larger number will also increase the time required for CICS to shutdown gracefully.

Note: Multiple Listeners can be started in a single CICS address space. Each Listener, however, must listen on a different Port ID. Initializing a Listener on a port that is already in use (either through a CICS Listener or other some other service) will fail.

Worker Task (Socket Processor)

A Worker task is designed to: (1) take ownership of the incoming socket connection, (2) serially receive the AFMS messages, (3) process the messages, and (4) return the AFMS response to the client. Each Worker task stays active as long as the socket is held open. For example, the OFX server is designed to open a socket, process a series of messages as a batch, and then close the socket. In this example, the Worker task lasts only as long as needed to process all of the messages in the batch. Unlike the APPC gateway – where each message is initiated with different transaction IDs – the IP socket gateway uses a single transaction ID for processing all of the AFMS messages in the set.

When a new Worker task is required, the Listener sets the identification of the new transaction. To determine this ID, the Listener looks at the name of the transaction under which it was started, and replaces the last character with the @ symbol. For example, if the Listener is started using transaction ‘ECBL’, the Worker task would be initiated with the transaction ID ‘ECB@’.

Note: If you are doing a DPL to a remote application-owning region, and you believe that you need to define a remote transaction other than the one that matches the original (first three characters of the Listener Transid + ‘@’), then the CEDA entry for the program must have the Transid option of the Remote Attributes set with a value ending with an @. If you do not set the last character of the Transid in the Remote Attributes to an @, unpredictable application errors will occur.

The number of Worker tasks that can be started concurrently is a function of defined resources.

Note: The Worker task has a read timeout function. The timeout is used to ensure that if no message is forthcoming from the client, after ‘timeout’ number of seconds, the Worker task will assume that the client has failed and automatically gracefully shut itself down. This prevents ‘orphan’ sockets from cluttering up the CICS task chains. The duration of the read timeout can be configured at installation time (using the REATIME macro value – see the installation JCL below in Section 5.1.1 “Sample JCL To Build the EZACONFG File”) or via the EZAC transaction. Accordingly, the higher the REATIMEout value, the longer a Worker task will remain on the active list – with a corresponding increase in the CICS shutdown time; the shorter the value, the more often products such as IWB will have to re-establish a new socket.

In the case of OFX translation servers, sockets are opened and closed for each OFX XML file received. Intelidata’s IWB server manages the sockets by pooling them. This means that you may see Worker tasks remaining active for long periods of time. This is especially true in the case of a high-traffic environment. This is normal and acceptable.

Interpose Transaction Engine V. 4.1

IP Socket Gateway IP41-SK.102.1

InteliData Technologies

3INSTALLATION OF THE IP SOCKET GATEWAY

The following information describes some of the prerequisites and steps required to do a successful installation of the IP Socket Gateway (see Section 2.3 “How the IP Socket Gateway Operates” for more information):

3.1Pre-installation Requirements

Validate the Installed TCP/IP Release Levels

The TCP/IP protocol stack running under OS/390 must be Release 3.2 or higher. The CICS TCP/IP socket interface is a component of this version of TCP/IP for MVS/ESA.

Apply the Following PTF From IBM

A PTF may be required to run the TCP/IP protocols and listen on port IDs with a number greater than 32000. The PTF ID is UQ42499 and can be downloaded from IBM’s OS/390 support site. This PTF supports up to 999 concurrent connections to the Listener task.

3.2Installation Procedures For CICS TCP/IP Socket Interfaces

The following steps provide the set up details and requirements for installing the socket interfaces.

3.2.1Step 1: TCP/IP Software

Ensure that the software (obtained from IBM at is properly loaded on the system. The primary location for the necessary modules is in either hlq.SEZALINK or hlq.SEZATCP. Review section 2.0 through section 4.0 of the TCP/IP socket guide for more information.

3.2.2Step 2: Define SEZATCP library

Ensure that the SEZATCP library is defined in the PROGxx member, then IPL OS/390, if required.

3.2.3Step 3: CICS Startup Configuration

Add the necessary JCL to the CICS startup. This procedure is fully described in section 2.2 of the TCP/IP socket guide.

3.2.4Step 4: Define CICS Resources

Define the CICS resources (transactions, programs, mapsets and files) using CICS RDO. The requirements for these resources are defined in section 2.3 of the TCP/IP socket guide. The resources must be defined exactly as shown in the guide, or the TCP/IP services will not work correctly.

3.2.5Step 5: Create VSAM Files

Run the batch configuration processes to create the necessary VSAM files (EZACONFG, EZACACHE). The JCL for these files is listed under Section 5 ”Appendix A.” These configurations can also be used to define socket listener transactions to the interface.

3.2.6Step 6: Define the OMVS Segment

Ensure that the CICS region has an OMVS segment defined, according to your security package.

3.3Method for Linking Programs Using the Socket Interface

When linking application programs, the SYSLIN DD statement for the link editor MUST include the statement ‘INCLUDE SYSLIB(EZACICAL)’. If this include statement is not appended to the SYSLIN DD input stream, the CICS socket programs will link successfully but, upon execution, may cause the entire CICS region to hang.

3.4Getting the Source To the Mainframe

The TCP/IP socket modules are delivered on a 3480 cartridge. Use institution-specific methods for unloading the libraries.

Create and run a set of JCL using the example in Section 7.2 “Tape Unload JCL.” This JCL unloads the INSTALL and SORCLIB libraries from the tape labeled ITE006.

Interpose Transaction Engine V. 4.1

IP Socket Gateway IP41-SK.102.1

InteliData Technologies

4Compiling, Linking, and Assembling the System

After loading the libraries to the mainframe, the next step of the installation is to convert the provided source code to machine-readable object code. This code should be in the form of load modules defined to CICS and stored in a special dataset. However, a separate load dataset can be used, or the load modules can be placed in an existing common load dataset. If a separate dataset is used, it will need to be defined to the system before any compilation or assembling can take place and should have the following attributes:

RECFM = U

LRECL = 0

BLKSIZE = 23200

Size = 100 tracks of 3380 DASD

Directory blocks = 50

4.1The Compilation Process

The installation JCL dataset, ‘INSTALL’, contains members that support this process. Each member involves a parameterized in-line JCL procedure and job steps for each module that will be assembled or compiled. A hardcopy of each of these members is listed under Section 6 “Appendix D.”

4.1.1STEP 1 – STEP1IP – Assembling the Listener Program

Assemble and link the Listener program used with the Interpose system. The JCL in Section 8.1.1 “STEP1IP: Assembling the Listener Program” can be used to perform this step. While it is not mandatory to use this JCL, ensure that the JCL used contains the proper calling sequence for the 370 assembler, and that appropriate macro libraries are included in the concatenation.

If the provided JCL is used, change all parameters to match the system requirements. Also ensure that the library concatenations reference the correct libraries in your system.

4.1.2STEP 2 – STEP2IP – Compiling the Message Adapter

Translate, compile, and link the message adapter used with Interpose. The JCL in Section 8.1.2 “STEP2IP: Compiling the Message Adapter” can be used to perform this step. While it is not mandatory to use this JCL, ensure the JCL used contains the proper calling sequence for the translator, COBOL compiler, and linkage editor, and that the appropriate copybook and macro libraries are included in the concatenation for the compiler. Also ensure that the linkage editor uses the appropriate load module libraries.

If the provided JCL is used, change all parameters to match the system requirements, and ensure that the copybook, load module, and library concatenations reference the correct libraries in your system.

4.2Preparing CICS

The next step of the installation process is to define the CICS resources (transactions, programs, mapsets and files) using CICS RDO. The requirements for these resources are defined in section 2.3 of the TCP/IP socket guide. The resources must be defined exactly as shown in the guide or the TCP/IP services will not work properly.

CICS parameter definition can be performed using either macro definition or resource definition.

4.2.1File Control Table (FCT)

The FCT tables define the VSAM files used by the IP Socket Gateway. The JCL for this table is listed in Section 6.1.1 “File Control Table (FCT).”