[Top] [Previous] [Next] [End of Book]

# Chapter 3 . Installing BEA Connect TCP for IMS

Installing BEA Connect TCP for IMS consists of the following basic tasks:

- Allocating the necessary MVS datasets

- Unloading and copying the distribution files from the distribution media (CD-ROM) to the corresponding MVS distribution libraries

- Linking the supplied object files to create the BEA Connect TCP for IMS BMP load module

- Defining the BEA Connect TCP for IMS BMP to IMS

- Defining the BEA Connect TCP for IMS configuration

- Creating the JCL for the BEA Connect TCP for IMS BMP

- Testing BEA Connect TCP for IMS

## How to Install BEA Connect TCP for IMS

1. Allocate MVS Datasets

Allocate the following datasets to receive the BEA Connect TCP for IMS distribution files (hlq1 and hlq2 are dataset name high-level qualifiers appropriate to your installation):

>        DSNAME: hlq1.hlq2.CONTROL
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: IMS sample definitions, sample configuration file

>        DSNAME: hlq1.hlq2.INCLUDE
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: C header file, COBOL copybooks

>        DSNAME: hlq1.hlq2.JCL
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: Job Control Language

>        DSNAME: hlq1.hlq2.OBJECT
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 3200
>        SPACE: 1 cylinder
>        Usage: Component object files

>        DSNAME: hlq1.hlq2.SOURCE
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 1cylinder
>        Usage: Sample IMS client and server transactions

Allocate the following run-time datasets for use by the BEA Connect TCP for IMS BMP (hlq1 and hlq2 are dataset name high-level qualifiers appropriate to your installation):

>        DSNAME: hlq1.hlq2.LOAD
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: U
>        LRECL: 0
>        BLKSIZE: 6133 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: Load library

>        DSNAME: hlq1.hlq2.CONFIG
>        DSORG: PS
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: Configuration File

>        DSNAME: hlq1.hlq2.MSGLOG
>        DSORG: PS
>        RECFM: VB
>        LRECL: 1028
>        BLKSIZE: 6144 (or other valid blocksize)
>        SPACE: 1 cylinder
>        Usage: Message Log

>        DSNAME: hlq1.hlq2.SVRLOG
>        DSORG: PS
>        RECFM: VB
>        LRECL: 32756
>        BLKSIZE: 32760 (Note: required blocksize)
>        SPACE: 1 cylinder
>        Usage: Server Response Log

2. Unload the Distribution Files

The BEA Connect TCP for IMS product is distributed on a single CD-ROM (along with other members of the BEA Connect product family). The BEA Connect TCP for IMS distribution files are grouped under one of the following directory structures:

- For UNIX the directory is `/cdrom/unixmf` where `/cdrom` is the directory where the drive is mounted.

- For Windows NT the directory is `D:\ntmf` where `D:` is the CD-ROM drive.

The previous directory structures include the following sub-directories:

Subdirectory | Contents
--- | ---
CONTROL | Sample IMS definitions, sample BEA Connect TCP for IMS configuration file
INCLUDE | C header files, COBOL copybooks for use by IMS Client and Server transactions
JCL | Job Control Language for linking and executing the BEA Connect TCP for IMS BMP
OBJECT | Object component files of the BEA Connect TCP for IMS BMP
SOURCE | Sample IMS Client and Server transactions for use with BEA Connect TCP for IMS

Because the distribution files are located on a CD-ROM, you will probably use a UNIX-based system or a PC-based system to access the files on the CD-ROM and file transfer them to MVS.

You must transfer the contents of each subdirectory to the corresponding distribution library on the MVS system. You can do this by using a file transfer program (such as FTP) or any other mechanism that allows you to transfer files to your MVS system. The file transfer program must have the following capabilities:

- Properly transferring both text and binary files

- Properly creating members in a target library (PDS)

The IBM File Transfer Program (FTP, distributed as part of TCP/IP for MVS) satisfies both of these requirements.

Each file in each subdirectory on the distribution CD-ROM corresponds to a member of the associated target library. For example, file BEATCPI in the JCL subdirectory corresponds to member BEATCPI in the JCL distribution library.

Note: All files in the CONTROL, INCLUDE, JCL, and SOURCE subdirectories are text files; be sure to specify text (or ASCII) mode when you transfer these files from the CD-ROM to their corresponding MVS distribution library members.
All files in the OBJECT subdirectory are binary files; you must specify binary (or image) mode when you transfer these files from the CD-ROM to the corresponding MVS distribution library members.

3. Link-Edit the BEA Connect TCP for IMS BMP

The BEA Connect TCP for IMS BMP is a pre-linked object file.

Use the LNKBMP31 JCL file for linking with IBMs TCP/IP V3R1 product or Interlink's TCP Access Version 4.1 product. Use the LNKBMP31 JCL to run IBMs TCP/IP V3R2 using IUCV.

Use the LNKBMP JCL file for linking with IBM's TCP/IP V3R2 HPNS product.

You will need to tailor the JCL as required to match your installation's standards and naming conventions. Review the following items and make the necessary changes before you submit the job:

