What you need to know about CICS

Programming for CICS is very similar to programming for any other environment, but there are some basic CICS facilities to understand and a few areas where programs for IBM Z behave differently to other platforms.

New to CICS? Introduction to CICS - an IBM Redbooks course shows you what it is and what it does.

Open a section below to get a brief summary and links to more information.

Introduction to CICS - an IBM Redbooks course

CICS facilities

CICS® services

Through its API, CICS provides services to an application: services such as data management, communications, and diagnostic services. A terminology point: CICS service managers usually have the word control in their title: for example, program control.

Find out more:
CICS resources

The resources that CICS or its applications use, such as files, programs and so on, act like metadata objects. First, you define the resources to a catalog. In CICS, the resource catalogs are VSAM data sets. Different data sets are used according to the method that you use to define the resources. One data set is called the CICS system definition data set (CSD), also known as the CICS system definition file (CSD), and it contains the resource definitions of any resource that is defined to CICS through the following methods: the CEDA transaction, CICS Explorer, the CSD update batch utility program DFHCSDUP, or CSD API commands. Another data set is called EYUDREP and it contains the resource definitions of any resource that is defined to CICS through CICSPlex SM Business Application Services (BAS).

At run time, you install an instance of the resource definition to work with it. When a resource definition is installed, information about the resource is used to construct the data structures that represent the resource in the CICS address space.

In Java, CICS resources are represented by instances of the appropriate Java class. To work with, for example, a CICS temporary storage queue (TSQ), you first create an instance of a TSQ object. Then, assign it a name that corresponds to the name of the TSQ that you want to use, and use its methods to manipulate the queue.

Resource names are shown in CICS documentation in capital letters: for example, a resource that defines a JVM server is called a JVMSERVER.

Find out more:
CICS bundles and bundle parts

A resource that you will use with Java programs is a CICS bundle. A CICS bundle is a packaging and deployment mechanism for CICS resources (see How it works: Java in CICS). It acts as a container for related resources that are grouped and managed together. CICS bundles can provide versioning for resource updates and can declare dependencies on other resources outside the bundle. The bundle is deployed to zFS. When you install (deploy) a bundle, CICS reads the manifest in the bundle directory and dynamically creates the CICS resources. CICS also checks that any required dependencies, for example programs or files outside the bundle, are present in the CICS region.

The resources inside a CICS bundle are called CICS bundle parts.

It's easy to confuse CICS bundles with OSGi bundles. OSGi bundles are components of the Java OSGi system. The OSGi CICS bundle part references an OSGi bundle and allows CICS to deploy that OSGi bundle into an OSGi JVM server when the CICS bundle is enabled. OSGi environments outside of CICS have no concept of CICS bundles, so OSGi bundles in the wild are generally deployed directly to the OSGi framework. The CICS approach offers benefits, though, such as the ability to control the lifecycle of both OSGi bundles and CICS resources within the same packaging mechanism.

As if that potential confusion wasn't enough, Liberty also has a containment mechanism for OSGi bundles, called an Enterprise Bundle Archive, or EBA. Importantly, though, EBAs aren’t just a way to deploy multiple OSGi bundles, but also a way to deploy sets of OSGi bundles as a single isolated subsystem (think of a mini OSGi container for each application). CICS steps up to the mark and provides an EBA CICS bundle part for deploying EBAs to CICS Liberty. Ultimately, your OSGi bundle sits inside an EBA, and your EBA sits inside a CICS bundle.

Find out more:
CICS transactions and units of work

In CICS, a transaction consists of an item of processing that can be run by one or more application programs. Transactions can be defined by users of CICS and are referred to as user transactions in CICS documentation. CICS also supplies transactions to control CICS operations, and these are called CICS transactions. Each transaction is identified by its transaction identifier (TRANSID). CICS transactions have transaction identifiers that start with C and are 4 characters long; for example, CEMT.

In many other IT contexts, a transaction describes a unit of recovery: typically, a complete operation that is recoverable. It can be committed or rolled back (backed out) as an entirety, as a result of a programmed command or a system failure. CICS calls this unit of recovery a unit of work. In many cases, the scope of a CICS transaction is also a single unit of work - but it doesn't have to be. Developers have flexibility to let CICS handle integrity at the CICS transaction scope or to use API calls explicitly to process units of work. There is no API to explicitly start a new unit of work. A new unit of work is considered active when the previous one ended. The end of a unit of work is called a syncpoint (synchronization point) so the command that is used in COBOL programs to commit all changes to recoverable resources since the last syncpoint is EXEC CICS SYNCPOINT.

In Java, you can use JCICS commit and rollback methods in the Task class to complete the current unit of work and update resources in line with that work.

Other resources:
CICS tasks and threads

When CICS receives a request to run a transaction, it starts a new task that is associated with this one instance of this type of transaction. You can think of it as analogous to a thread. CICS tasks run in parallel as threads in the same JVM server process. The JVM is shared by all CICS tasks, which might be running multiple applications concurrently. All static data and static classes are also shared. So, to use a JVM server in CICS, a Java application must be threadsafe.

