There are various reasons why businesses choose to use CICS Transaction Gateway (CICS TG) in their environment.

In this blog I discuss three of them:

To act as a network concentrator

For intelligent routing

For offering simple, flexible solutions

As a Network Concentrator

Do you need to consolidate disparate systems and applications?

Do you want to protect your CICS resources?

Do you want to simplify your network?

If the answer to any of these questions is “yes” then CICS TG can provide a solution.

You can choose to have CICS TG act as your network concentrator on any one of a wide range of platforms including zOS, AIX, Linux and Windows. It is likely that you can integrate CICS TG into your current solution using existing hardware, with minimal time and effort.

CICS TG connects to all versions of CICS TS for zOS, CICS TS for VSE, CICS TS for i, and TXSeries. Whether your client applications are on mobile devices, or in ATMs, banks, post office branches, or shops, for example, all can connect to your CICS servers via CICS TG. This simplifies your networks and therefore reduces the number of IP sockets to CICS.

Simplified networks reduces network maintenance, saving you time and money.

Figure 1: CICS TG can handle requests from multiple different sources, and forward them
to any CICS server.

Intelligent routing

Do you want workloads automatically redirected based on a target server?

Do you want to interrogate each request and route it intelligently?

Do you want to block requests from unwanted sources?

CICS TG allows you to flexibly control the flow of work to CICS servers. For example, you might prefer to have dedicated CICS servers for handling mobile requests, and others for traditional workloads. In addition, CICS TG can automatically redirect workloads based on a target server. If you wish, you can also interrogate incoming requests and route them according to payload type, program ID, transaction ID, or even a user ID.

Intelligent routing is ideal for consolidating disparate systems and applications, perhaps as a result of a company merger. Furthermore, with CICS TG you can route new applications to your test servers whilst allowing existing applications to access the production servers.

Tip! You can safeguard your CICS servers by using CICS TG to reject requests from specific IP addresses, as well as known user IDs, specific program IDs or transaction IDs.

Wherever your client applications reside, whatever language they are written in, it is likely that CICS TG can handle them.

Your client applications can be in Java, C, COBOL, C++, use COM, or Microsoft’s .NET framework, whilst your mobile applications can use JSON web services. If your requests come from an application server, then as long as it’s a certified JEE application server such as WebSphere Application Server, Oracle WebLogic, GlassFish, or JBoss, CICS TG will process these requests.

As CICS TG supports a large variety of platforms and programming languages, it is likely that you can use existing investments of skills and hardware. If you’re involved in a merger and acquisition, then the flexibility of CICS TG will make your transition simple, straightforward, and cost-effective.

You may decide to start with a small solution running on desktops, perhaps sending requests to TXSeries. Then, as your business grows, you can easily move your solution
to a larger environment, and if desired, to work on System Z alongside CICS TS.

The choice is yours!

Figure 3: As your business grows you can easily move your solution to a larger CICS TG environment.

In a nutshell …

IBM CICS Transaction Gateway provides flexible solutions for your CICS connections and is ideal for any business environment.

This article makes it easier for you to try out the examples in the new IBM Redbooks publication Cloud Enabling CICS (SG24-8114-00).

The IBM Redbooks publication explains how you can cloud enable your CICS environment with step-by-step incremental examples.
By following the steps you can:

Manage a CICS application as a single entity

Provide automated controls via CICS policies

Deploy and back-out application versions with no service downtime

And even deploy multiple versions of the application concurrently

Below are snapshots of the CICS Explorer projects at various stages of the example, along with instructions on how to import them into CICS Explorer.
You can use these projects to quickly jump to the section of the publication you wish to investigate, without needing to start from the beginning.
All you need is the latest version of CICS Explorer.

CloudEnablingCICS_Chapter5_Platform_Policy_ApplicationV1.0.1.zip contains the development CICS platform and the platform scoped CICS policy. It also contains version 1.0.1 of the CICS application which has been updated to include a CICS policy scoped to the application. These projects are a snapshot by the end of chapter 5.

Preparing for application multi-version support, CloudEnablingCICS_Chapter6_Platform_Policy_ApplicationV1.0.2.zip contains the CICS platform and platform policy along with the next version of the CICS application. Midway through chapter 6 you will create version 1.0.2 of the application which will package the definitions for the application entry points into the application.

Instructions for importing the projects into CICS Explorer

The individual zip files contain a snapshot of all of the Explorer projects, up until that stage of the book. Therefore it is not required to import any preceding chapters, just the point at which you plan to begin from.

Perform the following steps to import the projects contained in the zip file into CICS Explorer:

Download the required zip file to a temporary location on your workstation.
For example C:\temp\CloudEnablingCICS_Chapter4_Platform_ApplicationV1.0.0.zip

In CICS Explorer, right click in the Project Explorer view and select Import....

In the Import wizard select General → Existing Projects into Workspace, click Next >

Choose Select archive file: and click on the Browse... button next to it.

Locate the zip file in the temporary location that you downloaded in step 1. The project contents of the zip file will display in the Import wizard. Ensure they are all selected (see later instructions in this blog if clashes are found).

