Preparing a Java EE application to be called by a CICS program

With CICS® TS APAR PH14856, you can use annotations to enable a Java™ method to be invoked by a CICS application - CICS creates the PROGRAM resource for you. The Java EE application runs in a Liberty JVM server, and can be deployed within a WAR or EAR.

1. Add the @CICSProgram annotation class to the classpath of your Web Project.
   • If you are using the preinstalled CICS Explorer® SDK in CICS Explorer, the SDK includes the Liberty JVM server libraries, which provide the @CICSProgram annotation.
   • If you're using your own build toolchain, you need to declare dependence on the com.ibm.cics.server.invocation.annotations artifact that's available on Maven Central or use the com.ibm.cics.server.invocation.annotations.jar JAR file as described in Developing applications using other tools.
2. Create a new class to contain the methods that CICS calls.
   Creating a new class is good practice because it keeps the CICS specific code separate from the rest of your application.
3. Create a method for each CICS PROGRAM resource to be created.
4. Annotate each method with the @CICSProgram annotation, giving it a parameter of the PROGRAM name, such as @CICSProgram("PROGNAME").
   A CICS PROGRAM name must be 1 - 8 characters.

   Acceptable characters

   A-Z a-z 0-9 $ @ #

   Example of a simple class with a single method, annotated with the @CICSProgram annotation:

   public class CustomerLinkTarget 
   {
       @CICSProgram("CUSTGET")
       public void getCustomer() 
       {
          // do work here                       
       }                
   }

5. Enable annotation processing for the Web Project.
   • If you are using CICS Explorer, either:
     • Hover over a @CICSProgram annotation with a warning underline and use the quick-fix to enable annotation processing, or:
     • Right-click the Web Project and select Properties. Search for the Annotation Processing page. Check both Enable project-specific settings and Enable annotation processing.
   • If you're using a build toolchain such as Maven or Gradle, configure the Java compiler to use com.ibm.cics.server.invocation as an annotation processor, as described in Developing applications using other tools.
6. Validate the annotation is correctly specified.
   • If you are using CICS Explorer, validation happens automatically to ensure that your annotation is correctly positioned and that the method that it annotates and the containing class fulfills the following requirements.
   • If you're using Maven in Eclipse, you can use the m2e-apt plugin to get the annotation processing configured in Eclipse based on the dependencies specified in your pom.xml file.
   The annotation:

   • Must be on a method;
   • Must have a value attribute of a PROGRAM name.

   The method:

   • Must be concrete (not abstract);
   • Must be public;
   • Must have no arguments.

   The class:

   • Must have a constructor with no arguments (implicit or explicit), unless all annotated methods are static;
   • Must be top level (not nested or anonymous);
   • Must not have more than one method that is annotated with the same PROGRAM name.
7. Write the content of the annotated method. The content is likely to involve the following stages:
   1. Obtain containers from the channel;
   2. Obtain input data from containers in a channel;
   3. Use data mapping code to convert the input data to Java objects;
   4. Call the application business logic;
   5. Use data mapping code to convert the resulting Java objects to output data;
   6. Place the output data in containers in a channel.
   Example of a class with a single method, annotated with the @CICSProgram annotation, and code to take input data from a container and put output data to 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);
      }                
   }

8. Build the application.
   • If you are in CICS Explorer, you can right-click the Web Project and select Export > WAR 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.
   • If you are building the Java code by 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've done that in Steps 1 and 5, they are resolved automatically during build. Otherwise, you must ensure 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 the com.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.
   • If the class is packaged in a library JAR inside the WEB-INF/lib directory of a WAR file, export the generated metadata when building the JAR. In CICS Explorer, you can do this by adding the library project to the deployment assembly of the Dynamic Web project. From the properties dialog for the Dynamic Web project, choose the Deployment Assembly page, click the Add button, and select the library project. CICS does not support @CICSProgram annotations on classes that are packaged in a utility JAR within an EAR file.
9. Deploy the application.

EXEC CICS LINK PROGRAM("CUSTGET")CHANNEL()