A TCB (task control block) is a dispatchable unit of work in z/OS. The z/OS dispatcher dispatches TCBs. The CICS dispatcher dispatches CICS tasks to run on the TCBs. When CICS was first developed, all CICS tasks that ran user applications ran on a TCB called the quasi-reentrant TCB (QR TCB). Nowadays, an open transaction environment (OTE) allows threadsafe application code to run on its own TCB inside the CICS address space without interference from other transactions. Java programs run in the OTE. Although the OTE offers applications to run either on a class of TCB called an open TCB or on the quasi-reentrant TCB (QR TCB), Java applications run only on an open TCB while they run Java code. If the Java application executes a non-threadsafe CICS command, runs in a CICS region that uses transaction isolation, or runs a non-threadsafe task-related user exit, it switches to the QR TCB.

In the OTE, CICS manages open TCBs in separate pools. Each pool contains a different type (or mode) of open TCB. Each mode has a two-character identifier to indicate its specific purpose, and is handled by CICS in a different way. The mode of TCB used by Java applications is T8. Each thread in the JVM server process runs under a T8 TCB.

A CICS task is not restricted to execution on a single TCB. During the lifetime of a task, the CICS dispatcher can perform multiple TCB change mode operations to provide the user application with the correct environment. These changes are not apparent to the user application at run time but they do incur a small performance penalty.

Find out more:
Linking between programs

Calling from one CICS program to another is known as a link (or LINK, from its EXEC CICS command name). The CICS LINK passes control to the target program and waits for it to complete. The starting program is temporarily suspended and the linked-to program is started. When the linked-to program returns, control is given back to the original program. The started program is still part of the same unit of work so any work that is done to recoverable resources by both programs is backed out if the task does not complete successfully. In other words, a CICS LINK works just like a subroutine call except that the calling and called programs are not statically linked together. A link differs from a Java method call in that the target program can be implemented in any language that is supported by CICS and can also reside on a different CICS system. However, a Java method call is considerably more lightweight than a LINK command.

Passing control to another program is done with the XCTL (transfer control) command. The program that issues XCTL does not receive control back when the target program terminates. Rather, the program that is up one level in the call hierarchy does.

The Java equivalents to EXEC CICS LINK and EXEC CICS XCTL are the methods Program.link() and Program.xctl(). You create an instance of class Program, call its setName() method to supply the name of the program you want to transfer control to, and call link() or xctl().

Find out more:
Passing data between programs

There are two main ways to pass data between programs: through a communications area (in CICS, called a COMMAREA) or through channels and containers.

A COMMAREA is a piece of storage, which contains a data structure that is defined by a program. Most commonly, this data structure is a COBOL copybook. In CICS, a COMMAREA is just a sequence of bytes, CICS does not attempt to format the data structure; it just facilitates the transfer of the data between the programs. The COMMAREA has a maximum size of 32 KB. Calling and called programs must both have exactly the same definition of the COMMAREA layout to enable correct intercommunication. The data structure is described by an interface, where the fields are defined by a language-specific structure such as a COBOL copybook. For a Java application to communicate with an application that is written in another language, you use a byte array to represent the COMMAREA and to hold the data to be transferred. Tools that generate the Java classes make it easier to construct the required byte array.

Channels and containers address the limitations with COMMAREAs. A channel is a named area of CICS-managed storage that is associated with a task. Within a channel, you can store multiple pieces of data in the form of named containers. Containers are classified as holding either CHAR data, where CICS manages any code page conversion required; or as holding BIT data, where no conversion takes place. Multiple containers can be passed between programs within a channel so you can compare a channel to a parameter list.

Find out more:

Getting used to z/OS

Abends and exception handling

What's an abend? A CICS abend is an abnormal end. You can think of it like an unchecked exception or a runtime exception in Java. The error percolates up through your program and, if you don't explicitly handle that error, your program will fail. You can set an abend handler to catch these exceptions.

In traditional languages, CICS indicates the success or failure of a CICS command by returning a condition code to your application program (normally called the RESP value because you use the RESP keyword to retrieve it). For each RESP value that can occur in CICS, there is a corresponding Java exception class.

Find out more:
EBCDIC and character encoding

One of the biggest considerations in converting a distributed program to run in z/OS is EBCDIC encoding. This isn't so much a CICS thing as a general z/OS platform thing but it's important to understand. Without understanding how the encoding works for data that is being passed between CICS programs and the output that you want end users to receive, you can end up with unusable data.

CICS always runs in EBCDIC (check out Wikipedia for a definition of EBCDIC) but the JVM can use a different code page from CICS for character encoding. OSGi JVMs usually run in EBCDIC but Liberty JVMs try to run in ASCII (UTF-8). Java Strings are Unicode but COBOL character data and Java byte arrays are encoded when they are passed into, or returned from, Strings. By default, the JCICS API uses the code page that is specified on the LOCALCCSID system initialization parameter for the CICS region and not the underlying JVM. If the two code pages are different, either your program must handle them or you must get a CICS system administrator to change the JCICS character encoding by updating a JVM system property in the JVM profile.

Find out more:
zFS

z/OS File System (zFS) is the primary type of z/OS UNIX file system and is widely used with CICS. zFS is part of the Distributed File Service base element of z/OS. Like other UNIX systems, zFS is a hierarchical file system, containing files and directories that can be accessed with z/OS UNIX application programming interfaces (APIs).

Find out more:

Where next?

Get started This page Design choices for Java in CICS
What you need to know about CICS Explore the Java APIs Try Java in our sandbox
Try Java in your environment Get involved FAQ