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.
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,
A customer ID can then be added to the URI to interact with that customer record, for example 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;
The properties file is then passed to the
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
In order to have the Gateway daemon process HTTP requests the following configuration is added to the
Writing the CICS Program
The CICS program needs to take the following steps during it's execution:
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
Which customer record?
If a customer record number is specified in the URI then it is stored in the
Working with customer data
Any customer data sent to the program via a
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
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.
Question 1: Very interesting concept however in my organization COBOL calls are used not EXEC CICS LINKS.
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.
Answer: You cannot use the BLDL macro for load modules associated with private PROGRAM resources as the user exit does not identify which library and dataset or dataset is being used. However, RFE 24835 "Provide load module attributes at auto install time" may offer a more elegant solution.
For more information please see my previous articles on this blog starting with What is CICS Application Multi-versioning?, perhaps listen to my recent "CICS V5.2 - Multi-Versioning" podcast, and of course take a look at in the IBM Knowledge Center under Cloud enablement with platforms.
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:
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:
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:
Connecting to CPSM...
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:
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:
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.
You can find the source of the sample application here: https://www.ibm.com/developerworks/community/blogs/cicsdev/resource/Application_AVAILABLE_Sample_Code.zip
|Modified on by ijmitch|
This post is an iframe for the CICS Social Media Aggregator. The page is dynamic will update as new content arrives. The links and buttons are active so you can participate.
For a full page experience, visit https://www-304.ibm.com/social/aggregator/cics
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.
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.
More information on CICS Transaction Gateway V9.1 is available in the announcement letter.
More information about continuous delivery and DevOps is available at the IBM DevOps homepage.
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
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:
and then used the web services assistant to generate the high level language structures:
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:
The configuration options have the following affect
When the Gateway daemon is started the following log messages are written which shows that the web services have been successfully created:
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
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:
Creating the Worklight Application
To call the procedures in the Worklight Adapter I use the client API provided by Worklight as in the following code snippet
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.
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.
CICS provides different levels of tracing to assist with problem determination. Standard trace level 1 is the default setting for each component to be traced within CICS. The user can use CETR to specify what trace levels are set for each component of CICS. By default, INTTR, SYSTR and USERTR are set ON. This means the master system and user trace flags default to be set on, and internal tracing is active. STNTR defaults to 1, as do all the STNTRxx values. This means standard trace component tracing defaults to level 1 for all CICS trace components (a consequence of this is that by default a CICS system will incur the CPU usage to provide this level of internal CICS trace data).
There is a trade-off between the CPU cost in capturing trace data for problem determination, set against the ability to diagnose problems should they occur. Some customers elect to run with limited levels of tracing active on their system. While consciously choosing to use CICS trace does increase processing requirements, NOT using CICS tracing reduces the amount of problem determination information that is available for the CICS region.
It should be noted that CICS always performs exception tracing when it detects an exception condition, so a minimum of first failure data capture is provided regardless of your CICS trace setting. However, exception tracing is by its nature limited in what diagnostic data it can provide, and it is very hard to perform initial problem determination without CICS tracing being active and all components capturing their trace data, to identify the flow of system activity and events in chronological order leading up to a failure. For this reason it is recommended that the default settings of all CICS domains and components should be used when tracing is active, to assist with problem determination. This is standard trace level 1 tracing.
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.
A bit of information you need to know
Firstly - understanding when to hide an item is important. You'll know from Isabel's blog post about using CMCI (https://www.ibm.com/developerworks/community/blogs/cicsdev/entry/the_cmci_restful_api_part_1_talk_to_cics_using_the_browser?lang=en) that pretty much anything that can be done in CICS Explorer can also be done using a browser and a bit of searching. This means that hiding an item to prevent users from using it is not secure - if their user ID has sufficient permissions then they could just call CMCI directly. You must have your security, including RACF, set up correctly.
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.
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:
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:
<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="3.4"?> <plugin> <extension point="org.eclipse.ui.activities"> <category name="Filter actions category" id="actions.exclude.category" /> <categoryActivityBinding activityId="actions.exclude" categoryId="actions.exclude.category" /> <activity name="Exclude actions" description="Exclude actions" id="actions.exclude" /> <activityPatternBinding activityId="actions.exclude" pattern=".*/com\.ibm\.cics\.core\.ui\.editors\.region\.shutdown\..*"> </activityPatternBinding> </extension> </plugin>
This XML declares an extension to the Eclipse activities extension point. It defines a category and an activity, binds the activity to the category, and sets up an activityPatternBinding which contains a regular expression pattern defining the items to be excluded. You can find more information about activities, and how you might make refer to an ID without using a regular expression, in the Eclipse documentation (http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fworkbench_advext_activities.htm).
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.
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".
For more ideas or background, see the Eclipse infocenter I previously linked to: http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fworkbench_advext_activities.htm
Also, Lars Vogel has a more general description of activities than I provide in this blog post: http://blog.vogella.com/2009/07/13/eclipse-activities/
Thanks for reading!
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.
Here's a list of the PTFs needed for the PD and ICING Tools that support CICS TS. The APARs are all available - I'll update this post with the PTF and APAR numbers when I get them.
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.
For further detail regarding JSON web services, and what else is available in the CICS TG for z/OS V9.1 open beta, see the following summary deck:
.. and download the open beta to try today:
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.
An introduction to developing applications using Eclipse can be found here: https://www.ibmdw.net/wasdev/docs/developing-applications-wdt-liberty-profile/
Configure the resource adapter
To configure the resource adapter I grabbed a copy of the
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
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
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
The value of the lookup parameter needs to exactly match the value of the
Deploying the application
The application is deployed as a standard WAR file but some extra configuration is required in order to avoid
The value for
Phil_Wakelin 20000028VV Tags:  article howto mq eclipse jvm_server liberty 1 Comment 8,401 Views
This article describes how to deploy a Java application that uses the IBM MQ classes for Java into a CICS OSGi or Liberty JVM server
To follow the setup in this article you should already have performed the following:
You will require the following minimum software requirements:
The software levels used in this article are as follows:
About this task
The MQ Java classes can be used in a CICS Java application to get and put messages to queues, using the MQ connection that is maintained by CICS. To develop the Java application you will first need download the MQ JAR files to your workstation, and then add these to your Eclipse development environment. Then having developed your application, you will need to add your application to a CICS bundle project, export to zFS, and install it into the JVM server. The CICS JVM server environment must then be configured with the correct levels of the MQ Java and native libraries, and these much match the level of MQ libraries specified in the CICS STEPLIB.
The following 3 steps will need to be performed to configure your Eclipse environment and the CICS JVM server:
1. Download the MQ JAR files
To develop your Java application you will require access to the MQ Java classes, unless you have the MQ product installed on your workstation, these should be obtained from the MQC71 SupportPac, which entitles you to download the MQ V7.1 clients free of charge.
Having download and installed the SupportPac you will find the MQ JAR file com.ibm.mq.jar in the following directory
and the MQ OSGi bundle com.ibm.mq.osgi.java_7.1.0.n.jar in the following directory, where n is the maintenance level of MQ V7.1
See the following topic in the MQ information center for further details on the MQ classes for Java.
2. Configure the Eclipse IDE
The development environment, for Java programs that are developed for CICS, is the Eclipse Integrated Development Environment (IDE). Eclipse is an open development platform, produced by the Eclipse Foundation (www.eclipse.org), composed of extensible frameworks, tools, and run times for building, deploying, and managing software across the lifecycle. In this section, we assume you have already setup this environment and provide instructions on installing both the MQ Java libraries into this environment. For further details on installing the CICS Explorer SDK for developing CICS Java applications refer to the IBM Redbook, CICS and the JVM server: Developing and Deploying Java Applications, SG24-8038
There are 2 distinct types of Eclipse project you may be developing for use in CICS, either OSGi plugin projects if you are deploying into a OSGi JVM server, or web projects, if you are deploying servlet or restful web applications using a Liberty JVM server. The way you setup the Eclipse enviroment for each of these types of applications is as follows:
2.1 OSGi plugin project
An OSGi plugin project is used to create an OSGi bundle for deployment to an OSGi JVM server. To make the MQ Java classes available to an OSGi plugin project, you can either create a wrapper OSGi project, or add the bundles to the Target Platform. The usual way is to use the Eclipse Target Platform as this is the most flexible method.
To do this perform the following steps in Eclipse:
The OSGi environment will now have been updated to include both the MQ OSGi bundle and the CICS OSGi bundle required for development.
2.2 Web applications
There are 2 distinct ways of developing a Web application to run in a Liberty JVM server. You can either use either an OSGi application project (or EBA) or a dynamic Web project (or WAR).
2.2.1 OSGi application project
An OSGi application project is a superset of OSGi projects, such as Web enabled OSGi bundles (WABs) and OSGi bundles or fragments. The OSGi application project is deployed as an EBA archive, which has the distinct advantage that all the code in the referenced projects are visible to the deployed Web application. This means that code can be packaged as OSGi bundles and reused or shared between different Web applications in the same EBA.
To make the MQ Java classes available to an OSGi application project, you should use the same method as for an OSGi plugin project, and add the MQ OSGi bundle to the Target Platform. However, you should use the CICS TS V5.2 with Liberty and PHP Target platform to ensure the web development libraries are also included in the Target Platform.
2.2.2 Dynamic web project
If using a dynamic Web project, this will create a WAR file archive for deployment. This doesn't use the OSGi framework in Eclipse and so simply requires that the MQ JAR files are added to the project build path.
To update the project build path do as follows:
The build path of the project should now have all the correct interfaces for development of a web application using both CICS and MQ APIs.
3. Set up the CICS JVM server
MQ on z/OS supplies the JARs and native libraries (DLLs) in the /usr/lpp zFS filing system, and both of these must be added to the JVM server enviroment to use the MQ Java classes. On our system they could be found in the following zFS directory:
The native libraries should be added to the JVM server library path, so add the lib directory to the LIBPATH_SUFFIX option of the JVM server as follows. You should ensure that the version of these libraries is the same as the MQ version specified in the CICS STEPLIB datasets.
Next it is necessary to add the JAR libraries to the classpath of the JVM server. These can be found in the same location as a native libraries. How you configure the classpath depends on what type of Java application archive you are deploying, there are 3 possibilities as follows:
3.1. If deploying an OSGi bundle to an OSGi JVM server
Add the com.ibm.mq.osgi.java_7.1.0.n.jar OSGi bundle to the OSGi JVM server middleware bundles list using the OSGI_BUNDLES JVM server variable as follows:
3.2. If deploying a WAR to a Liberty JVM server
Add the MQ JARs to the Liberty global library, which will add them to the classpath for all non-OSGi web applications (such as WARs). The global library is available to all non-OSGI applications installed in a Liberty JVM server, and can be defined in the Liberty server.xml configuration file as follows:
<fileset id="mqjars" dir="/mqm/V7R1M0/java/lib" includes="*.jar"/>
Note these libraries can not be used by an Enterprise Bundle Archive (EBA) deployed into a Liberty JVM server, for further details refer to the WebSphere Application Server information center topic
3.3. If deploying an EBA to a Liberty JVM server
Add the com.ibm.mq.osgi.java_7.1.0.n.jar OSGi bundle to the Liberty shared bundle repository. The bundle repository is a set of OSGi bundles that are made available to all OSGi applications running in the Liberty JVM, and can be defined in the Liberty server.xml configuration file as follows:
<fileset id="mqosgilib" dir="/mqm/V7R1M0/java/lib/OSGi" includes="com.ibm.mq.osgi.java_7.1.0.n.jar"/>
Lastly restart your JVM server and deploy your Java application using a CICS bundle project.
IsabelArnold 060000AEQ2 Tags:  blog howto cmci http article restful cics_explorer 4 Comments 9,033 Views
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
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:
If you connect CICS Explorer to a CICSPlex
if you don't have a CICSPlex set up and connect CICS Explorer to a single CICS region
Congratulations! You just performed your first HTTP GET request.
How to construct the GET URI
So how do you construct this URI to retrieve different resources?
This is the URI syntax for a GET request
|--/--CICSSystemManagement--/--+-| resource parameters |-+------> '-| cache parameters |----' >--+--------------+--+------------+--+-------------+------------| '-NODISCARD--&-' '-ORDERBY--&-' '-SUMMONLY--&-'
We will first look at the resource parameters.
Your URI contains the following resource parameters.
|--resource_name--/--context--/--+-------+--+-----------+--?----> '-scope-' '-//--count-' >--+---------------------------------------+--------------------> '-CRITERIA=--escaped_criteria_string--&-' >--+--------------------------------------+---------------------| '-PARAMETER=--escaped_parameter_string-'
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.
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.
"But where do I specify my CSD?" you might ask. We will cover this later when we look at parameter strings. For now, let's look at installed resources only.
Define filter criteria strings
You already know where to find the resource name, let's have a look at the CRITERIA you can use to filter. They are attached to your URI in the following way
http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourCICSRegionName//10?CRITERIA=(yourAttribute1=yourValue1 AND|OR yourAttribute2=yourValue2 ...)
Use parameter strings to specify a CSD
So what to use parameters for? If you look at the resource table for local Files you will notice that for a GET request no parameters are available.
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.
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:
|--/--CICSSystemManagement--/--+-| resource parameters |-+------> '-| cache parameters |----' >--+--------------+--+------------+--+-------------+------------| '-NODISCARD--&-' '-ORDERBY--&-' '-SUMMONLY--&-' Cache parameters: |--CICSResultCache--/--cache_token--/--+-/--------+--+----------+--?--| '-index--/-' '-count--/-'
Go back to your very first example that queries all local Files and add ?NODISCARD&SUMMONLY, for example
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.
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!
Melita Saville 270005DUQB Tags:  manuals publications ibm-knowledge-center information-center cics documentation kc ibm knowledge-center information pdf 1 Comment 7,721 Views
IBM Knowledge Center will soon become the central location for online documentation about IBM products, replacing all the separate information centers. You do not need to take any action, links to the existing CICS information centers will be automatically redirected to IBM Knowledge Center from May onwards, but you will notice some changes in the look and function of the CICS online documentation.
You can find the IBM Knowledge Center here: www.ibm.com/support/knowledgecenter/.
Why are information centers changing?
What does IBM Knowledge Center offer?
Replacing all information centers is the first step. Over time, IBM Knowledge Center will become a fusion of technical content from IBM developerWorks, IBM Redbooks publications, and elsewhere. There will be a cust
What changes will CICS users see?
Find out more
Let us know what you think and if you have any questions by clicking on the Feedback button at the bottom of most pages within the IBM Knowledge Center
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:
2 - On Open Office Calc. Click on Tools -> XML Filter Settings...
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.
Matthew Webster 060000AMGC Tags:  cloud blog multi-versioning applications 3 Comments 8,284 Views
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:
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.
For more information please see “Making unavailable, disabling, and discarding applications” in the CICS Transaction Server 5.2.0 open beta Knowledge Center.
Mark Cocker 2000002GYC Tags:  web_services article java liberty blog jvm_server 3 Comments 8,768 Views
[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.
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.
Download the Web Services Sample
Deploy the web services sample in CICS
Start the web services sample in CICS
Update the sample to include some calls to the CICS Java API JCICS and redeploy
Call the web service using the Eclipse Web Services Explorer
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.