Your workspace will contain the projects as created in the relevant chapter of the IBM Redbooks publication "Cloud Enabling CICS".

Customizing the imported projects

The CICS Explorer projects from CICS application version 1.0.2 and upwards (after chapter 5) require customization due to the LIBRARY resource datasets.

Perform the following steps to customise the dataset locations:

Import the required projects into CICS Explorer.

Expand the project general.insurance.customer.applicationservices.to.dev.bundle and double-click on the file GENAAPSV.library to edit the LIBRARY definition resource.

Edit the high level qualifier in the GENAAPSV LIBRARY editor. You should change USERHLQ to the user ID used in your GenApp installation as described in the IBM Redbooks publication.

What to do if you get clashes during the import of projects

Importing the projects assumes that they do not already exist in the CICS Explorer workspace. If you do have existing projects then you may get clashes during the import , such as shown below:

You can prevent import clashes by either creating a new workspace before importing the projects, or deleting the existing projects. If you opt to delete the existing projects, then ensure you also delete them from disk in the Delete Resources dialog as shown below:

So does this mean that when I use CICS Cloud resources within my organisation, I need to share and import ZIP files with my colleagues?

No. This articles is using archive files as a simplification for sharing projects with others. For an explanation of how to share CICS Explorer projects within your organisation and incorporating your Source Code Management (SCM), refer to the CICSdev blog CICS Explorer and Source Control.

It's a well documented fact that the earlier a bug is discovered the easier it is to fix. One of the challenges of writing applications to run in CICS is that you have to have a region available for running the applications in. If this is then shared with other developers you can run into issues as only one remote debugger can be attached to a JVM server at any one time.

A potential solution is to write automated unit tests that run inside the development environment, but before we can do that we need to be able to use the JCICS APIs outside of a CICS region.

The easiest way to do this is to using a Mock Object framework which allows us to stub out Objects and control the behaviour of methods on those objects. In the following examples we make use of the Mockito and PowerMock frameworks.

For the example we are going to be using a very simple CICS program which links to another CICS program and returns the result of that link in the COMMAREA. The code is as follows:

The first annotation on the class definition tells JUnit that we want to use the PowerMockRunner class to run the tests rather than the standard JUnit TestRunner class. The second tells the PowerMock framework that we will be inserting mock objects into the MockDPL class.

The test then performs the following steps:

Create a mock object version of the Program class.

Tell PowerMock to return this mock object whenever a call to the no-arguments constructor is made.

Create a mock object version of the CommAreaHolder class.

Configure the mock object so return a specific byte array when the getValue() method is called. This is to simulate the COMMAREA that would be returned by the linked program.

Call the JCICS program, passing in the mocked CommAreaHolder.

Finally test that the value in the CommAreaHolder matches what is expected.

This test covers our expected path when everything works correctly and there are no issues when running the target CICS program. However given that there are a number of Exceptions that can be thrown by the link method, and we have specific processing in the catch block we should test that code path as well.

In this test we perform the same steps to create the Program mock object and inject it into the runtime. However this time when the link method is called with any byte array then an InvalidProgramIdException will be thrown. We can then check that the correct error is returned in the COMMAREA.

Using these techniques, of inserting mock objects into the existing program and then controlling their behaviour to drive the various code paths allows us to prove the correctness of the code (according to the specifications) before we deploy it to the test regions.

Do you have Java applications running in pooled JVM? Are you considering the upgrade to CICS TS V5? If so then this article should help to smooth the migration of those applications.

The introduction of JVM server in CIC TS V4.2 offers a number of advantages over the existing pooled JVM implementation. The multi-threaded industry standard environment allows a single JVM within a CICS region to host all Java workload previously handled by a pool as well as the opportunity to consolidate multiple application regions. The OSGi framework brings further advantages including the ability to add, update or remove an application from a JVM without having to restart it.

Moving to this more scalable and dynamic environment does require a few changes including repackaging you application. We strongly recommend doing the migration on V4.2 before upgrading to V5 where pooled JVM is not supported (if you have V4.1 where JVM server is not available then consider using the CICS Developer Trial). The checklist we have put together will link you to the documentation you need as well as the experience gained by other customers.

Repackaging your application as OSGi bundles. The Eclipse Plug-in Development Environment (PDE), which is used for developing OSGi applications, offers several different approaches for converting either an existing binary JAR file into an OSGi bundle or converting source code projects. See 10.4 “Converting from a JVM pool to a JVM server” in CICS and the JVM server Developing and Deploying Java applications.

Check for 3rd party frameworks. Some frameworks and libraries such as Spring and Log4j make use of dynamic class loading. An application that worked in pooled JVM may not in JVM server. We have recently released APAR PI25045 to assist with migration of applications to the OSGi environment and an upcoming article on this blog will report on our experience.

Deploy your application to the JVM server. The CICS Explorer greatly simplifies this process but you will need to validate whether you have configured all the necessary application dependencies in the JVM server profile. See 3.1.4 “JVM server profile for user applications” in CICS and the JVM server Developing and Deploying Java applications. If you have chosen either the “injection” or the “conversion” packaging method you can also re-deploy your application to pooled JVM to verify that any changes you have made don’t affect execution.

