CICS has introduced a choice for how Liberty runs inside a JVM server: standard-mode and integrated-mode. Read all about it in this blog.

There’s a new way to run Liberty in CICS that’s less integrated with CICS than ever before. Hold up! Less integrated? Haven’t the CICS team worked hard to provide increased CICS-Liberty integration for the last few releases? Yes, but don’t panic, this is in addition to the existing (and growing!) set of integrated Liberty features.

So why this new standard mode? In an agile delivery world we recognise the need for running standard applications within the CICS ecosystem. The benefits include using fewer CICS resources by default and being able to run existing Liberty Java Enterprise Edition (Java EE) applications unchanged in CICS.

Does this mean we’re investing less in CICS-Liberty integration? Absolutely not. Full integration with Liberty features continues to forge ahead. The July 12th announcement details a whole new list of supported Liberty features available in CICS TS V5.3 and the open beta. The announcement affirms our commitment to achieving Java EE 7 Full Platform support with CICS integration. Don’t worry, if you’re happy using integrated-mode, this will continue to be the default – nothing will change beneath you.

What do the new modes mean?

CICS integrated-mode Liberty

Let me start with some context. The mode of operation you’ve come to know and love has been given it’s own name. In CICS parlance (not WebSphere) we call it CICS integrated-mode Liberty. In CICS integrated-mode Liberty, all web requests are fulfilled by a CICS-enabled thread. The requests run under a CICS task and provide access to CICS resources from your Java web application. That’s a great place to be if the features you require are supported in this mode, but that’s not always the case. From speaking to many of our customers, the following scenario is common:

“We’d like to use features A, B, and C, but only need access to CICS from feature C”.

Wouldn’t life be easy if everyone agreed that only feature C needed access to CICS resources! In reality each customer requires a different feature set and different access to CICS. The upshot is that CICS needed a fresh approach to accelerate support for Liberty features.

Introducing CICS standard-mode Liberty

After a thorough brain-storming session (or in IBM terms, some Design Thinking) we decided to turn things on their head. What if Liberty in CICS ran just like it does outside of CICS? In other words, you would not run on CICS-enabled threads, there would be no CICS security integration, and no access to CICS native drivers for DB2. Our support for Liberty features would be accelerated, enabling us to satisfy customers who’s need for function outweighs the need for integration. We’d certainly give the migration path a boost; moving Liberty applications from outside of CICS into CICS would be significantly easier with everything supported as standard. To top it off, offering an opt-in API that allows a developer to request execution on a CICS-enabled thread would provide ultimate flexibility.

So that’s precisely what we’ve done. With a single line option in the JVM profile you can transform your Liberty JVM server from CICS integrated-mode Liberty to CICS standard-mode Liberty and run the entire Java EE 7 Full Platform set of features. Let’s dwell on that a little… we’re not just talking about Java EE7 Web Profile… we’re talking about the FULL Java EE 7 Platform, EJBs and all. If that doesn’t give you the heebie-JEEbies, nothing will!

Of course you won’t have the automatic CICS integration – so if you are in the game of frequent JCICS calls to CICS resources, you won’t get the optimised performance of the dedicated CICS thread-pool (introduced in CICS TS V5.3) – but if the workload is more Java EE than ‘CICS-ee’, this could be the option for you.

So why do we call it CICS standard-mode Liberty? Apart from the fact that disintegrated-mode never really caught on, the name reflects that we’re offering a more standard and less CICS-integrated runtime. However, you’ll continue to get life-cycle and administrative control over the Liberty server instance. CICS bundle application deployment is available, and programmatic opt-in to CICS-enabled threads will provide the expected access to CICS resources, CICS security, and native DB2 drivers.

So which one should you use?

Now that you’ve seen the headlines, let’s look at little closer at the differences between the CICS integrated-mode Liberty and CICS standard-mode Liberty. Here’s a little table that might help you…

Capability CICS integrated-mode Liberty CICS standard-mode Liberty
Supported feature set Java EE 7 Web Profile
Java EE 6 Web Profile
Java EE 7 Full Platform
Java EE 7 Web Profile
Java EE 6 Web Profile
Java CICS API (JCICS) Yes Yes under runAsCICS() API only
Native driver for DB2 Yes Yes under runAsCICS() API only
Ease of app migration to CICS Liberty Moderate Easy
Asynchronous operations and nested transactions Some restrictions Yes
CICS bundle deployment of app? Yes Yes
CICS Liberty autoconfigure available? Yes Yes
JVM server creates and controls the Liberty server? Yes Yes
zIIP eligibility Up to 90% Up to 99%
CP Integration overhead Minimal overhead
CICS thread-pool optimisations Yes No

