QuickStart ESB proxy for a CICS program, using Eclipse plugins.

QuickStart description

This is an alternative to MuleLegStarProxyQuickStartAnt using Eclipse plugins rather than ant scripts.

Using Eclipse plugins, we will walk you through the process of integrating a backend IBM CICS system with a Mule service.

Once deployed, the generated Mule service will act as a proxy for a CICS COBOL program. In this example, the COBOL program acts as a client and the proxy Mule service invokes a POJO (plain old java object) method on behalf of the COBOL client.

If you would rather use WebSphere MQ instead of HTTP as the wire protocol to reach Mule from the mainframe then the Mule configuration will be:

Installation

Follow instructions in:InstallationInstructions.

The src/com/legstar/xsdc/test/cases/jvmquery folder of your legstar-mule installation, contains a sample POJO called JVMQuery.java. As the name implies, JVMQuery queries a JVM for system variables such as environment variables and locale. A caller can specify an array of environment variables for which values should be queried. If you look at the queryJvm method, you will notice that it takes a single data object called JVMQueryRequest as input and produces a data object called JVMQueryReply.

Start Eclipse and select menu option Help-->Software Updates-->Find and Install...

From there check the Search for new features to install option and click next.

Create a New Remote Site named legstar-mule and have the URL point to: http://dist.muleforge.org/legstar-transport//eclipse/update

With this new site selected, when you press the finish button, you are presented with all the plugins you need. Select the entire LegStar group, click next, accept the license terms and then click finish which should end the installation process.

Generate a Mule service proxy for a mainframe program

Start by creating a new Java project called MuleJvmquery and select the project.

Import the target POJO source code into your Java project. This is not strictly necessary (the POJO could already be on Mule classpath) but you will need these classes on your classpath at compile time anyway and you can take a moment to look into the source code.

The sources for the sample POJO are in the src folder of the product installation location, under package name com.legstar.xsdc.test.cases.jvmquery:

If you get compilation errors on the JRE 1.5 annotations (this sample POJO can also be exposed as a Web Service) you can just remove them.

If you look at the queryJvm method, you will notice that it takes a single data object called JVMQueryRequest as input and produces a data object called JVMQueryReply.

We will be generating all the artifacts that are needed to give a CICS COBOL program the ability to call the queryJvm method.

Map the Java data objects to XML Schema

First step is to generate an XML schema from the target Java data objects JVMQueryRequest and JVMQueryReply.

Select the Structures Mapping plugin:

Then select the "Java classes" source type and type the name of the target XML Schema, jvmquery.xsd:

Click next and click on the Select java classes from workbench link. This will pop up a class selection dialog which is empty at first. Type JVMQuery and the dialog will list all matching classes.

Select JVMQueryRequest and JVMQueryReply then click OK. You are presented with a recap of the classes you selected:

Click on the Finish button, this starts the mapping process and the generated XML Schema is opened. You will notice that each Java data object has been mapped to a COBOL data structure as well as an XML Schema type.

Bind the XML Schema to Java annotated classes

Next step turns the XML schema types into Java annotated classes.

From the package explorer view, expand your Java project. The generated jvmquery.xsd file should appear. Select the file, right click to show the context menu and then select LegStar-->Generate Binding classes:

jvmquery.xsd contains 2 complex types, select them both and click Finish:

Your package explorer should now display 2 new packages. A library containing the LegStar dependencies should have been added to the project Build path.

If you open JvmQueryReply.java, you will notice that classes exhibit annotations that bind java types both to XML and COBOL:

Generate an Mule service proxy for the JVMQuery POJO

The last step generates the queryJvmLocalUMO Mule service.

With your MuleJvmquery project selected, select the Operations mapping plugin:

Enter name jvmquery.cixs for the operations mapping file.

After you click finish, use the Add... button to create a new operation. The operation name can be any name you please but we will be using the target POJO method name. In our case, the JVMQuery POJO exposes a method called queryJvm so type in operation name queryJvm:

An operation maps to a mainframe program in a request/response exchange pattern. What you need to do at this stage is specify the input and output structures. You select these structures from the set that was bound during the previous step. These are displayed when you click on the Add button, successively for Input and for Output:

