|
|
|
|
|
|
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:
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
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 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
*****************************************************************
* INREC - Sample inbound record definition *
*****************************************************************
01 INREC-START.
05 INREC-CUSTNO PIC X(007).
Listing 7-2 COBOL Copybook Generated from Outbound Record 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 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:
*****************************************************************
* 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).* 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);
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.
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
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
-t target
-f pool
-u userid
-p password
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.
|