QuickStart ESB proxy for a CICS program, using ant scripts.

QuickStart description

The purpose of this quickstart document is to quickly build a functioning sample 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 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.

Generate a Mule service proxy for a mainframe program

These steps will guide you through the process of generating an ESB proxy using ant scripts. There is an alternative method, using Eclipse plugins, that will be described later.

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

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

Go to folder samples/mule/quickstarts/legstar_proxy.

From the ant folder, run command ant -f build-pojo.xml, this will compile the target POJO.

From the ant folder, run command ant -f build-java2xs.xml. This should create a schema folder with a generated XML schema jvmquery.xsd.

If you open jvmquery.xsd you will notice that each Java class has been mapped to a COBOL data structure as well as an XML Schema type.

Next step turns the XML schema types into Java annotated classes. This is achieved with 3 ant scripts build-jaxb.xml, build-coxb-jvmqueryrequest.xml and build-coxb-jvmqueryreply.xml:

• Run command ant -f build-jaxb.xml. As a result, the src folder contains generated JAXB classes. These were derived from the generated XML Schema in the schema folder. Sources are also compiled, with binaries stored under build.

• Run command ant -f build-coxb-jvmqueryrequest.xml, then ant -f build-coxb-jvmqueryreply.xml. This should create binding classes which can be used as an alternative to the JAXB classes to achieve high performances.

The last step generates the transformers and Mule configuration.

From the ant folder run command ant -f build-cixs2mule.xml. By default, this script uses HTTP connectivity from CICS. For WebSphere MQ edit the script and follow directions.

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 if you chose HTTP, 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 chose MQ connectivity, the generated program uses the standard MQ API.

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.