Part 3 – Managing your application

Automating deployment. The steps in Parts 1 & 2 all use CICS Explorer to deploy the application. CICS offers a number of APIs to help you automate the process. We have recently released APAR PI24367 to assist with updating a Java application in production, and this CICSdev article explains how you can use this to automate the phasein of a Java application into a running JVM server.

This checklist will evolve as we learn more from you. Please also look at for follow-up articles on this blog covering some of the steps in more detail. For more information about JVM server and OSGi please see the following

Have you been wondering where to get started with CICS applications, platforms and policy? Are you unsure whether the CICS cloud enablement capability in CICS TS V5 applies to your applications or environment? The recently released Cloud Enabling CICS redbook takes an existing 3270-COBOL-VSAM application and describes how to exploit these features including a fully worked example of how to use multi-versioning to safely and reliably apply and back-out application changes without service interruption. It also shows you how CICS cloud enablement builds on operational facilities including monitoring, events, transaction tracking, CICS Bundles, and CICSPlex® System Manager to integrate with your existing deployment and management processes. Download a copy right now and get started with cloud enabling your CICS.

One of the advantages of using the latest version of CICS TG to provide mobile enablement of CICS programs is that we are not limited to using CICS Transaction Server, we can use any of the CICS family of transaction servers that are supported by CICS TG.

In this post I show how to create a RESTful API for customer data using the mobile support introduced in CICS TG V9.1, to invoke transactions on TXSeries. With this API a user can add, retrieve, update or delete a single customer record as well as getting a list of all the customer IDs in the system.

Topology

For development purposes I installed TXSeries 8.1 and CICS TG 9.1 on a Linux on Intel machine and configured an IPIC connection between them. IPIC was used because the CICS program called by the RESTful API has to use a Channel for passing information. Even though the program was written for, and tested in TXSeries the function would work in CICS Transaction Server with no changes.

Defining the RESTful API

The API being defined allows for full control of each of the customer records. The first part of the URI, customers/, will allow have the following actions:

Verb

Action

GET

Return an array of customer URIs

POST

Add a new customer

A customer ID can then be added to the URI to interact with that customer record, for example record 0000000001 would be accessed using the URI customers/0000000001. The mapping from HTTP verb to action is shown below:

Verb

Action

GET

Retrieve the customer record

DELETE

Delete the customer record

PUT

Update the customer record, or create it if it doesn't exist

POST

Not supported for an individual record

Creating the web services bindfile

To build a RESTful API we start with the structure of the customer data that will be passed back and forth and describe this with a JSON schema file

Once the structure of the data is defined I used the CICS TG Web Services Assistant to generate the language structure header for the back end program and the bind file. The following properties are stored in a properties file:

It is worth noting that when creating the bindfile for the RESTful service I only need to specify a single schema and LS parameter as the same data structure is used for input and output. The other key parameters are; TARGET-CICS-PLATFORM which tells the assistant that the CICS program supporting this web service will be running on TXSeries on Linux on Intel, MAPPING-MODE which must be set to JS2LS and LS-RESTFUL which specifies the name of the header file to create, which is then imported into the application.

The properties file is then passed to the ctgassist utility which parses the input and then produces the output header file and web services bind file.

Adding the web service to CICS TG

Having created the bind file the web service definition needs to be added to the CICS TG configuration file. The following section is added to the configuration file:

The uri parameter is worth noting that as it ends in an * which allows for the customer ids to be added to the end of the URI as required by our REST API. The rest of the parameters are standard, specifying the location of the bindfile and the name of the server to send the requests to.

In order to have the Gateway daemon process HTTP requests the following configuration is added to the SECTION GATEWAY part of the configuration file:

SUBSECTION HTTP
port=2080
ENDSUBSECTION

Writing the CICS Program

The CICS program needs to take the following steps during it's execution:

Check which HTTP verb the web service was called with

Perform the required action upon the data

The header file created by the CICS TG web services assistant is included in this program as the contents will be needed when it comes to process data received from and sent to the clients.

Which HTTP verb?

The HTTP verb is passed in a container named DFHHTTPMETHOD so by getting this container with an EXEC CICS GET CONTAINER('DFHHTTPMETHOD') I can compare it against the expected verb names; GET, POST, PUT, DELETE and react accordingly.

Which customer record?

If a customer record number is specified in the URI then it is stored in the DFHWS-URI-RESID container which we can then use to access a specific record.

Working with customer data

Any customer data sent to the program via a PUT or POST request is stored in the DFHWS-DATA container. The contents of this map directly onto the structure created by the assistant, so after performing an EXEC CICS GET CONTAINER the program the information supplied by the client is available to the CICS program. Alternatively when the program needs to send back a customer record, a completed struct can be put into the container for sending back to the client.

Sending a GET request to the /customers/ URI is required to behave differently to all other requests due to the rules of REST APIs. Instead of returning a single customer record the program needs to return an array of all the URIs that are available. As this is a different data structure to the one that is processed by the bindfile transformation the program needs to build the JSON data itself and then have it returned to the client. It does this by putting the response into a container called DFHRESPONSE instead of using the DFHWS-DATA container.

