In a previous chapters, we've discussed COBOL running inside CICS and the Application Programming Interface (API).
We've seen how easy it is to include command-level EXEC CICS commands in a COBOL program, to request with CICS services.
As CICS has evolved, with features being announced with every release, so the API has been enhanced to provide support for these new features.
For example, the introduction of WEB commands to support web protocols, and commands to support Channels and Containers.
In this chapter we look at three new features:
- Asynchronous programming
- Event processing
- Link to Liberty
7.1 Asynchronous programming
CICS TS V5.4 introduced a set of API to simplify asynchronous programming for application programmers.
7.1.1 Asynchronous programming analogy
To explain what we mean by asynchronous programming, let's consider an example.
Debra goes to the market, to shop, on Saturday morning.
She always parks in the short duration car park, so only has a limit amount of time to complete her shopping.
She needs to buy bread and cakes from the baker, eggs from the butcher and fruit and vegetables from the grocers.
She goes to the shops in sequence, first the Baker, then grocer and finally the butcher.
Unfortunately, in the bakers she must wait for bread to come out of the oven.
This means she takes too long and gets a parking fine.
See Figure 7-1.
The following Saturday, she takes her three sons, Will, Martin and Jim with her.
She sends Will to the bakers to buy bread and cakes, Martin to buy fruit and vegetables and Jim is sent to the butchers to buy the eggs.
She waits in her favourite café until they had completed the tasks.
She has asked all three boys to text her when they have finished shipping so she can arrange a place to collect them.
When they had all responded, Debra finishes her coffee, jumps in her car and goes off to collect them.
Debra has completed the task asynchronously.
See Figure 7-2.
7.1.2 Asynchronous programming principles
The example demonstrates the main principles of asynchronous programming.
Firstly, the ability to split work into separate tasks that can be run independently – sending her boys off to shop.
Secondly, trace the completion of the asynchronous work – the boys sent their mum a text when finished their shopping.
Finally, ok this was not demonstrated by the example but still important, is to pass data safely between main and asynchronous tasks.
To be fair, asynchronous programming has been around for a while as a concept and application programmers have used various programming techniques, such as EXEC
CICS START and EXEC CICS DELAY with some kind of “polling” to test if the called program has completed.
Or an EXEC CICS WAIT /POST combination.
But these techniques have proved to be non-trivial and notoriously difficult to implement for several reasons including timing windows.
The aim of the CICS asynchronous APIs is to simplify this process for the application programmer by providing the function natively within CICS.
The CICS asynchronous API is built around a parent to child programming model.
CICS APIs address the three main aspects just mentioned using four API commands:
- EXEC CICS RUN TRANSID to initiate a CHILD transaction that runs asynchronously
- EXEC CICS FETCH CHILD to inquire on the status of a “specific” CHILD task
- EXEC CICS FETCH ANY to inquire on the status of “any” completed child task which has not yet been fetched.
- EXEC CICS FREE CHILD to forget a child that has not responded
Additionally existing EXEC CICS PUT CONTAINER and EXEC CICS GET CONTAINER commands pass data between asynchronously running processes.
Consider a Parent task running some business logic.
At some point, a child task is run (EXEC CICS RUN TRANSID) and the parent passes data to the child in a PUT Container.
The child begins to run as a separate task in the same region as the parent (Figure 7-3).
Importantly, the parent can continue processing independently of its child, it is not blocked by the child, as would happen if the parent had LINKed to the child
When the parent is ready for the result from the Child it issues a FETCH CHILD and waits.
It does not have to continuously “Poll” for the result.
The child can issue the CICS API and can link to a remote region or invoke a web service (Figure 7-5).
When the children task completes, the parent is resumed.
The child passes data back to its parent in a container (Figure 7-6).
To recap, the new API provide an easy to implement asynchronous programming from your application.
You don’t need to worry about how it works, just that you can split off independent units-of-work from the main program, but still have the capability of tracking
7.2 Event processing
CICS applications have been the bedrock of mission critical applications for decades.
But, for a number of reasons, the business logic in some legacy programs is locked into the code and can be difficult to enhance or extend.
Event Processing is a CICS feature that can detect and respond to events occurring within an application.
The ability to detect events and emit them for consumption can give an insight into the application’s performance and open up a number of new opportunities.
7.2.1 Event processing in CICS
Using Event Processing, certain points of interest are registered as capture points.
These capture points are based on a subset of existing CICS API – EXEC CICS commands plus a new, Event Processing API – EXEC CICS SIGNAL EVENT. See Figure 7-7.
By coding a SIGNAL EVENT in existing applications, events can be picked up by Event Processing and sent to an external consumer for evaluation.
But, in cases where it is not possible to include the new SIGNAL EVENT API into the program - for example, where the COBOL source has been lost - it is possible
for CICS to generate a business event without amending the application.
Using CICS Explorer®, an Event Binding is created to define Capture Specification and link these to an Event Specification (Figure 7-8).
The Event Specification defines the business event and what application data will be passed to the consumer.
The Capture specification defined capture points are EXEC CICS commands that can be used to trigger an event.
These can be filtered by command options and source information, such as the name of the calling program.
Adapters are programs that format and then emit events from a CICS system.
At runtime, if the user program issues an EXEC CICS command that matches the Capture point filter criteria defined by the event binding, then Event data is passed
to the relevant Adapter for formatting and then routed to the appropriate external event consumer.
One such consumer is IBM Operational Decision Manager. See Figure 7-9.
7.2.2 Event processing example
A betting company is interested in bets placed over $10,000.
The program that manages bets is BETTING and the point we are interested is when BETTING links to program PLACEBET (Figure 7-10).
Using the Event Binding Editor, an Event specification is created naming the event and outline the data passed to the Event consumer.
In this case, the data passed is the Customer name and Betting shop location (Figure 7-11).
The Capture Specification would specify the Capture point as an EXEC CICS LINK PROGRAM to PLACEBET located in BETTING (Figure 7-12).
Finally, the Adapter would start a New CICS Transaction “BET1”. Notice, the exact location of the LINK in the program is not specified, and probably not even known.
To recap.Using Event Processing, events are defined and controlled independently of the business logic, extending a business application without modification.
This provides the business real time metrics about the performance of the application – unlocking secrets of legacy applications.
7.3 Link to Liberty
The previous module explained how to extend applications using Java.
A further enhancement to Java support is a “Link to Liberty” feature introduced at CICS TS 5.3.
Link to Liberty allows a non-Java CICS program to invoke a Java Enterprise Edition (EE) application running in a Liberty JVM server, in CICS.
A Java method is identified as a “Target” for an EXEC CICS LINK (or START) in a non-Java program.
This method acts as an Entry Point into the Java application running in the Liberty JVM server. See Figure 7-13
Let’s look at what needs to be setup to enable a non-Java program to invoke a Java application called CUSTGET.
We will illustrate this using CICS explorer, but other tools such as Gradle are available.
First, prepare the Java EE application.
Create a Dynamic Web project using CICS Explorer and add the annotation class to the project classpath (Figure 7-14).
In a suitable class, add the method that will act as the target method, for the non-Java program to use.
Then, create the method, including the “@CICSProgram” annotation, giving it a parameter of PROGRAM.
In this case, the program name is CUSTGET (Figure 7-15).
For the @CICSProgram to work with the compile, Annotation Processing needs to be Enabled for the Web Project, so the compiler can handle the @GETProgram syntax
Code your Java application using the Target method as the Entry Point.
Now, build the application and export it to the z/OS platform as a WAR file.
During the Java compile, the annotation processor validates contents and location of @GETProgram annotation and generates code and artifacts required by CICS to
invoke the application.
This makes the target method available as a linkable program when installed into the Liberty JVM.
The application and its artifacts are then exported to the z/OS platform as a WAR file, where it can be deployed into a liberty JVM server.
When the application is deployed, either as part of a CICS Bundle or directly from server.xml or from a file by using an element, CICS will create a
CICS Program resource dynamically.
The name of the RDO program resource will the program name on the @GETProgram annotation in the Java method.
Non-Java programs can use CICS API to invoke the Java application via the target method (XX).
This document was created or updated on December 17, 2020.
© Copyright IBM Corp.