In our case, we select JVMQueryRequest for Input and JVMQueryReply for Output, because the JVMQuery POJO expects these data objects as input and output:

After you click on ok, the Generate button is now enabled. If you click on it, you should be able to select the Mule proxy target:

Clicking on ok again will get you to a multi-tab dialog showing pre-filled generation options:

You need to provide the generator with the class name of the target JVMQuery UMO. In our case, Mule will directly use the POJO to process mainframe requests. If you click on the browse button, you are presented with a dialog that allows you to pick up a class from the Eclipse build path. If you type JVMQuery, you should see:

The first class in the list is our implementation so select it and click OK.

Check the Deployment options tab. Your Mule proxy component will be listening for incoming
requests from the mainframe on the host name, port number and path provided here:

There is also a choice of COBOL client sample programs you can generate. These programs are examples you can use to invoke the component from your own program. DFHWBCLI is a simple API that comes with CICS since version TS 2.3 and is still available in recent CICS versions. The CICS WEB API is part of CICS since TS 3.1 and above. Finally, you can use the LegStar own HTTP client API. These are C libraries that are part of the LegStar z/OS distribution.

As an alternative to HTTP, you can select WebSphere MQ connectivity to the mainframe:

If you selected WebSphere MQ rather than HTTP, the generated COBOL sample uses MQ APIs.

When you are satisfied, click on Finish which will generate the Mule proxy:

Under src/com/legstar/test/cixs/mule/jvmquery you will find the generated transformer classes that turn java value objects or XML to mainframe byte arrays. These transformers can be used in any Mule configuration and are independant from the transport chosen.

Under legstar_proxy, a Mule configuration sample is generated:

mule-proxy-config-jvmquery-http.xml

Is the Mule service descriptor. This implements a Request/Response exchange pattern. Upon receiving data from the mainframe, a transformer turns that data into a JvmQueryRequest java data object. On return from invoking the POJO, another transformer turns the JvmQueryReply java data object into a mainframe reply.

Check the connectivity parameters in the configuration file to see if they fit your needs.

The ant folder contains the build.xml generated ant script which bundles the mule-legstar-jvmquery.jar file and deploys the generated component to your Mule installation (Defined by the MULE_HOME environment variable).

Testing the Mule service proxy

The cobol folder contains a generated skeleton COBOL CICS program that you can use to test the ESB proxy. Edit this code and perform the following changes:

Right after the "TODO set input values in COM-REQUEST" comment, insert these lines of code:

           MOVE 2 TO envVarNames--C OF COM-REQUEST.           
           MOVE 'MULE_HOME' TO envVarNames OF COM-REQUEST(1). 
           MOVE 'JAVA_HOME' TO envVarNames OF COM-REQUEST(2).

Right after the "TODO do something useful with data returned in COM-REPLY" comment, insert these lines of code:

           STRING 'INVOKE-SERVICE success. Server language is '     
                  DELIMITED BY SIZE                                 
                  language OF COM-REPLY                             
                  DELIMITED BY SPACE                                
                  INTO ERROR-MESSAGE.                               
           EXEC CICS SEND TEXT FROM(ERROR-MESSAGE) FREEKB END-EXEC. 
                                                                    
           DISPLAY 'country=' country OF COM-REPLY.                 
           DISPLAY 'currencySymbol=' currencySymbol OF COM-REPLY.   
           DISPLAY 'formattedDate=' formattedDate OF COM-REPLY.     
           DISPLAY 'language=' language OF COM-REPLY.               
           DISPLAY 'envVarValues--C=' envVarValues--C OF COM-REPLY. 
           DISPLAY 'envVarValues(1)=' envVarValues OF COM-REPLY (1).
           DISPLAY 'envVarValues(2)=' envVarValues OF COM-REPLY (2).

You should now be able to upload this program onto your mainframe and get it compiled and defined to your CICS region. Please note that this program calls the CICS DFHWBCLI program defined in the CICS standard DFHWEB group. Alternatively, legstar-mule supports the new EXEC CICS WEB API or even supports older version of CICS with its own HTTP library.

If you associate the JVMQUERY program to a CICS transaction and run that transaction, it should return with a short message telling you which locale
the Mule server is actually using. The standard CICS/LE CEEMSG and CEEOUT should show detailed traces.