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

Web-enabling an IBM 3270 Application with eLink Adapter for Mainframe and CrossPlex

BEA eLink products use ISC DPL to access CICS applications on the mainframe. When using eLink Adapter for Mainframe, these applications must be architected to separate the business logic from the presentation logic. This requirement is eliminated for IBM 3270 applications by integrating eLink Adapter for Mainframe with CrossPlex by SofTouch.

Integration of eLink Adapter for Mainframe with CrossPlex provides the following benefits:

- Rapid 3270 integration

- Access to applications with unavailable or inaccessible source code

The eLink Adapter for Mainframe Gateway can be easily configured to link to CrossPlex through DPL instead of the original intended application. This link passes CrossPlex all control information necessary to dynamically initiate the CICS transaction through a virtual terminal maintained by Front End Programming Interface (FEPI) or CICS Bridge. The virtual terminal is defined by CrosssPlex. This scenario requires no host code modification.

Overview of the eLink Adapter for Mainframe and CrossPlex Architecture

The combination of eLink Adapter for Mainframe and CrossPlex allows customers to efficiently create, test, and deploy transactional e-business applications that can be scaled as business needs demand.

CrossPlex installs and operates on the OS/390 mainframe. It runs in a CICS region but has the ability to make Virtual Telecommunications Access Method (VTAM) connections to other systems, such as Information Management System (IMS). It makes these connections by creating a virtual terminal, using an IBM component of CICS called FEPI or another component called CICS Bridge. Figure7-1 illustrates the process.

Figure 7-1 CrossPlex Architecture

Developing an ATMI Client that Invokes a CrossPlex Script on the Mainframe

The following sections contain a scenario that shows how to develop an ATMI client that invokes a CrossPlex script on the mainframe.

Note: Although the sample code in this section represents typical applications, it is intended for example only and is not supported for actual use.

Sample code for the UNIX or Windows portion of this scenario is included in the elink/sna/crossplex directory that is installed with eLink Adapter for Mainframe. Refer to your CrossPlex installation for examples of the mainframe code. Refer to the BEA eLink Adapter for Mainframe Installation Guide for the list of files. Refer to your CrossPlex Middleware Programmer's Guide for detailed information on how to complete the tasks described in this scenario.

The following tasks are required to invoke the sample CrossPlex script on the mainframe:

- Task 1: Create a CrossPlex Script

- Task 2: Create a View Definition Describing the Application Data

- Task 3: Code Your Client Program

- Task 4: Configure eLink Adapter for Mainframe to Communicate with CrossPlex

- Task 5: Use the Application

Task 1: Create a CrossPlex Script

A CrossPlex script provides the business logic to execute one or more 3270 transactions running on the mainframe. Transactions in any VTAM system, such as CICS or IMS, can be accessed. When a script executes in CrossPlex, it usually requires some input data, such as customer number, or part number. This inbound data is passed from the application in a container called a record definition.

During execution, a script selects and optionally reformats data from the screen displays of the executed 3270 transactions. This selected data is returned to the application in an outbound record definition.

Note: Record definitions do not necessarily conform to any known data record in a file. A record definition is simply a description of a series of data fields being passed to and from a script.

Record definitions are created with the CrossPlex development system. An online editor is used to define each field in the record, along with its length and type (alpha, numeric, binary, packed). A single record definition may be used for both inbound and outbound data, or two definitions may be used.

Another of the CrossPlex development tools creates a COBOL copybook, using a record definition as input. The generated copybook is stored in a PDS member, where it can be copied into your application program as needed.

Figure7-1 illustrates the processing flow from the eLink Adapter for Mainframe front end to retrieve data from one or more mainframe transactions.

The following steps describe how a CrossPlex script may be created for this scenario.

Step 1: Prepare Inbound Record Definition

Assign a record name and description, then define each data field to be passed to the CrossPlex script. The process of defining a record definition is described in detail in the CrossPlex Middleware Programmer's Guide.

To illustrate, assume the mainframe application is a simple name/address display that requires a customer number as input. For this example, the inbound and outbound record definition are different, though the same record definition can be used for both. Figure7-2 shows how the inbound record might appear.

