Table of Contents
Java 1.5+ and ANT 1.6.5+ are both prerequisites for LegStar.
LegStar requires a JDK, or an international version of the JRE, that includes charsets.jar.
Make sure JAVA_HOME and ANT_HOME environment variables are set and that $JAVA_HOME/bin (%JAVA_HOME%/bin on Windows) and $ANT_HOME/bin (%ANT_HOME%/bin on Windows) are both in your system path.
The mainframe Service Generator requires JAX-WS 2.1 (JSR 224). The Sun's JAX-WS reference implementation is shipped with LegStar. You can replace this implementation with any JAX-WS 2.1 compliant provider.
Since Service Generator is modular, there might be more prerequisites depending on your target choice (Adapter or Proxy) and, if you chose Adapters, what transport you want to use. For each of these choices, documentation is available either online or in the docs folder.
Warning: make sure you completely uninstall any previous version before proceeding with a new install.
Download the latest distribution.
Unzip the binary distribution package into the directory of your choice, referred to as <installDir> in the following steps.
The directory tree should look like this:
<installDir>
|-->LICENSE
|-->readme.html
|--><docs>
|-->*-README
|--><lib>
|-->*.jar
|--><samples>
|--><quickstarts>
|--><adapter_lsfileae>
|-->build-*.xml
|--><cobol>
|-->lsfileae
|--><schema>
|-->lsfileae.xsd
|--><src>
|-->**/*.java
|--><chttprt>
|-->build.xml
|-->legstar-invoker-config.xml
|-->lsfileae.properties
|-->readme.txt
|--><src>
|--><cmockrt>
|-->legstar-invoker-config.xml
|-->readme.txt
|--><cmqrt>
|-->build.xml
|-->legstar-invoker-config.xml
|-->lsfileae.properties
|-->readme.txt
|--><src>
|--><csokrt>
|-->build.xml
|-->legstar-invoker-config.xml
|-->lsfileae.properties
|-->readme.txt
|--><src>
|--><pooling>
|-->legstar-engine-config.xml
|-->legstar-pooling-config.xml
|--><proxy_pojo_jvmquery>
|-->build-*.xml
|--><java>
|-->*.jar
|--><jcl>
|-->COBCJVMQ
|--><schema>
|-->jvmquery.xsd
|--><src>
|-->**/*.java
|--><proxy_ws_cultureinfo>
|-->build-*.xml
|--><jcl>
|-->COBCCULT
|--><schema>
|-->cultureinfo.xsd
|--><src>
|-->**/*.java
|--><webapp>
|--><jaxws-cultureinfo>
|--><WEB-INF>
|-->web.xml
|-->sun-jaxws.xml
|--><war>
|-->legstar-engine.war
|--><zos>
|--><C370>
|-->*.C
|-->*.H
|--><cobol>
|-->*.cbl
|--><JCL>
|-->*
|--><docs>
|-->*-README
if you plan on using the Service Generation capabilities, copy the content of <installDir>/lib to your J2EE container shared libraries (ex $CATALINA_BASE/shared/lib).
From the samples/quickstarts/adapter_lsfileae folder, run command ant -f build-cob2xsd.xml. This should create a schema folder with a generated XML schema from the sample cobol source in the cobol folder.
Run command ant -f build-coxb.xml from the samples/quickstarts/adapter_lsfileae folder and check the result. This should create a src folder containing generated JAXB classes and Transformers from the sample XML Schema in the schema folder.
From the samples/quickstarts/adapter_lsfileae folder, run command ant -f build-jws2cixs.xml. This should add a set of java files to the src folder, these implement a JAX-WS endpoint. This also creates a webapp and an ant folders.
From the samples/quickstarts/adapter_lsfileae/ant folder, run command ant -f build-war.xml. This should generate a war file in the dist folder, ready for deployment.
Deploy the generated war file from the war folder into your J2EE container deployment folder (ex $CATALINA_BASE/webapps).
See the FAQ for common deployment issues.
You will notice that a jar file is also generated in the dist folder. As an alternative to JAX-WS RI (Metro) you can deploy this jar to Apache AXIS2, servicejars folder.
Optionally, you can use build-jws-client.xml to generate a Web service client using JAX-WS.
In order to actually run the deployed Web Service, you need to select a transport and put a customized version of the legstar-invoker-config.xml configuration file in a location such as $CATALINA_HOME/shared/classes.
There are sample invoker configuration files for each of the transports supported in:
samples/quickstarts/chttprt for HTTP transport
samples/quickstarts/cmqrt for WebSphere MQ transport
samples/quickstarts/csokrt for Socket transport
There are 2 proxy samples, one that consumes a POJO and one that consumes a Web Service.
Change directory to samples/quickstarts/proxy_pojo_jvmquery/.
The distribution contains a simple POJO called jvmquery. It is provided as a jar file in the samples/quickstarts/proxy_pojo_jvmquery/java folder and as source are in samples/quickstarts/proxy_pojo_jvmquery/src.
Run command ant -f build-java2cob.xml which generates a COBOL-annotated XML schema named jvmquery.xsd in the schema folder.
Each java type, from the jvmquery source, maps to an XML schema complex type. Each XML schema element has special Cobol annotations with default attributes, such as maximum character string sizes.
Run command ant -f build-coxb.xml from the samples/quickstarts/proxy_pojo_jvmquery folder and check the result. This should add to the src folder generated JAXB classes and Transformers from the sample XML Schema in the schema folder.
From the samples/quickstarts/proxy_pojo_jvmquery folder, run command ant -f build-cixs2jws.xml. This should generate a web.xml file in the webapp/cixs-jvmquery/WEB-INF folder, an ant script in the ant folder and a sample COBOL program in the cobol folder.
From the samples/quickstarts/proxy_pojo_jvmquery/ant folder, run command ant -f build-war.xml. This should generate a war file in the dist folder, ready for deployment.
Deploy the generated war file from the dist folder into your J2EE container deployment folder (ex $CATALINA_BASE/webapps).
The sample COBOL program is an almost complete working sample of a proxy client. You can follow instructions in the code to add the missing instructions or just run ant -f build-jvmquery-cobol-src.xml that automatically does that.
Edit the JVMQUERY.cbl source and check the W00-SERVICE-URI, make sure it points to the machine where you deployed the proxy. You can now upload that program to z/OS, compile and run it. A sample compilation jcl is in the jcl folder.
Change directory to samples/quickstarts/proxy_ws_cultureinfo/.
The distribution contains a simple Web Service called cultureinfo. It is provided as a war file in the samples/quickstarts/proxy_ws_cultureinfo/war folder.
The war file contains a simple JAX-WS endpoint. If the JAX-WS libraries are not available in your target J2EE container, you can get them from <installDir>/lib.
Deploy this war file to your J2EE container deployment folder (ex $CATALINA_BASE/webapps).
Check the build-xsd2cob.xml inputXsdUri parameter. It assumes the J2EE container you deployed the target Web Service to, is listening on localhost, port 8080. You might need to customize this.
You can now run command ant -f build-xsd2cob.xml which generates a COBOL-annotated XML schema named cultureinfo.xsd in the schema folder. It does so by reading the target Web Service WSDL.
Each complex type and element from the source WSDL also exists in the generated mapping XML schema. Each element also has special Cobol annotations with default attributes, such as maximum character string sizes.
Run command ant -f build-coxb.xml from the samples/quickstarts/proxy_pojo_cultureinfo folder and check the result. This should create a src folder containing generated JAXB classes and Transformers from the sample XML Schema in the schema folder.
From the samples/quickstarts/proxy_pojo_cultureinfo folder, run command ant -f build-cixs2jws.xml. This should generate a web.xml file in the webapp/cixs-cultureinfo/WEB-INF folder, an ant script in the ant folder and a sample COBOL program in the cobol folder.
From the samples/quickstarts/proxy_pojo_cultureinfo/ant folder, run command ant -f build-war.xml. This should generate a war file in the dist folder, ready for deployment.
Deploy the generated war file from the dist folder into your J2EE container deployment folder (ex $CATALINA_BASE/webapps).
The sample COBOL program is an almost complete working sample of a proxy client. You can follow instructions in the code to add the missing instructions or just run ant -f build-cultureinfo-cobol-src.xml that automatically does that.
Edit the CULTUREI.cbl source and check the W00-SERVICE-URI, make sure it points to the machine where you deployed the proxy. You can now upload that program to z/OS, compile and run it. A sample compilation jcl is in the jcl folder.