[Java] Run a CICS-Java application-(1) run a simple sample app

7 minute read


Speaking of application development languages of CICS Transaction Server for z/OS, COBOL, PL/I, and Asembler are often used, but Java has been supported for a long time. This means that you can write your CICS applications in Java. A Java class library (JCICS) corresponding to the EXEC CICS command is provided, so you can use Java methods to perform operations such as EXEC CICS LINK and EXEC CICS START. Here, let’s try running a sample of a CICS-Java application (OSGi compliant) in action.

*By the way, you can also run a Java EE application on CICS. Reference: Run a Java EE application on CICS

Related article

Run CICS-Java application-(1) Running simple sample application Run CICS-Java application-(2) Maven build management Run CICS-Java application-(3) Build management by Gradle Move CICS-Java application-(4) Spring Boot application

Environmental information

Development environment Windows10 CICS Explorer V5.6(Beta)

Execution environment z/OS V2.4 CICS Transaction Server for z/OS V5.6(Beta)

About Java support for CICS

Here is a summary of Java support for CICS. CICS supports OSGi-compliant Java applications. The following procedure is required to run a CICS application implemented in Java.

Runtime preparation To execute a Java application, create a resource definition called JVMSERVER in the target CICS region and prepare a Java execution environment.

development of Development work is done using the free Eclipse-based tool “CICS Explorer”. Create a Java application that imports the JCICS library and package it as an OSGi bundle (like an extension of a jar). (Reference: Outline of OSGI)  At this time, the top logic that you want to recognize as a CICS program must be implemented in the main function. Package several OSGi Bundles into a unit called a “CICS Bundle”. *Liberty can also be run on CICS, and Java EE applications can also be run on Liberty on CICS. In that case, the Java EE application is packaged in units of WAR and EAR, but in that case, the idea of packaging them in the unit of “CICS bundle” is similar.

Deployment Transfer the CICS bundle onto the USS of z/OS in the execution environment. Create a BUNDLE definition in the resource definition of the CICS region and recognize the CICS bundle (Java application) transferred on USS. Create a PROGRAM definition in the resource definition of the CICS region and register the Java class included in BUNDLE as a CICS program.

The relation between each CICS resource definition and the entity is as follows. image.png

Advance preparation

Development environment

Refer to the following and download and set up an Eclipse-based tool called CICS Explorer. Reference: Downloading and starting CICS Explorer *This tool is free for CICS users.

As a host connection definition, configure FTP connection to z/OS where the target CICS is running. image.png

Execution environment

Prepare a CICS region to run the sample. Here, we will use the region named CT56B4A1. Add a resource called JVMServer to run the Java application.

JVM profile

Prepare a JVM profile on USS. (The properties related to JVMServer are effectively specified in a file on this USS. The JVMSERVER resource definition points to the file name of this JVM profile.) A sample is provided so you can copy it and use it.

Create a directory called /var/cicsts/cicsts56/CT56B4A1/JVMProfiles and copy /usr/lpp/cicsts/cicsts56/JVMProfiles/DFHOSGI.jvmprofile (sample definition for OSGi located under the CICS installation directory) into it. To do. Customize as appropriate for your environment.

DFHOSGI.jvmprofile excerpt

- Xms32M
- Xmx256M
- Xmso1M
- Xgcpolicy:gencon
- Xscmx256M
- Xshareclasses:name=cicsts%g,groupAccess,nonfatal
- Xtune:virtualized
- Dcom.ibm.tools.attach.enable=no


Specify the directory where the above property file is placed in the SIT parameter “JVMPROFILEDIR”.


Restart the region for the changes to take effect.

JVMServer definition

Prepare the JVMSERVER resource definition. Copy the JVMSERVER definition “DFHJVMS” in the DFH$OSGI group provided by the product to an appropriate group and install it.

 CEDA View JVmserver( DFHJVMS)
  JVmserver: DFHJVMS
  Group: TAG$OSGI
  DEScription: CICS JVM server to run OSGi samples
  Status: Enabled Enabled | Disabled
  Jvmprofile: DFHOSGI (Mixed Case)
  Lerunopts: DFHAXRO
  Threadlimit: 015 1-256
  DEFinetime: 06/02/20 17:28:17
  CHANGETime: 06/02/20 17:28:17
  CHANGEAGRel: 0730

*Jvmprofile: DFHOSGI, which means that the file DFHOSGI.jvmprofile under the directory specified in JVMPROFILEDIR of SIT is used as the JVM property file.

It is OK if CEMT I JVM SERVER shows Enable.

    Threadc(000) Threadl( 015) Cur(9965280)