1. Supply an appropriate Job Card for the job.

2. Change the names of IBM product datasets as required to match those in your particular installation, including LE/370 datasets (for example, SYS1.SCEELKED), TCP/IP for MVS datasets (for example, SYS1.SEZACMTX), and IMS (for example, IMSV5R1.RESLIB).

3. Change the names of BEA Connect TCP for IMS datasets as required to match those you allocated in Step 1 (for example, BEATCPI.DIST.OBJECT).

4. Change the name of the link-editor (HEWL) as required to match the name used by your installation.

   Note: The link job references components supplied by LE/370, TCP/IP for MVS, and IMS.

When the job completes successfully, you will receive a return code of 0 from the link-edit steps and an executable load module (the BEA Connect TCP for IMS BMP) will be placed into the specified target load library. The load module should have attributes of AMODE=31, RMODE=24. There should be no unresolved external references.

4. Define BEA Connect TCP for IMS to IMS

In order to integrate BEA Connect TCP for IMS into your IMS environment, you must properly define it to IMS. Member BEATCPI in the CONTROL distribution library contains the required IMS definitions, including the appropriate APPLCTN, TRANSACT, PCB, and PSBGEN macros. These definitions should be furnished to an IMS systems programmer who will include them in the overall IMS system definition. The APPLCTN and TRANSACT definitions are included as part of the input to an IMS Stage 1 gen, while the PCB and PSBGEN definitions are processed as input to a subsequent PSB gen.

Use the definitions as supplied; do not make changes. In particular, note the following:

- BEA Connect TCP for IMS is a transaction-oriented BMP.

- BEA Connect TCP for IMS is not a WFI (Wait For Input) BMP; do not attempt to define it as such.

- EXPRESS=YES must be specified.

- BEA Connect TCP for IMS must have a modifiable Alternate PCB.

- BEA Connect TCP for IMS is written in the IBM C programming language; therefore, LANG=ASSEM must be specified (or allowed to default).

  Note: If desired, you may change the BMP transaction code and/or PSB name (the supplied default is BEATCPI). If you do, however, be sure to make the corresponding changes elsewhere (for example, in your user-written Client and Server transactions).

Once the required Stage 1 and PSB gens have been successfully completed, BEA Connect TCP for IMS should be defined to IMS.

Any BEA Connect TCP for IMS Client and Server transactions that you write must also be properly defined to IMS. In general, BEA Connect TCP for IMS imposes no special requirements on these definitions, so you define them exactly as you would any IMS transaction. In order to communicate with BEA Connect TCP for IMS through the IMS Message Queue, however, user-written Client and Server transactions must be defined with a modifiable Alternate PCB.

5. Create a BEA Connect TCP for IMS Configuration File

BEA Connect TCP for IMS makes use of a text configuration file which is read and processed during initialization to establish the configuration. Any text editor (such as the ISPF Editor) can be used to create the configuration file. Member CONFIG in the CONTROL distribution library is a sample configuration file which you may use as a starting point for creating a configuration file tailored to your particular installation. Refer to Chapter 4, "Configuring BEA Connect TCP for IMS," for detailed information on defining a configuration.

In general, a configuration file includes four basic sections:

- A SYSTEM statement that defines global operating parameters

- One or more statements that define the local (IMS) gateway

- One or more statements that define remote gateways

- One or more statements that define services offered by remote gateways

System parameters control the overall operational environment of BEA Connect TCP for IMS. Because BEA Connect TCP for IMS cannot "wait" on the IMS Message Queue, the queue is periodically interrogated (polled) to determine if any new work has arrived (i.e., IMS Client requests or Server responses). The SleepTime parameter specifies the amount of time that BEA Connect TCP for IMS will "sleep" (wait) during idle periods before checking the IMS Message Queue for work. Refer to Chapter 4, "Configuring BEA Connect TCP for IMS," for information on how to specify the sleep time.

You must provide at least one GATEWAY TYPE=LOCAL statement to define access to your local (IMS) gateway by remote systems. In particular, this statement specifies:

- The IP Address that remote systems use to establish TCP/IP connections with this gateway

- The Port Number that remote systems use to establish TCP/IP connections with this gateway

- The Account ID and Password (if used) that must be supplied by remote systems to successfully establish an inbound session with this gateway

- The maximum number of concurrent inbound sessions (TCP/IP connections initiated by remote systems) that will be accepted via the specified port

The IP Address should be that of the MVS machine on which BEA Connect TCP for IMS will be running. You should specify a Port Number that is not a well-known port number and one that is not used by any other TCP/IP application. Make sure that remote systems are correctly configured with the corresponding IP Address, Port Number, Account ID (if used), and Password (if used). Otherwise, attempts by remote systems to connect to this gateway will fail.

GATEWAY TYPE=REMOTE statements define access to remote systems by the IMS gateway. In particular, each GATEWAY TYPE=REMOTE statement specifies:

- The IP Address to use to establish a TCP/IP connection (that is, connect) with the remote gateway

- The Port Number to use to establish a TCP/IP connection (that is, connect) with the remote gateway