Figure 7-2 Inbound Record Illustration

The inbound data required by the mainframe transaction is CUSTNO, a seven-byte alphanumeric field beginning in position one of the record.

Step 2: Create a Copybook of the Inbound Record Definition

Store the generated copybook in a PDS member where it can be easily copied to the development system. For a complete description of the process of creating a COBOL Copybook from a record definition, refer to the CrossPlex Middleware Programmer's Guide.

Continuing with the same example, Listing7-1 shows an example of how a COBOL copybook generated from the previously illustrated record definition (inrec) might look.

Listing 7-1 COBOL Copybook Generated from Inbound Record

>     *****************************************************************
>     *	INREC	- Sample inbound record definition		*
>     *****************************************************************
>       01	INREC-START.
>     	05	INREC-CUSTNO			PIC X(007).

Step 3: Create an Outbound Record Definition and Copybook

If the outbound data is to use a different record format from the inbound, steps 1 and 2 are repeated to prepare the outbound record definition and copybook. For this example, Figure7-3 and Listing7-2 show examples of how the the outbound record definition and copybook might look.

Figure 7-3 Outbound Record Definition

Listing 7-2 COBOL Copybook Generated from Outbound Record

>     *****************************************************************
>     *	OUTREC	- Sample outbound record definition		*
>     *****************************************************************
>     01  OUTREC-START.
>         05  OUTREC-CUSTNO                      PIC X(007).
>         05  OUTREC-NAME                        PIC X(025).
>         05  OUTREC-ADDR1                       PIC X(025).
>         05  OUTREC-ADDR2                       PIC X(025).
>         05  OUTREC-CITY                        PIC X(025).
>         05  OUTREC-STATE                       PIC X(002).
>         05  OUTREC-ZIP                         PIC 9(005).
>         05  OUTREC-PHONE                       PIC 9(007).
>         05  OUTREC-BUSPHONE                    PIC 9(007).
>         05  OUTREC-SDATE                       PIC 9(006).
>         05  OUTREC-DUEDAY                      PIC 9(002).
>         05  OUTREC-DEPOSIT                     PIC 9(006).
>         05  OUTREC-TOTDUE                      PIC 9(006).
>         05  OUTREC-PAYHIST                     OCCURS 006 TIMES.
>             10  OUTREC-PMONTH                  PIC 9(003).
>             10  OUTREC-PAMOUNT                 PIC 9(006).
>             10  OUTREC-PDATE                   PIC 9(006).
>             10  OUTREC-PAMTDUE                 PIC 9(007).
>         05  OUTREC-FILLER                      PIC X(019).

Step 4: Prepare the CrossPlex Script

Scripts can be coded using the CrossPlex script editor, or they may be coded on any external editor and imported into the CrossPlex control file. The CrossPlex script language and the process of creating a script are described in the CrossPlex Middleware Programmer's Guide.

Note: In the CrossPlex documentation, scripts are also known as command streams and stream objects.

A script is prepared to navigate through a series of 3270 transactions in the same manner as a terminal operator. The script acts as a virtual operator, performing a log-on to the OLTP system, sending inbound terminal data as if keyed on a keyboard, examining the returned screen display for correct execution, and selecting data from the screen if needed. Any number of transactions may be executed. The script language also provides a method of linking to a user program on the mainframe in order to perform direct retrieval of data that may not be available in a 3270 transaction display.

Continuing with the example of name/address data retrieval, Listing7-3 shows an example of how the script might appear.

Listing 7-3 CrossPlex Script