Returning an error

If the CICS program were to end in an error condition then that abend information will be sent back to the client in an error response, but that requires the client to parse the response to find the abend code and parse it. A more RESTful approach is to return a relevant HTTP return code which is more easily understood by the client.

To do this the program can put the return code into a container named DFHHTTPSTATUS with the following format:

HTTP/1.1 nnn text

Where nnn is the return code number and text is the description of the return code. So for the case when a customer id is specified for a record that doesn't exist the program puts the following string into the container:

HTTP/1.1 404 Not Found

Putting it all together

With the CICS program installed into the TXSeries server and everything up and running testing the API is as simple as getting hold of a REST client and sending the relevant HTTP verbs to the URI to either retrieve or update some existing customer records, or create some new records.

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.

Thanks to everyone who came to my Wednesday session “Managing Multi-version Applications in CICS” in Pittsburgh and especially to those who spent the time providing an evaluation. It was a really interactive session and the feedback helps the project plan what we should do at future meetings. As well as comments there were some questions that I have answered below for the benefit of the SHARE attendees and anyone else interesting in the application multi-versioning capability in CICS TS V5.2.

Answer: To use application multi-versioning with COBOL you need to declare one or more entry points using either a PROGRAM or a URIMAP. That first program must be called with an EXEC CICS LINK so we can set up the application context but all the rest of the programs in you application can continue to use COBOL dynamic calls.

Question 2: There was some confusion between programs and tran codes that invoke those programs. It is entirely possible to not only have duplicate program names, but to also have duplicate transaction codes.

Answer: In V5.2 we only support private LIBRARY, POLICY and PROGRAM resources. We know that TRANSCATION, FILE and other resources are important as well as application-specific DB2 access and as always appreciate help prioritizing what we should do next. Please visit the CICS Request for Enhancement (RFE) page where I have just created a new “Cloud Enablement” group.

Question 3:Hope you are able to implement an easier way to detect AMODE 31 load modules so as to set DATALOCATION=ANY in program autoinstall.

CICS Transaction Server V5.1 introduced the capability to combine and manage multiple disparate application resources as a single entity, which can be versioned and moved rapidly through the development, test, and production lifecycle. Dependency management is handled, and you can measure entire applications for resource use and internal billing. You can also dynamically manage applications by applying policies during run time.

CICS Transaction Server V5.2 builds on this functionality by introducing the concept of application multi-versioning. While user requests are being routed to the old version, a new version of the application can be installed. Once the new version of the application has been confirmed as being properly ENABLED, i.e. all dependencies satisfied, resources enabled and entry points declared across all the regions on the platform; then user requests can be routed to the new version by changing the state of the application to AVAILABLE.

For more information on the lifecycle around applications, check out Matthew Webster's blog articles on the topic:

Making an Application AVAILABLE

To move an enabled application into the AVAILABLE state, open up the Cloud Explorer view in the CICS Explorer application and use the GUI menu options to "Make Available" the installed application resource. For more information on the procedure used, see the "Working With Applications" section in the IBM Knowledge Center:

Note there's a tip in the Knowledge Center which states the following:

Tip: The availability status of a CICS bundle is not restored if you start or restart a CICS region in the platform after the time when you make available the CICS bundle, or the application containing it. When you have verified that the application has been installed and enabled correctly in the started or restarted CICS region, select the appropriate version and make it available in the CICS region.

This can pose a problem in automated environments where a human operator may not be present to manually make applications available when a CICS region restarts. Fortunately we can use the CPSM API to perform the same task by running a simple CICS program - a task which is easily automated.

Sample COBOL Program

We are exploiting CICS TS V5.2 functionality in this program, so the application should be compiled using CICS TS V5.2 libraries. The program runs within the CICS environment and if you are using the integrated translator, should have the CICS('CPSM') option enabled in the compiler, with your SEYUCOB dataset defined in the SYSLIB concat.

To linkedit, you should include both SDFHLOAD and SEYULOAD datasets in the SYSLIB concat, with the following SYSLIN definitions in place:

ORDER DFHELII
INCLUDE SYSLIB(DFHELII)
INCLUDE SYSLIB(EYU9AMSI)
INCLUDE OBJLIB(APPLACTV)
MODE AMODE(31) RMODE(ANY)
ENTRY APPLACTV
NAME APPLACTV(R)

The resulting program should then be made available to CICS in the DFHRPL concat, or a separate library, and appropriate transaction and program resources defined. The APPLACTV program is only required to be defined in one region within the CICSplex.

The example COBOL program has the following logic:

Establish a connection to CPSM

Query CPSM to provide a result set containing all applications installed in the CICSplex

Fetch each of the applications in turn, and perform the SET AVAILABLE action on them

Prior to running the application, we have the following display in the CICS Explorer:

Note that we have three applications installed and ENABLED, but are all in the UNAVAILABLE state.

Now we can run the sample application, which produces the following output:

After the program has completed execution, we can refresh the view in Explorer, to find the applications are all now AVAILABLE:

During CICS initialization, bundles are installed after the majority of the startup processing takes place: this means that we cannot add our program to the PLT (either first phase or second phase) as a simple solution.

As an alternative, if we define a transaction which runs the application, and the appropriate CICS console definitions, then we can invoke the transaction from an MVS console using your standard automation techniques. For example, we could define the CICS transaction APPL which will run the program APPLACTV. By issuing the MVS command:

/MODIFY CICSJOB,APPL

we can then execute the program, and hence automate the processing from start to finish.

For simplicity, in the sample code all of the applications installed in the CICSplex are queried, and the SET AVAILABLE action is performed on them without any checking. In a more robust application, you may wish to extend the processing to:

filter the applications to limit the scope of the operation

verify each application is fully enabled before attempting to make the application available

provide some wait and retry logic to cope with a CICS region which takes longer to start than expected

Summary

The CICS Explorer provides a high-level, easy-to-use environment for the administration of CICS and cloud applications. Using a very small amount of application code, we have seen how we can programmatically make a set of applications available and open for business in situations where use of the Explorer is not appropriate.

This programmatic interface can be invoked as a CICS transaction from an MVS console, and therefore allows for CICS applications to be made AVAILABLE in a completely automated way, as part of your regular CICS region startup processing.

If a customer finds a bug in your application, wouldn't it be great if you could build, test and deploy a fix in hours or days, rather than in weeks or months? Reducing turn-around time and aiming for continuous delivery allows your organization to constantly improve and evolve the applications and services provided to customers. There's no reason why your CICS-based applications and services shouldn't be included in the continuous delivery model.

Continuous integration and CICS

Let's say you have two teams, one team that maintains your CICS applications and infrastructure, and another team that develops the front-end applications which call into CICS. Wouldn't it be great if the front-end application developers could make code changes and test them in isolation, without actually calling into CICS and incurring MIPs? Wouldn't it also be great if your CICS developers and admins could quickly test any changes to verify that they won't break your front-end applications?

With CICS Transaction Gateway V9.1 and Rational Integration Tester V8.6, it is easier than ever before to allow the front-end application and CICS teams to operate more independently. Increasing the autonomy of the two areas of your organization allows you to reduce the turn-around time for application and CICS changes, and reduce cost by removing the unnecessary CICS workload incurred through front-end application testing.

Rational Integration Tester (RIT) is part of Rational Test Workbench and facilitates the testing of both CICS-side applications and client-side Java and JCA applications in isolation.

How does it work?

Using the request monitoring capabilities in CICS Transaction Gateway, Rational Integration Tester records the interactions between the front-end applications and the back-end CICS server. A developer configures CICS TG to enable recording, then exercises all the necessary function of the front-end application. As the developer does so, Rational Integration Tester records all of the request and response data passing between the application and the CICS server. These recorded interactions can then be used to generate test cases and stubs.

Testing CICS changes without the front-end application

The recorded interactions can be quickly and easily used to create test cases within Rational Integration Tester, for testing the behaviour of CICS directly from RIT through CICS TG. After making changes to the CICS system, the system programmer can run the applicable test cases to verify that the changes will not affect existing front-end applications.

RIT also allows test cases to be constructed from scratch rather than from recorded interactions. This allows new CICS capabilities to be tested before a client application has been created to drive them.

Testers can adjust the validation performed by each test case to cater for expected variations in the response data. For example, if the response will contain variable data such as a time stamp, the test case validation rules can be adjusted to match against a pattern, or to not validate a particular part of the response.

Testing front-end application changes without calling CICS

Recorded interactions can also be used to create stubs, for testing front-end Java and JCA applications without making calls into CICS and incurring the cost of additional MIPs. After making changes to the application, the developer can quickly test that the application behaves as expected by using a stub to replace the actual CICS infrastructure.

As with test cases, RIT allows stubs to be created from scratch rather than from recorded interactions. This allows new Java and JCA applications to be tested before the back-end CICS infrastructure is in place.

IBM Rational Test Workbench

Rational Integration Tester is part of the Rational Test Workbench suite of testing tools, which also includes Rational Functional Tester for user interface testing, and Rational Performance Tester for performance and scalability testing. The workbench also includes Rational Test Control Panel, which can be used to manage RIT stubs and test cases, and display test execution results from multiple instances of RIT.

RIT can be configured to write its results to a central database, and the results can then be viewed in Rational Test Control Panel. This allows a test coordinator to oversee test execution and prevent changes that will affect your customers from being promoted into the production environment.

Conclusion

With Rational Integration Tester V8.6 and CICS Transaction Gateway V9.1, it is easier than ever before to adopt a continuous delivery model for your CICS-based applications and services. RIT and CICS TG can remove testing bottlenecks and reduce the workload on CICS generated through testing. By allowing the CICS and front-end development teams to operate independently, your organization can deliver new function more quickly and cheaply without compromising on quality.