- The Account ID and Password (if used) that must be supplied to establish an outbound session with the remote gateway

- The minimum and maximum number of concurrent, outbound sessions that will be established with the remote gateway

The IP Address, Port Number, Account ID, and Password must match the configuration of the remote system. Otherwise, attempts to establish an outbound session with the remote system will fail.

If you specify a value other than zero for the minimum number of sessions, BEA Connect TCP for IMS will attempt to establish the specified number of outbound sessions with the remote system during initialization.

SERVICE TYPE=REMOTE statements define remote services to which BEA Connect TCP for IMS has access. Each statement specifies:

- The corresponding local and remote service names

- The remote system (Logical Machine ID) that offers the service

- A time limit for processing the request

The Local Service Name is the name used by an IMS Client transaction to request the service. The Remote Service Name is the name of the service as defined on the remote system. These need not be the same, but note that the Remote Service Name must match the configuration of the remote system.

The remote system offering the service is identified by a Logical Machine ID, which must correspond to the Logical Machine ID specified in a GATEWAY TYPE=REMOTE statement.

The Time Limit (in seconds) specifies how long BEA Connect TCP for IMS will "wait" for a response to a request sent to a remote system before assuming that the request has "timed out" and that no response will be forthcoming. Specify a realistic value that makes a reasonable allowance for network latency and overall system load. Small values should be avoided because they may result in requests timing out under otherwise normal circumstances.

Note: It is permissible to have more than one SERVICE TYPE=REMOTE statement for the same (local) service name. When this is the case, each statement must identify a different remote Logical Machine ID. This allows BEA Connect TCP for IMS to "spread" requests for a particular service among multiple remote systems offering the service, thus balancing the load and improving overall throughput.

Place your completed configuration file in the configuration dataset (allocated in Step 1).

6. Create JCL for the BEA Connect TCP for IMS BMP

BEA Connect TCP for IMS is a standard, transaction-oriented IMS BMP (BMP Message Processing) program. IMS BMPs are submitted and run as ordinary batch jobs.

IMS normally supplies a cataloged procedure (PROC) for executing BMPs, and you should use the procedure supplied with your release of IMS, if available. Member BEATCPI in the JCL distribution library is a sample job for executing BEA Connect TCP for IMS and can be used as a reference when modifying the JCL supplied with your version of IMS.

When tailoring the JCL for your installation, pay particular attention to the following:

- You will need to supply an appropriate Job Card for the job. The job card should specify TIME=1440, since BEA Connect TCP for IMS executes as a non-ending job.

- BEA Connect TCP for IMS is written in the IBM C language and requires access to the LE/370 run-time environment. Add DD cards to the STEPLIB for the LE/370 run-time datasets, including SYS1.SCEERUN and SYS1.SCEELKED. Use whatever dataset names are appropriate for your installation.

- For diagnostic purposes, you may wish to add DD cards for SYSUDUMP and/or CEEDUMP. In the event of an abnormal termination (ABEND), LE/370 writes a formatted dump to CEEDUMP.

- Add a DD card for SYSTCPD pointing to the TPC/IP Data file (e.g., TCPIP.V3R1.DATA - change the dataset name as necessary to conform to your installation). This dataset is used by TCP/IP in the BEA Connect TCP for IMS address space.

- Add DD cards for the BEA Connect TCP for IMS run-time datasets: CONFIG, MSGLOG, and SVRLOG (all of which were allocated in Step 1, above).

- If you want to preserve messages from previous executions of BEA Connect TCP for IMS, code DISP=MOD in the MSGLOG DD statement; new messages will be appended to the end of the dataset (existing messages are preserved). If you want the Message Log to be overwritten with each new execution of BEA Connect TCP for IMS, code DISP=OLD (or DISP=SHR) in the MSGLOG DD statement; existing messages are lost.

- Code CKPTID=NOMSG681 on the BMP proc invocation to suppress IMS message DFS681I (which would otherwise be issued every time the BMP issues a CHKP call).

- Code PGMLIB=hlq1.hlq2.LOAD on the BMP proc invocation to identify the library containing the BMP (BEA Connect TCP for IMS).

- Code the proper values for the MBR, IN, and PSB parameters on the BMP proc invocation. The default for each of these is BEATCPI, but if you elect to change the load module name, transaction code, or PSB, code the appropriate name(s).

7. Start BEA Connect TCP for IMS

BEA Connect TCP for IMS is started by submitting the JCL prepared in Step 6. Before you attempt to start BEA Connect TCP for IMS for the first time, make sure that the proper IMS definitions are in place and that the BEA Connect TCP for IMS transaction code and PSB are defined and started (i.e., not stopped). Refer to Chapter 6, "Programming BEA Connect TCP for IMS," for information on starting BEA Connect TCP for IMS.

8. Test the Installation

   When you start BEA Connect TCP for IMS for the first time, you should do so in a controlled environment, using a small, simple configuration to methodically test the system to verify your installation and the configuration. Refer to Chapter 6, "Programming BEA Connect TCP for IMS," for additional information.

[Top] [Previous] [Next] [End of Book]