Chapter 5: Mainframe Tier

This chapter describes any installation or configuration needed at the mainframe to support the deployment of eBiz or Data Access Transaction mainframe components in a CICS region.

Overview

The environment required to support the deployment of eBiz or Data Access Transaction mainframe components consists of:

• Micro Focus Mainframe Access (optional but recommended)

  Mainframe Access is a client-server connectivity tool that enables you to either offload mainframe source files or access them in place. Installing Mainframe Access also eases the installation of the SOA Express Server.

• SOA Express Server

  The SOA Express Server consists of run-time modules that are deployed to support CICS eBiz or Data Access Transactions. See the section SOA Express Server below for details.

• Middleware to link the middle and mainframe tiers. Either:
  • WebSphere MQ - see the chapter WebSphere MQ Middleware for details; or
  • ECI - see the chapter ECI Middleware for details. You need to install CICS Transaction Gateway, which you can install anywhere, not necessarily the mainframe.

SOA Express Server

The SOA Express Server consists of:

• Micro Focus CICS 3270 Bridge Exit (MER0BRIP)

  The Micro Focus CICS 3270 Bridge Exit intercepts certain CICS API calls from the legacy application (notably SEND MAP, SEND CONTROL, SEND TEXT and RECEIVE MAP). For each call, it passes appropriate message data between the legacy application and the mainframe component of the eBiz or Data Access Transaction, using the CICS Bridge facility. For more information about the CICS 3270 Bridge, refer to the IBM CICS External Interfaces Guide.

• Micro Focus Restart and Recovery Programs

  These are a set of related programs that can assist recovery in the event of a CICS region failure.

  When you define an eBiz Transaction, you specify whether it is recoverable and, optionally, its associated recovery exit program. You can also specify a recovery program for the project as a whole, to be used if there is no recovery program for a particular eBiz Transaction.

  • eBiz Transaction Global User Exit (MER0XRCI)

    This program is activated at the standard global exit points XRCINIT and XRCINPT. During a CICS warm or emergency restart, it copies records relating to recoverable eBiz Transactions from the CICS system log to an extrapartition transient data queue (TDQ) named MERJ, from the last keypoint up to the time of the failure.

  • eBiz Transaction Recovery Driver (MER0MERJ)

    If required, this program can be activated at CICS post-initialization time. It reads the MERJ queue and for each failed eBiz Transaction it activates the associated recovery exit program or, if none is specified, the project recovery program. MER0MERJ also collates data about each eBiz Transaction's in-doubt tasks (steps) in a set of temporary storage queues (TSQs). An eBiz Transaction is deemed to have failed if it does not have a termination record; an in-doubt task is one that is not known to have completed correctly.

  • eBiz Transaction Recovery Viewer/Player (MER0MERV)

    This program, when activated through the MERV transaction ID, reads the TSQs set up by MER0MERJ and displays a list of all in-doubt tasks. From this list you can view the underlying 3270 terminal workflow and screen images. You can use this information to determine the best course of action to complete the eBiz Transaction.

    MER0MERV can also be activated through the MERP transaction ID, in which case it presents a similar display for all tasks that had trace enabled.

  For more information about turning on logging, and associating recovery programs with SOA Express projects and individual eBiz Transactions, refer to the Defining eBiz Transactions chapter in your User's Guide.

• Micro Focus WebSphere MQ Middleware Interfaces for z/OS
  • MER0MQMW program

    Also known simply as the mainframe MWI, the MQMW transaction provides the interface between WebSphere MQ and the eBiz or Data Access Transactions.

    When using the CICS START bridge, MER0MQMW links via a CICS LINK to the eBiz or Data Access Transaction.

    When using the Link3270 Bridge, MER0MQMW links via a CICS START of transaction MQST under the authority of the user ID passed up from the client. See also MER0MQST program below.

  • MER0MQST program

    When using the Link3270 Bridge, program MER0MQMW executes a CICS START using transaction MQST, specifying the user ID entered in the client. This forces program MER0MQST to run under the specified user ID. Program MER0MQST then links via a CICS LINK to the eBiz or Data Access Transaction that runs under the specified user ID.

• Micro Focus Message Trigger Monitor (MER0MMTM)

  The MMTM transaction starts a separate instance of the mainframe MWI for each WebSphere MQ message received from the middle tier.

• Micro Focus ECI Middleware Interface for z/OS (MER0MECI)

  The MECI transaction provides the interface to handle the ECI calls between CICS Transaction Gateway and the eBiz or Data Access Transactions.

