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
- 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.
- 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.
- Create a method for each CICS PROGRAM resource to be created.
- 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
}
}
- 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.
- 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.
- Write the content of the annotated method. The content is
likely to involve the following
stages:
- Obtain containers from the channel;
- Obtain input data from containers in a channel;
- Use data mapping code to convert the input data to Java
objects;
- Call the application business logic;
- Use data mapping code to convert the resulting Java objects
to output data;
- 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);
}
}
- 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.
- 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()