Preparing an OSGi application to be called by a CICS
program using @CICSProgram
Annotations can be used to enable a Java™
main
method to be invoked by a CICS®
application - CICS creates the program resource for you. The
OSGi application runs in an OSGi JVM server and can be deployed within an OSGi bundle
JAR.
Before you begin
First, identify which Java class and method you want to call. Then - while adhering to site standards and CICS naming rules - determine a suitable CICS program name.
To avoid concurrency issues, JCICS objects should only be stored in local or instance variables.
Procedure
- Add the
@CICSProgram
package to the dependencies of your project.- CICS Explorer If you are using the preinstalled IBM CICS SDK for Java in CICS Explorer, the SDK includes the OSGi JVM server libraries as a CICS TS 6.1 Target platform template.
- GradleMaven If you are using your own build
toolchain, you need to declare dependency on the
com.ibm.cics.server.invocation.annotations
artifact available on Maven Central, or use thecom.ibm.cics.server.invocation.annotations.jar
file. For more information see Managing Java dependencies using Gradle and Maven and Manually importing Java libraries.
- Create a class to contain the methods that CICS calls. Creating a class is good practice because it keeps the CICS-specific code separate from the rest of your application.
- For each Java method that you wish to be eligible
for a CICS LINK, annotate the method with
@CICSProgram
. When the application is installed, CICS automatically generates a corresponding PROGRAM definition (or you can manually create definitions and these will take precedence). - When you annotate each relevant method with the
@CICSProgram
annotation, give it a parameter of the PROGRAM name, such as@CICSProgram("PROGNAME")
. CICS PROGRAM names must:- Be 1-8 characters in length.
- Match the pattern
A-Z A-z 0-9 @#
.
An example of how to annotate your Java method in a simple class:public class CustomerLinkTarget { @CICSProgram("CUSTGET") public void getCustomer() { // do work here } }
- Enable annotation processing for the OSGi bundle project.
- CICS Explorer If you are using CICS
Explorer, either:
- Hover over a
@CICSProgram
annotation with a warning underline and use the quick-fix to enable automation processing, or: - Right-click the Web Project and select Properties. Search for the Annotation Processing page, and check both Enable project-specific settings and Enable annotation processing.
- Hover over a
- GradleMaven If you are using a build
toolchain such as Gradle or Maven, configure the Java compiler
to use
com.ibm.cics.server.invocation
as an annotation processor as described in Managing Java dependencies using Gradle and Maven.
- CICS Explorer If you are using CICS
Explorer, either:
- Validate that the annotation is correctly specified.
- CICS Explorer If you are using CICS Explorer, validation occurs automatically to ensure that your annotation is correctly positioned and that the method it annotates and the containing class fulfill the following requirements.
- Maven If you are using Maven
in Eclipse, you can use the
m2e-apt
plug-in to get the annotation processing configured in Eclipse, based on the dependencies specified in your pom.xml file.
- Be on a method.
- Have a value attribute of a PROGRAM name.
- Be concrete - not abstract.
- Have no arguments.
- Be declared
void
.
- Have a constructor with no arguments (implicit or explicit) unless all annotated methods are static.
- Be top level - not nested or anonymous.
- Not have more than one method that is annotated with the same PROGRAM name.
- Write the content of the annotated method, which is likely to involve:
- Obtaining containers from the channel
- Obtaining input data from containers in a channel
- Using data mapping code to convert the input data into Java objects
- Calling the application business logic
- Using data mapping code to convert the resulting Java objects into output data
- Placing the output data in containers within a channel
@CICSProgram
annotation, including code that takes input data from a container and placing output data in a container:public class CustomerLinkTarget { @CICSProgram("CUSTGET") public void getCustomer() { Channel currentChannel = Task.getTask().getCurrentChannel(); Container dataContainer = currentChannel.getContainer("DATA"); // do work here Container resultContainer = currentChannel.createContainer("RESULT"); byte[] results = null; // change this to be the result of the work resultContainer.put(results); } }
- Build the application.
- CICS Explorer If you are using CICS Explorer, you can right-click the Web Project and choose Export > JAR file, or right-click a containing CICS Bundle Project and select Export Bundle to z/OS UNIX file system.
- If you are using the CICS build toolkit, the annotation processor is invoked automatically.
- GradleMaven If you are building the Java
code using other tools, ensure that the dependency on the CICS annotation and the annotation
processor configuration are correctly specified by using the artifacts on Maven Central. If you do
that according to steps 1 and 5, they are resolved automatically during build.Otherwise, you must ensure that the
com.ibm.cics.server.invocation.annotations.jar
JAR file (which defines the@CICSProgram
annotation) is on the classpath of the Java compiler. Also, ensure that thecom.ibm.cics.server.invocation.jar
JAR file (containing the annotation processor) is on the classpath of the Java compiler, or is otherwise specified in the -processorpath option. You can find both JAR files in the usshome/lib directory on z/OS UNIX, where usshome is the value of the USSHOME system initialization parameter.Note: The CICS annotation processor generates additional classes and XML files within thecom.ibm.cics.server
package to represent your annotated resources, alongside your annotated code.
- Deploy your application. See Deploying OSGi bundles in a JVM server for more information.
Results
EXEC CICS LINK PROGRAM("CUSTGET") CHANNEL()