The SOA Express Server also includes the support modules listed in Table 5-1.

Setting up the Mainframe Environment

To set up the mainframe environment you must:

1. Check the software prerequisites
2. Install Mainframe Access
3. Install the SOA Express Server
4. Install WebSphere MQ or CICS Transaction Gateway. You can install the latter anywhere, not necessarily the mainframe.
5. Set up eBiz Transaction Restart and Recovery

Checking the Prerequisites

Software Requirements

Ensure the following are in place before continuing. For supported versions, see the chapter Third Party Software in your Readme:

• IBM OS/390 or IBM z/OS
• COBOL Compiler

  Applications must run with Language Environment (LE) extensions.

• IBM CICS Transaction Server

  Install one of the following to acquire the necessary CICS 3270 Bridge support, depending on the 3270 bridge software you are using:

  • IBM 3270 Bridge - IBM Customer Information Control System (CICS) Transaction Server (TS)
  • IBM Link3270 Bridge - CICS Transaction Server for z/OS

Installing Mainframe Access

Mainframe Access has a client component and three individually-installable server (mainframe) components, namely the Mainframe Access Standard, CICS and Endevor Servers. A Mainframe Access client is installed automatically with SOA Express. The Mainframe Access servers are included on the Host Connectivity CD supplied with Mainframe Express Enterprise Edition (for detailed installation instructions, refer to your Mainframe Access Installation and Usage Guide).

The Setup program prompts you to specify details about your mainframe. For an initial installation of Mainframe Access, the program generates a set of tailored JCL files and installation notes (text files). However, once the Mainframe Access Standard Server has been set up, the program can call upon Mainframe Access itself to upload and install additional or updated servers to the mainframe.

Installing SOA Express Server

When you install Mainframe Express Enterprise Server, the SOA Express Server installation files are installed in the mfe-install-dir\SOA Express\mainframe folder. This folder contains two sets of installation files - one set for IBM’s original IBM 3270 bridge and one set for the Link3270 bridge. JCL and PROC files are also provided; these files are common to both the original 3270 bridge and Link3270 bridge. Table 5-2 shows a list of the files provided.

The proc.txt and jcl.txt files referenced above are used to install both the 3270 and Link3270 bridge runtime modules.

To install or update the Server modules:

1. Pre-allocate the following TSO/mainframe datasets substituting a high level dataset name qualifier appropriate to your own site for your.name. Use the same qualifier for both datasets. These datasets will be used to store the files that you upload from the SOA Express CD.

   your.name.LOADLIB.X
   A sequential fixed block file
   organization  PS
   record format FB
   record length 80
   block size    3120

   your.name.DATA.X
   A sequential fixed block file
   organization  PS
   record format FB
   record length 80
   block size    6160

2. Depending on which 3270 bridge software you are using, transfer the appropriate set of two binary images from the mfe-install-dir\SOA Express\mainframe folder to the TSO/mainframe datasets you have just created. These files must be transferred to the mainframe in binary mode (no ASCII to EBCDIC conversion). These examples show the appropriate ftp commands, you can transfer the files using ftp, IND$FILE or any other file transfer tool that you have.
   • 3270 bridge
     • Transfer emrglseq.bin to your LOADLIB.X dataset. For example:

       put emrglseq.bin your.name.LOADLIB.X

     • Transfer emrgdseq.bin to your DATA.X dataset. For example:

       put emrgdseq.bin your.name.DATA.X

   • Link3270 bridge
     • Transfer put cg_link3270_loadlib.bin to your LOADLIB.X dataset. For example:

       put cg_link3270_loadlib.bin your.name.LOADLIB.X

     • Transfer cg_link3270_data.bin to your DATA.X dataset. For example:

       put cg_link3270_data.bin your.name.DATA.X

   Notes:

   • A CICS region can contain either the SOA Express runtime for the 3270 bridge or the Link3270 bridge, but not both. If you want to switch from one to the other, you must re-install the appropriate .bin files as outlined above. Existing eBiz Transactions are not affected by the switch and therefore do not require regeneration.
   • Cross region environments must have the same type of bridge runtime (either 3270 bridge or Link3270 bridge) installed in all participating regions.
3. Transfer the two text files from the SOA Express CD to any suitable PDS, substituting the name of the PDS for your.pds. These files must be transferred to the mainframe in ASCII mode. Although this example shows the appropriate ftp commands, you can transfer the files using ftp, IND$FILE or any other file transfer tool that you have:

   put jcl.txt your.pds(MERJCL)
   put proc.txt your.pds(CUSINST)

