bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Java Adapter for Mainframe > Configuration and Administration Guide > Integrating Applications With WebLogic JAM |
Configuration and Administration Guide |
Integrating Applications With WebLogic JAM
This section provides information and steps to help guide you through the process of determining which applications you want to integrate, capturing the parameters necessary for configuration in the WebLogic Administration Console, and configuring your mainframe client applications.
This section provides information on the following subjects:
Understanding Application Integration with WebLogic JAM
WebLogic JAM enables you to easily reuse existing mainframe applications and integrate them with new applications built on WebLogic Server. CICS programs, IMS programs, and APPC programs can be integrated with WebLogic applications without changes to the original mainframe application. Existing mainframe applications can be exposed to WebLogic applications with configuration using the WebLogic Administration Console.
Application Integration Considerations
After defining the connectivity of the CRM to the back-end application environment, you must identify applications that you want to access. Accessing these applications include determining the link and the region where the mainframe application resides. It also includes determining how to handle data translation.
Discuss the following list of topics with your system administrator. These topics are relevant to both the WebLogic and mainframe application environments.
Data Translation
It is usually necessary to convert the format of the data passed between WebLogic Server applications and mainframe applications. It may require collecting information about data formats from a mainframe application (usually a copybook) for configuration of these applications. For additional information about using data translation in your applications, see the BEA WebLogic Java Adapter for Mainframe Programming Guide.
For information about using schemas to perform data translation with WebLogic JAM and WebLogic Integration, refer to the BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide.
Access to Mainframe and WebLogic Applications
In considering application integration, you should determine whether you need to access WebLogic applications from the mainframe or access mainframe applications from WebLogic.
When you create a service definition to expose a mainframe application to a WebLogic application, a service entry in the WebLogic Administration Console maps a service name to the name of the application on the mainframe. It also defines various other parameters depending on the type of mainframe application. You must also determine the mainframe region where the application resides as well as the link used by the CRM to access that region.
When a WebLogic application sends a request to WebLogic JAM with this service name, WebLogic JAM invokes the mainframe application that is mapped to the specified service name.
Applications built on WebLogic can also be invoked by mainframe applications via WebLogic JAM. By creating an export definition within the WebLogic Administration Console, you can configure mainframe applications to invoke EJBs, enqueue data to a JMS queue, or enqueue data to the workflow engine of WebLogic Integration. The export definition maps a service name, specified by the mainframe application, to a WebLogic application. When a mainframe application sends a request to WebLogic JAM with this service name, WebLogic JAM invokes the configured WebLogic application.
Exposing Mainframe Applications to J2EE Clients
WebLogic JAM enables CICS, standard IMS, and APPC/MVS applications (that run in CICS, IMS, or as a batch job) to be invoked from the WebLogic environment.
This section provides information on the following subjects:
Exposing a CICS Distributed Program Link as a DPL Service
Distributed Program Link (DPL) programs are CICS programs that accept a COMMAREA (short for communication area) as input. To configure WebLogic JAM to invoke a CICS DPL program, you must enter configuration parameters into the WebLogic Administration Console.
This section provides information about the following:
You will need certain parameter information to complete WebLogic JAM configuration, such as program name and WebLogic service name. You will also need to select the region in which the service is available. This section provides information to help you understand and capture the parameters you will need to enter into the WebLogic Administration Console in a later step.
Steps for Exposing a DPL Program
To configure WebLogic JAM to invoke a CICS DPL program, you must determine the data translation considerations and the program definition for the CICS region.
Step 1: Determine Data Translation Requirements
The data format of the DPL program is given by the declaration of the COMMAREA (short for communication area). For a DPL program written in COBOL, the COMMAREA is declared in the LINKAGE section of the program. You may need to obtain the COMMAREA copybook used in the LINKAGE section for use with WebLogic JAM's eGen Application Generator or WebLogic Integration. For information about obtaining and using the copybook declaration, refer to the BEA WebLogic Java Adapter for Mainframe Programming Guide.
For information about using schemas to perform data translation with WebLogic JAM and WebLogic Integration, refer to the BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide.
Step 2: Determine Program Access
In order to access a CICS program with a DPL request, there must be a CICS program resource definition that defines the CICS program to the CICS region. If a resource definition does not exist, ask your CICS administrator to create one.
A distributed program link occurs when the program is invoked on a "different" CICS system from the invoker. A special CICS program (DFHMIRS) handles the distributed request and invokes the designated CICS program. When the DFHMIRS program invokes the CICS program, the CICS program becomes associated with either the mirror transaction ID CSMI or CVMI, or an alternate transaction for DFHMIRS (as defined by the system administrator.) Transaction IDs are used in CICS for resource tracking and to restrict access to database resources.
It may be advantageous to use alternate transaction IDs to execute the DPL program so that resources can be tracked and database resources can be restricted. If this DPL program should be associated with a transaction ID other than CSMI or CVMI, then you must get the transaction ID from your CICS administrator.
WebLogic Administration Console Parameters for DPL Services
WebLogic JAM requires the parameters shown in Table 3-1to expose a CICS DPL program link as a DPL service.
Table 3-1 DPL Service Parameters
Steps for Configuring DPL Services in the WebLogic Administration Console To create the configuration information that WebLogic JAM needs to invoke this DPL program, use the WebLogic Administration Console to perform the following steps:
The List DPL Services page displays.
Exposing a Standard IMS Transaction Program as an APPC Service
Standard IMS applications use the DL/I application-programming interface to get input messages and insert output messages. IMS provides implicit APPC support that translates these DL/I calls into APPC communications. WebLogic JAM can invoke these IMS transactions via APPC if the transaction ID of the IMS application is configured. To make this work, you must configure WebLogic JAM with the IMS transaction ID of the program and the IMS regions in which this transaction is available.
This section provides information about the following:
You will need certain parameter information to complete WebLogic JAM configuration. This section provides information to help you understand and capture the parameters you will need to enter into the WebLogic Administration Console in a later step.
Steps for Exposing a Standard IMS Transaction Program
To configure WebLogic JAM to invoke a standard IMS transaction program, you must determine the data translation considerations and the program definition for the IMS region.
Use the following steps to configure WebLogic JAM to make an IMS transaction program available to WebLogic Server applications:
Step 1: Determine Data Translation Requirements
The data format of the IMS transaction program is given by the declaration of the Input/Output Program Control Block (IOPCB). When this program is written in COBOL, the IOPCB is declared in the LINKAGE section of the program. For information about obtaining and using the IOPCB declaration copybook from the LINKAGE section, refer to the BEA WebLogic Java Adapter for Mainframe Programming Guide.
For information about using schemas to perform data translation with WebLogic JAM and WebLogic Integration, refer to the BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide.
Step 2: Determine Program Access
In order to access an IMS application, there must be a transaction ID associated with the IMS program. Obtain this transaction ID and IMS region where the transaction program resides from your IMS administrator.
WebLogic Administration Console Parameters for an IMS Transaction Program Exposed as an APPC Service
WebLogic JAM requires the parameters shown in Table 3-2 to expose an IMS program as an APPC service.
Table 3-2 IMS Service Parameters
Steps for Configuring IMS Programs as APPC Services To create the configuration information that WebLogic JAM needs to invoke this IMS transaction program, use the WebLogic Administration Console.
The List APPC Services page displays.
Exposing an APPC/MVS Transaction Program as an APPC Service
An APPC application is an APPC/MVS batch job, CICS transaction, or IMS transaction that uses the CPI Communications API (CPI-C), or other specific APPC mainframe API, to explicitly communicate with other applications through an APPC conversation. Other examples of mainframe APIs include CICS Distributed Transaction Program (DTP) and the APPC/MVS API. These types of APPC applications may run as batch jobs, CICS transactions, or IMS transactions. You can configure WebLogic JAM to invoke the application through standard APPC protocol regardless of the environment in which the APPC application executes.
This section provides information about the following:
You will need certain parameter information to complete WebLogic JAM configuration. This section provides information to help you understand and capture the parameters you will need to enter into the WebLogic Administration Console in a later step.
Steps for Exposing an APPC/MVS Transaction Program as an APPC Service
To configure WebLogic JAM to invoke an APPC/MVS application as an APPC service, you must determine the data translation considerations and the program definition for the batch region.
Use the following steps to configure WebLogic JAM to make an APPC transaction program available to WebLogic Server applications:
Step 1: Determine Data Translation Requirements
Use WebLogic JAM's eGen utility to generate Java classes (DataViews) that can translate data to and from the mainframe format expected by this APPC program. For programs that are written in COBOL, the data is passed into the LINKAGE section. For information about obtaining and using the LINKAGE section of the data format of the request and response messages of the APPC program, refer to the BEA WebLogic Java Adapter for Mainframe Programming Guide.
For information about using schemas to perform data translation with WebLogic JAM and WebLogic Integration, refer to the BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide.
Step 2: Determine Program Access
In order to access an APPC/MVS application, there must be a transaction profile definition associated with the application. Obtain this transaction profile name where the transaction program resides from your system administrator.
WebLogic Administration Console Parameters for an APPC Transaction Program Exposed as an APPC Service
WebLogic JAM requires the parameters shown in Table 3-3 to expose an APPC/MVS program as an APPC service.
Table 3-3 APPC Service Parameters
Steps for Configuring APPC/MVS Transaction Programs as APPC Services To create the configuration information that WebLogic JAM needs to invoke this APPC program, use the WebLogic Administration Console.
The List APPC Services page displays.
Exposing J2EE Applications to Mainframe Clients
WebLogic JAM enables mainframe applications to invoke J2EE applications by mapping a service name to a J2EE application. The WebLogic Administration Console provides you with a way to configure a mapping between a service name and a J2EE application (EJB, JMS, or WebLogic Integration application).
When WebLogic JAM receives a request from a mainframe application with the specified service name, WebLogic JAM invokes the corresponding J2EE application.
This section provides information on the following subjects:
Configuring Mainframe Client Applications
WebLogic JAM enables CICS DPL, standard IMS, and APPC programs (that run in CICS, IMS or as a batch job) as mainframe clients to invoke J2EE applications. Depending on the type of mainframe client application, some configuration may be required on the mainframe. This configuration usually involves creating a program or transaction definition that points to WebLogic JAM.
It will usually be necessary to convert the format of the data passed between WebLogic Server applications and mainframe applications. It may be necessary to collect information about data formats from a mainframe application (usually a copybook) for use in data conversion. For further information about using data conversion in your application, refer to the BEA WebLogic Java Adapter for Mainframe Programming Guide.
The following sections provide information on additional configuration for each different type of supported mainframe clients:
CICS Distributed Program Link Clients
A CICS program can invoke a J2EE application by requesting a service configured for WebLogic JAM.
WebLogic JAM enables CICS programs on the mainframe to execute a CICS EXEC LINK call to a J2EE application as if it were a CICS program on a remote CICS region. The PROGRAM name parameter of the EXEC CICS LINK call may corresponds to a CICS program resource definition or these may be coded directly on the EXEC LINK statement. These two approaches are described in the following sections:
Specifying the SYSID Parameter on the EXEC CICS LINK Call
When the program link statement contains the SYSID(systemname) parameter, then the CICS program resource definition is not used. The values are taken directly from the LINK statement. Listing 3-1 provides a sample CICS LINK statement with the SYSID parameter specified:
Listing 3-1 Sample CICS LINK Statement
EXEC CICS LINK
PROGRAM (name)
SYSID(systemname)
COMMAREA(data-area)
LENGTH(data-value)
The parameters used to send the request to WebLogic Server (J2EE) applications are:
Using a CICS Program Resource Definition
An alternative to specifying the SYSID parameter in the EXEC CICS LINK call is to create a program resource definition in CICS. This program definition specifies REMOTESYSTEM and REMOTENAME parameters that point to WebLogic JAM. CICS applications can then specify the name of the program resource definition as the PROGRAM parameter of the EXEC CICS LINK call. Using this approach, CICS client programs do not have to be modified when the SYSID parameter changes; instead, only the program resource definition is changed.
Listing 3-2 provides a sample CICS program definition with the REMOTESYSTEM and REMOTENAME parameters specified:
Listing 3-2 Sample CICS Program Definition
DEFINE PROGRAM (TRADE)
GROUP(BEA)
DESCRIPTION(DISTRIBUTED PROGRAM LINK DEFINITION)
LANGUAGE(COBOL)
REMOTESYSTEM(BEA1)
REMOTENAME(TRADCLNT)
The parameters used to send the request to WebLogic Server (J2EE) applications are:
Standard IMS Programs
Standard IMS applications can use the DL/I application-programming interface to send output messages to J2EE applications. IMS provides implicit APPC support that translates DL/I calls into APPC communications. Using this implicit APPC support, standard IMS applications can insert output messages to J2EE applications.
IMS applications must issue a Change (CHNG) call to change its output destination to an alternate Program Control Block (PCB). This alternate PCB can specify an LU 6.2 descriptor that points to WebLogic JAM. Then an output message can be inserted by issuing an Insert (ISRT) call. This call forwards the output message to WebLogic JAM, which then sends the message to the configured J2EE application.
Note: WebLogic JAM does not support the insertion of multiple output messages; it only supports a single output message per invocation.
Work closely with your IMS administrator to define an LU 6.2 descriptor with the following parameters:
Note: For more information on configuring LU 6.2 descriptors, see IMS documentation.
APPC Programs that Run in CICS, IMS or as a Batch Job
An APPC program can invoke a J2EE application by using CPI Communications (CPI-C), APPC verbs, or CICS DTP commands. WebLogic JAM supports a single request/response conversation between the APPC program and the specified J2EE application. For more information on how WebLogic JAM supports single request/response conversations with APPC programs, see Programming Flows in the BEA WebLogic Java Adapter for Mainframe Programming Guide.
Some configuration is recommended when you use APPC to connect to a J2EE application. An APPC program that connects to a J2EE application must identify that it wants to connect to a remote system and a remote partner transaction. Rather than hard coding these parameters in the APPC program, the recommended approach is to store these parameters in side information.
Side information allows an APPC program to identify its partner program with a symbolic destination name. This symbolic destination name is specified in the APPC program, and the remote system and remote partner transaction are configured in the correspondingly named side information. This allows the remote system and remote partner transactions to change without having to modify the APPC program.
Use the following information to help your system administrator configure side information to connect to J2EE applications using WebLogic JAM.
CICS Side Information
CICS provides a Partner Resource Definition for defining side information. The Partner Resource Definition should define the following:
For more information on creating CICS partner resource definitions see CICS documentation.
APPC/MVS Transaction Program Profile Definition
IMS and APPC/MVS batch implementations of APPC provide the following side information parameters.
Exposing Enterprise Java Beans to the Mainframe
Mainframe applications can invoke eGen-generated session Enterprise Java Beans (EJBs). When WebLogic JAM receives a request from a mainframe application for this EJB, WebLogic JAM looks up the EJB and invokes it on behalf of the mainframe client.
See the BEA Java Adapter for Mainframe Programming Guide for more information on creating an EJB using the eGen utility.
To make an EJB available to mainframe applications, you need the following information:
WebLogic Administration Console Parameters for Enterprise Java Beans Exposed to the Mainframe
WebLogic JAM requires the parameters shown in Table 3-4 to expose a EJBs to the mainframe.
Table 3-4 EJB Parameters
Steps for Creating an Export Definition for an EJB
The Exported EJBs page displays.
Exposing JMS Events to the Mainframe
WebLogic JAM can enqueue data sent by mainframe applications to a JMS queue or topic. WebLogic JAM can use a Java class called a DataView to translate the mainframe data to XML. WebLogic JAM then enqueues the data to the specified JMS queue or topic.
See the BEA Java Adapter for Mainframe Programming Guide for more information on generating a DataView class.
Use the WebLogic Administration Console to perform the following configuration tasks for creating JMS definitions:
WebLogic Administration Console Parameters for JMS Events Exposed to the Mainframe
WebLogic JAM requires the parameters shown in Table 3-5 to expose a JMS events to the mainframe.
Table 3-5 JMS Parameters
Steps for Creating a JMS Event Definition
The JMS Events page displays.