In our recent blog post about the new mobile support in CICS Transaction Gateway (CICS TG) we discussed how easy it was to create a new application to access existing CICS resources. In this blog post I'll show you how I put together a sample application which makes use of the programs and data provided by the the GENAPP support pac.

The architecture of the completed solution looks like

Setting up CICS TG

Configuring the Gateway daemon for http requests

To allow the Gateway daemon to receive and process http requests I added the following configuration to the SECTION GATEWAY part of the configuration file:

SUBSECTION HTTP
port=26682
ENDSUBSECTION

This tells the Gateway daemon that I want it to listen for http requests on port 26682. To check this configuration is correct, the following log message is output during the Gateway daemon initialization.

Creating the JSON web services

The application makes use of two web services, one to get a list of all the customers and the other to get all the details for a particular customer.

Create the web service bind files

The critical piece of configuration for each web service is the web services bind (WSBind) file. This file contains the information required to perform the transformation between a JSON object and a CICS application payload that can be passed to the CICS program.

To generate the bind files I made use of the web services assistant shipped with CICS TG which can generate a bind file from either the language structure definition of the data as the CICS program uses it or from a json schema describing the data as the web service client provides it.

The CICS program for retrieving a customer's details already existed so the bind file was generated from the COBOL source describing the COMMAREA structure. The parameters passed to the assistant for this were:

As well as the bind file this operation produces two json schema files which describe the JSON objects passed to and from this web service. This information is then used by the mobile application to ensure the call to the web service is correct.

Unfortunately there was no existing program to retrieve all the customers in the customer database so a new program had to be created. As this would be a brand new program I could start from the mobile application and decide how the information should be passed back and forth. To start I created a JSON schema to describe how the data would be formatted:

which produced the bind file and the language structure elements. Prefering to code in C rather than COBOL, I chose to produce C header files to describe the data format in the new program.

Configure the CICS Transaction Gateway

Once the WSBind files had been created I needed to configure the Gateway daemon to make the web services available. Each web service requires a new section in the configuration file, so for the demo the configuration file contains the following:

Building the mobile application

In order to easily build a mobile application that could be deployed on a variety of platforms I decided to make use of IBM Worklight to build the application as this provides an easy way to do this. There are two parts to the application, a Worklight adapter and the program to run on the mobile device.

Creating the Worklight Adapter

The Worklight adapter provides the link between the mobile application and the CICS TG. In it I configured the hostname and port where the CICS TG is, the port number matches the value configured in SECTION HTTP.

I then created two procedures, one for each of the web services that will be called by the application. The general outline of these procedures is to create the request JSON object, call the web service and return the result of the call. To get all the customers the procedure looks like:

The input object describes how the web service is invoked and the the results of invoking the web service are returned back to the caller of this function. This allows me to abstract away the full payload that needs to be sent to the webservice and send the response back to the mobile application.

Creating the Worklight Application

The mobile application itself is a hybrid application written in HTML5 and JavaScript as this allows for the same application to be deployed to a variety of mobile devices without the need to write specific applications for each mobile platform.

To call the procedures in the Worklight Adapter I use the client API provided by Worklight as in the following code snippet

The invocationData object contains the name of the Adapter that contains the procedure to call and the name of that procedure. This object is then passed to the invokeProcedure function along with the callback functions which will be called depending on whether the procedure call succeeds or fails.

To interact with the mobile device I make use of the Cordova plug-ins to access the camera and other applications on the device. In order to get a picture from the camera the following code snippet was used to open the camera, and then add the resulting picture to the page.

Conclusion

Through the creation of some new configuration pieces in the CICS TG and making use of the easy application design functionality provided by IBM Worklight I produced a professional looking application quickly and easily which leverages information stored in a back-end CICS TS system without any changes to the CICS server.

One of the frequent questions we receive from customers is "How can I customize the CICS Explorer GUI, for instance by removing items that confuse my internal users?"

While removing GUI items is not something we provide support for, because CICS Explorer is built on top of Eclipse technology there is an Eclipse technique you can use to hide some elements of the GUI.

In this blog post I'll walk you through some using an activity to hide a GUI item, techniques for establishing whether a GUI item might be hideable, and how to deploy this into a CICS Explorer instance.

Secondly - as part of this technique you'll be looking up internal action IDs for actions provided by CICS Explorer (and maybe Eclipse too!). These IDs might change in future releases. You'll want to incorporate a quick test that things have remained hidden, as part of your CICS Explorer acceptance tests.

What we'll be doing

The broad overview is like this.

We'll find the action ID of an action that is being contributed to the CICS Explorer GUI

We'll create a new plugin that declares an activity. This activity will refer to the action ID and hide it

We'll create a feature to contain the new plugin, and deploy it into a CICS Explorer instance

Finding action IDs

It's not possible to hide every GUI element - it depends how they were contributed. Most of the context menus on CICS resources should be possible, though. I'll go through the example of the Region shutdown options.

Finding IDs through the GUI

The simplest way of finding the action ID is using a tool called plugin spy. It's part of Eclipse and included with CICS Explorer by default. Open CICS Explorer, connect to a plex and open the Regions view.