4. Customize the installation JCL by editing the MERJCL member:

   //MFICPI JOB (9999,9999),'DEFINE ',
   //   MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID;,
   //   MSGLEVEL=(1,1)
   //MLIB  JCLLIB ORDER=your.pds
   //*******************************************************
   //STEP01 EXEC CUSINST,
   //       PREFIX='your.name',
   //       CICS='your.cics.LOADLIB',
   //       CSD='CICSTS13.DFHCSD5',
   //       CSDUPLIB='CICSTS13.CICS.SDFHLOAD'
   //STEP30.SYSTSIN DD *
     RECEIVE INDDNAME(INFILE)
        DSN('your.name.LOADLIB')
   /*
   //STEP50.SYSIN DD *
   COPYOPER  COPY OUTDD=OUT1,INDD=((IN1,R))
   //

   1. Tailor the job card as needed.
   2. On the //MLIB line, specify the name of the PDS where the MERJCL and CUSINST members reside.
   3. Set the PREFIX variable to the high level qualifier that you used for the DATA.X and LOADLIB.X datasets.
   4. Set the CICS variable to the loadlib dataset for your CICS region.
   5. Set the CSD variable to the CSD dataset for your CICS region. (Note that you must have update authority to the CSD in order to run this job.)
   6. Set the CSDUPLIB variable to your DFHCSDUP library.
   7. Change the dataset in the RECEIVE DSN parameter to your.name.LOADLIB where your.name is the high level qualifier specified in the PREFIX variable.
5. Run MERJCL to:
   • Allocate two libraries: your.name.LOADLIB and your.name.DATA.
   • Populate the libraries with the data extracted from your.name. LOADLIB.X and your.name.DATA.X.
   • Copy the CICS load modules from your.name.LOADLIB to your.cics.LOADLIB.
   • Delete the group MFCMPGEN from the resource definition file your.cicsdefn.file by running the utility program DFHCSDUP from the library your.dfhcsdup.lib.
   • Allocate a dataset called your.name.DATALIB and place three members in it:
     • EMRGRDO

       Contains all the CICS DEFINE commands.

     • DELRDO

       Contains the command to delete the group MFCMPGEN.

     • MER0MMTM

       Supplied source for the Micro Focus WebSphere MQ Message Trigger Monitor (MER0MMTM).

   • Add the group MFCMPGEN to the resource definition file your.cicsdefn.file by running the utility program DFHCSDUP form the library your.dfhcsdup.lib.
   • Define all Micro Focus supplied transaction, program, terminal and queue definitions and install these into the group MFCMPGEN.
6. Once the job completes, newcopy all of the MER0* programs.
7. Customize CICS definitions to suit your environment. If you use a TCTUA, ensure that the MER2, MER3, MER4 and MER5 terminals that were installed as part of the above process are associated with a TYPETERM that contains a USERAREALEN value matching the size of the TCTUA. Not doing this can cause abends when user applications are run under the IBM 3270 Bridge.

Installing WebSphere MQ

If you are using WebSphere MQ, you must install the following items of WebSphere MQ middleware at the mainframe:

• IBM WebSphere MQ Server for z/OS Version 1 Release 2 or later.
• WebSphere MQ CICS Adapter (part of WebSphere MQ Server).
• WebSphere MQ Client Attachment Feature (not part of WebSphere MQ Server) if WebSphere MQ Client is installed on the middle tier.

For installation and customization instructions, refer to your IBM WebSphere MQ for z/OS Program Directory and IBM WebSphere MQ for z/OS System Management Guide.

After installing WebSphere MQ, define WebSphere MQ objects as described in the chapter WebSphere MQ Middleware.

Setting up eBiz Transaction Restart and Recovery

To set up the Restart and Recovery feature for your eBiz Transaction(s):

1. Allocate a file for the MERJ extrapartition transient data queue with the following properties:

   • A sequential variable blocked file
   • Organization PS
   • Record Format VB
   • Record Length 32752
   • Block size 32756

2. Add a MER0MERJ DD statement for the file that you allocated in step 1 to your CICS startup job. For example:

   //MER0MERJ DD DISP=SHR,DSN=MFHOST.CMPGEN.MERJ

   (In this example the file is called MFHOST.CMPGEN.MERJ but you can use any name that you like.)

3. Add a pre-initialization PLT statement for MER0XPLT (prior to the PLT statement for DFHDELIM):

   DFHPLT TYPE=ENTRY,PROGRAM=MER0XPLT

Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.