As the table indicates, it is easier to migrate an application into CICS standard-mode Liberty. This is because more Liberty features are supported. The behaviour reflects the operation of Liberty outside of CICS, there are no CICS specific restrictions, or configurations. You will also get higher zIIP eligibility because native CICS-integration code does not run. In fact, the reason why there is a comparative reduction in CP cycles per request is because the native code isn’t bootstrapping into a CICS task environment for each request.

As your application looks to use CICS resources and integrate with CICS capabilities (eg. JDBC type 2), CICS standard-mode Liberty requires you to programmatically opt-into a CICS-enabled environment. This is done using the CICSExecutorService.runAsCICS() API. Just as in CICS integrated-mode Liberty, additional overhead and zIIP eligibility reduction are the trade-offs for running under a CICS task. CICS standard-mode Liberty requires your CICS resource work to be isolated into discrete operations that can be run through the runAsCICS() API. Componentisation is no bad thing though! You will get the most out of CICS standard-mode Liberty by keeping access to CICS minimal and within specific components.

As the level of CICS integration increases, the cost of running in CICS standard-mode Liberty compared to CICS integrated-mode Liberty rises. Although both environments can put your workload into a CICS enabled environment, CICS integrated-mode Liberty uses an internal thread-pool as well as other scalability optimisations not available to the one-shot CICS enabled threads of CICS standard-mode Liberty. There is another very important distinction too, the one-shot threads used to satisfy runAsCICS() requests are not Java EE capable. You cannot mix your JCICS with your Java EE. Conversely, requests running in CICS integrated-mode Liberty (using the optimised thread-pool technology) can happily mix and match Java EE APIs and JCICS APIs.

Are you ready to get started using Liberty in CICS?

So you’ve read the waffle, you understand the differences between the modes of operation, and you want to try it out? What should you do?

You’ll need to apply the V5.3 Service APAR PI58375 for the runtime support. To allow the new JCICS APIs to compile in your local development environment, you’ll need the CICS Explorer APAR IV86604.

If you haven’t already opted into using com.ibm.cics.jvmserver.wlp.autoconfigure=true in your JVM profile, that’s where you should start. Unless you really need to manually configure the Liberty server yourself, don’t, let CICS do it for you. You can add further Liberty features and configuration to server.xml yourself. CICS can’t guess which Java EE features you’ll need, so add them as required, autoconfigure is not going to mess with those unless you rip out something fundamental to CICS operation. If you do, it’ll just add it back! Tip: use the convenience feature Java EE 7 Web Profile which adds in all of the Java EE 7 Web-profile features.

You should be aware that some of the CICS-Liberty product extension features, like the cicsts:jcaLocalEci feature and the cicsts:zosConnect features are CICS integrated-mode Liberty only. Don’t worry, you’ll be offered a failure message if you mix them up 😉 .

While you are in the JVM profile, add the CICS_WLP_MODE=STANDARD option. Don’t be shy, give it a try! Underneath the covers (for those opting to manually configure the server.xml), it’s just a case of swapping out the cicts:core-1.0 feature and replacing it with the cicsts:standard-1.0 feature. That’s it for the runtime! When you next enable your Liberty JVM server it will be running in CICS standard-mode Liberty. If you try to configure the cicsts:core-1.0 and cicsts:standard-1.0 features in the same server you’ll be presented with a polite error message and the server will graciously fail to start.

With a successful server ‘enable’ under your belt, you can deploy applications within a CICS bundle as usual, or if you prefer, you can add your own <application> elements to server.xml. Even using Liberty drop-ins is supported.

Three things could happen next, either your application does not require access to CICS resources and it runs just as it would outside of CICS – smiles all round. Or your application contains JCICS calls and it doesn’t work any more – hold that thought. Or, you are way ahead of me and put your JCICS calls into a Runnable or Callable object and submitted them to the CICSExecutorService.runAsCICS() method, in which case you probably don’t need to be reading this.

