3.1 Introduction to the EXEC CICS API

CICS is a mixed language application server that runs on IBM Z.
As an application server, CICS hosts and provides services to application programs.
In this type of environment, CICS manages resources on behalf of the application.
This allows the application programmer to concentrate on coding the business logic without having to think about specific characteristics of CICS resources.
For example, CICS will open and close files so the COBOL program doesn’t need any File Descriptor entries in the FILE SECTION of the COBOL program.

How does your program request access to CICS resources?
CICS provides an Application Programming Interface (API) which gives the application program access to CICS services.

The API consists of several parts (Figure 3-1).

• A command-level programming interface, commonly known as the EXEC CICS interface.
• An EXEC infrastructure consisting of EXEC interface module DFHEIP and a set of EXEC processor modules.
  Plus, a control block called EIB used to store the status of the current CICS request being executed by the application.
• An EXEC stub that is link-edited with the COBOL program
• A command-level translator that interprets the command-level commands

The EXEC CICS command is the portion that goes in your COBOL program.
For each request to access a CICS resource, a command must be coded in the application logic.
The command starts with “EXEC CICS”, which is short for EXECUTE CICS.
This "EXEC CICS" string tells the command-level translator that an API command has been found.
Then there is the command itself, this determines the function being performed on the CICS resource.

There are over 340 commands available.
Then the command is followed by one or more options and their arguments, and we finish the command with the string “END-EXEC”.
Here's the template for an EXEC CICS command:

EXEC CICS command option(arg) .... END-EXEC

The Knowledge Center has a summary of each command showing (Figure 3-2):

• A schematic diagram illustrating the syntax and a description of the command
• A list of options and their usage

The schematic diagrams, or you might hear them referred to as railroad diagrams, are essential to the application programmer.
They explain exactly what can be specified on an EXEC CICS command.
This may sound daunting but luckily modern editors can supply context assist help to aid you when writing your code.

3.2 CICS API example

Let’s explain this by way of a simple example using the Payroll System application.

Our program PAYBUS needs to read a record from a file called “PAYROLL”, with a key stored in variable ws-key.
The data is to be returned to a Working Storage variable called payroll-record.

Looking at the schematic diagram for a READ, shows that options FILE and RIDFLD (which is the record key), are mandatory.
Options INTO and SET are alternatives, but you must have one of them.
The other options are optional. So, based on this, our code in the program looks like this:

EXEC CICS READ FILE(‘PAYROLL’) RIDFLD(ws-key) INTO(payroll-record) END-EXEC

Where EXEC CICS tells the translator that a CICS command is starting.
The command in this case would be a READ and you need three options containing arguments.

• FILE - we'll give it the filename “PAYROLL”
• RIDFLD - which we'll give the record key "ws-key"
• INTO - which is the location in your program, where CICS will place the record, and this will be our "payroll-record".

And then the command is terminated with the string END-EXEC

The argument for FILE is hardcoded with the string ‘PAYROLL’, which is why it's in quote marks, but the other arguments 'ws-key' and 'payroll-record', are variables in the WORKING-STORAGE SECTION of our COBOL program.

In the program called PAYBUS, it looks like Figure 3-3

When this command executes, the API will pass the READ arguments via the EXEC interface through to CICS.
CICS service modules will interact with VSAM to access the file and retrieve the record.
Sending the contents back to the program’s Working Storage field (Figure 3-4).

3.3 COBOL translator

These EXEC CICS commands are not reserved words in COBOL (or any other language), so how can the compiler understand it?

A command-level translator runs in conjunction with the COBOL compiler.
Either, integrated with the COBOL compiler or as a separate pre-compile step.
The translator converts the EXEC CICS API command into COBOL statements (Figure 3-5).

For this EXEC CICS READ example:

• You can see that the EXEC CICS command is commented out and replaced by COBOL statements.
• These COBOL statement call the EXEC stub, named DFHEI1, passing the COBOL option arguments, ‘PAYROLL’, ws-key and payroll-record KEY-I and AREA-O.
• The translator also copies the EIB copybook DFHEIBLK and DFHCOMMAREA into the LINKAGE SECTION.
• EIB copybook DFHEIBLK and DFHCOMMAREA on the PROCEDURE DIVISION header after the “using” phrase.

Based on this knowledge we can revisit how the API passes control to CICS (Figure 3-6).

• When the COBOL program executes the EXEC CICS command.
  It links to the EXEC stub DFHEI1
• DFHEI1 locates the address of EXEC interface module DFHEIP
• DFHEIP branches to the relevant processor module for the component responsible for handling the request.
  In this case, DFHEIFC.
• The processor module validates the argument list and branches to its CICS service modules.
• If the arguments were correct, then the record is retrieved from the file and control passed back to DFHEIP via processor module.
• DFHEIP updates the DFHEIB control block with the status of the command.
• It then returns control back to the application program

3.4 Response codes

So, how do we know if the command was successful?
On return to your program, the response from CICS is placed in EIB fields:
EIBRESP andEIBRESP2. The response code in each field consists of a two-digit decimal condition number.
These EIB response fields are placed in your program’s LINKAGE SECTION, by the CICS translator at compile time.

If the command was successful, then the EIBRESP will contain zero meaning NORMAL.
However, if the EIBRESP contains a non-zero value then a non-NORMAL Condition has occurred.

Going back to our example, if the READ on file ‘PAYROLL’ was for a record that didn’t exist then the EIBRESP would contain 13.

A list of the conditions for each command can be found in the command summary section of the Knowledge Center.
Looking in the Conditions under READ shows, condition number 13 means NOT-FOUND.
There may be several reasons for a condition.
If so, then EIBRESP2 is used to further qualify the condition.

So, how do you check for the response code in your program?
There are two ways to test the response code of a command:

• Code the RESP or RESP2 option on the command, with a Working Storage variable as the argument.
  CICS will place the EIBRESP in the working storage variable as the call returns.

  EXEC CICS READ FILE('PAYROLL') RIDFLD(ws-key) INTO(payroll-record) RESP(WC) RESP2(RC2) END-EXEC

  The working storage variable can then be tested using an IF or EVALUATE COBOL statements testing RESP.


• Alternatively, code an option nohandle.
  CICS updated the EIB, but does not handle the condition.

  EXEC CICS READ FILE('PAYROLL') RIDFLD(ws-key) INTO(payroll-record) nohandle END-EXEC

  The application can then test the EIB fields directly.

If the condition is not handled (nohandle and RESP are not coded) then CICS will issue an abend and terminate the program.

In summary, CICS is a powerful mixed-language application server, that provides access its resources using a wealth of interface commands.
Over the years, new API has been added, such as WEB, Asynchronous and SIGNAL EVENT commands.
We will cover some of these later in this publication.

This document was created or updated on December 17, 2020.