Developing Java applications to use JZOS generated records in an OSGi JVM server

JZOS generated Java™ records are used to interact with a CICS® application from a Java application.

Before you begin

If you have not already generated and built record classes based on your COMMAREA structure, then follow the procedure in topic Building Java records using the JZOS Record Generator utility.

Procedure

  1. In preparation to using the JCICS API in your development environment, set the Target Platform to ensure it can resolve locally. 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.
  2. Resolve JZOS dependencies. Your JZOS generated record classes (referred to as EDUPGM.jar if you followed the Building Java records using the JZOS Record Generator utility topic) has dependencies on the JZOS runtime, in particular the com.ibm.jzos.fields package. The classes in that package are provided with the JZOS record generator in jzos_recgen.jar and also with the IBM® SDK for Java on z/OS®® in ibmjzos.jar. It is possible to avoid downloading the JZOS JARS to your workstation by placing the previously compiled EDUPGM.jar on the Bundle-classpath of your application. However, this technique is not best practice, as it makes your application susceptible to classpath problems, and, unlike a pure OSGi approach, it hides those dependencies on JZOS, which might result in an NoClassDefFoundError at runtime.

    A better approach is to download the ibmjzos.jar to your workstation, then in Eclipse convert it into an OSGi bundle. If you have the CICS Explorer® SDK for Liberty plug-in, then use Import and select OSGi > Java archive into an OSGi bundle to create a new OSGi bundle project. Otherwise, using base Eclipse plug-in functions, you can create a new empty plug-in project, copy the ibmzos.jar into the project, select the manifest editor, and use the runtime tab to add the jar to the classpath. On the same tab, use Add in the Exported Packages section to add all the detected packages for export. Creating such a project allows any dependencies on JZOS to resolve in your workspace. An Import-Package statement for the com.ibm.jzos.fields package can be added to your application to achieve that.

    If you used the approach that avoids downloading the JZOS jar locally, then the transient dependency on the JZOS package is hidden. Unlike the download approach, Eclipse does not warn you that an Import-Package statement is required in your application bundle. If you deploy your application with no further action, you receive a NoClassDefFoundError at runtime. To prevent this failure, you must add an Import-Package for the JZOS package. However, because the JZOS JAR is not downloaded and wrapped in your workspace, such a dependency is not resolved, and your application fails to deploy. There are two ways to avoid this situation:
    • Use the optional resolution capability of OSGi. This technique requires full appreciation of its dangers as it bypasses a layer of the OSGi ahead of runtime protection. However, where you know that a certain a package is available in the runtime, even though it is not available at client compile time, by using the resolution:=optional statement on an Import-Package bundle header is a useful technique. In this example, the JZOS packages are provided in the JVMSERVER runtime.
    • Make your OSGi runtime behave like a classpath-based environment. If you are using CICS TS 5.3 or later, you can use the last resort bootdelegation behavior, which loads classes from the JVM boot classpath if they fail to load from the bundle class loaders. If the property osgi.compatibilty.bootdelegation is set to true in your environment (a safer but compromised default in CICS TS 5.3), you do not need to add an Import-Package statement to your application. This technique must be considered a last resort as it reduces portability, avoids the need to explicitly declare an application's dependencies, and can lead to unexpected failures if dependencies or runtime later change. If you run instead with the bootdelegation property set to false you have a stricter and more compliant OSGi environment that detects application problems ahead of runtime, with an optimized, performance-orientated approach to OSGi classloading.
  3. Create a CICS Java application. This example adds the JAR (EDUPGM.jar) to the bundle classpath of the new CICS application. Encapsulating the JAR in this way scopes the use of the CommareaWrapper to your application.
    1. Create an OSGi bundle project in Eclipse by using the wizard File -> New -> Other -> Plug-in Project.
    2. Create a Java package com.ibm.cicsdev.jzostest and add a class JZOSprog.
    3. Copy in the following code example, which makes a JCICS Program.link() call to a CICS COBOL program.
      public class JZOSprog
      {
          public static String proglink = "EDUPGM"; // Linked to COBOL program
      
          public static void main(String[] args)
          {
              // Get details about our current CICS task
              Task task = Task.getTask();
              task.out.println(" - Starting JOZSprog");
      
              // Wrapper objects for input and output commareas
              JZOSCommareaWrapper cwIn = null;
              JZOSCommareaWrapper cwOut = null;
      
              // Set the input data fields
              Short binarydigit = 1;
              String charstring = "hello";
              Short numericstring = 1234;
              Integer packeddigit = 123456789;
              Integer signedpackeddigit = -100;
              String bool = "1";
      
              cwIn = new JZOSCommareaWrapper();
              cwIn.setBinaryDigit(binarydigit);
              cwIn.setCharacterString(charstring);
              cwIn.setNumericString(numericstring);
              cwIn.setPackedDigit(packeddigit);
              cwIn.setSignedPacked(signedpackeddigit);
              cwIn.setBool(bool);
      
              // Create a reference to the CICS program
              Program prog = new Program();
              prog.setName(proglink);
      
              // Create byte array for input commarea from wrapper
              byte[] commarea = cwIn.getByteBuffer();
      
              try
              {
                  // Link to target CICS program
                  prog.link(commarea);
      
                  //Create output record from updated commarea
                  cwOut = new JZOSCommareaWrapper(commarea);
              }
              catch (Exception e)
              {
                  // Catch any other exception and force a rollback of CICS UOW
                  String msg = "ERROR: Exception on link to {0} with msg({1})";
                  task.out.println(MessageFormat.format(msg, proglink, e.getMessage()));
      
                  // Rollback the CICS Task
                  try
                  {
                      task.rollback();
                  }
                  catch (InvalidRequestException e1)
                  {
                      // If this fails, then throw Runtime Exception
                      throw new RuntimeException(e1);
                  }
              }
      
              String msg = "Returned from {0} with rc({1}) {2}";
              task.out.println(MessageFormat.format(msg,
              proglink, cwOut.getResultCode(), cwOut.getResultText()));
          }
      }

      This sample uses the setter methods from the generated CommareaWrapper to access the individual fields in the record. Each field in the language record can be written to using methods such as setBinaryDigit() and setCharacterString() and also read with corresponding getters. The entire byte array that represents the records can be passed into a call by using a Java byte[] array that is returned with the getByteBuffer().

      It is best practice when you are generating Java code from language records to rename the language data fields in a Java fashion. This means that the generated code has a naming convention that would be more familiar to a Java programming style.

  4. 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 2.0.0, so the range com.ibm.cics.server;version="[1.300.0,2.0.0)" is used in the example. The JZOS package is not taken from a versioned bundle. It is displayed to the runtime from an underlying JAR file with no version, and so com.ibm.jzos.fields 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.jzostest
    Bundle-SymbolicName: com.ibm.cicsdev.jzostest
    Bundle-RequiredExecutionEnvironment: JavaSE-1.7
    Bundle-Version: 1.0.0
    Import-Package: com.ibm.cics.server;version="[1.300.0,2.0.0)",
    com.ibm.jzos.fields;resolution:=optional
  5. Transfer the EDUPGM.jar containing the CommareaWrapper record onto the workstation. Create a folder in the project that is called lib , and then drag the JAR into this folder in your Eclipse project. Then, from the OSGi bundle manifest editor, add this JAR to the OSGi bundle classpath by using the menu Runtime -> Classpath -> Add. This adds the following statement to the manifest:
    Bundle-ClassPath: lib/EDUPGM.jar,.
  6. Add a CICS-MainClass: definition to the bundle manifest to register a MainClass service for your com.ibm.cicsdev.jzostest.JZOSprog 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.jzostest
    Bundle-SymbolicName: com.ibm.cicsdev.jzostest
    Bundle-RequiredExecutionEnvironment: JavaSE-1.7
    Bundle-Version: 1.0.0
    Import-Package: com.ibm.cics.server;version="[1.300.0,2.0.0)",
    com.ibm.jzos.fields;resolution:=optional
    Bundle-ClassPath: lib/EDUPGM.jar,.
    CICS-MainClass: com.ibm.cicsdev.jzostest.JZOSprog

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:
  1. Create a CICS bundle project in Eclipse and add the OSGi bundle project by using the menu New -> OSGi Bundle Project Include.
  2. Deploy to zFS by using the menu Export Bundle Project to z/OS UNIX File System.
  3. Create a CICS BUNDLE definition that references this zFS location and install it.
  4. Create a CICS PROGRAM definition that names the CICS-MainClass: com.ibm.cicsdev.j2ctest.JZOSprog in the JVMClass attribute and install it.
  5. If you need to run the application from a 3270 console, create a Transaction definition that references the PROGRAM.
When started, your Java class JZOSprog links to the COBOL EDUPGM by using the CommareaWrapper classes to marshal the input to the required COBOL record formats.


develop_java_jzos_api.html | Timestamp icon Last updated: Monday, 5 June 2017