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
- 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.
- 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.
- 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.
- Create an OSGi bundle project in Eclipse by using the wizard File -> New -> Other -> Plug-in Project.
- Create a Java package com.ibm.cicsdev.jzostest and add a class JZOSprog.
- 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.
- 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 - 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,. - 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
- 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.j2ctest.JZOSprog in the JVMClass attribute and install it.
- If you need to run the application from a 3270 console, create a Transaction definition that references the PROGRAM.
develop_java_jzos_api.html |
Last updated: Monday, 5 June 2017