>     * Establish connection to region defined as THISCICS in FEPI setup,
>     *   Then clear the terminal screen.
>     	Callcpx Target("THISCICS") Pool("POOLM2");
>        Callcpx Aid(CLEAR);
>     *  INVOKE LEGACY MENU
>     	 Callcpx Msgarea("YHPR,MWDEMO");
>     *  RESPOND TO MENU WITH OPTION 1
>     	 Callcpx Rowcol(20033) "1";
>     *  RESPOND TO KEY PROMPT WITH CUSTOMER NUMBER
>     	 Callcpx Rowcol(05023) &INREC-CUSTNO;
>     *  SELECT NAME/ADDRESS FIELDS INTO OUTREC
>     	 Select Record("OUTREC")
>     	   Rowcol(05023) Rfield("OUTREC-CUSTNO")
>     	   Rowcol(06023) Rfield("OUTREC-NAME")
>     	   Rowcol(07023) Rfield("OUTREC-ADDR1")
>     	   Rowcol(08023) Rfield("OUTREC-ADDR2")
>     	   Rowcol(09023) Rfield("OUTREC-CITY")
>     	   Rowcol(10023) Rfield("OUTREC-STATE")
>     	   Rowcol(11023) Rfield("OUTREC-ZIP");
>     *  PF3, RETURN TO MENU
>     	 Callcpx Aid(PF3) Inlength(0);
>     *  RESPOND TO MENU WITH OPTION 2
>     	 Callcpx Rowcol(20033) "2";
>     *  RESPOND TO CUSTOMER DETAIL KEY PROMPT WITH CUST NUMER
>     	 Callcpx Rowcol(03069) &INREC-CUSTNO;
>     *  SELECT CUSTOMER DETAIL FIELDS INTO OUTREC
>     	 Select Record("OUTREC"
>       	   Rowcol(05059) Rfield("OUTREC-PHONE")
>     	   Rowcol(05072) Rfield("OUTREC-BUSPHONE")
>     	   Rowcol(06068) Rfield("OUTREC-SDATE")
>     	   Rowcol(08046) Rfield("OUTREC-DUEDAY")
>     	   Rowcol(08005) Rfield("OUTREC-DEPOSIT")
>     	   Rowcol(19069) Rfield("OUTREC-TOTDUE")
>     	   Groupnam("OUTREC-PAYHIST")
>     	     Rowcol(12001) Rfield("OUTREC-PMONTH")
>     	     Rowcol(12006) Rfield("OUTREC-PAMOUNT")
>     	     Rowcol(12014) Rfield("OUTREC-PDATE")
>     	     Rowcol(12024) Rfield("OUTREC-PAMTDUE");
>     *  PF3, RETURN TO MENU
>     	 Callcpx Aid(PF3);
>     *  PF3, RETURN TO CLEAR SCREEN
>     	 Callcpx Aid(PF3);

Note: This example illustrates row/column addressing of screen data. CrossPlex also provides a method of assigning screen field names to avoid specific row/column references.

Step 5: Handling the Mainframe Sign-on

Most VTAM systems require the user to sign-on in the target region when first connecting. This procedure is also true when connecting to a target region with CrossPlex. This sign-on requirement can be handled in any one of the following ways:

- Interact with a user sign-on transaction in the script.

The most common situation, especially for CICS, requires that your script handle the sign-on. Many users have CICS configured so that upon the first connection, the terminal is presented with a sign-on panel that may have been customized for the installation. If this is the case, the first CALLCPX command of the script returns the sign-on screen to the script and a subsequent CALLCPX must send a valid user ID and password.

- Let CrossPlex perform a short-form sign-on.

Supplying a valid user ID and password in the CrossPlex header will cause CrossPlex to perform a short-form sign-on before sending the first transaction data from the script.

The mainframe sign-on is discussed in the CrossPlex Middleware Programmer's Guide.

Step 6: Test and Debug the Script

A script that will execute on the mainframe without connecting it to the front-end application can be fully tested and debugged. CrossPlex provides a variety of execution and debugging tools to ensure the back-end portion of the application is operating properly.

When the script is performing as required and returning correct data, the front-end of the application can be prepared and the script and front-end can be connected together.

The process of testing and debugging a script is described in the CrossPlex Middleware Programmer's Guide.

Task 2: Create a View Definition Describing the Application Data

This view definition should include both the CrossPlex header and the application data. It may be necessary to create two such views, one for the request data and the other for the response. In this example, the user data is all of type character and thus a combined view is usable. The view file in Listing7-4 describes the CrossPlex header. This file is the cpxview.v file included in the elink/sna/crossplex sample directory of your eLink Adapter for Mainframe installation.

Listing 7-4 CrossPlex Standard Commarea (Tuxedo VIEW)

>     #
>     #    compiled using "viewc -n cpxview.v"
>          VIEW CPXVIEW
>     # type   cname      fbname  count   flag   size   null  comment
>          char   xpcmd      -       4       -      -      -
>          long   xpexcep    -       1       -      -      -
>          short  xpexrc     -       1       -      -      -
>          short  xpextl     -       1       -      -      -
>          short  xpexmsg    -       1       -      -      -
>          short  xpexmof    -       1       -      -      -
>          char   xpexxp1    -       4       -      -      -
>          long   xpexxp2    -       1       -      -      -
>          long   xpexxp3    -       1       -      -      -
>          long   xpoptpl    -       1       -      -      -
>          char   xptarg     -       8       -      -      -
>          char   xpfpool    -       8       -      -      -
>          char   xpaid      -       6       -      -      -
>          char   xpinsc     -       8       -      -      -
>          char   xpotsc     -       8       -      -      -
>          short  xpcrow     -       1       -      -      -
>          short  xpccol     -       1       -      -      -
>          char   xpuser     -       8       -      -      -
>          char   xppass     -       8       -      -      -
>          char   xpfnode    -       8       -      -      -
>          short  xpfconv    -       4       -      -      -
>          char   xpdbugq    -       8       -      -      -
>          char   xpassoc    -       8       -      -      -
>          char   xpmode     -       4       -      -      -
>          char   xpxlate    -       8       -      -      -
>          short  xpilng     -       1       -      -      -
>          short  xpalng     -       1       -      -      -
>          short  xpolng     -       1       -      -      -
>          char   xptermop   -       1       -      -      -
>          char   xpusd      -       1       -      -      -
>          short  xpusdwt    -       1       -      -      -
>          char   xpsaveid   -       8       -      -      -
>          char   xplstrm    -       8       -      -      -
>          char   reserved11 -       8       -      -      -
>          char   xpprog     -       8       -      -      -
>          short  xprows     -       1       -      -      -
>          short  xpcols     -       1       -      -      -
>          char   xpstrm     -       8       -      -      -
>          short  xptimot    -       1       -      -      -
>          char   xpxltyp    -       1       -      -      -
>          char   xpdbugs    -       1       -      -      -
>          long   xpmaptr    -       1       -      -      -
>          long   xpmalng    -       1       -      -      -
>          long   xpmdlng    -       1       -      -      -
>          char   xpmause    -       1       -      -      -
>          char   xprecnm    -       8       -      -      -
>          char   xpecho     -       1       -      -      -
>          char   xpctyp     -       1       -      -      -
>          char   xpdfile    -       8       -      -      -
>          char   xpdtran    -       4       -      -      -
>          char   xpferrs    -       8       -      -      -
>          char   reserved99 -       21      -      -      -
>          char   xpmarea    -       1000    -      -      -
>          END

In this view, the field named xpmarea is the generic character block that contains the application data. This field may be replaced with specific field definitions for your application. This field is not limited to 1000 bytes. The header plus the data in xpmarea should not exceed 32K. If more than 32K of outbound data is to be returned, it must be defined as an alternate area (see the CrossPlex Middleware Programmer's Guide).

The following view describes the response data from the CrossPlex script. It must agree with the COBOL copybook generated from the outbound record as previously shown in Listing7-2.

Listing 7-5 CrossPlex Outbound Record

>     /* *****************************************************************
>        MWDREC - Middeware Demo Application, Consolidated Record
>     ***************************************************************** */
>     #pragma pack(1)
>     typedef struct tagMWDRECPAYHIST
>      {
>         unsigned char  pmonth    [3];
>         unsigned char  pamount   [6];
>         unsigned char  pdate     [6];
>         unsigned char  pamtdue   [7];
>      } MWDRECPAYHIST;

>     typedef struct tagMWDREC
>      {
>         unsigned char  custno   [7];
>         unsigned char  name     [25];
>         unsigned char  addr1    [25];
>         unsigned char  addr2    [25];
>         unsigned char  city     [25];
>         unsigned char  state    [2];
>         unsigned char  zip      [5];
>         unsigned char  phone    [7];
>         unsigned char  busphone [7];
>         unsigned char  sdate    [6];
>         unsigned char  dueday   [2];
>         unsigned char  deposit  [6];
>         unsigned char  totdue   [6];
>         MWDRECPAYHIST  payhist  [6];
>      } MWDREC;

Process the view with the view compiler using a command such as:

viewc -n cpxview.v

This command produces a C header file, cpxview.h, that is used to construct the client program.

Task 3: Code Your Client Program

The client program is written to call CrossPlex in CICS through eLink Adapter for Mainframe. CrossPlex executes the application transactions and gathers data from them as required. Data is returned to the program for display.

The xplxtuxs.c file in your eLink/sna/crossplex installation directory is a sample of a client program for use with eLink Adapter for Mainframe.

Task 4: Configure eLink Adapter for Mainframe to Communicate with CrossPlex

BEA eLink Adapter for Mainframe must be configured to communicate with the CICS region that hosts the CrossPlex installation. Refer to the BEA eLink Adapter for Mainframe User Guide for details on configuring eLink Adapter for Mainframe. Listing7-6 is a fragment of an eLink Adapter for Mainframe DMCONFIG file that illustrates the remote service entries that are needed. These entries must be modified to reference the actual local and remote domains in the configuration.

Listing 7-6 Sample DMCONFIG File Fragment

>     CPXSTREAM	AUTOTRAN=N
>     		LDOM=ldom1
>     		RDOM=SNAG1
>     		CONV=N
>     		RNAME="XPLXSBEA"
>     		INBUFTYPE="VIEW:CPXVIEW"
>     		OUTBUFTYPE="VIEW:CPXVIEW"
>     		FUNCTION="DPL"

Task 5: Use the Application

To use the application, complete the following steps:

- Step 1: Set Your Environment Variables

- Step 2: Start Your ATMI System

- Step 3: Run the Client Program

Step 1: Set Your Environment Variables

Set the following environment variables:

VIEWFILES=cpxview.v

VIEWDIR=<directory containing cpxview.v>

Step 2: Start Your ATMI System

Use the tmboot command to start the ATMI application containing the eLink Adapter for Mainframe Gateway. Verify that the Gateway starts successfully and that connection to your mainframe is established.

Step 3: Run the Client Program

The syntax for invocation of the sample client program is:

mwdemo {options..}

In this argument, options may be defined in one or more of the following ways:

-c customer

  Specifies the number of the customer to access from the mainframe application.

-t target

  Specifies the CrossPlex FEPI target to access.

-f pool

  Specifies the CrossPlex FEPI pool to access.

-u userid

  Specifies the user ID to use for mainframe access.

-p password

  Specifies the password to use for mainframe access.

When the program runs successfully, it prints a report similar to the example in Listing7-7.

Listing 7-7 Example of Report Produced from Client Program

>     Consolidated Customer Inquiry

>     Customer Number:  	1234567
>     Customer Name:    	Acme
>     Street Address:   		123 Main St.
>     Main Address:		    PO Box 500
>     City, State Zip:  	Plano, TX 75093
>     Home Phone:		    555-1234
>     Business Phone:   	555-4321
>     Start date:	       08/12/61
>     Initial Deposit:  	$ 5200.00
>     Total Amout due:  	$ 125.00

>     Payment history for previous six months:

>     Month 	Amount   	Date 		Amount due

>     Jan   	100.00   	01/12/00  		$ 625.00
>     Feb   	100.00   	02/10/00  		$ 525.00
>     Mar   	100.00   	03/14/00  		$ 425.00
>     Apr   	100.00   	04/12/00  		$ 325.00
>     May   	100.00   	05/12/00  		$ 225.00
>     Jun   	100.00   	06/13/00  		$ 125.00

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