BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
eLink for Mainframe TCP Documentation | eLink for Mainframe TCP Installation Guide | Previous Topic | Next Topic | Contents | Index

Installing BEA eLink TCP for IMS

Installing BEA eLink for Mainframe TCP for IMS (hereafter referenced as eLink TCP for IMS) consists of the following basic tasks.

- Preparing to Install

- Installing eLink TCP for IMS

Preparing to Install

Complete the following tasks prior to installing the eLink TCP for IMS software:

- Read the BEA eLink for Mainframe TCP Release Notes

- Install and verify the TCP/IP stack software

Installing eLink TCP for IMS

To install eLink TCP for IMS, complete the following tasks:

| Your action...
--- | ---
1. | Allocate OS/390 Datasets
2. | Unload the Distribution Files
3. | Link-Edit eLink TCP for IMS
4. | Define eLink TCP for IMS to IMS
5. | Create an eLink TCP for IMS Configuration File
6. | Create JCL to Run eLink TCP for IMS
7. | Start BEA eLink TCP for IMS
8. | Test the Installation

Task 1: Allocate OS/390 Datasets

The directory structures on the eLink TCP for IMS software CD include the following partitioned datasets:

Partitioned Datasets (PDS) | Format | Contents
--- | --- | ---
CONTROL | ASCII | Sample IMS definitions, sample BEA eLink TCP for IMS configuration files
INCLUDE | ASCII | C header files, COBOL copybooks for use by IMS Client and Server transactions
JCL | ASCII | Job Control Language for linking and executing BEA eLink TCP for IMS
SOURCE | ASCII | Sample IMS Client and Server transactions for use with BEA eLink TCP for IMS
OBJECT | BINARY | Object component files of BEA eLink TCP for IMS
MSGCAT (sequential dataset) | BINARY | File containing runtime messages that eLink TCP for IMS issue

1. FTP the JCL file INSTALL from the JCL subdirectory.

2. Execute this job to allocate datasets using high-level qualifiers appropriate to your installation (hlq1 and hlq2 are dataset name high-level qualifiers appropriate to your installation).

The following datasets are allocated to receive the eLink TCP file distribution.

Listing 2-1 Allocating OS/390 Datasets

>        DSNAME: hlq1.hlq2.CONTROL
>        DSORG: PO
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 80
>        BLKSIZE: 23440 (or other valid blocksize)
>        SPACE: 2 tracks
>        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: 2 tracks
>        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: 2 tracks
>        Usage: Sample LINK and execute JCL

>        DSNAME: hlq1.hlq2.MSGCAT
>        DSORG: PS
>        DIRBLKS: 10
>        RECFM: FB
>        LRECL: 100
>        BLKSIZE: 32000 (or other valid blocksize)
>        SPACE: 2 tracks
>        Usage: Message text

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

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

The following runtime datasets are also allocated.

Runtime Datasets | Format | Contents
--- | --- | ---
LOAD | Binary | Load library for BEA eLink TCP for IMS
CONFIG | ASCII | Configuration file for BEA eLink TCP for IMS
MSGLOG | ASCII | Message log for BEA eLink TCP for IMS
SVRLOG | ASCII | A log file containing server responses for BEA eLink TCP for IMS

Listing 2-2 Allocating Runtime Datasets

>        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 track
>        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

Task 2: Unload the Distribution Files

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

- For UNIX, the directory is /cdrom/unixmf.

In this directory structure, /cdrom is the directory where the drive is mounted.

- For Windows NT and Windows 2000, the directory is D:\ntmf.

In this directory structure, D: is the CD-ROM drive.

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

Transfer the contents of each subdirectory to the corresponding distribution library on the OS/390 system. Use a file transfer program (such as FTP) or any other mechanism that allows you to transfer files to your OS/390 system. The file transfer program must be able to:

- Properly transfer both text and binary files

- Properly create members in a target library (PDS)

The IBM File Transfer Program (FTP, distributed as part of TCP/IP for OS/390) 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 OS/390 distribution library members.

The MSGCAT file and all files in the OBJECT subdirectory are binary files; specify binary (or image) mode when you transfer these files from the CD-ROM to the corresponding OS/390 distribution library members.

