Back in April, I posted a blog entry called The CICS TS V5.3 open beta is here (already!), summarising the major new capabilities you could get your hands on, just in time for spring. Well, now it’s July and we’ve updated the CICS TS V5.3 open beta to ‘refresh 1’ level, just in time for your summer holidays. So, order a margarita, sit back in your deck chair and open up your mobile browser of choice to see how we continue to strive to help you “do more, with less, and do it faster/better”. Things are heating up…
Do More. In the first CICS TS V5.3 open beta, we added a raft of new features to the WebSphere Liberty Profile runtime that is integrated with CICS TS V5. In this refresh, we added a few more. Support for JPA (Java persistence architecture) completes the list of capabilities needed for the Java™ EE 6 Web Profile feature set. The addition of the WebSphere embedded messaging features introduces support for JMS 1.1 without the need for additional messaging software. The CICS TS V5.3 open beta now also ships with its own JCA local ECI resource adapter, removing the requirement to use the resource adapter provided by the CICS Transaction Gateway when porting JCA applications into a CICS Liberty JVM server.
Outside of Liberty, updating OSGi bundles in an OSGi JVM server becomes much less disruptive, with the introduction of a new phase-in capability that simplifies the process for updating OSGi bundles in a running JVM server. We have also upgraded the Java infrastructure to support running multiple levels of Java. IBM Java 7.0, IBM Java 7.1 and IBM Java 8 can all be used within the CICS TS V5.3 open beta, with different JVM Servers running on different levels of Java, even within the same CICS region. This can help customers standardise Java levels across the enterprise, remove the need to upgrade Java levels as part of a CICS TS upgrade, and quicken the adoption of latest technologies such as SIMD support in Java 8 with the new IBM z13.
With Less. In addition to the many performance related enhancements delivered in the first CICS TS V5.3 open beta, the performance of running z/OS Connect inside CICS TS is now dramatically improved through the introduction of a new native JSON parser. This new processing infrastructure provides greater throughput whilst using substantially less overall CPU than the current z/OS Connect solution. This CPU usage reduction is predominantly in the Java code path, meaning you should need less zIIP CPU to run the same processing. The new function is made available as a pipeline configuration option, and is thus transparent to the application. This allows you to choose the optimal parsing infrastructure based on preference for zIIP usage or throughput rates.
In our ongoing quest to most efficiently utilise each and every MSU, over 30 additional CICS TS SPI commands have been made threadsafe. A new HTTP flow control mechanism has been introduced to prevent HTTP requests from flooding a CICS region if it has reached capacity, allowing TCP/IP to route HTTP traffic more effectively. This mechanism prevents oversupply of new HTTP connections from being received and queued within a CICS region, enabling CICS to recover more quickly, whilst using less storage and CPU. In addition, for those times when something just doesn’t go according to plan, there is a new all-in-one task dump formatter to help you get up and running at full speed again.
Faster/Better. This is all about CICS DevOps and CICS Cloud. Three major new CICS DevOps capabilities were introduced in the first CICS TS V5.3 open beta: the CICS Build Toolkit, DFHDPLOY and an IBM UrbanCode Deploy Plug-in for CICS TS (which is fully GA and available now for CICS TS V4.1 or later). With this latest beta refresh, the types of bundles that can be built using the CICS Build Toolkit has been expanded to include CICS Liberty profile applications. Also added is support for variable substitutions for attributes in CICS bundle parts, such as high level qualifiers for data set names and JVM server names. This is especially helpful when moving applications through the lifecycle, since variables can be substituted for different values appropriate for target environments such as development, test and production without changing the source.
In the original CICS TS V5.3 open beta blog post, I stated that CICS Cloud is the future of CICS application deployments. This latest beta refresh adds even more credence to that by explicitly adding DB2 schema support into an application. This is important when the DB2 data to be accessed is different depending on the deployment environment, for example whether the application is deployed in test or production. There is also an additional policy added which can be triggered when the total number of EXEC CICS requests executed by a task exceeds a predefined threshold. This brings the total number of policy types to 14, containing more than 40 items that triggers can be set against.
Wow – our software engineering teams have been busy this spring. If you’d like to take any of that new capability for a spin, the CICS TS V5.3 open beta was updated to refresh 1 on the 10th July. You can grab it from here whilst it’s still warm.
As a reminder, 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 available with the open beta will run on z/OS, Linux, and Microsoft Windows operating systems, and will work with CICS TS V4.1 and later. And don’t forget, the UrbanCode Deploy plug-in for CICS is now fully supported for use with CICS TS V4.1 or later.
As always, please let us know your thoughts in the comments below. We in CICS would love to hear from you.
IBM CICS TS Product Manager.
NOTE: This blog post was updated on 21st July 2015 to clarify that the new JSON processing is a z/OS Connect enhancement.
This article describes a process which can be used to automate the phase-in of a Java application in a CICS bundle into a running CICS system. This process provides a similar lifecycle to the usage of the SET PROGRAM PHASEIN command used for traditional non-Java CICS programs, with the added benefits OSGi versioning brings to the application development lifecycle.
Whats in a bundle?
Java applications are deployed to CICS in a different manner than traditional COBOL or PL/I applications. Java classes are compiled into byte codes and then packaged in a binary archive called a JAR file. This like other zFS artifacts such as event bindings or policies is referenced from CICS using a BUNDLE resource, which itself is a standard CICS online resource definition similar to a TRANSACTION or PROGRAM definition. The Java code meanwhile must then be packaged using the CICS Explorer SDK within an Eclipse based CICS bundle project and built and exported to a zFS directory structure. This directory is then referenced using the BundleDir attribute on the BUNDLE definition when installing the Java application into a CICS region.
This process of build and deployment can be performed within the CICS Explorer SDK as follows.
In Eclipse create an OSGi bundle project containing the Java application. This project is versioned using a semantic versioning scheme with the form major.minor.micro (for instance v1.0.0), the importance of which will become clear later.
Using the CICS-MainClass header annotate the OSGi bundle manifest with details of the Java class which is to be made available as a linkable service from other CICS applications, for instance CICS-MainClass: mypkg.ClassB1
Create a CICS bundle project and add a reference to the OSGi bundle project, along with any other resources that are part of the CICS bundle. You must also version this CICS bundle, so its simplest to use the same version i.e. v1.0.0.
Export the CICS bundle project to zFS using the Export Bundle Project to z/OS UNIX File System menu in the CICS Explorer SDK. This builds the project and exports a directory structure containing the CICS manifest (cics.xml), the referenced bundle part file (i.e bundleB1.osgibundle) and the referenced JAR file. Your zFS file system would now look like this if you used the /tmp/cicsbundles directory.
In your CICS region you will then need to perform the following steps to deploy this application.
Using CEDA or the CICS Explorer create a CICS PROGRAM definition and in the JVMClass attribute name the service defined in step 2.
Create a BUNDLE resource definition, and wthin this refer to zFS location of #4 in the BundleDir attribute (i.e /tmp/cicsbundles/B_1.0.0)
Install and enable the BUNDLE definition and PROGRAM into the target CICS system(s). This does the following
Loads the OSGi bundle(s) into the OSGi framework of the JVM server
Activates the OSGi bundles, which validates the dependencies.
Installs the OSGi service(s) into the internal JVM OSGi service registry, making the application available to LINK commands
Disable any previous versions of the same OSGi bundle that were active using their associated BUNDLE definition
The OSGi manifest in the OSGi bundle project is used to define the properties of the OSGi bundle. This includes the version according to the scheme <major>.<minor>.<micro>. This version information is a key part of the lifecycle process as the version information will be used by the OSGi framework when multiple versions of the same bundle are loaded at once. In the example the bundle-symbolic name bundleB1 will be used as the name of the CICS BUNDLEPART resource and the bundle is versioned as 1.0.0 and defines a service entry point mypkg.ClassB1, which is the class with the main() method that will be invoked when the service is linked to.
Every time a new fix is built for a CICS Java application, steps 1-4 will need to be repeated to build a new version of the OSGi bundle and package as a CICS bundle. In a production environment these would usually be performed by an automated build process rather than manually using the CICS Explorer. In addition steps 6-8 would need to be performed to deploy this new application to zFS and load into a running CICS JVM server. However, a recent PTF available for CICS TS V5 via APAR PI24367 has now simplified this process so that the disabling of the old bundle (step 8) is no longer required to activate the new version. With the APAR applied all new versions of an OSGi service will become active even if they duplicate an existing OSGi service of the same name. In this situation the OSGi service that references the bundle with the highest semantic version will be used for any new EXEC CICS LINK commands as soon as the OSGi service is activated.
This process is fairly simple when used in a development or unit test environment, but in a production system the same process needs to be automated and scripted to allow fixes to be built and and promoted into the production system on demand. The problem in this situation is that the usage of either the CEDA transaction or the batch interface DFHCSDUP, to define RDO resources in a production system can cause further issues because CSD access is often not part of the normal deployment process in production. In addition when sharing a CSD across multiple regions, CSD access for the creation of resources is usually limited to a single region to minimize any CSD locking problems. To address these issues the CREATE SPI command can be used to avoid the need to access the CSD when deploying the new CICS bundle resource.
Using the CREATE command
The EXEC CICS CREATE command is a system programming command that can be used to create any CICS resource without recourse to defining this in the CSD or CICSPlex SM data repository (DREP). This can be used to create new BUNDLE definitions in a running system, and is especially useful if the resources required are temporary resources that do not need to be stored in the CSD for installation on a cold start of the CICS region.
Scripting the process
The following process assumes that the Java application is installed at startup of the CICS region using CICS bundle B0 from a CSD group in the CICS grouplist. Bundle B0 refer to the zFS location /tmp/cicsbundles/B/1.0.0 in its BundleDir attribute, which includes OSGi v1.0.0 of the OSGi bundle B.
A new version of the CICS bundle project is created with an incremented minor version (v1.0.1) and containing a new minor version (v1.0.1) of the OSGi bundle B. The CICS bundle project is then exported to the zFS location /tmp/cicsbundles/B/1.0.1
The following CICS SPI commands can then be issued:
Step (i). dynamically creates a new bundle definition in CICS and enables it. This loads the new version of the OSGi bundle B into the JVM server and activates its new OSGi service. At this point all new LINK commands to any PROGRAM that refers to the service for bundle B will use the new version of the Java application in version 1.0.1 of the OSGi bundle.
Step (ii) inquires on the state of the bundle from step (i) and if enabled (iii) disables the old version of the CICS bundle, which deactivates the OSGi bundle.
Step (iv) destroys the prior version of the CICS bundle resource, which removes the OSGi bundle from the OSGi framework but still allows any in-flight CICS transactions using this version of the OSGi bundle to run to completion.
Finally the CSD must be updated so that the BUNDLE definition for B0 refers to the new CICS bundle exported to /tmp/cicsbundles/B/1.0.1, in order for this to be used for a subsequent cold start. This can be performed using the DFHCSDUP batch utility to update the BundleDir attribute of the CICS Bundle resource B0, avoiding any need to use the CEDA transaction.
This deployment process can now be fully automated to support the deployment of new versions of a Java applications in a CICS bundle into a running CICS system, without interrupting existing workloads. In addition to backout the fix, the process simply needs to be reversed by enabling the previous version of the CICS bundle and then disabling the new version of the CICS bundle.
The options that are available to automate the SPI commands in steps i-iv from a z/OS batch job are as follows:
A CICS SPI program that is invoked from batch using the EXCI
An MVS console automation job which drives the CEMT and CECI commands in a CICS region
A REXX script using the CICSPlex SM API
An HTTP client which issues CICSPlex SM commands using the CMCI as described in this cicsdev article
The following references can be used to provide additional information on OSGi bundles and deployment into a CICS JVM server
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.
Java in CICS used to be a strange place. When I started working on CICS Transaction Server V3.1, having previously worked on WebSphere Application Server, I was frustrated to find an unusual Java environment inside CICS. It had strange options for its configuration and the idea that each CICS task had its own JVM (yes, a whole one) was baffling, and it didn’t understand Java threads. That was 10 years ago, but everything is different now.
The CICS JVM is a first-class enterprise Java environment. It’s so capable we can host the WebSphere Liberty Profile inside it. It uses the IBM 64-bit JVM, provides direct access to CICS runtime services, and is multi-threaded. Java in CICS is no longer a weird environment; it’s simply Java, as you would find it anywhere else. The CICS JVM server established a new baseline for the Java runtime in CICS. This document (https://ibm.biz/BdFVm4), written at the time of CICS TS V4.2, talks in detail about the JVM server implementation and the capabilities it offers.
The changes to Java in CICS have not been limited to the runtime, but have included new tooling to support Java developers building applications for CICS. The CICS Explorer SDK is the easiest point of entry for building Java applications, providing an Eclipse plugin for developing, packaging, and deploying Java applications into CICS.
The advantage of having Java inside CICS (including the WebSphere Liberty Profile) is that you can build new applications and services in Java and seamlessly integrate them with existing core COBOL applications, all within a single managed runtime environment. Using the JCICS API makes integration easy, and allows new Java components to become part of a CICS workload-managed application.
Serious enterprise application development of this sort needs seriously capable tools that can manage the multi-language environment. Tools like Rational Developer for z that provides the COBOL, PL/I, C++, Java and assembler development tools for building CICS, IMS, and DB2 applications.
On reflection, Java in CICS isn’t just like Java elsewhere – it’s more than Java elsewhere because it’s inside CICS.
Hidden in the release notes for the latest CICS Explorer V5.1.1 you will see an enhancement that provides the “Ability to edit a CICS Platform project, CICS Application project, or CICS Application Binding project”. The required server-side APAR PM81540 is now available.
These new editors are a significant improvement to the user experience of working with CICS Applications, CICS Bindings and CICS Platforms so if you are interesting in the cloud enablement capability in CICS TS V5.1 please try out these downloads.
On Friday June 14 we GAed z/OS Explorer V2.1 and CICS Explorer V5.1.1, that is to say, they became generally available for download. That wasn't all - we also made our new repository of compatible plug-ins available, with plug-ins for five CICS Tools, five IBM Problem Determination Tools, IBM Data Studio, Rational Team Concert, a 90-day trial version of Rational developer for System z.
I've been the marketing manager for CICS Explorer, and more recently, z/OS Explorer, for over five years now, so I obviously have an interest. When we started CICS Explorer back in 2008 - earlier if you count the planning and development - we had a SupportPac with read-only support for CICS TS along with plug-ins for three CICS Tools. Now we have a common component used by 15 plug-ins from three IBM brands. So, even though it was Saturday, since I'd been waiting for this for some time, I decided to try the installation.
I started by going to the download tab on the z/OS Explorer page, and selected the download in Scenario 1, which uses IBM Installation Manager (IM). The IM package is about 700MB so took about 10 minutes on my home broadband. Another 10 minuets to unzip it. Then I ran the launchpad.exe in the disk1 folder which first installs IM and then z/OS Explorer. I then ran z/OS Explorer from the Start menu and configured my FTP and z/OSMF connections, and was able to access z/OS datasets, z/FS files, and JES jobs and output.
I then launched IM again, this time from the Start menu and used File/Preferences to create a repository definition with URL http://public.dhe.ibm.com/software/htp/zos/2/1/0 . I then selected Install, and clicked on the Check for other Versions, Fixes and Extensions button, and saw all of the products listed above. I installed them in groups - CICS Explorer and CICS Tools, Data Studio, and the Rational products - so that I could see how long they all took, but you can select and install them all at once. All of the plug-ins are downloaded as part of the install, so you need to be attached to a network, but I think that you can create an internal staging server within your own networks. You need to enter a jazz.net id and password to access the rational products, and an IBM id (like you'd use here on dWorks) to access Data Studio, but once you've entered them once, you can save them for future use.
All in all, it probably took a couple of hours to install everything - some of the downloads are quite large, so it may take longer on some networks. But, after that time, I was able to run z/OS Explorer again and find all of the perspectives, views, and actions contributed by ten different products within a single IDE. The five PD Tools aren't loaded on the IM repository yet, though they are available in the Eclipse P2 repository, but I'm sure they'll be there in the next day or so. With them, and MQ Explorer and IMS Enterprise Explorer - both slated for future delivery in a recent Statement of Direction - you'll be able to run close to twenty products covering z/OS and its key subsystems in a single workbench.
I have to admit that I was concerned that running so many plug-ins in one would really slow down the z/OS Explorer start-up time, and the first time I used it after each install it did take longer to start, but the second and subsequent times it was back to normal, taking about 20 seconds.
All in all, a pretty good showing. Ten plug-ins from three different brands, all installed smoothly. Pretty amazing. I know that many of you have experienced issues trying to get different products working together in Eclipse and I hope that the z/OS Explorer initiative makes your life a lot easier in future.
Thanks to everyone who made it happen. It's a great story and I thought it needed to be told.
Updated Tuesday 18th June 2013
Warning: Long path names A few people have experienced problems unzipping the initial downloads on Windows XP machines. The problem is caused when the package is unzipped to a folder whose path is longer than about 90 characters - our longest file has a path of about 160 characters. Older unzip product like WInzip and Windows compressed folders cannot create files with a pathlength longer than 255. Either unzip the package from a short path, or use something like 7-Zip. Updated 20th June: Apparently the unzip problem is well known, if not well understood. Learn more in this technote.
Overnight, the PD Tools were added to the IM repository, so I reran IM, selected the plug-ins for the five PD tools and within about 15 minutes, the plug-ins were successfully installed, as you can see in the following screenshot. When I restarted z/OS Explorer, it still just took 22 seconds - now with 18 plug-ins!
The following steps will enable you to create a CSV extract using CICS PA and then use the supplied sample JCL and REXX exec to convert the CSV to a format that can be used with the Mobile/zCAP Workload Reporting Tool (MWRT).
Note that this version of the solution only supports CICS TS V5.1 and above because it relies on the presence of the CPUTONCP CMF field, introduced in CICS TS V5.1.
Step 1: Use a CICS PA FORM as below to generate the report JCL for the CICS PA CSV extract.
/ Name + K O Type Fn Description
STOP K A DATEISO Task stop time
STOP K A TIMES Task stop time
MVSID K A MVS SMF ID
TASKTCNT Total Task Termination count
CPU TIME TOT CPU time
CPUONCP TIME TOT CPU time on standard CP
EOR ---------------- End of Report ----------------
EOX ---------------- End of Extract ---------------
You will need to make sure you specify the APPLID(s) you need the CSV extract for. If the CSV extract is for a group of APPLIDs then you can specify this using a CICS PA System Group. You will also need to specify the mobile transaction IDs. You can use a CICS PA Object List for this.
In the example below I have specified MOBAPPL* for APPLID and MOB* for TRAN. When you run the CSV extract report using the form above, the JCL should look something like this:
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.
The CICS team are very proud to announce the beta release of the CICS TS plug-in to enable deployment of CICS applications using IBM UrbanCode Deploy.
UrbanCode Deploy is a tool to orchestrate and automate the deployment of applications, middleware configurations and database changes into development, test and production environments. UrbanCode Deploy V6.1 and enhancements in V6.1.1 announced today include the zOS Utility plug-in to deploy zFS files and MVS datasets, and to run your REXX, UNIX, and JCL scripts. DevOps as it relates to z/OS is discussed further in the video Getting to the Promised Land of DevOps with UrbanCode.
The new CICS TS plug-in provides steps to:
Perform a NEWCOPY or PHASEIN of a program or list of programs.
Install a resource definition, group or list from CSD or BAS.
A simple use case, to deploy new load modules and perform a NEWCOPY on the related programs, involves steps from both the CICS TS and the zOS Utility plug-ins. The following diagram shows what this process looks like in the UrbanCode Deploy process editor:
Other examples include binding DB2 DBRMs, moving or copying zFS files, starting automated tests, or seeking approvals. There are over 115 plug-ins to work with most of today's popular systems that host enterprise applications.
Abstract: CICS CMCI connections can only be defined manually in CICS Explorer. This is suitable if you have to create a small number of connections but does not fit if you have to define a large number of connections. This document will show you how to generate Connections.pref from an Open Office spread sheet. This article is based on CICS Explorer 5.1.1
Objective: Generate Connections.pref from Open Office spread sheet (See picture below)
How you will reach your objective: By following this guide you will define an XML Filter on OpenOffice. You will then use the newly created XML Filter to Export the spread sheet. You will then use Open Office in this way: On OpenOffice Calc, click on File -> Export, on Save as type Select the newly created export type. (See picture below)
What needs to be done:
1 - Store the attached sample files:
1.1 Download the ExportConnectionSampleFiles.zip attachement.
1.2 Unzip the attachment in a suitable place on your workstation
1.3 Explore the content of the unzipped folder. You should find three files:
- XSLTExportConnections.xml - Artifact to be pointed by OpenOffice Calc (See instructions on 2.1)
- Sample.ods - Sample spread sheet file to demonstrate the Export process
- Sample.pref - Sample output generated using this guide
2 - On Open Office Calc. Click on Tools -> XML Filter Settings...
2.1 Click on New.
2.2 Specify values as the followings:
NOTE: XSLTExportConnections.xml points to the file that you have downloaded from the attachments.
Explanation: The XML file that you have referenced in Open Office Calc is a XSLT file. XSLT is language used in many contexts (for example Mobile development) by which you can specify XML transformations.
In this case you wil use an XSLT transforamation to transform a XML file format (Apache Open Office Calc) into another format.
Of course, this transformations can be customized as needed, try editing the XSLT file!
In my previous article “What is CICS Application Multi-versioning?” I described how the new multi-versioning capability in the CICS TS V5.2 open beta could be used to eliminate name clashes when hosting independently developed applications on the same CICS platform. This allows you to take advantage of the increased operational efficiency and reduce the number of regions required. In this article I will explain how use to the multi-versioning capability to increase service agility.
Service agility allows you to deploy a new application or in this case a new version of an application with the confidence that users will not be impacted. This means not only ensuring continuity of service i.e. zero down time for the application but also the ability to quickly back-out a change if a problem occurs.
In the CICS TS V5.2 open beta we have introduced a new application available state in addition to the existing enabled state. This allows you to install and ENABLE a new version of an application while user requests are still routed to the old one. Only when you make the new version AVAILABLE are new requests routed it. This allows you to ensure it is properly ENABLED i.e. all dependencies satisfied, resources enabled and entry points declared across all the regions on the platform before it’s “open for business”. It also allows you to easily switch back to the old version if there’s a problem.
In this example Application A version 1.0.0 is already installed and AVAILABLE. The entry point E1 can be called from program S using a traditional EXEC CICS LINK. In fact the owner of program S doesn’t need to know that program E1 is actually an application entry point. But there’s a bug in program P that you want to fix.
First you package and install a modified program P’ in version 1.0.1 of Application A. Then you ENABLE the application to make sure everything is OK. While you are doing this, program S will still be calling version 1.0.0.
When you are ready make, version 1.0.1 AVAILABLE and program S will now use the new version. Any previous requests will complete normally using program P. Version 1.0.0 is still AVAILABLE but CICS always routes requests to the highest available version of an application.
If the update doesn’t fix the bug or made it worse you can easily revert to version 1.0.0 of Application A by making version 1.0.1 UNAVAILBLE. This is because you still have the old installed and ENABLED program P. All new requests will immediately go to the old version of the application so there should be no interruption to service.
This approach has a number of advantages over just loading a new copy of program P as you might have done if it wasn’t part of an application:
You can update multiple resources at the same time: what if you need to change program Q as well? By packaging the required updates in a new version of the application you can guarantee to get either the old versions or the new versions of both P & Q
You have total control of the update: all new requests go to version 1.0.1 while those tasks still using version 1.0.0 complete normally. If you make version 1.0.1 UNAVAILABLE all new requests revert to version 1.0.0
You have better diagnostic information: each task is associated with either Application A version 1.0.0 or version 1.0.1. All messages, Monitoring, etc will identify the specific application version so you can tell whether program P’ fixed the problem
You have an audit trail: changes in the application and CICS bundles can be recorded in your source control management system. You can see who did what and when
You can easily undo the update: it is simply a matter of making the new version UNAVAILABLE to back out the update. The process can even be automated if you are prepared to write a utility that looks for any problems e.g. messages or abends and the calls the right API
One thing that might concern you at this point is footprint. Haven’t you just doubled the storage needed for the application code during the time period when you phase in the new version? The answer is no because you can share the programs that are the same i.e. E1 and Q so you only need extra storage for P’.
In this article you have seen how to use multi-versioning to simply and reliably phase in a new application version to fix a bug and easily revert to the previous version if a problem occurs. But what if you actually want to host two different versions simultaneously on the same platform, perhaps to allow a subset of users to beta test a new feature. In the next post I will show you how you can do this using a Liberty JVM server.
[7/Oct - article updated to refer to CICS TS V5.2 and some WASDev links updated]
CICS TS V5.2 includes the latest WebSphere Application Server Liberty Profile (WLP) V8.5.5 that provides features for the Java API for XML Web Services (JAX-WS) and the Java Architecture for XML Binding (JAXB). Together these technologies enable you to write SOAP web services in Java as part of a CICS application.
You may be thinking, why not use the CICS TS native web services stack as it is fast, efficient and good at mapping XML data? The issue here is that Java developers will likely prefer to use annotations, API and tooling based on JAX-WS and JAXB to process the SOAP web service so the application remains cross-platform. Indeed you may want to host existing services in CICS so it can benefit from co-location to DB2, VSAM, and other CICS applications, with as little change as possible.
Another option is to use Apache Axis2 provided in CICS TS V4.2 and above - however development and use of Axis2 has slowed in favour of Apache CXF. WLP uses CXF.
This article shows you how to set up Eclipse with a local WLP server and CICS Explorer, then download and test a sample web services project. Once you have that running, it goes on to deploy the sample into CICS, modify the sample to use JCICS, and test it with the Web Services Explorer.
CICS TS V5.2 downloaded and configured. This is needed to run WLP 8.5.5 in CICS.
Install WLP developer tools into Eclipse - Start Eclipse then select Help > Eclipse Marketplace... > IBM WebSphere Application Server V8.5.5 Liberty Profile Developer Tools for Eclipse Juno > Install > Confirm > accept the license agreement > Finish. After the installation completes, restart Eclipse.
Create a local WLP server instance for testing – In Eclipse select File > New > Other... > Server > Next > WebSphere Application Server V8.5 Liberty Profile > Next > download or install. This starts the “Install Runtime Environment” wizard.
Select Download and install a new runtime environment from: > IBM WebSphere Application Server V220.127.116.11 Liberty Profile > Next > IBM WebSphere Application Server V18.104.22.168 Liberty Profile Extended Content > Add > Next.
Accept the license agreement > Next > enter a target installation folder such as /home/cockerma/liberty8553 > Finish. Once complete you will be returned to the “New Server” wizard with the path of the new server instance completed.
Select Next > change the server name from defaultServer if you wish > Finish.
Install CICS Explorer V5.2 – In Eclipse select Help > Install New Software... > Add.. > Archive > navigate to and select the file cicsts52.explorer.sdk.zip > Select All > Next > Next > accept the license agreement > Finish. After the installation completes, restart Eclipse.
Add CMCI and z/OSMF connections - Switch to the CICS SM perspective. Select the Host Connections view and add a CMCI connection to your CICSPlex SM or CICS region, then add a z/OSMF or z/OS FTP connection to your z/OS system. Alternatively you can export connections from another CICS Explorer installation and import them here.
Test the connections using the CICS SM and z/OS perspectives.
Download the Web Services Sample
Download the sample as file JAXWSWebSample.jar from WASdev.
Expand the sample - Expand JAXWSWebSample.jar to a temporary directory. We are only interested in the file JAXWSWebSample.war that is in the sub-directory wlp/usr/servers/JAXWSWebSample/apps/.
Import dynamic web project - In Eclipse select File > Import > WAR file > WAR file: select the file JAXWSWebSample.war from the temporary directory > Finish.
Optionally, test the sample on your local WLP server.
Select the project JAXWSWebSample > Run As > Run on Server > WebSphere Application Server V8.5 Liberty Profile at localhost > Finish.
This will start the server, deploy the application and start a web browser. Experiment with the application to send and receive a web service.
Deploy the web services sample in CICS
Switch to the resource perspective. Select Window > Open Perspective > Resource.
Create a new CICS bundle project. Select File > New > Other... > CICS Bundle Project > Next > Project name: JAXWSWebSample.bundle > Finish.
Include the dynamic web project in the CICS bundle. The CICS bundle manifest editor is started. In the Define Resources > New... > Include Dynamic Web Project in Bundle > JAXWSWebSample > JVM Server: DFH$WLP > Finish. Your JVMSERVER resource name for the WLP server may be different.
Deploy the CICS bundle. Right click on the CICS bundle project JAXWSWebSample.bundle > Export bundle project to z/OS UNIX File System > Export to a specific location in the file system > Next. Select an appropriate z/OSMF or z/OS FTP connection. In Parent Directory, select the directory to deploy the bundle project to. Select Clear existing contents of the Bundle directory > Finish. The bundle will be deployed to zFS.
Define a CICS BUNDLE resource. Select Definitions > Bundles Definitions. Right click in the list of bundles > New. Enter an appropriate CSD group and name of JAXWSDEM. For bundle directory type in or use Browse to select the zFS directory of the bundle you just deployed. Do not install the bundle yet.
You can set -Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true in the JVM profile to automatically create the WLP configuration files and directories when the JVM server is enabled. Once these are created change this option to false so that changes to server.xml are not overwritten.
Enable the JAX-WS feature. Edit the WLP configuration file server.xml and add:
within the featureManager XML node then save the file. Changes to server.xml will be picked up within 5 seconds by default. Enabling jaxws-2.2 will automatically enable the jaxb-2.2 feature.
Install the BUNDLE resource JAXWSDEM created previously and check the bundle is enabled. The JVM server output file, usually named with extension .dfhjvmout, should contain some messages to indicate the web application was installed, such as:
[AUDIT ] CWWKT0016I: Web application available (default_host): http://winmvs2c.hursley.ibm.com:27510/JAXWSWebSample/
The WLP messages.log file will contain more details messages with timestamps.
Use a web browser to navigate to the web application URL in the above message, and use the DEMO A: @WebService/Stub Client link on the left pane to test sending and receiving a web service.
Update the sample to include some calls to the CICS Java API JCICS and redeploy
Add the JCICS API to the project build path. Right click on the JAXWSWebSample project and select Build Path > Configure Build Path... > Libraries > Add Library... > Liberty JVM server libraries > Next > ensure the version of CICS is CICS TS 5.2 > Finish.
Add some Java code to call the JCICS API. Expand the JAXWSWebSample project, then section Java Resources > src. Add the Java package com.ibm.cics.test and the following Java class into that package:
Update the web application to call this method and display the results on the web browser. Expand project JAXWSWebSample, then section WebContent and edit index.jsp. Immediately after the text JaxWs Demo –- Liberty</h2> and before the text <td> add the following lines:
Refresh the CICS bundle. Disable the BUNDLE resource JAXWSDEM, then discard it. Deploy the JAXWSWebSample.bundle project to zFS as you did previously, then install the BUNDLE resource JAXWSDEM.
Note: Strictly speaking you only need to disable/enable the bundle to pick up changes to web applications. However, it is generally good practice to discard/install to pick up changes in the bundle manifest and lifecycle all bundle parts in unison.
Refresh the web browser to see the modified banner with the CICS region applid, task number etc.
Call the web service using the Eclipse Web Services Explorer
Expand the project JAXWSWebSample, then section WebContent > WEB-INF > wsdl.
Right click on SimpleEchoService.wsdl, then select Web Services > Test With Web Services Explorer.
With SimpleEchoServiceSoapBinding highlighted in the Navigator section, in the Actions section next to Endpoints, select Add.
In the Navigator section, click on the + sign to expand SimpleEchoServiceSoapBinding, then select echo.
In the Actions section next to arg0, select Add.
Enter your name in the entry box and press Go.
The SOAP web service request and the Status section contains the response from the JAX-WS application.
This article has taken you through how to deploy and test a sample web application into CICS TS V5.2 that exposes some of its capabilities as SOAP web services using the Java community driven standards JAX-WS and JAXB.
This article shows how the IBM Health Center can be easily installed into the CICS Explorer and used to create customized perspectives for monitoring CICS JVM servers. Together these two tools provide a powerful platform for profiling CICS Java applications, monitoring memory usage and garbage collection, and performing further diagnostic commands.
To follow the setup in this article you will require the following minimum software requirements:
CICS TS for z/OS V4.2 or later
IBM Java SDK for z/OS V7.0 for SR6 (or later)
A Windows or Linux client with the CICS Explorer installed, using a supported IBM Java SDK.
The configuration in use in this article was as follows:
IBM Monitoring and Diagnostic Tools for Java - Health Center -v22.214.171.124401101227
Windows 7, with CICS Explorer V126.96.36.199 open beta and IBM Java SDK 7.0 for Windows
What is the IBM Health Center?
The IBM Health Center is a diagnostic tool for monitoring the status of a Java Virtual Machine (JVM) and can be used with any IBM JVM including CICS JVM servers. It has a low runtime overhead and provides a highly customizable client as part of the IBM Support Assistant (ISA) workbench. Since the Health Center client is Eclipse based, it can also be installed into other Eclipse environments such as the IBM CICS Explorer.
Installing the Health Center
The first step is to install the Health Center plugin into your CICS Explorer Rich Client Platform (RCP). To do this you will need to add a new software repository to your CICS Explorer, as follows:
In the CICS Explorer, click Help -> Install New Software
Click Add to add a new software repository and provide the following location information
Next click the drop-down box labeled Work with, and select the site that was just added in step 2. This will validate that the Health Center is available in the repository specified.
Click Next in the Install Details window to confirm the Health Center Core Feature will be installed.
Review the license information and click Next.
Click OK to confirm the installation of unsigned content, and then click Yes to restart the CICS Explorer when prompted.
Configuring the JVM for monitoring
To enable a JVM for monitoring it is necessary to add a few JVM arguments to enable the Health Center agent and the TCP/IP port it will listen on. When using a CICS JVM server the JVM arguments are set in the JVM profile, which is located in the USS directory specified by the CICS JVMPROFILEDIR SIT parameter.
To edit this file in CICS Explorer, click Window - > Open Perspective -> z/OS
This will open a new Eclipse Perspective, which is a customizable set of views and includes the CICS Explorer z/OS UNIX Files view for editing zFS files. However, before you can access z/OS you will first need to define an FTP connection to your z/OS system. To do this in the Host Connections view expand z/OS -> z/OS FTP and click Add.
In the Host name field, enter the hostname of the FTP server for the z/OS system and click Save and Connect. This will then display the Signon window. Enter a z/OS user ID and password as credentials for the FTP connection and click OK to connect to the FTP server
Now using the z/OS UNIX Files view navigate to the location of the zFS directory used to store the JVM profiles for this CICS region. In our example we are using the DFHOSGI.jvmprofile stored in the /var/cicsts/dfhconfig/JVMProfiles/ directory.
Add the follwoing -Xhealthcenter JVM argument, this enables the Health Center agent to collect monitoring data and specifies the listening port. We specified the port number 8125
Health centre also uses an additional listening port for its IIOP connection. If you want to control which ports are used ahead of time then you can add the following system property which sets the additional IIOP port used by the Health Center.
Your CICS JVM server profile should now look similar to the following:
To enable the new JVM settings it is necessary to stop and restart the JVM. This can be done using the CICS Explorer JVM Servers view as follows:
In CICS Explorer click Window –> Show View -> Others, select JVM Servers and click OK.
Select the CICS region in the CICSplex Explorer view, this will show the state of the JVM servers in this CICS region.
Select the JVM server and click Disable -> Phase Out and then click OK
Select the JVM server again and click Enable and then OK to start the JVM.
Once the JVM server is started the Health Center agent will initialize and immediately start buffering monitoring data ready for collection by the Health Center client. At this stage you can check the Health Center agent is listening on the TCP/IP port using the following MVS TSO command
NETSTAT (PORT 8125
In addition if the JVM server stderr file is viewed, this will show log messages similar to the following indicating the Health Center agent was successfully started and is listening on the configured ports.
Dec 31, 2013 1:16:48 PM com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean <init>
INFO: Agent version "188.8.131.5231003" Dec 31, 2013 1:16:48 PM com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean startMBeanServer
INFO: IIOP will be listening on port 8126 Dec 31, 2013 1:16:49 PM com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean startAgent
INFO: Health Center agent started on port 8125.
Connecting the Health Center client to the JVM
Now that the JVM server is running you can use the Health Center views to monitor the CICS JVM server.The Health Center Environment perspective provides a convenient way to access all the Health Center function. It can be simply accessed using Windows -> Open Perspective -> Other -> Health Center Environment
To connect to the Health Center agent running in the JVM you have to run the connection wizard. This can be accessed from any of the Health Center perspectives using File -> New Connection menu. This starts the Health Center connection wizard.
Click Next and then enter details for the listening port, 8125, as specified previously in the CICS JVM profile.
Click Next and this displays the following window to confirm the port is being used by a Health Center agent on the host.
Then click Finish to connect, and the Configuration view is now displayed and provides useful information on all the Java parameters, dump options, and classpath settings in the JVM.
The Status view in this perspective can now be used to access the different functions of the Health Center, such as CPU, Environment, Garbage Collection, Locking, Native Memory, Profiling and Threads. The next section will discuss how some of these can be used to analyze the CICS JVM server environment.
The Garbage Collection perspective provides a set of views to assist in analyzing the garbage collection (GC) process used by the JVM to manage memory in the JVM heap. Using the default gencon GC policy splits the Java heap into two areas, the new or nursery area, and the old or tenured area. CICS JVM server statistics call new or nursery activity minor GC and call old or tenured activity major GC. The Summary view provides detailed information on the GC process, however, much of this information is also displayed in the CICS Explorer JVM Servers view, which can be added to the Garbage Collection perspective using Window -> Show view -> Other –> JVM Servers. In addition individual Health Center graphs for Used heap and Pause time can also be added using the same Show view menu, and a customized perspective created with a combination of both Health Center and CICS views as shown below.
Custom perspectives such as these can be saved for future use by right-clicking on the current perspective and selecting Save As, which will add the perspective to the list of available perspectives on the top row.
In our example above, you can see that the initial heap of 30MB provides adequate space for the current memory usage, and the GC process is able to minimize the heap occupancy to approximately 6.8MB each time it is invoked. Out of the 949 garbage collections events that have run, all but 5 were in the nursery area (minor), which indicates most garbage is short lived objects from the CICS transaction invocations.
One of the most useful GC views provided by the Health Center is the Analysis and Recommendations view. This provides analysis for each perspective, and is a simple way of analyzing heap usage. In the Garbage Collection perspective above, the following analysis was provided, which relates accurately to the increase in workload used to generate this test.
The Profiling perspective allows method level profiling of the applications running within the JVM. The methods can be filtered by class or package name. In the figure below we can see that during 23.1% of the samples taken, the method that was running was called from the main method of the JavaLinker class which is defined as the entry point for our CICS program. In addition the formatTime() method was active in 3 samples out of 44, and so could be considered as a candidate for optimization.
Additionally the Invocation and Called method views allows you to analyze the call path of each profiled method to ascertain how it was invoked, and what further methods it calls.
The Threads perspective provides detailed analysis of all the threads running within the JVM. The Current threads view supplies a useful Thread name filter box, which allows the display to be filtered. Using a filter of *.TASK.* will locate the CICS task threads which are dubbed with the pattern program.task.tranid. For each thread displayed it is possible to show the call stack, this will show where each thread is currently suspended. In our example we can see that CICS task 53525 is running under transaction ID CSMI and is currently suspended in a Thread.sleep() method called from the main method of the JavaLinker() class.
Customizing data collection
Instead of requiring a socket connection to a monitored JVM, Health Center can save the data that it is analyzing to a number of .hcd files on the local machine. These files can then be opened in the Health Center Eclipse client at a later date, without the need for a live connection. This is termed headless mode, and is useful for systems where you cannot connect a client to the agent. For example, where firewall restrictions prevent connection.
To enable headless mode set the following property in the CICS JVM profile.
To control the directory location of the temporary files used to buffer data for headless collection you can set the following system property. In the example below this is set to a a directory unique to the specific CICS JVM server using the &APPLID and &JMVSERVER substitution symbols which will be substituted at runtime by the relevant CICS values.
To analyze the run transfer the .hcd suffixed file to your workstation in binary mode and open using the File -> Load Data menu in the Health Center client, which will then enable analysis of the run using any of the facilities described.
If the data that Health Center collects exceeds the maximum file size of 2GB the agent automatically creates a second file, and so on. If you are gathering lots of data, a long headless run will result in the collection of multiple files. By default, Health Center keeps only the last 10 files. You can override this value by using the following system property.
Alternatively to minimize data collection in a JVM that is not being monitored you can start the agent but delay collection until a client connects. This means there is no impact on the application that is running, until the client actually connects to the agent. To enable this mode set the following JVM property.
This article has shown how the functionality of CICS Explorer for monitoring Java workloads in CICS TS, can be easily extended using the IBM Health Center plugin. Let us know how you get on and what further information you are interested in.
If you wish to explore this area further the following articles and papers may be useful references:
Over the past five years the CICS Transaction Gateway team have released a number of SupportPacs to support the development of applications calling CICS using CICS TG APIs. This post provides a summary of these SupportPacs, including detail on the evolution of the API for .NET Framework-based applications.
Click the links to the specific SupportPacs to find further detail and API documentation.
CA5F: IBM CICS TG 'gateway' intercept plug-in support
CA5F: IBM CICS TG 'gateway' intercept plug-in support is one of our more recent application development SupportPacs, for use when developing and testing Java and JCA applications that call CICS using CICS TG. The SupportPac provides updated versions of the CICS TG Java and JCA APIs which allow applications to be tested without needing a running CICS TG or CICS instance. By supplying an intercept plug-in, a tester can simulate the responses from CICS to verify that the application behaves as expected. The real power of the SupportPac comes when used with integration test tools such as IBM Rational Test Workbench which can record the interactions between an application and CICS and then use those recorded interactions to simulate responses from CICS for application testing. This SupportPac is for use with CICS TG V8.0 or later.
CA0B: 64-bit ECI Version 2 support for CICS Transaction Gateway V8
For developers of C or C++ programs on AIX, we produced CA0B: 64-bit ECI Version 2 support for CICS Transaction Gateway V8 which provides a 64-bit version of the ECI V2 API for AIX to allow 64-bit C or C++ programs to call COMMAREA-based CICS programs. After its initial release the SupportPac was updated to allow ECI calls to be executed asynchronously. The content of the SupportPac was incorporated into CICS TG V9.0 and extended across all non-z/OS platforms to make the asynchronous capability available to both 32-bit and 64-bit programs, and to include support for CICS channels and containers, password phrases and ESI.
CA76: CICS Transaction Gateway V9 SSL connectivity for .NET applications
For use with CICS TG V9.0, CA76: CICS Transaction Gateway V9 SSL connectivity for .NET applications extends the .NET API provided in CICS TG V9.0 to allow Secure Sockets Layer (SSL) technology to be used to provide secure communication between the .NET application and CICS TG. As this SupportPac is based on the CICS TG V9.0 API it benefits from both 32-bit and 64-bit operation without any dependency on ECI V2, and in combination with the IPIC over SSL capabilities provided in V9.0 allows you to secure all communication links in your environment.
CA75: CICS TG 8.0 channel and container support for .NET clients
For use with CICS TG V8.0, CA75: CICS TG 8.0 channel and container support for .NET clients extends the .NET API provided in CICS TG V8.0 to include support for CICS channels and containers. When using the IPIC protocol to communicate with CICS, channels and containers allow the data limits of COMMAREA-based applications to be far exceeded, and applications benefit from automatic code page conversion for character data. The content of the SupportPac was incorporated into CICS TG V8.1 but it is useful if you want to use channels and containers with CICS TG V8.0.
CA73: CICS TG V7.2 .NET application support
For use with CICS TG V7.2, CA73: CICS TG V7.2 .NET application support contains the earliest version of the CICS TG API for .NET, which was later included in CICS TG V8.0. This version of the API allows .NET applications to call COMMAREA-based CICS programs and remains useful if you are using CICS TG V7.2 or developing applications that target version 2 of the .NET Framework.
CA72: CICS TG: Developing .NET components for CICS connectivity
The original .NET SupportPac was CA72: CICS TG: Developing .NET components for CICS connectivity in which I describe how to create a .NET wrapper around the CICS TG ECI V1 API for C. Such a wrapper allows .NET applications to call COMMAREA-based CICS programs when CICS TG is installed on the same machine and you are using the TCP/IP or SNA protocols to communicate with CICS. The SupportPac also includes full source code for the wrapper and despite its age it remains a useful guide to developing your own APIs.
Below is a summary of the 6 SupportPacs I've just described:
CICS TG version
CICS TG V8.0, V8.1 or V9.0
Java and JCA, 32-bit and 64-bit
Windows, Linux, AIX, Solaris, HP-UX, z/OS
CICS TG V8.0 or V8.1
C and C++, 64-bit
CICS TG V9.0
.NET, 32-bit and 64-bit
CICS TG V8.0
CICS TG V7.2
Any CICS TG, Windows only
Further resources for application developers using CICS Transaction Gateway:
Writing RESTful web services using a CICS Liberty JVM server - Part 1
My name is Daniel Fitzgerald, I'm a trainee software developer in the CICS team based at IBM Hursley UK. I've been working for the last six months on the Mobile Extensions Feature Pack V1.0 for CICS Transaction Server. As part of the project we looked at using JAX-RS, JSON and RESTful designs within Liberty. This article, coming in two parts is the result of these investigations.
The CICS Liberty server is a web container technology based on WebSphere Application Server Liberty Profile. It comes as part of CICS TS V5.1 at no extra cost and offers the potential for significant zAAP offload compared to a regular CICS Web Service. The CICS Liberty server offers a lightweight Java container with all the features of Java Servlets and JavaServer Pages (JSP's) as well as local access to your existing CICS applications and data. You can expose these existing resources to the web using Java Servlets hosted in the CICS Liberty server and design them in a RESTful way. But before we begin what exactly is REST?
The term 'REST' refers to Representational State Transfer, a design pattern for interacting with resources stored in a server. Each resource has an identity, a data type, and supports a set of actions. The RESTful design pattern is usually used in combination with HTTP, the language of the internet. In this context the resource's identity is its URI, the data type is its Media Type, and the actions are made up of the standard HTTP methods GET, PUT, POST and DELETE.
REST vs SOAP
Now we understand what REST is, why would we want to use it? Why not use Simple Object Access Protocol (SOAP)?
RESTful designs tend to be simpler, easier to understand and work much more closely to the way the web works.
By using HTTP headers to describe the data we are exposing we save on overheads incurred by the SOAP envelope.
SOAP and Web Services Description Language (WSDL) are designed to be machine-readable, RESTful URI's should be human readable and describe the data being exposed. This makes testing and debugging simpler and easier.
RESTful designs put the onus on the client to remember state and by careful use of the 'Expires' HTTP header can improve caching while reducing server-side complexity.
Whilst you decide if a RESTful architecture is for you, let's consider some business cases:
You want to modernize the interface to your application by replacing terminal screens with a Web browser and a RESTful client.
You want to use Java based tools to develop, package and deploy web solutions using existing CICS applications and resources to ease development and speed up time to deployment.
You already use the Liberty profile technology but want to see how running it in CICS will offer added benefits. These include easy access to local CICS resources and co-location with your data source such as DB2.
A quick note on exactly what JAX-RS is. It stands for Java API for RESTful web services and is used for designing web services according to the Representational State Transfer (REST) design pattern. It uses annotations to convert between Java and web data. There are many implementations of JAX-RS in use today including the CICS Liberty Server, WebSphere Application Server and Apache Wink.
In the next part of the article I'll discuss the actual implementation of such a service including packaging and deployment to the CICS Liberty server complete with screenshots and code samples.
In the latest version of the CICS PA plug-in we have attempted to bring a new approach to CICS performance monitoring and assessment. Traditionally users of CICS Performance Analyzer are performance system experts who have honed their skills over many years and have evolved a wealth of knowledge of keeping their CICS systems well balanced and ways of spotting problems before they have a detrimental affect to overall system performance.
We are currently distilling this knowledge and experience into the CICS PA plugin to help new or inexperienced CICS users appreciate more of the factors that influence their CICS systems and what the implications of different aspects of their overall CICS configuration can be.
CICS Statistics – The early warning system
Stats alerts are one of the first points of contact most performance analysts have with their system and generally an alert here requires them to trawl through many different stats records to get a reasonable handle on what is happening inside their system. We have taken some of that experience derived work away from them and now present certain common alerts in a manner that can be more readily consumed or appreciated. CICS PA now presents an interval plot of the users statistics data from before and after an alert. Plotted in this graph are the specific values that contribute the the alert condition they are studying.
Transaction Alert “Maximum tasks reached”
An example is the Transaction Alert “Maximum tasks reached”. This is displayed in the context of: The “max task” value specified, the current and peak active user transactions and the number of times at “max task”. There are additional references and values displayed alongside each interval on the interval plot but the points being shown over a time period give the visual indication of what critically has been happening to the region.
Help me out here..
In conjunction with the interval plot we have put a great deal of effort into the contextual help a user receives. Although the online documentation covers every aspect of their system it is not focussed on the specific situation the analyst is looking with the alert. So rather than the user taking time out to assimilate the online documentation hitting F1 provides the users with the genuine voice of experience that describes the problem domain and what the relevance of these numbers or the rate of change can mean. Not only that it provides users with the practical advise such as understanding areas of caution that need to be considered before going ahead and making changes.
Transaction class “Maximum active transactions in class reached:
The maximum active transactions in class alert is in the same family, as the global transactions alert but in this visualisation we show a breakdown of the transactions that make up that class and the number of transaction attaches. From here the user can link to the equivalent interval plots for both the Applid itself or any specific transaction.
Transaction: “Storage violations for transaction ID”
The final member of this alert family is for individual transaction itself. The Transaction interval plot is shown for a Storage violations for transaction ID alert and these plots can also be selected by menu from the sheet view of the respective stats table. When creating this view the input we received was that it was necessary to look at the transaction attaches in conjunction with the attaches associated with the transaction class if applicable and that of the region overall.
These views have been designed to be navigable and joined up meaning the users are able link from one to another as needed. They show your CICS stats data in a way that has not been shown before letting you make informed decisions about your system supported by real life help and information.
In the fall of 2012, I had the opportunity to return to the United Kingdom after 36 years. My initial visits were very quick, since the United States Navy would only allow you on shore for a short period. Nevertheless, my thoughts of the UK were still centered around the days of King Arthur ...leading up to the James Bond 007 era. Then there was my remembrance of William Shakespeare, the greatest poet and playwright ever and William Wilberforce, an English politician and philanthropist that led the movement to abolish the slave trade and most of all, the monarchies of the United Kingdom. Of course, my memory of these people and the fictitious character come from my days in school and my watching a host of movies. For the record, let me state that Skyfall is the best James Bond movie ever. I am a Bond fan.... and I had to make sure everyone recognized this fact. So don't hate!
On this trip, I headed to the town of Winchester, UK. It was once the capital of England.... I never would have guessed. Winchester gives the appearance of a country town but later I found it to be an expensive town. How fortunate to come here, this was an opportunity to grasp some new knowledge. Entering into Winchester, I was met by King Alfred the Great, standing high upon his podium. King Alfred was the only monarch to be labeled "The Great", and he is well-known for successfully defending his kingdom from a Viking takeover. King Alfred is also known for being a strong leader who encouraged education. It was education and technology that brought me to the area.
In the Winchester area exists one of the greatest innovation centers known, the IBM Hursley Lab. It is where software development is the name of the game... and CICS is the champion of them all. Wait a minute! I think we may have some haters out there....but don't hate. It's time to Recognize!
I visited IBM Hursley to learn and understand the latest updates to the JVM server for IBM CICS Transaction Server. The JVM server was introduced in the IBM CICS Transaction Server V4.1 - June 2010. Since then a host of updates have taken place and now a new deliverable is being made available to CICS clients around the globe. You will find the deliverable, CICS and the JVM server - Developing and Deploying Java applications, SG24-8038 at IBM Redbooks web site. Specifically, the inspiration behind this new JVM server Redbooks publication is due to the OSGi framework and benefits associated with the new multi-threaded 64-bit JVM server capabilities provided in CICS TS V4.2.
On a daily basis, Java applications run within the JVM server runtime inside CICS, providing access to CICS resources such as VSAM files, queues or databases, with the same qualities of service for transactional recovery, security and scalability as provided for traditional COBOL applications. More details can be found in the IBM Redbooks publication, Architect’s Guide to IBM CICS on System z, SG24-8067.
In CICS TS V4, the JVM server is used by several other CICS features/components such as Axis2 Web services, Dynamic scripting Feature Pack and Compute Grid SupportPac, In CICS TS V5.1, the JVM server is also used by the newly announced Mobile extensions and Modern Batch Feature Packs as well as by the Liberty runtime for Web based servlet applications and other IBM or 3rd party components such as WebSphere Operation Decision Management (ODM).
Many of us know that CICS is widely used across in the financial, telco, and retail industries and the JVM server supports this effort as follows:
· Providing a multi-language application server runtime for applications written in Java, COBOL, PL/I, C, C++, and scripting languages.
· Supporting re-use of components from JEE application servers and other 3rd party Java frameworks
· Supporting the growing availability of Java development skills in the application development marketplace
After what I had learned visiting the home of King Alfred the Great, I must suggest to our audience of architects, application programmers, and system administrators that you must take advantage by downloading and reading the IBM Redbooks publications stated above. You will get a CIC from King Alfred as well.
CICS version 3 will always be a special release for me as it was the first CICS release I ever worked on. I was a member of the functional test team for the web services functionality. I spent many a day (and a few nights) building and executing test cases to try and find fault with the product. Looking back at the release it is important to note the amazing technology that CICS version 3 brought to the party.
We allowed existing customer applications to be exposed as web services. Not startling in itself but when you consider that the customer didn't even need to recompile any of their source code in order to exploit this capability. This allowed customers valued assets to be exploited by any process running on any platform in any language.
Since its inception CICS programs have been forced to share data through a 32kb area of memory known as the commarea. This area of data could be passed between programs running in different address spaces. Several customers had requested that we increase this limit to something larger as for them 32kb was becoming a constraint. Version 3 delivered channel and container technology that allowed programs to share blocks of data in named containers within a named channel. Not only did this alleviate the data limit constraint it also allowed that data to be functionally divided into separate pieces. No longer would the error code be at a certain offset into the commarea it could now be in it's own container.
We also extended our TCP/IP support to allow CICS systems to communicate over TCP/IP as a replacement for ISC connections over SNA. CICS programs could now be called over a TCP/IP network using an IPIC connection thus reducing the requirement for SNA networks. Each release since we have been adding capability to this feature, allowing function shipping over IPIC etc.
As the release of 3.1 marked the start of my CICS career it was also the start of a journey for CICS. Each release we have created capability that allows our customers to drive further value from their CICS installations. Developing new applications or deriving new value from existing programs CICS has shown that it is a modern, flexible and High quality transaction processor ready to meet the demands of a modern enterprise.
That journey continues today with the announcement of some feature packs for CICS that extend current releases of the product into new and exciting areas. For more information see:
These announcements excite me (although I have known about them for a while). Once released these capabilities will allow customers to easily integrate mobile application development with CICS resources. It will also allow them to integrate batch workload with existing transactional workloads. If you are a CICS customer why not have a look at the announcements and start thinking about where the new technology could take your business.
We're delighted to announce that we've just launched a brand new Developer Center for CICS. This will be the new home of blogs and other collateral, produced by the development and support teams, to help you make the most of your CICS installations.
The new site allows us to integrate more closely with dwAnswers, IBM's question and answer forum designed to help you get the information you need as quickly as possible. We now have a CICS Smart Space which provides an aggregation of all CICS content on dwAnswers, which can also be accessed via the "CICS Q&A" menu item on the new developer center. We'll use this to provide support that we used to do through the CICSdev and CICS explorer forums - simplifying the support channels so you can focus on getting the help you need, rather than figuring out where to find it.
We are in the process of migrating still relevant content from CICSdev to the new DevCenter, with the hope being that we will sunset CICSdev around the start of the new year. Once a blog has been migrated we'll add a link to the new post in the original CICSdev blog so you can quickly find the post on the new site. This gives you a bit of time to update any bookmarks you may have for posts. However, we do believe that the new site should be relatively straight forward to navigate with an improved search mechanism and categorisation capabilities.
Please do take a look and let us know what you think. The site is still in its infancy, we'll be adding new content and improvements as often as we can - so be sure to check back regularly. If you have any suggestions for improvements feel free to comment on this blog - or on the Welcome to CICS post on the new site.
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.