Chapter 6. The Java CICS API
6.2 A short overview of the JCICS API
In this section, we provide a high-level overview of the CICS API, briefly describing its various categories. Later in this chapter, we describe most of the API in more detail.
Figure 6-2 shows a class diagram of the JCICS API. Due to limited space, we only show some particularly important classes and show more detail in later sections.
Figure 6-2 Overview of the JCICS API
In the following sections, we briefly describe several functional areas of the API.
6.2.1 Program control
Program control services allow one program to call another program in the same unit of work. Data can be passed to and received back from the called program. Until recently this was
achieved by means of a shared area of storage known as the COMMAREA, but in CICS TS Version 3.1, an additional mechanism known as channels and containers is available as an alternative to a COMMAREA.
6.2.2 File control
Using file control services you can access VSAM files, which come in three different flavors:
Key Sequenced Data Sets (KSDS)
Entry Sequenced Data Sets (ESDS)
Relative Record Data Sets (RRDS)
6.2.3 Synchronization
Synchronization services provide a mechanism to ensure mutual exclusion when dealing with shared resources that must not be modified (or even accessed) by more than one transaction at a time.
6.2.4 Scheduling services
Scheduling services allow a program to start other transactions asynchronously, either immediately or at some specified later time.
6.2.5 Unit of work
This is one of the easiest and probably most important JCICS services to use. You use these services to commit or roll back the current unit of work, which either makes the results of the current transaction permanent or backs them out.
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.
To commit the current unit of work, use the Task.commit() method: Task.getTask().commit();
To back out the current unit of work, use the Task.rollback() method: Task.getTask().rollback();
6.2.6 Document services
Document services are most often used in conjunction with CICS Web support services (6.2.7, “Web and TCP/IP services” on page 93) to dynamically build HTML pages that are to be sent back to a Web browser.
You can work with document templates, which are portions of a document that are created offline (or by another program) and might contain symbols that represent dynamic content. You can then replace those symbols to produce the actual document to be sent back.
We show an example of using the Document API in Chapter 7, “Evolving a heritage application using Java” on page 135.
Chapter 6. The Java CICS API 93
6.2.7 Web and TCP/IP services
Web services allow CICS programs to produce dynamic Web content, probably in response to a client request from a Web browser. In other words, they can act much like CGI programs that are supported by most Web servers or like Java servlets.
The JCICS API provides the following Web-related and TCP/IP-related services:
Examining an HTTP request
Sending a response back to the client
Getting the client’s host name
Security-related services, such as getting authorization method and certificates
We show how to use Web services in conjunction with Document services in Chapter 7, “Evolving a heritage application using Java” on page 135.
6.2.8 Transient storage queues
Temporary storage is the primary CICS facility for storing data that must be available to multiple transactions. Data items in temporary storage are kept in queues whose names are assigned dynamically by the program that stores the data. Think of a temporary storage queue that contains multiple items as a small data set whose records are addressed either sequentially or directly, by item number. If a queue contains only a single item, think of it as a named scratch-pad area.
6.2.9 Transient data queues
Transient data queues (TD queues) are similar in some respects to transient storage queues, but there are some major differences:
They cannot be created on-the-fly but must be predefined.
Items can only be read sequentially and cannot be changed.
Reading from TD queues is destructive, that is, each item can be read only once. After a transaction reads an item, that item is removed from the queue and is not available to any other transaction.
Today, TD queues are pretty much obsolete, because the preferred alternative is to use WebSphere MQ message queues. Therefore, we do not further discuss TD queues in this book. However, they are fully supported by the JCICS API.
6.2.10 Terminal control
Terminal control services allow an application program to interact with the user’s terminal by displaying data on and retrieving user input from the terminal.
However, terminal control in Java is not widely used because there is no JCICS support for an important feature called
Basic Mapping Support
(BMS). To put it simply, BMS is a set of CICS services and tools to create, display, and interact with panel forms from an application program. As you can imagine, BMS panels are much easier to use (and more portable) than direct interaction with the raw terminal.During the course of this residency, we developed a small package called
JBMS
(for Java Basic Mapping Support), which allows you to create and interact with panel forms, just like the real BMS does. Read all about it in 6.13, “Terminal services” on page 125.6.2.11 Miscellaneous services
In this section, we cover several services that do not fall into one of the categories above.
Specifically, you can:
Inquire about the system name and VTAM® application ID of the CICS region using Region.getSysId() and Region.getAPPLID(), respectively.
Enable and disable tracing in the CICS region: Region.enableTrace(), Region.disableTrace().
Examine and modify the contents of the
Common Work Area
(CWA), using Region.getCWA() and Region.setCWA(). Retrieve the transaction name and program name under which the current program is executing, which is useful for logging purposes.
Get the name of the user who started the transaction.
Examine and modify the
Transaction Work Area
(TWA). The TWA is a small (up to 32 K) area of storage that is allocated when a transaction is initiated and is initialized to binary zeros. It lasts for the entire duration of the transaction and is accessible to all local programs in the transaction. Using the TWA is no longer recommended for new applications. Find out how the current program was started using Task.getTask().getSTARTCODE(). Table 6-1 lists the different possible startcodes and their meanings.
Table 6-1 Startcodes as returned by Task.getTask().getSTARTCODE()
Startcode Meaning
D The task was initiated to process a distributed programming link (DPL) command that did not specify the SYNCONRETURN option. (The task is not allowed to issue syncpoints.)
DS The task was initiated to process a distributed programming link (DPL) command containing the SYNCONRETURN option. (The task is allowed to issue syncpoints.) QD CICS initiated the task to process a transient data queue that reached trigger level. S Another task initiated this one using a START command that did not pass data in the
FROM option.
SD Another task initiated this one using a START command that passed data in the FROM option.
SZ The task was initiated with a FEPI START command (see CICS Front End Programming Interface User’s Guide, SC34-6234, for further information).
TO The task was initiated to process unsolicited input from a terminal (or another system), and the transaction to be executed was determined from the input.
TP The task was initiated to process unsolicited input or in response to a RETURN IMMEDIATE command in another task. In either case, the transaction to be executed was preset (in the RETURN command or in the associated TERMINAL definition) without reference to input.
Chapter 6. The Java CICS API 95
6.2.12 Services that the JCICS API does not support
JCICS does not support these CICS services: APPC unmapped conversations
CICS Business Transaction Services
DUMP services
Journal services
Storage services
Timer services
BMS services SEND MAP and RECEIVE MAP