Reference: 2005/04/26

Adapter Tutorial

Tutorial 2 : Invoking a CICS transaction through the Oracle AS Adapter This tutorial describes the steps needed to integrate the BPEL Process Manager with CICS through the Oracle AS Adapter for CICS. The Adapter uses EXCI (EXternal Call Interface) to invoke CICS transactions and uses COMMAREA transactions to exchange message buffers. The Adapter creates a metadata schema for CICS by importing COBOL copybooks and transforming them into mapping definitions for Oracle Connect for CICS on the OS/390 machine and by associating the data structures with specific physical files. The Adapter is also capable of receiving events from CICS. These steps are not covered as part of this tutorial.

Tutorial 2 : Invoking a CICS transaction through the Oracle AS Adapter............................................................................................ 1

Overview......................................................................................................................... 1 Configuring the CICS Transaction ................................................................................. 1 Configuring a BPEL Service to invoke the above Adapter Service ............................. 11 Deploying and testing the BPEL process...................................................................... 15

Overview The Oracle AS Adapter for CICS 10.1.2 is part of the Oracle AS Adapters CD. The Oracle AS Adapter for CICS consists of 2 run-time components – Oracle Connect process that talks to the various legacy/mainframe system and a pass-through JCA Adapter that gets deployed on top of the Oracle Application Server platform. The Oracle Studio is used for design-time configuration of the run-time components. The Adapter Framework (FW) is used for the bidirectional integration of the Oracle AS Adapter for CICS with BPEL Process Manager. Adapter FW is based on open standards and employs the Web Service Invocation Framework (WSIF) technology for exposing the underlying JCA Interactions as Web Services. It also functions as a pseudo JCA 1.5 container for deployment on top of J2EE servers that support JCA 1.0 specification only.

Configuring the CICS Transaction Oracle Connect is a component that resides on the legacy and mainframe platform. It

consists of native adapters for communicating with the mainframe application and data stores. The design-time configuration of Oracle AS Adapter for Legacy and mainframes consists of 2 steps. The first step involves using Oracle Studio for configuring the Oracle Connect engine and the metadata is stored on a file system at the Oracle Connect end. The second step consists of exposing the metadata obtained in the first step through a WSIL servlet. The BPEL Partner Link activity has a WSIL browser which inturn connect to the WSIL servlet. The WSIL servlet communicates with Oracle Connect and exposes the metadata as WSDL with JCA extensions. The WSIL servlet is deployed in the BPEL J2EE container and it needs to be up and running at design-time.

1. The Oracle Studio connects to Oracle Connect running on the mainframe. Oracle Connect for CICS needs to be installed and configured on the OS/390 machine. The steps for the above is detailed in the Adapter User Guide. Go to the “Configuration Explorer” View and select “Machine” folder. Right-click and select “New”. This will bring up the connection panel on the right-had side. Specify the connection parameters as shown below.

2. Expanding the connection object shows a “Bindings” folder for defining

workspaces (domains) and a default workspace called “Nav”. Expanding the binding shows an “Adapters” and “Events” folder. The “Adapters” folder is used to define JCA outbound interactions (request-response services) and the “Events” folder is used to define JCA Inbound Interactions (event services).

3. The “DataSource” folder is used to define a CICS connection. Right-click on the “DataSource” folder and define the CICS connection parameters as shown below.

4. You need to perform the following steps to create a JCA Outbound Interaction (request-response service). Select Adapters folder , right-click and select the New

Adapter option. This brings up the New Adapters screen as shown in the figure. Select the type of Adapter that you wish to create. This example uses a CICS Adapter to connect to a CICS transaction.

5. Select the Adapter instance that was created. Right-click and select Open Import Perspective to import COBOL copybooks.

6. Right-click on the Adapter instance and select New Import. Follow the steps shown below to import COBOL copybooks

7. Select Add to proceed further.

.

8. This example uses a COBOL copybook found on the local machine.

9. Navigate to the location where the files reside and select the files to be transferred and the transfer method (Text or Binary)

10. The Apply Filters pane shows up. Expand the cobolFilter and accept all default setting for the sample copybook.

11. Select Next to proceed to Step 3 of 5 12. The AddInteractions pane shows up. Specify the interaction parameters. The

CICS transaction used in this example is “ATTUNDPL”. The interaction is named “FindInvoiceRecord” and takes “SHIP_DATA” as input and output parameters.

13. Select Next to generate XSD files.

14. Select Next again to export the metadata to Oracle Connect running on the mainframe.

15. Navigate to the “Edit Metadata” perspective as shown in the figure below.

The Oracle Studio has a test run capability that can be used to test the interactions.

Configuring a BPEL Service to invoke the above Adapter Service

1. Create a BPEL process using the synchronous process template. The default “Client” partnerlink and the “inputVariable” and “outputVariable” gets generated. Please refer to the BPEL PM Developer’s Guide for further details.

2. Drag & drop a BPEL PartnerLink activity. Select the “WSIL Browser” option (torchlight symbol).

3. Expand the WSIL browser to view the Adapter Services as shown in the figure.

The WSDL file for the Adapter Service is created dynamically and the URL for the example is http://127.0.0.1:9700/BPELConsole/wsil/adapters/legacy/mvs08/IRPCDINI/NAVIGATOR/AD_CICS_COBOL/FindInvoiceRecord?wsdl

4. The configured PartnerLink –CICS Service is as shown below.

5. Drag & drop an invoke activity to point to the PartnerLink defined in the above

step. Browse the available list of global variables and pick the process input and output variables – “inputVariable” and “outputVariable”. These represent the input and output of the CICS Service.

6. Edit the “inputVariable” and “outputVariable” to point to the CICS Service request and response message types as shown below. Navigate to the Structure Pane and select Variables folder. Expand the folder to show the “inputVariable” and “OutputVariable”.

7. The end to end BPEL process is shown below

Deploying and testing the BPEL process

1. Edit the deployment descriptor of the legacy adapter – “oc4j-ra.xml” with the appropriate values as shown below.

2. Deploy the BPEL process from Jdeveloper . Navigate to the BPEL project. Right-click to select the “deploy” option. Select the BPEL server, specify password and version and finally select “OK”.

3. Bring up the BPEL Console to verify that the deployment was successful and to test the Adapter Service. These steps are captured below.