```### bundle file placement directory
Create a directory on USS to place the bundle file.
Here, I will create a directory called `/var/cicsts/cicsts56/CT56B4A1/bundles/`.

# Sample app operation check
Reference: [Java samples: JCICS examples](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-samples/java_samples_jcics.html)

## Creating a sample project

Select Window-Preferences from the CICS Explorer menu to open the Preferences window.
Plugin Development-Select Target Platform and click Add.

Select the target CICS version in the template. Select CICS TS V5.6 here.

Check and apply the added CICS TS 5.6.

In the Java perspective, select File-New-Other from the menu

Select CICS Bundle OSGi Sample

Continue to next

End as it is

A sample project will be created.

## Check the contents of the sample
This project provides some sample apps, but let's look at the simplest Hello World source.
(examples.hello.HelloCICSWorld.java included in com.ibm.cics.server.examples.hello project (OSGi bundle))

#### **`HelloCICSWorld.java`**

package examples.hello;

import com.ibm.cics.server.CommAreaHolder;
import com.ibm.cics.server.Task;

public class HelloCICSWorld
    public static void main(CommAreaHolder CAH)
        Task t = Task.getTask();
        if (t == null)
            System.err.println("HelloCICSWorld example: Can't get Task");
            t.out.println("Hello from a Java CICS application");

JCICS com.ibm.cics.server.Task is used. Task.out means PrintWriter for terminal output, so it has a logic to send a simple string to the terminal. Reference: Javadoc-Task

Check META-INF/MANIFEST.MF of the same project.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Hello Plug-in
Bundle-SymbolicName: com.ibm.cics.server.examples.hello
Bundle-Version: 1.0.0
Bundle-RequiredExecutionEnvironment: J2SE-1.4,
Import-Package: com.ibm.cics.server;version="[1.0.0,2.0.0)"
CICS-MainClass: examples.hello.HelloCICSWorld, examples.hello.HelloWorld

In the specification of CICS-MainClass, the class that has the main method is specified. The main method of the class specified here can be recognized as a CICS program (it can be linked with the program definition).

Check the CICS bundle project called com.ibm.cics.server.examples.bundle. If you open META-INF/cics.xml in the CICS Bundle Manifest Editor, you can see that the above OSGi bundle is included. image.png

Open com.ibm.cics.server.examples.hello.osgibundle. image.png

Check the value of jvmserver specified here. You need to specify the name of the JVMSERVER definition to run here. Modify it according to the name of the JVMSERVER definition created in advance. If you copy the sample definition with the same name, it will be DFHJVMS, so no change is necessary.

Deploying the application to CICS

Deployment to CICS is done in “CICS bundle” units. Right-click the com.ibm.cics.server.examples.bundle project and click Export Bundle Project to z/OS UNIX File System image.png

Select Export to a specific location in your file system and click Next image.png

End by specifying the directory for the bundle file created earlier image.png

Confirm message image.png The bundle file is placed on USS.

Copy each resource in the CICS-supplied DFH$OSGI group to the appropriate group. Customize the BUNDLE definition “DFH$OSGB” and set the value of BUNDLEDIR to the directory (/var/cicsts/cicsts56/CT56B4A1/bundles/com.ibm.cics.server.examples.bundle_1. 0.0).

 CEDA ALter Bundle( DFH$OSGB)
  Bundle: DFH$OSGB
  Group: TAG$OSGI
  DEScription ==> CICS bundle containing OSGi sample bundles
  Status ==> Enabled Enabled | Disabled
  BUndledir ==> /var/cicsts/cicsts56/CT56B4A1/bundles/com.ibm.cics.server.(Mixed Case) ==> examples.bundle_1.0.0
  BAsescope ==>
  (Mixed Case) ==>
  DEFinetime: 06/02/20 18:27:37
  CHANGETime: 06/02/20 18:27:37

Make sure it is installed and enabled.

 Bun(DFH$OSGB) Ena Par(00003) Tar(00003)
    Enabledc(00003) Bundlei(com.ibm.cics.server.exampl)

By the way, if you check the resource definition in CICS Explorer, you can check not only the BUNDLE definition but also the BUNDLE PARTS included in BUNDLE. image.png

Sample execution

This time I will run the Hello World sample, so I will additionally install the resource definitions related to this sample. Reference: Running the Hello World example

Program definition “DFJ$JHE2” and transaction definition “JHE2”. The actual Java program is already installed as BUNDLE. Both are provided in DFH$OSGI, so copy them and install them as they are. By the way, looking at the definition of DFH$JHE2,

  Group: TAG$OSGI
  DEScription: OSGi Hello CICS world sample program
  Language :CObol | Assembler | Le370 | C | Pli
  RELoad :No No | Yes
  RESident :No No | Yes
  USAge: Normal Normal | Transient
  USElpacopy :No No | Yes
  Status: Enabled Enabled | Disabled
  RSl :00 0-24 | Public
  CEdf: Yes Yes | No
  DAtalocation :Any Below | Any
  EXECKey :Cics User | Cics
  COncurrency: Required Quasirent | Threadsafe | Required
  Api :Cicsapi Cicsapi | Openapi
  DYnamic :No No | Yes
  EXECUtionset: Fullapi Fullapi | Dplsubset
  JVM: Yes No | Yes
  JVMClass: examples.hello.HelloCICSWorld
  (Mixed Case):
  JVMProfile: (Mixed Case)
  Hotpool :No No | Yes

Like this, JVM:Yes, JVMClass:examples.hello.HelloCICSWorld, JVMServer:DFHJVMS are specified (classes installed by BUNDLEPARTS). *If the JVM Server name created in advance is different, please modify it accordingly.

Now that the resources are ready, let’s execute it. Run the JHE2 transaction from your CICS terminal. image.png The string output from the Java program Hello from a Java CICS application was displayed! Now you can see that Java has worked as a CICS program.