Linking to an OSGi application from a CICS program

You can link to an OSGi application that is running in an OSGi JVM server as the initial program of a CICS transaction or by using the API commands from CICS programs.

To be linked to by a CICS program, an OSGi application must be a plain old Java object (POJO) packaged as part of an OSGi bundle in a Java archive (JAR) file.

Several reasons exist as to why it's useful to link to Java code in an existing program from a CICS® program.
  • Only a single piece of logic needs to be maintained to allow your code to access CICS resources by using JCICS APIs.
  • You want to write new functions in Java as part of your CICS application - for example, you might want to use third-party libraries or APIs that exist in Java.
  • You want to reimplement existing COBOL applications in Java. For example, to make the most of your organization's Java skills or reduce the cost of maintenance. Alternatively you might want to enable your applications to run on specialty processors rather than general-purpose processors.

When you link to a Java application from a CICS program, CICS transfers control into the JVM through the Java Native Interface (JNI) to target the Java application. The Java application runs on the same task and unit-of-work (UOW) as the calling program. Any updates that are made to recoverable CICS resources are committed or backed out when a transaction ends.

It is recommended that Java code that is linked by your CICS program is part of your application's business logic rather than its presentation logic.

You can define Java code as a link target with the CICS-MainClass in the OSGi manifest, or the @CICSProgram annotation - the differences are summarized in the table.

Table 1. Supported features
  Commarea Input message Channel Program auto-install Multiple definitions per class
CICS-MainClass Yes Yes Yes No No
@CICSProgram No No Yes Yes Yes

CICS-MainClass targets a single, static main method of a class and requires configuration in the OSGi manifest file, together with a CICS program definition. It supports Commarea, channels, and Input Message, providing a broader range of link types.

@CICSProgram supports linking with a channel only, but benefits from having its configuration declared in the source code. It can also generate and install program definitions automatically and allows multiple methods to be targeted in the same class.

OSGi is a modular technology, so a JVM server can host multiple versions of the same OSGi bundle. When a CICS program is defined that targets Java code in JVM servers, it might be important to target the code in a specific version of an OSGi bundle.

By default, CICS targets the Java code in the OSGi bundle with the highest version with that code available. To target a specific version, or version range, parameters can be added to the JVMCLASS value.

Scenarios for selecting a specific version, or version range, include.
  • Installing a new version of an OSGi bundle and verify the installation without impacting running applications.
  • Incrementally updating applications to use new function, available at a new version.
  • Remove function from a new version without affecting existing applications.
  • Keeping tight control over dependencies of applications.
Note: When CICS links to Java code in an OSGi bundle, it finds the current highest version, within the specified version range, at the time the link occurs. The link is not wired or cached. Installing a new OSGi bundle into a JVM server can cause the behavior of a link to change automatically.