To use plugin spy, press Alt+Shift+F2 - you'll see the cursor change to an icon of a document with a magnifying glass. The next time you click on a menu, a window will pop up giving you information about that menu option.

So - you have the Regions view open. Press Alt+Shift+F2 (you'll see the cursor change to a document with a magnifying glass) and right-click on a Region in the Regions view, choose Shutdown and Normal.

Next you'll see the Plugin spy window pop up.

This gives you some information about the selection. We're interested in the action ID - com.ibm.cics.core.ui.editors.region.shutdown.normal. This is the action ID that we need, to prevent the normal shutdown option from appearing on a Region resource.

Finding IDs from the plugin files

Most of the CICS Explorer context menus on resources are currently (CICS Explorer 5.2!) declared in an XML file. In your CICS Explorer installations, find the plugins directory and look for the com.ibm.cics.core.ui.editors jar file. In it, open the plugin.xml file. If you search for "com.ibm.cics.core.ui.editors.region.shutdown.normal" you'll see how we declare the normal shutdown option, and adjacent are the other shutdown options, so we have:

com.ibm.cics.core.ui.editors.region.shutdown.normal

com.ibm.cics.core.ui.editors.region.shutdown.immediate

com.ibm.cics.core.ui.editors.region.shutdown.takeover

Creating an activity to hide some actions

To create an activity, we must create a plug-in project. A plug-in project can be installed into an Eclipse application like CICS Explorer and contributes to its behaviour at runtime. CICS Explorer itself is just a collection of plug-in projects!

Create a plug-in project using File > New > Other... - "Plug-in Project" will be near the top of the list. Choose Next and give the project a name - perhaps "FilterMenus".

Click Next through to the Templates page. Choose the template "Plug-in with a popup menu" and Finish. Answer yes when you're prompted to switch to the plug-in perspective.

From the Package Explorer, the view on the far left, double-click on plugin.xml to open the plugin metadata editor. Choose the plugin.xml tab (near the far right)

Replace the text in this editor with the following, and save the editor:

Testing that our new plug-in works

It's always good to test some code once you've written it! Right-click on the plug-in you created in the Package Explorer

Choose Run As > Eclipse Application. This will start up a *new* copy of CICS Explorer with your plug-in installed, for testing. Make a connection, find the Regions view, and check that Shutdown no longer appears in the context menu.

Hurrah!

Deploying the plug-in to our users

The final step is to package the plug-in so that other users can install it into their CICS Explorer instances. To do this you must create a feature containing the plug-in, and export. Have a look at the previous "Extending CICS Explorer" blog post for a full description, in the section "Deploying the new perspective to our users".

It's been a busy 18 months for the IBM CICS and Problem Determination Tools development teams, keeping pace with the latest and greatest in CICS TS for z/OS V5.2 and adding lots of new capabilities as well. New releases of five core CICS Tools plus an updated Solution Pack, together with enabling PTFs (where required) for PD Tools will help you to maximize the benefits from the latest run-time release. Don't worry if you are running an earlier release of CICS - most of the new capabilities will help you too.

Here's a brief summary of the updated CICS Tools - you'll find more information in the announcement letter here.

CICS Configuration Manager for z/OS, V5.2 (CICS CM). New support for CICSPlex SM Topology and Workload Management definitions allows mobile workloads to be quickly reconfigured. New plug-in support for Migration Schemes and Deployment Analysis.

The CICS Transaction Gateway for z/OS V9.1 open beta includes new capabilities enabling HTTP clients to invoke COMMAREA or Channel-based CICS programs using JSON data, while benefiting from the established high availability and instrumentation features which CICS Transaction Gateway customers already rely upon.

Based upon the WS BIND data transformation technology and tooling already used for CICS Transaction Server web services, the proven reliability and scalability of CICS TG delivers further options for robust integration of JSON web services with CICS Transaction Server. Compatibility with z/OS Connect also means that investment in the creation of WS BIND files for JSON data transformation is reusable, allowing the transfer of these assets between z/OS Connect-compatible solutions.

Using JCA with the CICS TG in WebSphere Liberty Profile

The April betas of the WebSphere Liberty Profile provide an optional feature which enables support for the Java Connector Architecture (JCA) part of the Java Enterprise Edition (JEE) specification. As this has been one of the primary methods for connecting to CICS with the CICS TG, it made sense for me to check not only that it works in Liberty, but also how to make use of the CICS TG resource adapters from applications in a remote mode topology.

Getting the beta

Head over to http://wasdev.net and grab the latest Liberty profile beta of the runtime and extensions jar file, and follow the instructions for installing it. While there, it is worth getting the Eclipse tooling as this will help with developing the application and configuring the Liberty server.

Configure the resource adapter

To configure the resource adapter I grabbed a copy of the cicseci.rar from my CICS TG install (or alternatively you can use the CC03 SupportPac) and stored it in a directory on my local machine. I then added the following section to my server.xml file:

This makes the resource adapter available to the Liberty profile server and allows us to add the rest of the Liberty profile configuration options. The value of the id property should be set to something meaningful as we'll be using it through the rest of the Liberty configuration.

Create a ConnectionFactory

Now that the resource adapter is available within the Liberty profile server, the next step is to create a ConnectionFactory which is used in our application to connect to the Gateway daemon and invoke the backend CICS programs. The entry in server.xml looks like:

The properties.eciResourceAdapter element is mandatory and allows for the setting of the custom properties on the ConnectionFactory. In this case I'm connecting to a Gateway daemon running on the same system and listening on port 2006. The properties name, eciResourceAdapter, must match the id set in the resourceAdapter entry. The jndiName property is set to a meaningful value which is used in the application later to reference the ConnectionFactory.

Building the application

I created a servlet application to connect to the CICS TG, call the CICS application and display the results in the browser. The main function requires getting a reference to the ConnectionFactory, requesting a Connection from it and then executing an Interaction against it. Rather than doing a JNDI lookup from an InitialContext to find the ConnectionFactory we must use the new dependency injection framework to have the ConnectionFactory object passed to it. This means in my servlet I create an instance variable with a @Resource annotation.

@Resource(lookup="eis/ECI")
private ConnectionFactory cf = null;

The value of the lookup parameter needs to exactly match the value of the jndiName parameter in the connectionFactory definition created earlier. The rest of the code then uses the standard JCA API calls:

Deploying the application

The application is deployed as a standard WAR file but some extra configuration is required in order to avoid NoClassDefFound or ClassNotFound exceptions. This is because the application relies on classes supplied in the resource adapter file, ECIInteractionSpec being the main one. In order for the application to use these classes a classloader definition is added to the webApplication definition in server.xml:

The value for classProviderRef matches the id specified for the resourceAdapter and with that we can deploy the application and once it's run the date and time of the CICS server are retrieved and displayed in the browser.

Many of us have used CICS Explorer to manage CICS. But did you know that you can use the underlying CICS Management Client Interface (CMCI) from your browser (or any other HTTP client)? The CMCI request structure consists of

an HTTP header with a method (GET, PUT, POST, DELETE)

followed by a URI (Universal Resource Identifier) and

an optional XML body containing details of any changes to be made to CICS or CICSPlex SM resources

To try out the examples you need to know the hostname (called yourHostName in this article) and the CMCI port (called yourCMCIPort) that you use to connect CICS Explorer to your system.

In this part you will only use your browser to send GET requests - we will cover PUT, POST and DELETE in another article.

Send your first Request

As a first example, try the following URL from your browser to return all installed Files in a specific CICS region:

Congratulations! You just performed your first HTTP GET request.
You will see all your local Files currently installed in that region. In my example there are 19 Files in that region (the recordcount is 19) from which 10 are displayed (displayed_recordcount).I strongly recommend you always limit the number of results when you try out the following examples.

How to construct the GET URI

So how do you construct this URI to retrieve different resources?
The URI includes

the External Resource Name of a CICS resource

and specifies a series of parameters to

refine the scope and nature of the query

identify one or more instances of the specified resource by name or other filter criteria

I already introduced you to the count parameter when you issued your very first request and limited the results to 10. Let's have a look at the other parameters.

Select the resource type

In the previous example you requested a CICSLocalFile.
The CICSPlex SM resource table architecture has been extended to allow it to work with the CMCI’s RESTful approach:
There is a new external resource name section for each resource type (V5.1 | V4.2) for example

External resource name

CICSPlex SM resource name

Description

CICSLocalTransaction

LOCTRAN

CICS local transaction

CICSRemoteTransaction

REMTRAN

Remote transaction

CICSDefinitionTransaction

TRANDEF

Transaction definition

CICSLocalFile

LOCFILE

CICS local file

Set the context and scope

If you use CMCI in a CICSPlex SM environment, the context is the name of the CICSplex or CMAS associated with the request, in my example HEROPLEX.
If CMCI is installed as a single server, context is the application ID of the CICS region associated with the request.
With the scope you can further refine your request, for example to focus on a specific CICS region or SYSGROUP in your CICSPlex.
The values of scope and context must not contain spaces and are not case-sensitive. So to retrieve your list of Files you could use

Use parameter strings to specify a CSD

Now is a good time to look at resource definitions because we need parameters there to specify the CSD. If you look at the file definition resource table you will see parameters that can be specified.

The following example filters for FILEA in group DFH$FILA

cache parameters

During your requests you probably returned large amounts of data. Therefore you are probably interested in how you can limit the number of results and cache the rest to retrieve them in chunks. The URI syntax for a GET request contains more options that will help you:

Note that the limitation to 10 is ignored. SUMMONLY will return the number of records matching your request and together with NODISCARD give you a cachetoken representing your request. You can now use the returned cachetoken to step through your results.

My following example returns the 9th until the 13th element of my result set. Always specify NODISCARD to ensure your results will not be deleted by CICS.

Summary

Congratulation! You used your browser to query installed resources from CICS as well as resource definitions from the CSD. And using the caching mechanism you can even break down the results into chunks.

And this was only what the GET method offers you! Next time we will look at POST (create resources), PUT (installs & change resources) and DELETE. Happy Browsing!

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

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)

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.