Table of Contents
We show 2 use cases in the following sections.
The Adapter use case is one where you start from a commarea-driven COBOL CICS program (LSFILEAE) and turn it a Web Service.
The Proxy use case is one where you started from a WSDL (Microsoft LIVE search) and access the LIVE Web Service from a COBOL CICS program.
You have the choice between using ant scripts and Eclipse plugins.
The process starts by translating COBOL Structures to XML Schema.
You can use the build-cob2xsd.xml ant script from the samples/quickstarts/adapter_lsfileae folder as your starting point.
The sample script translates the lsfileae COBOL program from the cobol folder to an XML schema called lsfileae.xsd in the schema folder.
The script executes a single ant task: cob2xsd.
Generally, there are 4 things you will need to check in build-cob2xsd.xml in order to adapt it to your needs:
Make sure the classpath setting for the cob2xsd task is correct. The fileset should point to the location where you installed LegStar.
The target parameter should point to the location where you want the translated XML Schemas to go.
The targetNamespace parameter will become the translated XML Schema target namespace. It must be a valid URI.
The fileset parameter of the cob2xsd ant task must designate one, or more, COBOL source fragments that you want to translate to XML Schema.
For a complete list of options for the cob2xsd task, you can refer to CobolStructureToXsdTask.
After you run the script, you should get XML Schema files such as lsfileae.xsd which are named after the COBOL fragments translated.
Open one of these files and notice that each COBOL data structure in the LSFILEAE COBOL source has been mapped to an XML Schema type. Each Schema type has COBOL annotations that serves as mapping meta-data for other tools.
You can use the build-coxb.xml ant script from the samples/quickstarts/adapter_lsfileae folder as your starting point. It generates Transformers for the LSFILEAE COBOL program which takes the same input and output structure called Dfhcommarea.
Generally, there are 4 things you will need to change in build-coxb.xml in order to adapt it to your needs:
Make sure the classpath setting is correct. The fileset should point to the location where you installed LegStar.
The xsdFile parameter of the jaxbgen ant task must point to the location of you XML Schema with COBOL annotations.
The jaxbPackageName parameter, for both jaxbgen and coxbgen ant tasks, must be set to the same value conforming to your naming standards.
The jaxbRootClass parameter of the coxbgen ant task must designate one, or more, JAXB classes that you want to turn into Transformers.
build-coxb.xml executes 3 steps (or targets in ant parlance):
The first target, generateJAXB, runs the jaxbgen ant task and turns an XML Schema with COBOL annotations into JAXB classes with COBOL annotations.
For a complete list of options for the jaxbgen task, you can refer to CobolJAXBGenerator.
The second target, compileJAXB, is a regular java compilation step for the JAXB classes previously generated.
The third target, generateCOXB, runs the coxbgen ant task and produces the actual Transformers. The generation process reflects on the JAXB classes compiled at the previous step.
You will notice that the coxbgen ant task takes one or more jaxbRootClass elements. These are needed to designate which JAXB class (or classes) should become a Transformer. You would generally pickup the higher classes in the hierarchy but you don't have to.
By default you get Java to Host Transformers only. In addition, you can get Host to XML and Host to JSON Transformers (use the xmlTransformers and jsonTransformers options).
For a complete list of options for the jaxbgen task, you can refer to CoxbBindingGenerator.
The Using generated tranformers section gives examples of code you could write to run Transformers.
The final step in the process is to generate a Mainframe Adapter, which is a JAX-WS Endpoint.
You can use the build-jws2cixs.xml ant script from the samples/quickstarts/adapter_lsfileae folder as your starting point.
The sample script produces several artifacts and is primarily a single step script running the jaxws2cixsgen ant task.
Let us review the important parameters that you will need to change in build-jws2cixs.xml in order to adapt it to your needs:
Make sure the classpath setting for the jaxws2cixsgen task is correct. The fileset should point to the location where you installed LegStar.
It is also important that the JAXB and Transformers previously generated be on the classpath.
jaxws2cixsgen takes a series of file system locations as parameters. Follow the comments in the ant script to select the correct locations.
The cixsJaxwsService element is where the actual Adapter is described. The name and packageName parameters are up to you but must be valid java identifier and package name respectively.
The cixsOperation element is there because you can implement more than one operation for a Service. You just need a different name (a valid java identifier) for each operation.
The cicsProgramName parameter must exactly match an existing CICS program. The generated service will attempt to run that program.
The input and output elements must refer to JAXB types and package names as generated by the COBOL Transformers generator. In the case of LSFILEAE, the JAXB type is Dfhcommarea for both input and output.
Finally the webServiceParameters element is JAX-WS specific. It specifies the way the service will be exposed via WSDL.
For a complete list of options for the jaxws2cixsgen task, you can refer to Jaxws2CixsGenerator.
After you run the script, you should get a new set of java classes which implement the JAX-WS endpoint.
Besides the JAX-WS java classes, you will also find ant scripts that were generated to help you with deploying your endpoint. build-jar.xml bundles the classes in a jar archive that you could deploy to AXIS2 for instance. build-war.xml bundles a war file suitable for Sun's JAX-WS RI (Metro).
Once deployed, you can use the Web Service with any SOAP client such as soapUI.
The process starts by mapping XML schema types, from the target Web Service WSDL, to COBOL data items.
You can use the build-xsd2cob.xml ant script from the samples/quickstarts/proxy_ws_cultureinfo folder as your starting point.
The script executes a single ant task, xsd2cob, which can process WSDL or XML Schema as input to produce a new XML Schema with COBOL annotations.
Assuming you want to customize build-xsd2cob.xml for the Microsoft LIVE search SOAP service. Follow these steps:
Make sure the classpath setting for the xsd2cob task is correct. The fileset should point to the location where you installed LegStar.
The inputXsdUri is the location of your input WSDL or XML Schema. In the case of Microsoft LIVE Web Service you can use: http://soap.search.msn.com/webservices.asmx?wsdl
The targetXsdFile parameter should point to the file name for the generated XML Schema with COBOL annotations (Can also be a folder name in which case the file name is derived from inputXsdUri).
The targetCobolFile parameter should point to the file name for the generated COBOL copybook (Can also be a folder name in which case the file name is derived from inputXsdUri).
For a complete list of options for the xsd2cob task, you can refer to Xsd2CobTask.
After you run the script, you should get a new XML Schema file with the name you specified. You should also get a COBOL copybook.
Open this file and notice that each root Elements and Complex Types in the WSDL source has been mapped to a COBOL data item. Each Schema type has COBOL annotations that serves as mapping meta-data for other tools.
Since we started from a WSDL, a certain number of default COBOL data attributes were assigned. For instance, all character strings are 32 characters long. While this might be an acceptable default, it is not always the case. In our situation, the application ID (AppID) must be 40 characters long. We need to change the COBOL picture from X(32) to X(40).
You can use the build-coxb.xml ant script from the samples/quickstarts/proxy_ws_cultureinfo folder as your starting point. It generates Transformers for the cultureinfo Web Service which takes the GetInfo structure as its input and the GetInfoResponse structure as its output.
Refer to COBOL Transformers Generation for an Adapter for a description of what you need to customize in build-coxb.xml and how it works.
Assuming you want to customize build-coxb.xml for the Microsoft LIVE search SOAP service. Follow these steps:
Change xsdFile parameter of the jaxbgen ant task to point to the location the XML Schema that was produced with the WSDL/XSD Structures Mapping tool.
Change the jaxbPackageName parameter, for both jaxbgen and coxbgen, to something like com.microsoft.schemas.msnsearch.
Change the jaxbRootClass parameters to Search and SearchResponse, which are the wrapper elements expected and produced by the target LIVE Web Service.
if you execute the ant script as is, you will get a JAXB error:
[ERROR] A class/interface with the same name "com.microsoft.schemas.msnsearch.SearchResponse" is already in use.
This is because Microsoft uses the same names for Complex Types and Elements in their XML Schemas which confuses JAXB. To solve this, you can use the typeNameSuffix parameter on the jaxbgen task. The Task should now look like this:
<jaxbgen
xsdFile="LIVESearch.xsd"
targetDir="src"
jaxbPackageName="com.microsoft.schemas.msnsearch"
generateIsSetMethod="true"
serializableUid="1"
typeNameSuffix="Type"
/>
You can now execute the ant script.
The Using generated tranformers section gives examples of code you could write to run Transformers.
The final step in the process is to generate a Mainframe Proxy, which is a JAX-WS Client that responds to Mainframe requests and mediates the call to the target Web Service, for instance the Microsot LIVE Search Web Service.
You can use the build-cixs2jws.xml ant script from the samples/quickstarts/proxy_ws_cultureinfo folder as your starting point.
The sample script produces several artifacts and is primarily a single step script running the cixs2jaxwsgen ant task.
Let us review the important parameters that you will need to change in build-cixs2jws.xml in order to adapt it to your needs:
Make sure the classpath setting for the cixs2jaxwsgen task is correct. The fileset should point to the location where you installed LegStar.
It is also important that the JAXB and Transformers previously generated be on the classpath.
cixs2jaxwsgen takes a series of file system locations as parameters. Follow the comments in the ant script to select the correct locations.
The hostCharset parameter is your mainframe character set (for instance IBM01140). It must be one of the available java character sets.
The proxyTargetType parameter is either POJO or WEBSERVICE. In the case of LIVE Search it must be WEBSERVICE.
The sampleCobolHttpClientType parameter is the type of COBOL sample that you would like to generate. This COBOL/CICS code uses HTTP to access the Proxy and therefore your choice depends on the APIs available to your CICS region. There are 3 possibilities: DFHWBCLI, WEBAPI and LSHTTAPI.
The cixsJaxwsService element is where the actual Proxy is described. The name parameter is up to you but must be valid java identifier.
The cixsOperation element is there because you can implement more than one operation for a Service. You just need a different name (a valid java identifier) for each operation.
The cicsProgramName parameter designates the sample COBOL client that will be generated.
The input and output elements must refer to JAXB types and package names as generated by the COBOL Transformers generator. In the case of LIVE Search, the JAXB types are Search and SearchResponse on input and output respectively.
Finally the webServiceTargetParameters element gives the datail on how to access the target Web Service. In the case of LIVE search, it should look like this:
<webServiceTargetParameters
wsdlUrl="http://soap.search.msn.com/webservices.asmx?wsdl"
wsdlTargetNamespace="http://schemas.microsoft.com/MSNSearch/2005/09/fex"
wsdlServiceName="MSNSearchService"
wsdlPortName="MSNSearchPort"
/>
For a complete list of options for the cixs2jaxwsgen task, you can refer to Cixs2JaxwsGenerator.
After you run the script, you should get a new set of artifacts which implement a JAX-WS client.
The Mainframe proxy is a Servlet to be deployed in a J2EE container. The implementation uses Sun's JAX-WS RI (Metro) as a Web Service client. The build-war.xml ant file that is generated allows you to bundle the servlet ready for deployment.
The generator also creates a sample COBOL program that behaves as an HTTP client.
The sample COBOL source contains TODO comments to help you locate where you should set values for the search request and where you can display the results. The LIVE search service requires a developer ID that you can get for free and enter in the AppID field.
This is an example of code to set the search structures properly:
MOVE ZERO TO Flags--C OF COM-REQUEST.
MOVE ZERO TO SortBy--C OF COM-REQUEST.
MOVE ZERO TO ResultFields--C OF COM-REQUEST.
MOVE ZERO TO R-string--C OF COM-REQUEST.
MOVE 1 TO SourceRequest--C OF COM-REQUEST.
* You should specify your own Microsoft LIVE application ID
MOVE '5588C3ACE949317B3ECAADDQ908611BDF5D8D5ZA'
TO AppID OF COM-REQUEST.
MOVE 'Mainframe' TO Query OF COM-REQUEST.
MOVE 'en-US' TO CultureInfo OF COM-REQUEST.
MOVE 'Moderate' to SafeSearch OF COM-REQUEST.
MOVE ZERO TO Latitude OF COM-REQUEST.
MOVE ZERO TO Longitude OF COM-REQUEST.
MOVE ZERO TO Radius OF COM-REQUEST.
MOVE 'Web' TO R-Source OF COM-REQUEST(1).
MOVE ZERO TO Offset OF COM-REQUEST(1).
MOVE 1 TO R-Count OF COM-REQUEST(1).
MOVE SPACES TO FileType OF COM-REQUEST(1).
And these are lines to display the result:
STRING 'INVOKE-SERVICE success. First hit is '
DELIMITED BY SIZE
Description OF COM-REPLY(1, 1)
DELIMITED BY SIZE
INTO ERROR-MESSAGE.
EXEC CICS SEND TEXT FROM(ERROR-MESSAGE) FREEKB END-EXEC.
DISPLAY 'Response data length=' WBCLI-RESPONSE-BODY-LEN.
DISPLAY 'SourceResponse--C ='
SourceResponse--C OF COM-REPLY.
DISPLAY 'R-Source(1)=' R-Source OF COM-REPLY(1).
DISPLAY 'Total(1)=' Total OF COM-REPLY(1).
DISPLAY 'R-Title(1, 1)=' R-Title OF COM-REPLY(1, 1).
DISPLAY 'Description(1, 1)='
Description OF COM-REPLY(1, 1).
After you add these lines of code, you should be able to upload the source 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 supports the new EXEC CICS WEB API or even supports older version of CICS with its own HTTP library.