I’m going to assume we’re on the JCICS failed path, I’m pretty sure I would be. You were probably disappointed to see a “naah! naah! you’re not on a CICS thread” Exception (don’t quote me on the actual Exception message). There is a solution though…

To allow your application to make JCICS or CICS native DB2 calls:

    • create a Callable or Runnable object and put your code inside the call() or run() method.
    • Next, create an instance of the Callable or Runnable containing the JCICS method(s), and pass that instance to the CICSExecutorService.runAsCICS() method.

Note: CICS will asynchronously spawn a CICS task on a Java thread and run your code. To pass data back to the mainline code, or even for the mainline code to wait for a result (synchronisation) then use a Callable rather than a Runnable. Submitting a Callable to the runAsCICS() API will return to you a Future object on which you can invoke the isDone() method to wait for work to complete, and subsequently the get() method to receive your data.

I’ll provide a simple example in just a moment, but there is another key piece of information you might find useful. All workload submitted to runAsCICS() will run under transaction CJSA by default. You might not want that, and you might not have realised that your Java work is not a Web-request so the normal URIMAP matching capability isn’t available. Fortunately, we provide another way to run work under a transaction ID of your choice. That’s where the new CICSTransactionCallable and CICSTransactionRunnable interfaces come in, they are provided by JCICS for your delight. Simply add the ‘implements’ keyword for the relevant interface, and implement the getTranid() method. Returning a simple four character string of choice runs your code on that transaction ID. Don’t forget to clone CJSA and install it as the transaction ID you’ve specified.

So here’s a really basic example of how to use a CICSTransactionCallable:

 
package com.ibm.cics.ivan.executor;

import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;

import com.ibm.cics.server.CICSExecutorService;
import com.ibm.cics.server.CICSTransactionCallable;
import com.ibm.cics.server.IsCICS;
import com.ibm.cics.server.TSQ;
import com.ibm.cics.server.Task;

public class ExecutorTest
{
    // Java Callable used to encapsulate CICS work
    static class TSQCallable implements CICSTransactionCallable<String>
    {
        private String tsqName;
        private String tsqMessage;

        public TSQCallable(String qname, String message)
        {
            tsqName = qname;
            tsqMessage = message;
        }

        public String call()
        {
            // construct a JCICS representation of the TSQ object
            TSQ tsqQ = new TSQ();
            tsqQ.setName(tsqName);

            // Show we are on a CICS enabled thread/task
            System.out.println("API status = " + IsCICS.getApiStatus());

            // Write a message to the TSQ
            int myTask = Task.getTask().getTaskNumber();
            try
            {
                tsqQ.writeString("TransactionCallable Task: " + myTask + " says: " + tsqMessage);
            }
            catch (Exception e)
            {
                e.printStackTrace();
            }

            return "Callable has completed";
        }

        @Override
        public String getTranid()
        {
            // The Transaction ID you want to run this work under
            // Don't forget to install the transactionID in CICS!
            return "TRAN";
        }
    }

    public static void main(String[] args)
    {
        // Submit a new Callable to the CICSExecutorService,  and receive a Future object
        Future<String> future = CICSExecutorService.runAsCICS(new TSQCallable("TEST", "HelloWorld"));

        // Wait for the test to complete (optional)
        while(!future.isDone())
        {
            try
            {
                Thread.sleep(500);
            }
            catch (InterruptedException e)
            {
                e.printStackTrace();
            }
        }

        // Print the return data from the Callable
        try
	{
	    System.out.println("ExecutorTest: '" + future.get() + "' from the Callable");
	}
	catch (InterruptedException | ExecutionException e)
	{
	    e.printStackTrace();
	}	
    }
}

Anything else?

Beyond that I’ll refer you to the CICS Knowledge Center and the recently published performance Redpaper A CPU Utilization Study of Java EE applications running in CICS TS V5.3 for further information.

As always we appreciate your comments and requirements on how we can improve the technology. Give us your comments below, through your CICS advocate, or raise a request for enhancement (RFE).

1 comment on"CICS is now arriving at the Java EE 7 Full Platform"

  1. Phil_Wakelin May 25, 2018

    Note that as of APAR PI77502 CICS TS V5.3 now supports the Java EE 7 Full Platform set of features in an integrated-mode Liberty JVM server. Support is also provided in the GA version of CICS TS V5.4

Join The Discussion

Your email address will not be published. Required fields are marked *