Developing Java applications to use the JZOS Toolkit API in an OSGi JVM server

The IBM® JZOS Toolkit consists of classes in package com.ibm.jzos, which is distributed with the IBM Java™ SDKs for z/OS® in a single JAR file ibmjzos.jar.

These classes give Java applications on z/OS direct access to traditional z/OS data sets and files and access to z/OS system services and converter classes for mapping byte array fields into Java data types.

Before you begin

If the JZOS Toolkit API is not downloaded to your workstation, then transfer the ibmjzos.jar file from the relevant version of the IBM Java SDK on z/OS to your workstation.

Important: If you are using IBM CICS Explorer® or an Eclipse-based IDE at version 2022-03 or later, your default compiler compliance level must match the Java version of the target runtime to which the application or sample is deployed to avoid issues. You can change this setting in IBM CICS Explorer by selecting Preferences, then Java and then Compiler.

Procedure

Set the Target platform. To prepare to use the JCICS API in your development environment, set the Eclipse Target Platform to ensure it can resolve locally. In an OSGi development environment Target Platform definitions are used to define the plug-ins that applications in the workspace is built against. For CICS Explorer use the Eclipse menu, Windows > Preferences > Plug-in Development > Target Platform. Click Add, and from the supplied templates select the CICS® TS release for your runtime environment. Don't forget to apply the target platform to your workspace.
Create an OSGi wrapper bundle for the JZOS Toolkit. If you have the IBM CICS SDK for Enterprise Java (Liberty) plug-in, then select File > Import > Java Archive into an OSGi bundle to create a new OSGi Bundle Project. Ensure that the newly created bundle exports all the available JZOS Toolkit packages that are required by the Java application such as com.ibm.jzos, com.ibm.jzos.fields, or com.ibm.jzos.wlm. This ensures that these packages are available to be imported by other OSGi projects in the Eclipse workspace.
For example:
```
Export-Package: com.ibm.jzos,
  com.ibm.jzos.fields
```

Create a CICS Java application.

Create an OSGi Bundle Project in Eclipse by using the wizard File > New > Other Plug-in Project.
Create a Java package com.ibm.cicsdev.jzos.sample and add a class ZFilePrint.

Copy in the following code example, which opens a z/OS data set pointed to by the //INPUT DD and writes the output to a CICS temporary storage queue.

package com.ibm.cicsdev.jzos.sample;

import com.ibm.jzos.ZFile;
import com.ibm.jzos.ZUtil;
import com.ibm.cics.server.TSQ;

public class ZFilePrint 
{
    public static void main(String[] args) throws Exception 
    {
        ZFile zFile = new ZFile("//DD:INPUT", "rb,type=record,noseek");
        TSQ tsqQ = new TSQ();
        tsqQ.setName("JZOSTSQ");        

        try 
        {
            byte[] recBuf = new byte[zFile.getLrecl()];
            int nRead;
            String encoding = ZUtil.getDefaultPlatformEncoding();

            while ((nRead = zFile.read(recBuf)) >= 0) 
            {
                String line = new String(recBuf, 0, nRead, encoding);                
                tsqQ.writeString(line);
            }            
        } 
        finally 
        {
            zFile.close();
        }
    }
}

Add the following Import-Package statements to the bundle manifest for the JCICS and JZOS packages. The JCICS import should follow best practice to specify a range of versions the application operates with. Typically this range will go up to, but not include, the next API breaking change. For JCICS that would be version 3.0.0, so the range com.ibm.cics.server;version="[1.401.0,3.0.0)" is used in the example as this is the minimum level that is required to support the JCICS TSQ.writeString() method. The JZOS package is not taken from a versioned bundle. It is displayed to the runtime from the underlying JAR file with no version, and so com.ibm.jzos can be listed without a referenced version, which allows any available version (including 0.0.0) to be chosen.
```
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: com.ibm.cicsdev.jzos.sample
Bundle-SymbolicName: com.ibm.cicsdev.jzos.sample
Bundle-Version: 1.0.0
Bundle-RequiredExecutionEnvironment: JavaSE-1.7
Import-Package: com.ibm.cics.server;version="[1.401.0,3.0.0)",
 com.ibm.jzos
```

Add a CICS-MainClass: definition to the bundle manifest to register a MainClass service for your com.ibm.cicsdev.jzos.sample.ZFilePrint class.

This allows the Java class to be linked to using a CICS program definition. Your manifest now looks similar to the following example:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: com.ibm.cicsdev.jzos.sample
Bundle-SymbolicName: com.ibm.cicsdev.jzos.sample
Bundle-Version: 1.0.0
Bundle-RequiredExecutionEnvironment: JavaSE-1.7
Import-Package: com.ibm.cics.server;version="[1.401.0,2.0.0)",
 com.ibm.jzos
CICS-MainClass: com.ibm.cicsdev.jzos.sample.ZFilePrint

Results

The application is now ready to be tested, and can be deployed into a CICS OSGi JVM server by using a CICS Bundle Project as follows:

Create a CICS Bundle Project in Eclipse and add the OSGi Bundle Project by using the menu New OSGi Bundle Project Include.
Deploy to zFS by using the menu Export Bundle Project to z/OS UNIX file system.
Create a CICS BUNDLE definition that references this zFS location and install it.
Create a CICS PROGRAM definition that names the CICS-MainClass: com.ibm.cicsdev.jzos.sample.ZFilePrint in the JVMClass attribute and install it.
Before you run the application, you need to define a z/OS DD in the CICS JCL referencing a valid z/OS data set and then restart your CICS region. For instance:
```
//INPUT    DD DISP=SHR,DSN=CICS.USER.INPUT
```
If you need to run the application from a 3270 console, create a TRANSACTION definition that references the PROGRAM defined in step 4.

When started, your Java class ZFilePrint reads the defined z/OS data set by using the JZOS Toolkit API and then write the contents to a CICS temporary storage queue using the JCICS API.