This article assumes that you have already set up a Liberty JVM in your CICS TS V5 region. A brief overview of the required resources that you should have in place is provided. Refer to Setting up a Liberty JVM server in 4 easy steps for further instructions on how to set up a Liberty JVM.
The CICS Liberty JVM server infrastructure
After you have set up the Liberty JVM server in your CICS region, you should have the following resources in place:
- JVMSERVER resource (resource definition for CICS)
- Liberty JVM profile file (file suffixed with
- Liberty profile server configuration (directory structure and
The picture below shows the overall view of how CICS will act as a service provider. The process will be as follows:
- HTTP web services request will be accepted by the Liberty HTTP listener using the z/OS Communication Server TCP/IP stack
- The HTTP request will be dispatched to the appropriate Liberty HTTP listener in the CICS Liberty JVM server
- The Java application using JAX-WS will manage web services request and use JCICS API to link to an existing CICS program
Service provider options
This section shows the minimum required configuration to enable CICS to function as a service provider using JAX-WS. For a list of supported Liberty features in CICS TS V5.2 please refer to Liberty features topic in the CICS TS V5.2 Knowledge Center.
To have Liberty JVM process HTTP(S) request you need to enable the Liberty JVM to accept HTTP connections. You need to have the following line in your server.xml
<httpEndpoint host="*" httpPort="9080" httpsPort="9094" id="defaultHttpEndpoint"/>
If the Java logic has to LINK to an existing CICS program you need to use JCICS API. The CICS feature
cicsts:core-1.0 installs the CICS system OSGi bundles into the Liberty framework. This feature is required for the JVM server to start.
<featureManager> â€¦ <feature>cicsts:core-1.0</feature> â€¦ </featureManager>
Web service features
In this article you will use JAX-WS to expose a web service. There fore you need to activate the JAX-WS feature.
<featureManager> â€¦ <feature>jaxws-2.2</feature> â€¦ </featureManager>
Optionally, you may need to use the JAXB API to manage complex XML documents, this requires the jaxb-2.2 Liberty feature which is included as part of the jaxws-2.2 feature.
Interacting with structured data from Java
This section presents the main aspects to take into account when developing or generating Java classes to wrap a binary structure such as a COMMAREA. For further details please refer to Interacting with structured data from Java or to Chapter 8 of the IBM Redbook, CICS and the JVM server: Developing and Deploying Java Applications. This section will give you a brief overview of the following methods:
- Developing Java wrapper classes yourself
- Generating Java wrappers with JZOS tooling
- Generating Java wrappers with J2C tooling
Note: Depending on which of these options you choose you will need to make sure the correct supporting classes have been added to the OSGi framework, in order to resolve the runtime dependencies
Developing your own Java wrapper classes
If you are familiar with traditional programming languages and you have a robust knowledge on how to treat binary structures in Java than you may find easy to develop your own classes to wrap binary data. However this approach may be error prone and it is recommended only if you have a strong requirement to use it.
Generating Java wrappers with JZOS tooling
You can generate Java wrapper classes using JZOS tooling for COBOL and Assembler data structures. This is accomplished using JZOS Record Generator.
JZOS Record Generator is a Java class library that generates Java classes to describe COBOL or Assembler records. It uses
com.ibm.jzos.fields which contains data-type converters for most data element. The
com.ibm.jzos.fields package is part of IBM JZOS toolkit and is required to both generate and execute the Java classes. The generation class library itself is not required to run generated Java classes.
You can download JZOS Record Generator at JZOS Record Generator.
Note: To download JZOS Record Generator you need to log in with an IBM account.
Dependencies of Java wrappers generated with JZOS Record Generator
JZOS utilities for COBOL or Assembler data binding generates Java classes that uses the following package:
This package is distributed with IBM z/OS Java and you have to make the JAR accessible to your application class path. You can find the JAR at:
Generating Java wrappers with J2C tooling
You can generate Java wrapper classes using J2C tooling provided by IBM Rational Application Developer (RAD). For further details on how to generate Java wrapper with J2C tooling please refer to Creating Java data binding classes using wizards.
Tip: When generating the Java classes you may find it useful to rename some data fields in the data structure. If you rename the data fields in a Java fashion the generated code will have a naming convention that would be more familiar to a Java programming style.
The picture below shows an example of a renaming done to a COBOL COPY data structure.
Dependencies of Java wrappers generated with J2C
The RAD J2C utilities for CICS/IMS Data Bindings generates Java classes that use the following packages:
com.ibm.etools.marshall is distributed with RAD as a redistributable JAR. A possible approach to make it available to Liberty applications is explained at Enabling generated record data on the Liberty profile. (Even though the topic in the link refers to Web Sphere optimized Local adapter the procedure described can be used in this context too).
javax.resource.cci is required by JCA, this package is supplied by the IBM z/OS Java SDK in the
standard/jca/connector.jar. file. The CICS JVM server include this package in the system class path by default.
When developing Java programs you always have different methods to package your applications, such methods differ in the way your application accesses imported packages. A deep explanation of packaging options that are available in Java is beyond the scope of this article. However, this section will give you a brief overview of packaging options that are available in the CICS Liberty JVM server. These are:
- JEE packaging
- OSGi packaging
Either packaging style you chose the actual Java code that you will develop in the application is the same. However, you will need to create different types of projects and do a minimal set up in your development environment.
JEE packaging includes WAR and EAR packaging of applications. This packaging is the most common and widespread. It is standard and most Java programmers are familiar with it.
Even though JEE packaging is quite widespread, it has some limitations that may lead to challenges when maintaining your applications. OSGi aims to ease such challenges by requiring a small, but valuable, extra effort when developing your application. To achieve this you simply need to add some information into your
MANIFEST.MF. to define the packages and classes you application needs to work with. Adding this extra piece of information may be very easy if done at development time, and it will boost the quality of your software.If you want to know more on OSGi development please refer to the OSGi alliance.
Setting up the development environment
To develop Java program for CICS you may use any development environment you are familiar with. This section present the pieces of software you need in your development environment.
The required components that you need to develop Java applications for CICS Liberty are freely available and are as follows:
- CICS Explorer SDK 5.2
- CICS Explorer SDK for Java support
- CICS SDK for Web and JSP support
- Web Sphere developer tools (only if you intend to deploy OSGi EBAs)
- OSGi Application development tools
- z/OS Explorer (only if you intend to manually move generated artifacts to z/OS)
For details on how to set up your development environment please refer to Setting up development environment.
Project structure for JEE packaging
If you intend to package your applications with this technique you have to develop WAR applications. You may find more information on how to develop your code at Creating a dynamic Web Project.
Basically what you need to do is:
- Create a new Web Project
- Configure the build path to add the CICS Liberty Libraries
- (optional) Create an Enterprise Application Project and reference the Web Project you have previously created
Project structure for OSGi packaging
If you intend to package your applications with this technique you have to develop OSGi bundles (known as Web application bundles) and package them into the EBA modules. You may find more information on how to develop your code at Creating an OSGi application Project.
Basically what you need to do is:
- Set up the plug in development Target Platform to CICS TS v5.2 with Liberty and PHP
- Create a plug in project selecting the standard OSGi framework, and disabling the generation of an Activator( you won’t need one for this case)
- Declare imported packages and dependencies
- Declare a context root for your OSGi Web modules
- Create an OSGi Application Project and reference the plug in project you have previously created
When you have finished you will have a MANIFEST.MF file that will look like the one below:
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: OSGiWebModule Bundle-SymbolicName: OSGiWebModule Bundle-Version: 1.0.0 Bundle-RequiredExecutionEnvironment: JavaSE-1.7 Import-Package: com.ibm.cics.server;version="1.500.0" Web-ContextPath: /JAX-WS/Services