CICS has supported Web Services for quite a while now such that it is now a popular CICS technology. This article provides links to some of the many sources of information you might find useful if you're interested to learn more about the family of technologies for the support of web services in CICS TS..
A little history
CICS TS V3.1 was the first release with integrated support for SOAP Web services back in 2004. Some readers may recall the earlier SOAP for CICS Feature (a technical preview from 2003) and the earlier still SOAP for CICS SupportPac (also 2003). In the years since then the technology has evolved considerably, additional specifications have been supported, JSON has arrived, and the use of Web services has become widespread.
Web services can be used to expose CICS assets to off-platform clients using open standards. The technology is also used by CICS applications that call remote Services hosted somewhere on the network. Traditional structured application data can be converted to and from XML and JSON data representations. Sophisticated user identity technologies can be used to track individuals across platforms. Complex business applications can be abstracted into Services, and made available to business partners and app developers, without exposing the CICS implementation details.
There are many tools and technologies that can be used to either implement or call Web services in CICS. These include (in no particular order):
SOAP Web Services, the integrated technology from CICS TS V3.1. This is sometimes referred to as 'native' Web services, implying that the technology is embedded in CICS and exploits the underlying services of the CICS platform.
Applications can use the integrated CICS service for transforming SOAP messages to and from application data (using WSBind files)
Applications can process/generate XML themselves, if preferred.
JAX-WS, the Java API for XML Web Services. This is a pure Java technology for Web services that can be hosted in the CICS Liberty Profile from CICS TS V5.1 onwards
Java applications can use the JCICS libraries in order to interact with CICS.
The Mobile Feature Pack, the initial offering for support of JSON Web Services in CICS. This is available from CICS TS V4.2 onwards, and is integrated into CICS TS V5.2.
Applications use WSBind files to facilitate JSON data transformations.
JAX-RS, the Java API for RESTful Services. This is a pure Java technology for RESTful Web services that can be hosted in a CICS Liberty JVM server from CICS TS V5.1 onwards.
Java applications can use the JCICS libraries in order to interact with CICS resources and the JSON Liberty profile feature for data interchange.
CICS TG V9.1, the CICS Transaction Gateway includes technology for transforming JSON data to and from structured application data. It can be used with the entire family of CICS products, including older versions of CICS TS and CICS VSE and TxSeries.
Applications use WSBind files to facilitate JSON data transformations.
z/OS Connect, a component of the WebSphere Liberty Profile on z/OS, it can be used to transform JSON data to and from structured application data, and interacts with CICS using WOLA.
Applications use WSBind files to facilitate JSON data transformations.
z/OS Connect in CICS, as of APAR PI25503, z/OS Connect can be hosted within CICS TS V5.2. It performs the same JSON data transformations as in the WebSphere Liberty Profile, but uses a local connection to CICS.
Applications use WSBind files to facilitate JSON data transformations.
There are various resources you might find useful if new to Web services, in addition to the CICS Knowledge Center.
A good place to start is the 2014 CICS Web Services, Part 1 - Development Webcast: http://www-01.ibm.com/support/docview.wss?uid=swg27043801 . It introduces SOAP and JSON Web Services from the point of view of an Application Developer. It will introduce you to the tools and techniques that are available.
Published in November 2008, this book begins with an overview of Web services standards and the Web services support provided by CICS TS V3. Complete details for configuring CICS Web services using both HTTP and WebSphere MQ are provided next. It concentrates on the implementation specifics such as security, transactions, and availability.
Published in May 2009, this book considers performance by using different scenarios including Security, MTOM/XOP, and the use of the IBM Tivoli® Monitoring tools to help identify problems that can affect the performance of Web Services. It uses ITCAM for SOA and OMEGAMON XE for CICS on z/OS to show how these tools can be of benefit to identify the cause when the performance of a Web service in CICS becomes unacceptable.
Published in December 2008, this book considers the different ways that CICS Web services can be secured. It considers transport-level security mechanisms such as SSL/TLS and CICS support for the message-based security specifications WS-Security and WS-Trust.
CICS Web Services Workload Management and Availability
Published in March 2008, this book discusses the different techniques that can be used to provide high system availability and workload management for CICS Web service applications and how high availability is provided across a Parallel Sysplex.
It's been a busy week at the SHARE conference in Orlando, with over 1000+ attendees attending 500+ sessions. And while it was a busy time for the CICS staff in attendance at the conference, they found time to collaborate with the IBM Redbooks team in a series of videos.
Andrew Bates talks about emerging CICS trends
Chris Poole describes how CICS TS supports a DevOps environment
Ian Burnett highlights some of the key publications describing CICS TS performance
Will Yates talks about building mainframe skills with IBM Redbooks
CICS web support is a collection of CICS services that enable a CICS region to act both as an HTTP server and as an HTTP client. When CICS is an HTTP server, a web client can send an HTTP request to CICS and receive a response. The response can be a static response created by CICS from a document template or static file, or an application-generated response created by a web-aware application program, or a SOAP response from a CICS web service.
Since CICS web support was introduced, it has become one of the most popular methods of interacting with CICS applications. The CICS TS V5.3 open beta offering delivers a number of significant optimizations in this area to help reduce the costs associated with serving HTTP requests:
Removing the need for the web attach task
Reducing TCB switching for CICS-provided SSL support
Support for AT-TLS aware
Removing the need for the web attach task
Prior to the CICS TS V5.3 open beta, a web attach task (CWXN transaction) is started in CICS, to process each HTTP request requiring a dynamically generated response, before passing the request to the user transaction such as CPIH for a web service or CWBA for a web application, which may then link to an AOR to invoke the required business logic application.
The optimizations provided mean that the web attach task is no longer needed for serving HTTP requests. Instead, the HTTP request is passed directly to the appropriate user transaction, thus reducing the CPU and memory overhead. The scenarios supported for optimzsation include any web or web service based application that doesn't use SSL and doesn't use an analyzer. The TCPIPSERVICE and URIMAP resource definitions for these scenarios would be as follows:
If your CICS web support configuration meets the criteria, you will get the benefit automatically by upgrading to the CICS TS V5.3 open beta.
If your configuration doesn't use a URIMAP or requires an analyser, you may want to review the configuration to take advantage of the potential optimization. If your configuration uses SSL in CICS, there have been other performance enhancements in this area but the web attach task is still required. However, it is still possible to remove the web attach task for SSL web requests by migrating from CICS SSL support to AT-TLS.
Reducing TCB switching for CICS-provided SSL support
CICS SSL support runs on S8 TCBs. In previous CICS releases, S8 TCBs were incapable of performing socket I/O. This meant that there would be multiple TCB switches to and from S8 TCBs during SSL handshakes and send and receive of encrypted data. In the CICS TS V5.3 open beta, most of the switches have been eliminated by making the S8 TCBs eligible to perform socket I/O. Therefore, scenarios using CICS SSL support also see performance improvements.
Adding support for AT-TLS aware
The optimization for removing the web attach task can be applied for inbound HTTPS requests, when SSL support is provided by the Application Transparent Transport Layer Security (AT-TLS) feature of IBM z/OS Communications Server. The CICS TS V5.3 open beta has been enhanced to exploit AT-TLS AWARE capability for inbound HTTP connections (those which connect using a TCPIPSERVICE configured with PROTOCOL(HTTP)).
AT-TLS is the component of z/OS Communications Server which can be configured to encrypt/decrypt message flows for specific ports (such as a TCPIPSERVICE port). AT-TLS defines an AT-TLS POLICY to configure properties such as KEYRING, CIPHERS, SERVER CERTIFICATE, TLS PROTOCOL(S) etc.
CICS can already be used today with AT-TLS in BASIC mode. In BASIC mode CICS is unaware that the data flowing on a socket is being encrypted and decrypted by AT-TLS and will only ever see clear text (unencrypted) data, and thus a TCPIPSERVICE will have SSL(NO) defined. A major drawback of this is that a server, such as CICS, is unaware that a client certificate may exist. This means that CICS is unable to exploit certain TCPIPSERVICE security setups when running AT-TLS in BASIC mode. For example, a TCPIPSERVICE cannot be configured with AUTHENTICATE(CERTIFICATE) when it also uses SSL(NO).
There is a second mode of AT-TLS operation called AT-TLS AWARE. In this mode, a server (such as CICS) 'discovers' that AT-TLS is active for a client connection by querying the AT-TLS state. The server retrieves state such as CIPHER used on the handshake, the client certificate (if one exists) and the certificate USERID. With this mode CICS is able to exploit TCPIPSERVICE options such as AUTHENTICATE(CERTIFICATE).
CICS is introducing a new TCPIPSERVICE SSL option :-
SSL(NO) remains the default
SSL(ATTLSAWARE) is only supported on TCPIPSERVICE definitions which also specify PROTOCOL(HTTP).
All new client connections for the SSL(ATTLSAWARE) TCPIPSERVICE will be queried to extract the following AT-TLS attributes :-
Connection status (AT-TLS secured/not secured)
Client Authentication type (NONE/PASSTHRU/FULL/REQUIRED/SAFCHECK)
Client Certificate (if present)
Client Certificate USERID
CIPHER negotiated on handshake
Having extracted the AT-TLS state for a connection CICS imposes certain 'rules'.
CICS expects all client connections to an SSL(ATTLSAWARE) TCPIPSERVICE to have been secured by AT-TLS.
Error message DFHWB0365 is sent to the CICS log if a new client connection is NOT secure.
The non-secure client connection is sent an HTTP 403 error response.
The first non-secure connection received for an SSL(ATTLSAWARE) TCPIPSERVICE causes a DFHSO0147 warning error to be sent to console as this could signify an AT-TLS setup error.
If the connection is secured and AT-TLS is using the ServerWithClientAuth handshake type but the AT-TLS CLIENTAUTHTYPE is set to PassThru then CICS issues message DFHSO0149 and closes both the client connection and the TCPIPSERVICE.
Assuming an SSL(ATTLSAWARE) client connection has been secured by AT-TLS using a supported AT-TLS policy CICS does the following ...
If a client certificate has been provided CICS retrieves the certificate from TCP/IP and saves it in the certificate repository.
Attributes of the client certificate can be retrieved later on by applications by using EXEC CICS EXTRACT CERTIFICATE.
Any client certificate USERID is stashed away. This can be used in conjunction with AUTHENTICATE option of the TCPIPSERVICE to establish the security context for the new web task. For example AUTHENTICATE(CERTFICATE) will require a CERTIFICATE USERID to be present to allow a web request to be processed.
The ID of the CIPHER suite used on the handshake will be saved in the socket and will eventually appear in a performance monitoring record – in existing field SOCIPHER.
The new SSL(ATTLSAWARE) option is supported for both the CICS Explorer and the CICSPlex SM WUI.
Initial performance evaluations show that using AT-TLS to secure HTTP socket connections reduces overall CPU consumption compared with using CICS-SSL support.
If you have any questions, please feel free to reach out.
CICS has long supported JNDI in JVM server environments. The recent announced support for IBM MQ classes for JMS (MQ JMS for the rest of this article) in CICS means that it is likely to be used more frequently. This short article describes JNDI and why you might want to use it.
JNDI stands for Java Naming and Directory Interface. It is a set of interfaces and classes that allow Java objects to be registered, and then later located, using a name, which is typically a string. It is often used in Java Enterprise Edition environments such as WebSphere Application Server (WAS) as it allows applications to access resources such as Java Message Service (JMS) and Java Database Connectivity (JDBC) providers without having to worry about how to create and configure these resources.
To elaborate further, consider the case of creating the MQ JMS object that represents a specific IBM MQ (MQ) queue called Q1. In the most basic case this is pretty simple and can be achieved using the code in listing 1.
Listing 1: Simple queue
MQQueue queue = new MQQueue("Q1");
So, what is bad about this? Well for one thing we now have a hard coded requirement on using MQ, as we have just created an instance of one of the MQ JMS classes - MQQueue. If you did need to swap JMS provider, say to use the Default Messaging Provider in WAS, you would have to change your code. Not ideal.
Further more, there are actually quite a lot of configuration options, 10 at the time of writing, that can be applied programmatically to an MQ queue. For example you could have written something like the code shown in listing 2.
Listing 2: Complicated queue
MQQueue queue = new MQQueue("Q1");
If you use many different queues in an application you could easily imagine this approach getting unwieldy, especially when things change as they inevitably do.
JNDI helps here by allowing the configuration of resources to be separated from the use of those resources. What typically happens is that an administrator creates a JNDI repository, which is the location where JNDI resources are stored; configures a number of resources, such as the MQQueue shown earlier; and then stores the resources in the repository using a key. For example you could create a JNDI repository, administratively create the MQQueue object shown above in listing 2, and then store the object into the repository using the key "myQueue".
To get the queue back out of JNDI in your application you could then use the following code.
Listing 3: JNDI with queue
Context ctx = new InitialContext(properties);
Queue myQueue = (Queue)ctx.lookup("myQueue");
Note that the object that gets returned is actually an MQQueue object, but as no implementation specific methods are being used the javax.jms.Queue interface is sufficient. This approach is much cleaner than directly creating MQ JMS objects. You are not tied to using specific class names, you don't need to worry about configuration, all you need to worry about is your application logic.
In listing 3 the connection to the JNDI repository is encapsulated in the creation of an InitialContext object. This object is part of the JNDI standard and is not tied to any particular JNDI implementation. The properties object that is passed into to the constructor contains the configuration parameters that are needed to specify and configure a connection to a particular JNDI repository. Note that in most cases you only need a couple of parameters to establish a connection to a JNDI repository so it is perfectly feasible to provide these parameters using system properties or something similar.
While there are many different JNDI repository implementations there are two that are usable in more places than others, and are commonly used with MQ JMS. The first of these, the LDAP repository (initial factory class: com.sun.jndi.ldap.LdapCtxFactory) is actually part of the JVM. However this JNDI repository doesn't work in OSGi environments because of the way OSGi class-loading works.
The second is a JNDI repository which is based on the file system (initial factory class: com.sun.jndi.fscontext.RefFSContextFactory). This repository works fine in CICS.
In order to use JNDI in a CICS OSGi JVM server some special steps are required. These are described here.
This article provides an example use of the file system JNDI repository in CICS.
About the author
Matt Leming has worked at the IBM Hursley laboratory for 12 years, either in the WebSphere Application Server or IBM MQ development teams. Currently he works in MQ for z/OS development. He holds an MSc in software engineering from Oxford University and a BSc in mathematics from Loughborough University. He has published several IBM developerWorks articles and recently was an author on the IBM MQ V8 Features and Enhancements Redbook. He has just finished adding support for MQ JMS in CICS OSGi JVM servers.
There are various reasons why businesses choose to use CICS Transaction Gateway (CICS TG) in their environment.
In this blog I discuss three of them:
To act as a network concentrator
For intelligent routing
For offering simple, flexible solutions
As a Network Concentrator
Do you need to consolidate disparate systems and applications?
Do you want to protect your CICS resources?
Do you want to simplify your network?
If the answer to any of these questions is “yes” then CICS TG can provide a solution.
You can choose to have CICS TG act as your network concentrator on any one of a wide range of platforms including zOS, AIX, Linux and Windows. It is likely that you can integrate CICS TG into your current solution using existing hardware, with minimal time and effort.
CICS TG connects to all versions of CICS TS for zOS, CICS TS for VSE, CICS TS for i, and TXSeries. Whether your client applications are on mobile devices, or in ATMs, banks, post office branches, or shops, for example, all can connect to your CICS servers via CICS TG. This simplifies your networks and therefore reduces the number of IP sockets to CICS.
Simplified networks reduces network maintenance, saving you time and money.
Figure 1: CICS TG can handle requests from multiple different sources, and forward them
to any CICS server.
Do you want workloads automatically redirected based on a target server?
Do you want to interrogate each request and route it intelligently?
Do you want to block requests from unwanted sources?
CICS TG allows you to flexibly control the flow of work to CICS servers. For example, you might prefer to have dedicated CICS servers for handling mobile requests, and others for traditional workloads. In addition, CICS TG can automatically redirect workloads based on a target server. If you wish, you can also interrogate incoming requests and route them according to payload type, program ID, transaction ID, or even a user ID.
Intelligent routing is ideal for consolidating disparate systems and applications, perhaps as a result of a company merger. Furthermore, with CICS TG you can route new applications to your test servers whilst allowing existing applications to access the production servers.
Tip! You can safeguard your CICS servers by using CICS TG to reject requests from specific IP addresses, as well as known user IDs, specific program IDs or transaction IDs.
Figure 2: CICS TG can separate mobile and traditional workloads using intelligent routing.
Simple Flexible Solutions
Do you want a wide choice of platforms and application languages?
Do you want a solution that scales as your business grows?
Do you want to use existing investments of skills and hardware?
Wherever your client applications reside, whatever language they are written in, it is likely that CICS TG can handle them.
Your client applications can be in Java, C, COBOL, C++, use COM, or Microsoft’s .NET framework, whilst your mobile applications can use JSON web services. If your requests come from an application server, then as long as it’s a certified JEE application server such as WebSphere Application Server, Oracle WebLogic, GlassFish, or JBoss, CICS TG will process these requests.
As CICS TG supports a large variety of platforms and programming languages, it is likely that you can use existing investments of skills and hardware. If you’re involved in a merger and acquisition, then the flexibility of CICS TG will make your transition simple, straightforward, and cost-effective.
You may decide to start with a small solution running on desktops, perhaps sending requests to TXSeries. Then, as your business grows, you can easily move your solution
to a larger environment, and if desired, to work on System Z alongside CICS TS.
The choice is yours!
Figure 3: As your business grows you can easily move your solution to a larger CICS TG environment.
In a nutshell …
IBM CICS Transaction Gateway provides flexible solutions for your CICS connections and is ideal for any business environment.
Have you been wondering where to get started with CICS applications, platforms and policy? Are you unsure whether the CICS cloud enablement capability in CICS TS V5 applies to your applications or environment? The recently released Cloud Enabling CICS redbook takes an existing 3270-COBOL-VSAM application and describes how to exploit these features including a fully worked example of how to use multi-versioning to safely and reliably apply and back-out application changes without service interruption. It also shows you how CICS cloud enablement builds on operational facilities including monitoring, events, transaction tracking, CICS Bundles, and CICSPlex® System Manager to integrate with your existing deployment and management processes. Download a copy right now and get started with cloud enabling your CICS.
Mother's Day weekend is always a great opportunity to honor Mom and perform a host of chores around her house. This particular weekend, Mom required her house to be painted and as a good son should, I responded ,"Let's Git-R-Done" ...as Larry the Cable Guy would say. To begin, I saw Mom break-out the paint and a couple of paint brushes. Immediately, it dawned on me how Mom would pull out paint brushes when I was a small lad to teach and discipline me to pay attention to details. Well, not this time, I went to the local hardware store and purchased a power paint roller. This was my opportunity to teach and discipline Mom on the importance of having the appropriate tools and to demonstrate how fast and accurate we could paint and utilize the rest of our time for rest and relaxation. She appreciated my buying the new tool but if you know my Mom, she had more on her to-do list than just painting. So her mission and my workload continued throughout the weekend.
If you have not heard it enough, it is important to have the right tools to use for a specific job. After my Mom saw how quickly her house had been painted, I think she was ready to farm me out across the neighborhood to beautify the area. I think all of us have had a day when everything went just right...and for those jobs that we thought were so complex, were not complex at all when we applied the appropriate tools. My experience with Mom made me think about our CICS clients, where several sought a need to improve the efficiency of their CICS platform and how maximizing the availability or up-time of their systems is a significant requirement. Just those two requirements alone justified the creation of IBM CICS Tools to help support application transformation and CICS-based SOA implementation. Yet, the creation of a few CICS Tools was only the beginning of the ingenuity of products produced by a host of development teams at IBM Hursley Park.
The first products in the IBM portfolio of CICS Tools were introduced about ten years ago. Many new introductions were made since that period, the latest of which is IBM CICS Deployment Assistant. The best features can be characterized in a few words: discovery, insight, optimization, automation, standardization, modernize, and integration when using the plug-ins for IBM CICS Explorer.
by architects and developers – to understand the impact of the system and application changes they make, to create controlled changes to CICS resource definitions, and to understand the performance of the applications they develop
by system programmers – to create and deploy new CICS regions, to analyze and optimize performance, and to diagnose and resolve performance and configuration issues
by system administrators and managers – to audit and manage change in a controlled manner, and track performance SLAs
As one of our clients said recently: “CICS Interdependency Analyzer is not a one and done tool”. Like many customers, they justified its purchase for threadsafe analysis, but quickly found it helped with application changes, CICS version upgrades, test coverage analysis, operational changes, and affinity analysis, to name a few of its capabilities.
IBM CICS Tools try to keep in synch with the latest features of the IBM CICS Transaction Server. For example, you can use the CICS IA to track the entry points for the new applications, use CICS PA to understand the actual and potential use of specialty engines both introduced in V5.1.
Whether it is banking, insurance, health care, retail, manufacturing, or government, you will find IBM CICS Tools being used.
Recently, John Knutson, IBM Software Group: Market Enablement - CICS Portfolio, commissioned the development of the Redpaper, Modernize Your Application Infrastructure with IBM CICS Tools V5.1, REDP-4953-00. He wanted to demonstrate to CICS users how the IBM CICS Tools could help them to optimize, automate, and modernize their infrastructure and applications, so that they can respond to new workload demands such as mobile. John would like to thank the authors, who have fulfilled his every wish.
I encourage you to download and view the Redpaper. The Redpaper is suitable for managers and technical users. The managers will understand the value that the tools can bring in terms of increased productivity, better control, and maintenance of standards. Technical users in all roles will recognize that CICS Tools can help them to do their jobs more effectively, with less time switching between interfaces.
I know my Mom is pleased knowing that IBM could be so thoughtful in helping to make everyone's workload much lighter. You can throw away those paint brushes now!
As you might have read in Andy Bates' post last month, the recently announced CICS TS V5.3 open beta has three core themes at its heart: Service Agility, Operational Efficiency and Cloud with DevOps. Or as Andy put it, "do more, with less, and do it faster/better".
As the hill lead for the Liberty JVM server function in CICS I wanted to spend a bit more time discussing the new function the team has been developing to allow you to "do more" with your CICS. A central area we've been working on are the Liberty features supported within the CICS runtime, which provide a rich set of Java web APIs and application frameworks for use within CICS.
As you can see below, we have several new Liberty profile features and enhancements included in the latest CICS TS V5.3 open beta offering (live as of March 2015), which sit nicely alongside the Liberty features already supported at CICS TS V5.2. I'd love to hear what you think about them, so if you have any feedback, please leave a comment!
New Liberty features
Here's a quick look at the new WebSphere Liberty Profile features you can find in the open beta:
Liberty profile features
Enterprise JavaBeans Lite
Support EJBs written to the EJB Lite subset of the EJB 3.1 specification
Java Management Extensions (JMX)
Provides the ability to manage and monitor applications and system objects, either using the JMX client API, or remotely using the JConsole utility supplied with the SDK, as described here.
Managed Beans and Contexts and Dependency Injection (CDI)
Makes it easier to integrate different types of Java™ Enterprise Edition (EE) components
Supports the use of a MongoDB Java Driver configured providing applications with the ability to interact with the popular no-SQL database on a remote system
Helps with run time debugging of applications that use the OSGi framework.
Database session persistence
Provides high availability and recovery when using HTTP session data in web applications. This support is only for data sources that use a JDBC type 4 driver, due to a restriction preventing usage of a local database and the CICS DB2 attachment.
1 Features also supported at CICS TS V5.2
Enhancements to existing functions
Existing Liberty profile features are enhanced, specifically by adding EAR support for deploying EJB project within CICS bundles, adding SQLJ support for use with DB2® type 2 driver data sources, and JTA transaction support for the Blueprint feature. These newly supported and enhanced features make Java-based web applications hosted in the Liberty profile JVM server even more capable and portable.
Linking between COBOL and Java components
Within the CICS JVM server environments, it has long been possible to sandwich Java components with existing non-Java applications such as COBOL or PL/I. To call out from Java to COBOL the Program.link() method is provided in the JCICS API which drives an EXEC CICS LINK into the specified CICS program passing a COMMAREA or channel interface. This provides a simple model for access existing non-Java programs (such as COBOL or PL/I) from Java applications deployed with a CICS region. However, the JCICS API is specific to CICS and so although supported in web applications in a Liberty JVM server, makes the usage of such web application non-portable to other JEE application server environments.
As a first step in addressing the lack of portability of the JCICS API, support has been introduced in the Liberty JVM server for the JEE Connector Architecture (JCA). This supports the deployment of JCA resource adapters into the Liberty JVM server and allows the CICS ECI resource adapter, supplied by the CICS Transaction Gateway, to be deployed into a Liberty JVM server. JCA based applications that use the ECI can then be ported into the Liberty JVM server without modification and can use the facilities of a remote CICS Transaction Gateway to connect into CICS.
Connecting to Java applications through EXEC CICS LINK
Additionally the CICS TS V5.3 open beta provides a preview of the ability to use EXEC CICS LINK calls from non-Java components into Java applications running in a Liberty JVM server. This is intended to provide COBOL and other non-Java CICS applications full access to the API features of a Liberty JVM server, promoting the sharing of Java code components between Web and traditional CICS applications.
Java Applications are exposed to the LINK command by the CICS-MainClass header in an OSGi bundle manifest, in the same manner as used in OSGi JVM servers. The CICS PROGRAM resource definition names the target using the attributes JVMSERVER name and JVM class (or OSGi service name). When a Java program is invoked by a LINK command, the service in the relevant JVM server is located in the OSGi famework, and the main class is invoked and passed the COMMAREA or channel interface. OSGi bundles with a CICS-MainClass can be deployed into a Liberty JVM server using an OSGI Application project and Enterprise Bundle Archive (EBA) as part of a CICS Bundle project, allowing the Java code to be shared between Web components in the EBA and COBOL, PL/I or even other Java applications deployed in the CICS region.
So that's my whistlestop tour - I hope it has been interesting and useful. If you'd like to keep up-to-date on the new features and functions for developing applications with the CICS TS V5.3 open beta you can use this cicsdev query and a great place to look for more detail is the open beta knowledge center.
Yes, you read that correctly. Just nine months after the general availability of CICS TS for z/OS V5.2, our industrious team of CICS TS software engineers have - for your application serving pleasure - made available an open beta of CICS TS V5.3. You can download it now from ibm.com/cics/openbeta. And as if that wasn’t enough for any die-hard CICS fan, we’ve even added a few of the new capabilities to existing CICS TS releases as well. Sound interesting? Better read on then…
The three major themes of the open beta; ‘Service Agility’, ‘Operational Efficiency’ and ‘Cloud with DevOps’, should not be a surprise to those who have kept up with CICS TS V5. We’ve continued with these three themes because we believe they continue to address the ongoing business challenges many companies continue to face. Stripping away the marketing, those themes are really synonymous with “do more, with less, and do it faster/better”. We like to think CICS TS can help with these challenges. Here’s how.
Do More. Even the world’s most popular mixed language application server is only as good as the applications it serves. Today, a strong candidate for the most popular language in which to write new business applications is Java. This is where the WebSphere Liberty Profile comes in. It is a production JEE runtime that is included with CICS TS V5, so that customers can run new Java applications (such as Servlets) and Java infrastructure (such as JAX-RS and JAX-WS), right next to existing CICS applications that are written in traditional languages like COBOL. Communication is done at the API level, removing the network latency and reducing the complexity of wiring together multiple runtimes. This open beta adds around 10 new Liberty features (many of which have also been delivered via the service channel on CICS TS V5.2) along with a host of improvements to cross language interoperability. So, do you still think CICS is just for COBOL?
With Less. In the CICS TS world, ‘with less’ is often followed by ‘GP CPU’. Whilst it can be a challenge to reduce the CPU path-length for a product that has been tuned for optimal performance over many decades, it can also (at least for some of our engineers) be a lot of fun! And what do you know, by leveraging some of the newer hardware instructions, optimizing cache alignment, re-examining some algorithms and numerous other mind-bogglingly clever tweaks, CICS trace and monitoring should see noticeable improvements across the board. Additionally, with more than 1/3rd of customers using CICS web services and more still using HTTP for other purposes, a reengineering of the HTTP pipeline processing to remove the intermediate web attach task (CWXN transaction) will reduce both CPU and memory overheads. More security options and better transaction tracking can reduce the need for custom code, nicely rounding out the operational efficiency enhancements in this open beta.
Faster/Better. CICS Cloud is the future of CICS application deployments, giving customers a way to deploy and manage multiple disparate CICS resources as a cohesive, declarative whole. It is a better way. If you haven’t yet examined what’s on offer here, a google search is definitely in order. The open beta expands our CICS Cloud support by adding Transactions as entry points, and providing four new types of threshold policy by which to dynamically manage resource thresholds. But CICS TS V5.3 open beta also introduces strong DevOps capabilities to enable you to do things faster. The new CICS build toolkit automates the building of CICS projects created using the CICS Explorer so that CICS cloud applications, as well as OSGi Java components, can be automatically built from source code. Once built, that CICS project can now be programmatically deployed across CICS systems by using a new set of DFHDPLOY scripting commands. And finally, a new CICS TS plug-in for UrbanCode Deploy supports the automated deployment of CICS applications as part of larger cross-platform and cross-system deployments. You can’t get much faster than automated!
You may also be interested to know that you won’t have to install the CICS TS V5.3 open beta to get started with some of these automation capabilities. The CICS build toolkit open beta will run on z/OS, Linux, and Microsoft Windows operating systems, and will work with CICS TS V4.1 and later. The UrbanCode Deploy plug-in for CICS came out of beta on 20th April 2015, and is now fully supported for use with CICS TS V4.1 and above. You can grab it from developer.ibm.com/urbancode/plugin/cics-ts/.
Not a bad list of new capabilities there. And I didn’t even get around to talking about z/OS Connect, which is now available to run inside a Liberty server under CICS TS V5.2. Or the fact that CICS OSGi JVM server can now use the WebSphere MQ classes for the Java Message Service (JMS), as an alternative to the proprietary WebSphere MQ classes for Java – also now available on CICS TS V5.2.
So, if any of that has whetted your appetite, check back here for further blog posts in the coming weeks with more details. Or you can, of course, check out the open beta at ibm.com/cics/openbeta.
Please let me know your thoughts in the comments below. We would love to hear from you.
This post is contributed by Catherine Moxey, IBM Senior Technical Staff Member - CICS Performance and Optimization
Here are Catherine's top 5 reasons for upgrading to CICS Transaction Server for z/OS Version 5:
Built-in WebSphere Liberty Profile - for hosting JEE applications directly in CICS, such as web front-ends to CICS resources.
Application Multi-versioning - enabling you to deploy more than one version of the same application to a single CICS region, or a set of regions within a cloud-enabled CICS platform, with versions of the programs that are private to each application being isolated from each other.
CICS Threshold Policy - for controlling and managing the resource usage of tasks running in your CICS environment.
Performance Enhancements and Operational Efficiencies - allowing you to run more tasks concurrently within a region, with further threadsafe support and virtual storage constraint relief. This could allow you to reduce the number of regions required to run a workload, with improvements both to performance and to management overheads.
Security Enhancements - in support of industry standard security mechanisms, such as SAML and Kerberos.
And a bonus sixth reason:
CICS Mobile Support - mobile support and z/OS Connect support in CICS, allowing you to easily connect CICS assets to JSON-based mobile applications
Have you upgraded to CICS TS V5 yet? What new feature have you found most useful? Let us know in the comments.
A number of our users create special perspectives tailored to their company, or workflow, pulling together the critical set of views for their situation. For a single user, it's simple enough to customize the perspective and save it using the Window > Save Perspective As... menu, but it's difficult to share these between users. The correct way to share perspectives between users is by Eclipse's extensibility features.
As an example, we're going to create a CICS Web Hosting Perspective that shows the information needed to manage files hosted as web files using CICS. We want to create this perspective in a way that we can distribute it to a set of people. The best way to do this is by creating our own plug-in.
This technique can equally be applied to z/OS Explorer, but some of the specifics of this example (e.g. including the Files view) are not available without CICS Explorer.
Creating a custom perspective
Start by downloading a copy of CICS Explorer 5.1.1 or newer, if you don't already have one.
We're going to write some Java code, so switch to Java perspective
Create a new plug-in project from the menu File > New > Project > Plug-in Project
Give your project a name e.g. "WebPerspective" and click Finish.
You'll be prompted whether to switch perspective - I prefer not to open the plug-in perspective but to stay in the Java perspective.
The WebPerspective project's manifest will be shown. Click the Extensions tab along the bottom; we want to see which extensions are available for us to use - this is one of the Eclipse mechanisms available for providing our own behaviour that extends Eclipse's.
Type "perspective" in the Extension point filter box
There are two extension points that we can extend. These are pieces of API provided by Eclipse that let us define our own perspectives.
We want to create my own perspective so I will choose org.eclipse.ui.perspectives. To give us something to work from, we're going to choose the "Release Engineering Perspective" and Next. Give the class name "WebPerspective" and the perspective name "CICS Web Hosting". Untick all of the boxes that give extras, because our perspective just needs some views in it.
I find the best next step is to try starting up Explorer with the new plugin to test it. That way if you break things while you're editing, you know you started with something that worked!
Right-click on the WebPerspective project in the Package Explorer view and choose Run As > Eclipse Application.
This is where it gets confusing - a second copy of CICS Explorer will open, this new one will contain the plug-in we just created. This lets you see how users will experience the plug-in. Use the Window > Open Perspective > Other menu option (or the perspective tool bar) to switch to the CICS Web Hosting perspective we just created.
Notice that you have the Navigator and JUnit views on the left hand side, with the Problems and History views in the bottom.
We want a perspective that has the CICSplex Explorer on the left, the URIMAP, TCPIPSERVICES, and FILES views so we can see the status of the artifacts involved in hosting a file in the middle, and the Properties, Error log, and Host Connections views at the bottom.
Customizing the new perspective to our requirements
Close the "new" CICS Explorer so you're back to being able to see the WebPerspective plug-in code. We need to find the WebPerspective Java class - use the Navigate > Open Type menu. Type WebPerspective and click OK. The Java code editor will open.
Scroll down until you find the addViews method, starting
private void addViews()
This method is what we need to edit.
There are a couple of paragraphs of code like this:
This is declaring a folder layout that will be docked at the bottom of the screen. The problems and history views are added to this folder, and a placeholder for the console view is provided so that if the console view is opened it will automatically add itself to this bottom folder.
Go back to the manifest file for the WebPerspective project. In the dependencies tab, click "Add..." and type com.ibm.cics.core - double click on com.ibm.cics.core.ui to add it as a dependency for our project, then save the editor (ctrl+s is a good shortcut!)
Open the WebPerspective code editor and replace the addViews method with this text:
Save the editor, you'll have a red cross on the main.addView() line because we need to pass in a parameter to addView. Click in between the brackets after main.addView, type "PluginConstants." and press ctrl+space which will offer the available options (this is called code complete). Type "F" and pick FILES_VIEW_ID. Save the file - there should be no red crosses. If you see red crosses, try Source > Organize Imports and save again.
At this point we should have just the Files view in our perspective - right-click on the project and run as Eclipse application again to test it. You shouldn't see any change because the old perspective layout is remembered in your workspace. Use the Window > Reset Perspective menu at which point you should just see a Files view. Hurrah!
Close the test Explorer and add in similar main.addView lines for the URIMAPS_VIEW_ID and the TCPIPSERVICES_VIEW_ID.
Now let's create the left hand folder - copy the 'main' IFolderLayout declaration that we started with:
IFolderLayout main =
And paste it in BEFORE the main folder's first line. You should get an error because the 'main' variable has already been used. Let's call this new one 'navigate' instead of main.
Then add in a navigate.addView line for the CICSPLEX_VIEW_ID. Start the test Explorer and reset the perspective. This is looking good but the CICSplexes Explorer is taking up much too much space - change the 0.75f for the navigate folder to 0.25f, restart, and reset perspective to see this take effect.
Now let's add a folder in between navigate and main for the bottom panel with the Properties view. At this point, your addViews method should look like this:
There we have our finished perspective! It's not all that far removed from the original sample, just with a little bit of ctrl+space shortcut usage and some messing around with percentages and orders of layouts.
Deploying the new perspective to our users
Now we need to distribute this to our end users. The simplest and most robust way to do this is using an update site, in a similar way to how the CICS Tools (CM, DA, IA) plug-ins are distributed.
To create an update site, our plug-in must be contained within a feature. Use the File > New > Other... menu to create a Feature project. We might use this feature project to contain other custom plug-ins. Let's call it the OurCompanyCustomizations feature.
Click Next and choose just our WebPerspective plug-in from the plug-in list. Click Finish. This creates a feature that contains only our new plug-in.
Right-click on the feature we just created, in the Package Explorer view. Choose Export and Deployable features. Choose Archive file and type a filename where the new update site will be stored.
Now your end users can use the Help > Install New Software feature to add your update site and install your feature (note that they'll need to untick "Group items by category").
Perhaps one of our lesser known programmes, were you aware that the CICS development team can offer a number of different fee-based services to help you manage your systems more effectively? We can share our expertise to help you take advantage of CICS’s latest features, to embrace industry shifts towards Mobile and Cloud solutions, or simply to ensure your system is as efficient and robust as your enterprise demands.
By working with your IBM account team we can discuss your requirements and tailor an engagement that suits you.
So what can we offer?
Learn IBM best practices
If you’re looking to understand a particular area (or areas) of CICS then look no further than the CICS workshops. These on-site offerings allow you to learn from subject matter experts on a number of different CICS topics including:
Upgrade Java in CICS Cloud Performance High Availability Mobile
CICS Health Check
Get a deep dive into your TP infrastructure.
If you want to ensure that your infrastructure is optimally configured to meet service-level agreements on performance and availability, or perhaps are experiencing issues in these areas, then the Health Check could be the right option for you. Here an IBM expert will analyse data from your systems and interview key members of your infrastructure and management teams, then present back their recommendations for improvements and best practices.
More information on both the Workshops and the Health Check can be found at:
An advocate is a personal contact from within the CICS team, who is able to learn - over time - your business needs and requirements from CICS. They are able to communicate and propagate your feedback and requirements to the rest of the development organisation, to ensure your voice is heard. They can also help keep you informed of the latest features that will be of particular interest to you and provide general advice & consultancy. As an added bonus, having an advocate is completely free of charge.
To get in touch about organising a Workshop or Health Check, or to declare your interest in the CICS Advocacy programme, simply send an email to CICSDTS@UK.IBM.COM.
This article explains how to provide a web-based installation of CICS Explorer. This is useful for system administrators who want to deploy the software to multiple desktops and provide automatic updates.
by Dave Nice, Steve Bolton, and Nick Bishop - IBM CICS Explorer Development
This article describes how it is possible to define a CICS policy and deploy it into a CICS region such that the policies rules are only applied to specific CICS user tasks rather than all user tasks that run in that CICS region.
CICS TS V5.1 introduced the capability to define policies to monitor the resource utilisation of a user task, and to automatically respond when resource usage exceeds the thresholds you define. In this way, excessive resource usage and looping and runaway transactions can be detected and dealt with appropriately. While primarily designed to be deployed with CICS applications and platforms to monitor application tasks they can also be deployed to stand-alone CICS regions to monitor any CICS user task. By default polices deployed to a CICS region apply to all user tasks executing in that region. However deploying polices with such a wide scope may not be suitable in all cases. What if you have a requirement to apply policy to specific tasks rather than all tasks ?. This article walks you through the steps required to restrict a CICS region policy so that its rules are only applied to specific user tasks.
Policy support in CICS TS
CICS Transaction Server V5.1 introduced the capability to define policies to monitor:
Number of SQL requests
Number of EXEC CICS file control requests
Number of EXEC CICS LINK requests
Number and size of EXEC CICS GETMAIN requests
CPU time consumed by a task
CICS Transaction Server V5.2 built on this support to add further polices to monitor
Number of EXEC CICS START requests
Number of EXEC CICS SYNCPOINT requests
Number of EXEC CICS transient data requests
Number and size of EXEC CICS temporary storage requests
Elapsed time of a task
A CICS policy is defined in a CICS bundle project and each bundle can define one or more policies. Once defined the bundle can then be deployed to a CICS region in one of three ways:
Add the CICS bundle to a CICS platform. The bundle is deployed with the platform and any policy rules scoped so they apply to any application tasks running on that platform
Add it to a CICS application or application binding. The bundle is then deployed with the CICS application and any policy rules scoped so they apply only to that particular application's tasks.
Export the bundle to zFS, and then define, install and enable a CICS BUNDLE resource for the CICS bundle project in a CICS region. In this case any policy rules apply to ALL user tasks running in the CICS region.
This article concentrates on the last of these methods of deployment and shows you how to define a policy such that its rules are only applied to specific user tasks. To find out more information on how to deploy CICS policy with CICS platform and application please refer to "Working with platforms, applications, and policies" in the CICS TS 5.2 Knowledge Center.
For the purpose of this article lets assume we want to enforce the following rules in a CICS region:
Abend any CICS task that consumes more than 1 second of CPU.
Emit a CICS event if any of my business critical transactions consume more than 125% of their average CPU consumption.
Defining a region scoped policy
So first lets define a policy to abend any task using more than 1 second of CPU. All policies are created in a CICS bundle project using CICS Explorer. For details of how to create a CICS bundle project please refer to "Creating a CICS bundle project" in in the CICS TS 5.2 Knowledge Center.
Once you have created a CICS bundle project, right click on the bundle project in the Project Explorer view and select New->Policy Definition. The policy is then defined as follows:
Click Finish and a new file "region_CPU_policy.policy" will be added to your bundle project. That completes the definition of a policy that once deployed will apply to all CICS user tasks.
Next we need to define the policy to emit a CICS event if any business critical transaction consumes more CPU than normal. Let's assume one of these transactions is ORDR and we know from the analysis of CICS monitoring SMF records that on average this transaction consumes 400ms of CPU. So allowing a 25% buffer this means we need emit an event if an ORDR transaction consumes more than 500ms.
So first we define a policy to emit an event if a task consumes more than 500ms of CPU. This second policy can either be defined in the same CICS bundle project or a separate one; the choice is yours on how you manage your different policies. In this case we will define the second the policy in the same bundle project so they can be deployed and managed together. So again right click on the bundle project in the Project Explorer view and select New->Policy Definition. The second policy is then defined as follows:
The EP Adapter named here; CPUMON; could be any of the supported types of EP Adapter. For example it could be a simple custom adapter that writes a message to an operator console or a HTTP adapter that routes the event to an event processing product such as IBM Business Monitor to update an operations dashboard. For details on the different types of EP adapter available please refer to "Event processing adapters" in the in the CICS TS 5.2 Knowledge Center.
So far this policy looks no different to the first policy. In fact as it stands if we deploy this policy it will trigger an event if ANY task, including ORDR tasks, uses more than 500ms of CPU which is not what we want; we need to restrict its scope to just ORDR tasks. To do this we exploit two of the new features added in CICS TS 5.1 for CICS application and platform support; namely application entry points and policy scopes. These features enable us to be much more specific about which tasks policies are applied to even when those tasks are not part of a CICS application and by exploiting these features we can restrict a policy to just those tasks that pass through a given entry point. CICS currently supports 2 types of entry point; PROGRAM and URIMAP (CICS TS 5.2 only). You can use either type of entry point to help restrict which tasks a policy is applied to. For web service tasks you might chose to use a URIMAP entry point instead but in this case we will use a PROGRAM entry point.
A program entry point can be defined for ANY program that a given task invokes during its lifetime but please be aware that the set of policy rules applied to a task is based on the FIRST entry point a task passes through during its lifetime; if a task passes through a second entry point program no policy rules associated with the second entry point are applied to the task and the original policy rules all still apply to the task. When selecting the program to define as an entry point a TRANSACTION's initial program is an obvious choice. In many cases this may be an appropriate choice but please bear in mind that:
the same initial program may be named on other transaction definitions
the program may be invoked by another task via EXEC CICS LINK or XCTL.
In both cases this could mean a policy may end up being applied to tasks it was not intended for so a program invoked by the initial program may be a more appropriate choice. However if the initial program is only invoked via the transaction it is the perfect choice to use as an entry point program to scope a policy to a particular TRANSACTION.
So if we assume that NEWORDER is the initial program of the ORDR TRANSACTION we define it at a program entry point as follows:
First open up the CICS Bundle Manifest Editor. To do this double click on the cics.xml file in the CICS bundle projects META-INF folder
Next select the "Entry Points" tab in the CICS Bundle Manifest Editor, and then
Press the "Add" button and define the entry point as follows;
i) Set Operation to "new_order_ep". This can be any meaningful string up to 64 characters in length.
ii) Let the Resource Type default to PROGRAM. If you are going to deploy the resulting CICS bundle project to a CICS TS 5.2 region you could chose to define a URIMAP entry point here by selecting it from the list of valid "Resource Type".
iii) Set Resource name. We will set this to the name of the chosen entry point program so in this case its the initial program of the ORDR transaction "NEWORDER".
That's defined the set of tasks we are interested in to be those that pass through the entry point program NEWORDER, next we need to associate critical_task_CPU_policy we defined above with this entry point. To do so we define a Policy Scope. Again this is defined using the CICS manifest editor as follows:
Select the "Policy Scopes" tab in the CICS Bundle Manifest editor, and then
Press the "Add" button and define the Policy Scope as follows:
i) Set Operation to the value specified when defining the entry point previously, i.e "new_order_ep".
ii) Set Policy Name to the name of the policy we defined earlier, i.e "critical_task_CPU_policy".
Debug tip: Both Policy Name and Operation are case sensitive attributes. If your policy fails to trigger then the first thing to check is that these 2 names match exactly with the names specified when creating the policy and the entry point.
What if I want to apply the same policy to multiple transactions ?
That's easy. You can just repeat the process above and define further entry points for those transactions and policy scopes to associate the same policy with those entry points.
Deploying the CICS bundle and its policies
For details of how to deploy these polices to a CICS region please refer to "Deploying the policies to a single CICS region" in the CICS TS 5.2 Knowledge Center. After deployment is complete the following rules will be enforced in all CICS regions into which the bundle is deployed:
Any ORDR task's consuming more than 500ms will cause a CICS event to be emitted to the CPUMON EP adapter.
Any task, including ORDR tasks, consuming more than 1 second of CPU will be abended,
In this article you have seen how you can use functionality that's been available since CICS TS 5.1 to restrict the affect of CICS policy deployed to a CICS region such that its rules are only enforced on specific user tasks. Thanks for reading and I hope you found the information above useful. If you have any questions please leave a comment below and I will get back to you.
The JCA local ECI feature provides an optimised JCA adapter supporting the CICS Transaction Gateway JCA ECI interfaces. This allows you to port existing JCA applications that use the JCA ECI interfaces from other JEE applications servers into the a CICS Liberty JVM server, and to developed new JEE applications that can link to existing CICS COBOL programs without being tied to the propietary JCICS Java API.
In the March CICS TS 5.3 Open Beta we announced support for JCA 1.6 in CICS Liberty JVM servers, this allowed applications using the CICS TG ECI resource adapter to be run inside CICS. However, these applications still had to go outside of CICS via CICS TG to call a CICS program, which is not an optimal solution.
Since then we've been working with CICS TG on creating a resource adapter which keeps the same API as the ECI resource adapter, but which uses CICS APIs instead of CICS TG to perform a locally optimised call to a CICS program: the JCA Local ECI resource adapter.
The JCA Local ECI resource adapter provides benefits to new applications as well as existing ones: it doesn't require JCICS, so applications can be made to be portable between CICS and distributed system and it provides optimisations for creating multiple containers in a channel on a program call.
The JCA Local ECI feature comes installed on all CICS TS 5.3 Liberty JVM servers. To enable the feature, edit the Liberty JVM servers server.xml to include the following feature cicsts:jcaLocalEci-1.0 in the feature manager element as shown in figure 1.
Figure 1: server.xml snippet to include the JCA Local ECI feature
<!-- Other features -->
<!-- Other content of the server.xml -->
Consolidating an existing application
Consolidating an existing Java EE application into a CICS Liberty JVM server is a 6 step process, which can be easily performed using CICS Explorer
If possible, update the JNDI name of the ConnectionFactory to eis/defaultCICSConnectionFactory. If this is not possible, define a new ConnectionFactory with the required JNDI name in server.xml, see figure 2 for details.
Create a new CICS bundle.
Add the existing application to the CICS bundle, target the Liberty JVM server you want to deploy the application too.
Export the CICS bundle to z/FS.
Create a new CICS bundle definition on the CICS region, targeting the location the of the exported bundle on z/FS.
Install the bundle.
To ensure the application is correctly installed, view the Liberty JVM servers messages.log file. A message should appear the the application has been enabled and the URL path to the root of that application.
There are some differences that owners of existing applications should be aware of in an environment which is local to CICS:
If the CICS program that is linked to issues a SYNCPOINT command then this will commit the CICS UOW, which is only possible if CICS is the transaction coordinator. If the Java web application has initiated a Java transaction using the UserTransation class then the CICS UOW will be subordinate to the Java transaction which is controlled by the Liberty transaction manager. In this case the CICS task will not be permitted to issue a CICS SYNCPOINT, either using an EXEC CICS SYNCPOINT command in a called program or a Task.commit() method using the JCICS API. Instead the Java transaction must user the UserTranaction.commit() or rollback() methods to control the transactional scope. However, if there is no Java transaction created by the web application then the LINKed to program will be able to issue a SYNCPOINT, and further if the linked to program is defined as remote it will be invoked using the SYNCONRETURN option allowing the programs linked to via a DPL to also issue a SYNCPOINT as they will run in a separate UOW to that of the calling program.
Setting the transaction ID using the EciInteractionSpec.setTPNNanme() method to set the name of the mirror transaction only functions on a call to a remote program, and will set the name of the mirror transaction alias that will be used. If you need to modify the transaction name under which a Liberty web application runs then this requires usage of a URIMAP resource definition with the USAGE attribute set to JVMSERVER.
Figure 2: server.xml snippet to create another ConnectionFactory with a different JNDI name
Creating a new application using the JCA Local ECI feature
Creating a new application which uses the JCA Local ECI feature is easily done using CICS Explorer and WebSphere Development Tools. This post will show how to create a basic web application (WAR), but the JCA Local ECI feature can be used in Enterprise Bundle applications (EBA).
Create a new Dynamic Web Project
Create a new Web Servlet
In the one of the inherited do methods, use JNDI to look up the ConnectionFactory object
Create a new ECIInteractionSpec object and configure properties on this object.
ECIInteractionSpec spec = new ECIInteractionSpec(); spec.setProgramName("EC01");
Create Record objects for the input and output of the program call.
RecordImpl input = new RecordImpl(); RecordImpl output = new RecordImpl();
Call the execute method on the Interaction object, passing in the ECIInteractionSpec and Record objects created.
interaction.execute(spec, input, output);
Read the output from the output Record.
ABEND in CICS will be wrapped in a Java ResourceException and the resource adapter will provide sensible error messages. More detailed information can be found in the JVM server's messages log file and STDERR.
The Local ECI resource adapter provides a simple mechanism of creating CICS channels and containers to pass to the CICS program. A special class EciChannelRecord can be created to represent a channel; this class extends the MappedRecord class (and through inheritance the standard Java Map class). Each record in this class represents a container, where the key of the record is the name of the container and the value is the contents of that container.
The data type of the value changes the mode of the container. For a container in BIT mode, a type of byte must be provided and for a container in CHAR mode, a type of String must be provided.
Using this method of calling CICS programs with channels and containers has another advantage: rather than creating individual containers in the channel as they are populated, the Local ECI resource adapter uses the object representation of a channel to create the containers in a single batch just before control is passed to the CICS program, keeping the Java code in the JVM for as long as possible.
This blog post has described how to consolidate an existing Java EE application which used the CICS TG ECI resource adapter to communicate with CICS into a CICS Liberty JVM server and how to create a new application which uses the JCA Local ECI feature. It has also explained how the JCA Local ECI feature can be used to call CICS programs with a channel using simple Java objects, rather than relying on JCICS classes, allowing applications to be portable between CICS Liberty JVM servers and distributed application servers.