Task 3: Link-Edit eLink TCP for IMS

The eLink TCP for IMS program is delivered as a pre-linked object file.

- Use the LNKBEAIL file for linking Interlink's TCPAccess Version 4.1 product.

- Use the LNKBEA34 JCL file for linking with IBM's TCP/IP V3R2 or V3R4 products.

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 product datasets as required to match those in your particular installation, including LE/370 datasets (for example, SYS1.SCEELKED), TCP/IP for OS/390 datasets (for example, SYS1.SEZACMTX), Interlink datasets (for example, SYS1.TCPACC.CLIB), and IMS (for example, IMSV5R1.RESLIB).

3. Change the names of eLink 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 OS/390, and IMS.

When the job completes successfully, you receive a return code of 0 from the link-edit steps and an executable load module is 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.

Sample JCL for Linking eLink TCP for IMS

Listing 2-4 is JCL to link the distributed object files into an executable load module.

Listing 2-3 Sample JCL for Linking Distributed Object Files

>     //JOBNAME JOB ETC.
>     //LKED     EXEC PGM=HEWL,COND=(4,LT),
>     //         REGION=2M,PARM='AMODE=31,MAP,XREF'
>     //SYSLIB   DD  DSNAME=SYS1.SCEELKED,DISP=SHR
>     //         DD  DSNAME=SYS1.SEZACMTX,DISP=SHR
>     //SYSPRINT DD  SYSOUT=*
>     //SYSLMOD  DD  DISP=SHR,DSNAME=BEATCPI.DIST.LOAD
>     //SYSUT1   DD  UNIT=VIO,SPACE=(TRK,(10,10))
>     //RESLIB   DD  DISP=SHR,DSN=IMSV5R1.RESLIB
>     //SYSLIN   DD  DISP=OLD,DSN=BEA.HLQ.OBJECT(PREBEA34)
>     //         DD  *
>      INCLUDE RESLIB(DFSLI000)
>      ENTRY CEESTART
>      NAME BEATCPI(R)
>     /*
>     //

Task 4: Define eLink TCP for IMS to MVS

To integrate eLink TCP for IMS into your IMS environment, you must properly define it to MVS.

OTMA Definition

To use OTMA to integrate eLink TCP for IMS into your OS/390 environment, you must properly define it in the program property table (PPT). Listing 2-5 is a sample program entry for the eLink TCP product. Also, you must link the program to an APF authorized library.

Listing 2-4 Sample Program Property Table

>     PPT PGMNAME(BEATCP34)     /* PROGRAM NAME = BEATCP34           */
>              CANCEL           /* PROGRAM CAN BE CANCELED           */
>              KEY(7)           /* PROTECT KEY ASSIGNED IS 7         */
>              SWAP             /* PROGRAM IS SWAPPABLE              */
>              NOPRIV           /* PROGRAM IS NOT PRIVILEGED         */
>              DSI              /* REQUIRES DATA SET INTEGRITY       */
>              PASS             /* CANNOT BYPASS PASSWORD PROTECTION */
>              SYST             /* PROGRAM IS A SYSTEM TASK          */
>              AFF(NONE)        /* NO CPU AFFINITY                   */
>              NOPREF           /* NO PREFERRED STORAGE FRAMES       */

Task 5: Create an eLink TCP for IMS Configuration File

BEA eLink 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. CONFIGOT, the OTMA sample in the CONTROL distribution library is a sample configuration file which you may use as a starting point for creating configuration files tailored to your particular installation.

Place your completed configuration file in the configuration dataset allocated in the Task 1: Allocate OS/390 Datasets section. A configuration file includes the following basic sections:

- SYSTEM Statement Definition

- Local Gateways Definition

- Remote Gateways Definition

- Remote Services Definition

- Local Services and IMS Host Systems Definition

Note: You must define local services and IMS host systems if running OTMA.

For detailed information about syntax and parameter definitions for the configuration file, refer to the BEA eLink TCP for IMS User Guide.

SYSTEM Statement Definition

