In this chapter, we look at how to code your application programs to run in CICS.

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 so that the application programmer can concentrate on coding the business logic without having to think about specific characteristics of CICS resources. For example, CICS opens and closes files so that the COBOL program does not 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) that gives the application program access to CICS services. 

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

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 was found. Then, there is the command itself, which determines the function being performed on the CICS resource. 

There are over 340 commands that are available. The command is followed by one or more options and their arguments. In this case, we finish the command by using the string END-EXEC.

Here is the template for an EXEC CICS command:

IBM Knowledge Center has a summary of each command, as shown in Figure 3-2 on page 17:

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. Luckily, modern editors can supply context help to aid you when writing your code.

This section describes simple CICS API example by using the Payroll System application. 

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

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

EXEC CICS tells the translator that a CICS command is starting. The command in this case is a READ, and you need three options that contain arguments:

The command is stopped by the string END-EXEC. 

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

In the program that is called PAYBUS, the API example looks like Figure 3-3.

When this command runs, the API passes the READ arguments through the EXEC interface through to CICS. CICS service modules interact with VSAM to access the file and retrieve the record, and then they send the contents back to the program’s Working Storage field (Figure 3-4).

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 with the COBOL compiler. This translator is either integrated with the COBOL compiler or is a separate pre-compile step. The translator converts the EXEC CICS API command into COBOL statements (Figure 3-5 on page 19).

For this EXEC CICS READ example:

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

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

If the command was successful, then the EIBRESP contains a zero, which means NORMAL. However, if the EIBRESP contains a nonzero value, then a non-NORMAL condition occurred.

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

A list of the conditions for each command can be found in the command summary section of IBM Knowledge Center. Looking in Conditions under READ shows condition number 13, which means NOT-FOUND. There might 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:

The working storage variable can then be tested by using IF or EVALUATE COBOL statements that test RESP.

The application tests the EIB fields directly.

If the condition is not handled (nohandle and RESP are not coded), then CICS issues an abend condition and stops the program.

In summary, CICS is a powerful mixed-language application server that provides access its resources by using a wealth of interface commands. Over the years, new APIs were added, such as web, asynchronous, and SIGNAL EVENT commands. We cover some of these APIs later in this paper.