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

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

Before you begin

Identify which Java class and method you want to call, and adhering to site standards and CICS naming rules, determine a suitable CICS program name.

Procedure

  1. Add the @CICSProgram annotation class to the classpath of your Web Project. If you are using CICS Explorer, the @CICSProgram annotation is provided as part of the Liberty JVM server libraries. If you are not using CICS Explorer, you need to use the com.ibm.cics.server.invocation.annotations.jar JAR file.
  2. 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.
  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").
    CICS PROGRAM names:
    • Must be 1 - 8 characters;
    • Must match the pattern 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. If you are using CICS Explorer, enable annotation processing for the Web Project. To enable annotation processing, either:
    • Hover over a @CICSProgram annotation with a warning underline and use the quick-fix to enable annotation processing;
    • Right-click the Web Project and select Properties. Search for the Annotation Processing page. Check both Enable project-specific settings and Enable annotation processing.
  6. If you are using the 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. 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 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 you are 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.

Results

If the application is installed by a CICS bundle, PROGRAM resources are created as the CICS bundle becomes ENABLED. If the application is installed directly from server.xml or from a file by using an <application> element; PROGRAM resources are created as the application is installed.

You can now link to the Java program from another CICS program by using:

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


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