SYSTEM parameters control the overall operational environment of BEA eLink TCP for IMS. Because eLink TCP for IMS cannot "wait" on the IMS Message Queue, the queue is periodically interrogated (polled) to determine if any new work has arrived (for example, IMS Client requests or Server responses). Set the SleepTime parameter to specify the amount of time that eLink TCP for IMS "sleeps" (waits) during idle periods before checking the IMS Message Queue for work.

Local Gateways Definition

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

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

- The IP Address should be that of the OS/390 machine on which BEA eLink TCP for IMS is running.

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

- 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.

- 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 is accepted via the specified port

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 fail.

Remote Gateways Definition

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 are established with the remote gateway

- If you specify a value other than zero for the minimum number of sessions, eLink TCP for IMS attempts to establish the specified number of outbound sessions with the remote system during initialization.

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 fails.

Remote Services Definition

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

- The corresponding local and remote service names

- 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 (Logical Machine ID) that offers the service

- 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.

- A time limit for processing the request

- The Time Limit (in seconds) specifies how long BEA eLink TCP for IMS "waits" for a response to a request sent to a remote system before assuming that the request has "timed out" and that no response is forthcoming. Specify a 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 eLink 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.

Local Services and IMS Host Systems Definition

SERVICE TYPE=LOCAL statements define local services offered by a local IMS host. There can be multiple SERVICE TYPE=LOCAL statements and multiple statements defining the same service, provided each specifies a different local IMSID. Each statement requires the following information:

- The corresponding local and remote service names

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.

Note: The local and remote service names can be different; however, the Remote Service Name must match the configuration of the remote system.

- The IMSID (Logical IMS ID) that offers the service

The IMSID is a symbolic name that uniquely identifies an IMS system definition. This name must match a logical IMS ID (IMSID) specified in a HOST, TYPE=IMS statement.

Task 6: Create JCL to Run eLink TCP for IMS

You must create JCL to run the BEA eLink TCP for IMS product. The following section specifies how to create JCL for running as an OTMA client.

JCL for OTMA Clients

When running the product as an OTMA client, BEA eLink TCP for IMS runs in its own address space under OS/390 as a started task or long running job. Member RUNOTM in the JCL distribution library is a sample job for executing BEA eLink TCP for IMS.

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

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

- BEA eLink TCP for IMS is written in the C language and requires access to the LE/370 runtime environment. Add DD cards to the STEPLIB for the LE/370 runtime 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 (for example, TCPIP.V3R1.DATA - change the dataset name as necessary to conform to your installation). This dataset is used by TCP/IP in the BEA eLink TCP for IMS address space (when using IBM TCP/IP).

- If you want to preserve messages from previous executions of BEA eLink TCP for IMS, code DISP=MOD in the MSGLOG DD statement; new messages are 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 eLink TCP for IMS, code DISP=OLD (or DISP=SHR) in the MSGLOG DD statement; existing messages are lost.

Task 7: Start BEA eLink TCP for IMS

Before you attempt to start eLink TCP for IMS the first time, make sure that the proper IMS definitions are in place.

If you are using RACF for security, you must set up a FACILITY Class Profile in RACF of IMSXCF.group.client. You can configure the group and client names for BEA eLink TCP for IMS.

Start BEA eLink TCP for IMS by submitting the JCL prepared in the "Task 6: Create JCL to Run eLink TCP for IMS" section.

For additional information on operating this product, refer to the BEA eLink TCP for IMS User Guide.

Task 8: Test the Installation

When you start BEA eLink 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. For additional information on using this product, refer to the BEA eLink TCP for IMS User Guide.

Distribution Libraries and Executables

The eLink TCP CD-ROM contains the following libraries and executable programs. After installing the eLink TCP for IMS software, verify that these libraries and programs are installed on your system.

Directory | Files
--- | ---
(top) | msgcat
CONTROL | beacrp01 beacrq01 beacrr01 beasvr01 beatcpi configbp configot
INCLUDE | beatcpi client server
JCL | install lnkbea31 lnkbea34 lnkbeail runotm
OBJECT | prebea31 prebea34 prebeail
SOURCE | beacrp01 beacrq01 beacrr01 beaotm beasvr01 dfsydru0 dfsyprx0

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.