When you need a CICS system service—for example, when reading a record from a file—you just include a CICS command in your code. CICS commands look like:

EXEC CICS function
          [option (argument)][option ...]... [terminator]

The options for this command are:

For example, the options for the READ command include FILE, RIDFLD, UPDATE. FILE tells CICS which file you want to read, and is always followed by a value indicating or pointing to the filename. RIDFLD (record identification field), that is the key that tells CICS which record within the file to address, and likewise needs a value. The values are called arguments and must appear after the keyword within parentheses (brackets). UPDATE, on the other hand, simply means that you intend to modify the record and update it (thereby invoking the CICS transactional protection we discussed earlier) and has no argument associated with it.

So, to read into a piece of working storage named ACCTREC, with intent to update, a record from a file known to CICS as ACCTFIL, using a key that we’ve stored in working storage at ACCTC, the command could be coded like this:

MOVE 'ACCTFIL' TO LF-ACCTFIL
EXEC CICS READ FILE(LF-ACCTFIL)             * Resource
          RIDFLD(ACCTC)                     * Key
          INTO (ACCTREC)                    * Storage
          UPDATE                            * Option
END-EXEC

When you specify a value, you can either use a character literal (enclosed in quotes), as we did for FILE above, or you can point to the name of a storage area that contains the value you want, as we did for RIDFLD above. In other words, we might have written:

EXEC CICS READ FILE(LF-ACCTFIL) UPDATE
         INTO (ACCTREC) RIDFLD(ACCTC)
END-EXEC

instead of our earlier command. If you use a literal, follow the usual language rules; for example, for COBOL put it in quotes unless it’s a number.

Data can be moved by CICS from and into your program storage by using the FROM and INTO options (also known as move mode) or you can access the data using a pointer together with the SET parameter (also known as locate mode).

You may be curious about what the compiler does with what is a rather English-like statement. The answer? The compiler doesn’t see that statement. Processing a CICS program for execution starts with a translation step. The CICS translator converts your EXEC CICS commands into native language statements; for example, for COBOL in the form of a CALL statement. You then compile the expanded source and link edit this in the normal way. By the way, in COBOL the generated statements never contain periods (full stops), unless you include one explicitly after the END-EXEC. This means you can use CICS commands within any COBOL construct such as IF or EVALUATE statements (by leaving the period out of the command), or you can end a sentence with the command (by including the period).

The biggest difference between standard COBOL programs and CICS COBOL programs is that you don’t define your files in a CICS program. Instead, they are defined using FILE definitions that are stored in a CICS table, the File Control Table (FCT), which is covered in Handling Files later in this chapter. Other differences are:

Some statements and compiler functions produce code that is incompatible with the CICS environment. You must not use the STOP ‘literal’ form of that COBOL verb, because it stops not only yourself but everyone else who uses your CICS address space. In general, you cannot use language features and compiler options that need operating system services during execution. COBOL examples include ACCEPT, OPEN, and READ. There are similar restrictions in the other supported languages.

Because CICS is managing the shared environment:

CICS COBOL programs should be usually short-running if data is shared. A batch COBOL program might process all records of a file; on the other hand, a typical CICS COBOL program processes just a few requests.

There are three READ commands:

The sample application uses the first two: READ and READNEXT as seen in Browsing a File, later in this chapter.

The command to read a single record from a file is:

EXEC CICS READ FILE(filename)
               INTO(data-area) LENGTH(data-area)
               RIDFLD(data-area)
           options
END-EXEC

The options for this command are:

In program NACT02, we need to find out whether the requested record is there. The command we use is shown in Example 5-1.

   EXEC CICS READ FILE(WS-LITS-FILES-ACCOUNT)
                  INTO(NACTREC-DATA)
                  RIDFLD(ACCTDO IN NACTREC-DATA)
                  RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
   END-EXEC
   IF CA-CRUD-RESP NOT DFHRESP(NORMAL)
* We may have a problem and the RESP2 field may contain more information
   END-IF

The major return code will be placed in CS-CRUD-RESP and a qualifier may be supplied in CA-CRUD-REAS.

In this command, the record is placed in the data area named NACTREC-DATA so it should be a data structure corresponding to the account file record. You could define this structure directly in the program, but you’ll also need it in several other programs. So instead you should put the record definition into a library in NACCTREC and copy it into the NACCRUD copybook, which is then copied into the NACT02 program.

In NACCCRUD:

10  NACTREC-DATA.
    COPY NACCTREC.

In NACT02:

01  DFHCOMMAREA
    COPY NACCCRUD.

Here ACCTDO IN NACTREC-DATA is where the account number was passed by the frontend that called the program. NACTREC-DATA is the location where the data is to be passed back to the frontend program.

In any application, it is a good idea to keep your record layouts in a library and copy them into the programs that need them. Even in the simplest of applications, the same record is usually used by several programs. This procedure prevents multiple programs from using different definitions of the same thing.

This argument applies equally well to any structure used in common by multiple programs. Map structures are a prime example, as are parameter lists and communication areas, which we’ll discuss later. Apart from its value in the initial programming stage of an application, this technique greatly reduces the effort and hazards associated with any change to a record or map format. You can make the changes in just one place (your library) and then simply recompile all the affected programs. Example 5-1 also introduces the method of testing the major CICS return code. The CICS translator replaces the DFHRESP(condition) with the numeric return code so programmers are able to write intelligible code.

Example 5-2 shows the COBOL record definition we need of the account file in the sample application. Its fields are described beginning at the 20 level in order to allow it to be used within other structures.

20  ACCTDO               PIC X(5).   //  Account number
20  SNAMEDO              PIC X(18).  //  Last/surname
20  FNAMEDO              PIC X(12).  //  First name
20  MIDO                 PIC X.      //  Middle initial
20  TTLDO                PIC X(4).   //  Title e.g., Mr./Mrs.
20  TELDO                PIC X(10).  //  Telephone number
20  ADDR1DO              PIC X(24).  //  Address line 1
20  ADDR2DO              PIC X(24).  //  Address line 2
20  ADDR3DO              PIC X(24).  //  Address line 3
20  AUTH1DO              PIC X(32).  //  Additional Authorized Card  User 1
20  AUTH2DO              PIC X(32).  //  Additional Authorized Card  User 2
20  AUTH3DO              PIC X(32).  //  Additional Authorized Card  User 3
20  AUTH4DO              PIC X(32).  //  Additional Authorized Card  User 4
20  CARDSDO              PIC X.      //  Number of cards issued to Customer
20  IMODO                PIC X(2).   //  Month card issued
20  IDAYDO               PIC X(2).   //  Day card issued
20  IYRDO                PIC X(2).   //  Year card issued
20  RSNDO                PIC X.      //  Reason code for card issued
20  CCODEDO              PIC X.      //  Card status coded e.g. G for Gold
20  APPRDO               PIC X(3).   //  Code of card issue approvers
20  SCODE1DO             PIC X.      //  Additional privilege code 1
20  SCODE2DO             PIC X.      //  Additional privilege code 2
20  SCODE3DO             PIC X.      //  Additional privilege code 3
20  STATDO               PIC X(2).   //  Account status
20  LIMITDO              PIC X(8).   //  Customer Account Credit Limit
20  PAY-HIST OCCURS 3.               //  Pay History first of last three
    25  BAL              PIC X(8).   //  Account Balance
    25  BMO              PIC 9(2).   //  Month
    25  BDAY             PIC 9(2).   //  Day
    25  BYR              PIC 9(2).   //  Year
    25  BAMT             PIC X(8).   //  Amount of balance
    25  PMO              PIC 9(2).   //  Payment month
    25  PDAY             PIC 9(2).   //  Payment day
    25  PYR              PIC 9(2).   //  Payment year
    25  PAMT             PIC X(8).   //  Payment mmount

The record format is already fixed and used by batch programs. Our online CICS sample program must use the same record definition.

When you search by name using NACT05, you need to be able to point to a particular record in the file, based on end-user input which maybe anywhere in the file. Then you can start reading the file sequentially from that point on. The need for this combination of random and sequential file access—called browsing—arises frequently in online applications. Consequently, CICS provides a special set of EXEC CICS browse commands to make this job easier, namely: STARTBR, READNEXT, READPREV, and ENDBR.

Before looking at these commands, a few words about the performance implications of browsing. Transactions that produce lots of output screens can monopolize system resources. A file browse is often guilty of this. Having a long browse can put a severe load on the system, delaying other transactions and increasing overall response time.

The CICS default design model assumes the end user initiates a transaction that accesses a few data records, processes the information, and returns the results to that user. This process may involve numerous I/O waits that allow CICS to schedule and run other tasks. However, CICS is not an interrupt-driven multitasking system—tasks that involve small amounts of I/O relative to processing are able to monopolize the system regardless of priority.

EXEC CICS STARTBR FILE(filename)
                  RIDFLD(data-area)
                  options
END-EXEC

EXEC CICS READNEXT FILE(filename)
                   INTO(data-area) LENGTH(data-area)
                   RIDFLD(data-area)
END-EXEC

EXEC CICS ENDBR FILE(filename)
END-EXEC

05  WS-LIMIT-NAMES.
    10  WS-BROWSE-SNAME             PIC X(18) VALUE SPACES.
    10  WS-MAX-SNAME                PIC X(18) VALUE SPACES.
    10  WS-MIN-FNAME                PIC X(12) VALUE SPACES.
    10  WS-MAX-FNAME                PIC X(12) VALUE SPACES.

 B-010.
     MOVE SNAMEDO IN CA-BRWS-ENTRY (1) TO WS-PASSED-SNAME
                                          WS-BROWSE-SNAME
                                          WS-MAX-SNAME
*
     INSPECT WS-MAX-SNAME REPLACING ALL SPACES BY HIGH-VALUES
*
     MOVE FNAMEDO IN CA-BRWS-ENTRY (1) TO WS-PASSED-FNAME
                                          WS-MAX-FNAME
                                          WS-MIN-FNAME
*
     INSPECT WS-MAX-FNAME REPLACING ALL SPACES BY HIGH-VALUES
     INSPECT WS-MIN-FNAME REPLACING ALL SPACES BY LOW-VALUES

05  WS-AVAILABILITY-IND             PIC X.
    88  SOME-AVAILABLE              VALUE 'Y'.
    88  NONE-AVAILABLE              VALUE 'N'.

10  CA-BRWS-FOUND               PIC 9(4).
    88  CA-BRWS-NONE-FOUND      VALUE ZERO.
10  CA-BRWS-MORE                PIC 9(4).
10  CA-BRWS-MORE-X REDEFINES CA-BRWS-MORE
                               PIC X(4).
    88  CA-BRWS-NO-MORE         VALUE '0000'.

* The interface to the Browse program is described in a copy book
* in order to ensure consistency. The values in this area designed
* to be in character format to enable ease of translation when the
* program is invoked from a remote system which uses a different
* encoding scheme (e.g., ASCII) than the EBCDIC of the mainframe.
*
* This is the working storage version of the interface to the
* Browse program.
*
     05  WS-BRWS-COMMAREA.
*
* This is an "Eyecatcher" and integrity check field.
*
         10  WS-BRWS-VERSION             PIC XXX VALUE SPACES.
             88  WS-BRWS-CORRECT-VERSION VALUE 'V1A'.
*
* Only two functions are provided by the Browse program:
* initiation of a Browse and Continuation of a previously
* initiated browse.
*
         10  WS-BRWS-FUNCTION            PIC X VALUE SPACE.
             88  WS-BRWS-REQ-BROWSE      VALUE 'B'.
             88  WS-BRWS-REQ-CONTINUE    VALUE 'C'.
             88  WS-BRWS-VALID-REQUEST   VALUE 'B' 'C'.
*
* The response field is designed to conform to the CICS EIBRESP
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* Browse program itself. If there was an interface error, this
* contains a special value of 'FRMT'.
*
         10  WS-BRWS-RESP                PIC 9(4) VALUE ZERO.
         10  WS-BRWS-RESP-X REDEFINES WS-BRWS-RESP
                                         PIC X(4).
             88  WS-BRWS-NO-ERROR        VALUE '0000'.
             88  WS-BRWS-BAD-FORMAT      VALUE 'FRMT'.
*
* The reason field is designed to conform to the CICS EIBRESP2
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* Browse program itself. If there was an interface error, this
* contains 'VERE' for Version Error, 'LENE' for Length Error (if
* possible), 'REQE' for Request Error, 'LIME' for Limit Error or
* 'MORE' for More Error (only occurs for a continuation request).
*
         10  WS-BRWS-REAS                PIC 9(4) VALUE ZERO.
         10  WS-BRWS-REAS-X REDEFINES WS-BRWS-REAS
                                         PIC X(4).
             88  WS-BRWS-VERSION-ERROR   VALUE 'VERE'.
             88  WS-BRWS-LENGTH-ERROR    VALUE 'LENE'.
             88  WS-BRWS-REQUEST-ERROR   VALUE 'REQE'.
             88  WS-BRWS-LIMIT-ERROR     VALUE 'LIME'.
             88  WS-BRWS-MORE-ERROR      VALUE 'MORE'.
*
* If the response contains a numeric value, this contains the
* character representation of the EIBFN value giving rise to
* the exception condition.
*
         10  WS-BRWS-CICS-FUNCTION       PIC 9(5) VALUE ZERO.
         10  WS-BRWS-CICS-FUNCTION-X
                REDEFINES WS-BRWS-CICS-FUNCTION
                                         PIC X(5).
*
* In order to prevent excessive searches, the caller must specify
* the maximum number of matches (s)he is prepared to handle.
* Also because a COMMAREA is limited to a maximum of approximately
* 32,000 bytes, the maximum limit has been set at 80.
*
         10  WS-BRWS-LIMIT-TO-GET        PIC 9(4) VALUE ZERO.
         10  WS-BRWS-LIMIT-TO-GET-X REDEFINES WS-BRWS-LIMIT-TO-GET
                                         PIC X(4).
*
* The Browse program indicates the number of matches found.
* The range is zero to the limit.
*
         10  WS-BRWS-FOUND               PIC 9(4) VALUE ZERO.
             88  WS-BRWS-NONE-FOUND      VALUE ZERO.
*
* After satisfying the limit, the Browse program will place
* either '0000' in here if there are no more records satisfying
* the search criteria or a number if there are more. On a
* continuation request this number must be returned to the Browse
* program since it is used to reposition the request.
*
         10  WS-BRWS-MORE                PIC 9(4) VALUE ZERO.
         10  WS-BRWS-MORE-X REDEFINES WS-BRWS-MORE
                                         PIC X(4).
             88  WS-BRWS-NO-MORE         VALUE '0000'.
*
* The records found on file for a match. Input is in the
* surname and first name fields of the first Entry.
*
         10  WS-BRWS-MATCHES.
             15  WS-BRWS-ENTRY           OCCURS 80.
*
* The description of the account record is placed in a copy book.
*
             COPY NACWTREC.

 C-START-BROWSE SECTION.
*
*
* This routine initializes the browse of the file via the
* STARTBR command and sets the availability indicator based
* on the possibility of a match.
*
     SET CA-BRWS-NONE-FOUND TO TRUE
*
     EXEC CICS STARTBR FILE(WS-LITS-FILES-NAME)
               RIDFLD(WS-BROWSE-SNAME)
               RESP(RESPONSE) RESP2(REASON-CODE)
     END-EXEC
*
     EVALUATE RESPONSE
         WHEN DFHRESP(NORMAL)
             SET SOME-AVAILABLE  TO TRUE
         WHEN DFHRESP(NOTFND)
             SET NONE-AVAILABLE  TO TRUE
             SET CA-BRWS-NO-MORE TO TRUE
*
* If any other condition other than success or NOTFND
* occurs, then a serious problem has occurred, so the
* error handler is invoked.
*
         WHEN OTHER
             PERFORM Z-ERROR-HANDLER
     END-EVALUATE
*
 END-C-START-BROWSE.
     EXIT.

  Y-READ-ONE SECTION.
 *
 * This code attempts to read a record from the file and
 * sets the availability indicator based on its success.
 *
 * This section is performed from the following sections -
 *      D-FILL-IN-MATCHES
 *      E-CONTINUE-BROWSE
 *
  Y-010.
      EXEC CICS READNEXT FILE(WS-LITS-FILES-NAME)
                         INTO(AN-ACCTREC)
                         RIDFLD(WS-BROWSE-SNAME)
                         RESP(RESPONSE) RESP2(REASON-CODE)
      END-EXEC
    EVALUATE RESPONSE
*
* If either condition occurs, it means a record was read.
*
         WHEN DFHRESP(NORMAL)
         WHEN DFHRESP(DUPKEY)
*
* But it may not match the full criteria.
*
             IF  SNAMEDO IN AN-ACCTREC > WS-MAX-SNAME
                 SET NONE-AVAILABLE TO TRUE
             ELSE
                 SET SOME-AVAILABLE TO TRUE
                 ADD 1 TO WS-RECORDS-READ
             END-IF
*
* If we have exhausted the file, then there
* are obviously no more matches.
*
         WHEN DFHRESP(ENDFILE)
             SET NONE-AVAILABLE TO TRUE
*
* If any other condition occurs, then a serious problem
* has occurred, so the error handler is invoked.
*
         WHEN OTHER
             PERFORM Z-ERROR-HANDLER
     END-EVALUATE
*
 END-Y-READ-ONE.
     EXIT.
     EJECT.

F-TERMINATE-BROWSE SECTION.
*
* This code terminates the browsing operation against the file.
*
F-010.
    EXEC CICS ENDBR FILE(WS-LITS-FILES-NAME)
              RESP(RESPONSE) RESP2(REASON-CODE)
    END-EXEC

There are three file output commands:

EXEC CICS REWRITE FILE(filename)
                  FROM(data-area)
                  RESP(data-area) RESP2(data-area)
END-EXEC

EXEC CICS WRITE FILE(filename)
                FROM(data-area) LENGTH(data-value)
                RIDFLD(data-value)
                RESP(data-area) RESP2(data-area)
END-EXEC

EXEC CICS DELETE FILE(filename)
                 RIDFLD(data-area)
                 RESP(data-area) RESP2(data-area)
END-EXEC

EXEC CICS WRITE FILE(WS-LITS-FILES-ACCOUNT)
                FROM(NACTREC-DATA)
                RIDFLD(ACCTDO IN NACTREC-DATA)
                RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXEC

EXEC CICS READ FILE(WS-LITS-FILES-ACCOUNT) UPDATE
               INTO(OLD-ACCTREC)
               RIDFLD(ACCTDO IN NACTREC-DATA)
               RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXEC

EXEC CICS REWRITE  FILE(WS-LITS-FILES-ACCOUNT)
                   FROM(NACTREC-DATA)
                   RESP(CA-CRUD-RESP) RESP2(CA-CRUD-REAS)
END-EXEC

EXEC CICS DELETE  FILE(WS-LITS-FILES-ACCOUNT)
                  RIDFLD(ACCTDO IN NACTREC-DATA)
                  RESP(CS-CRUD-RESP) RESP2(CS-CRUD-REAS)
END-EXEC

Before leaving the topic of file commands, we’ll list some of the other facilities that are available. You can find guidance information on using file control in the CICS Application Programming Guide, and a full list of commands, options, and exceptional conditions in the CICS Application Programming Reference. Both of these books are part of the CICS library and are found on the CD-ROM.

An affinity is created when a resource that contains state data of a pseudo-conversation is tied to one instance of a CICS. If the KanDoIT company takes over other companies, they will want to run multiple machines with many CICS regions/address spaces and if the state of one credit card is on one machine and the data on another, the application will not scale up because the transaction may (will) have an affinity to the first machine. The first place that this normally occurs is in the use of a resource that is tied to one CICS region, for example, a CWA. Secondly, it is using temporary storage with a key that uses a resource name that is unique to that CICS, for example, a termid. This is a highly complex subject; see the CICS Application Programming Guide for more information.

The installed program definition contains one entry for every program used by any application in the CICS system. Each entry holds, among other things, three particularly important pieces of information:

The installed transaction definition has an entry for every transaction identifier in the system (using “transaction” in the CICS sense of the word). The important information kept about each transaction is the transaction identifier and the name of the first program to be executed on behalf of the transaction.

You can see how these two sets of definitions work in concert:

There are two CICS commands for passing control from one program to another. One is the LINK command, which is similar to a CALL statement in COBOL. The other is the XCTL (transfer control) command, which has no COBOL counterpart. When one program links to another, the first program in working storage and remains in main storage. When the second (linked-to) program finishes and gives up (RETURNs) control, the first program resumes at the instruction after the LINK. The linked-to program is considered to be operating at one logical level lower than the program that does the linking.

In contrast, when one program transfers control (XCTL) to another, the first program is considered terminated, and the second program operates at the same level as the first. When the second program finishes, control is returned not to the first program, but to whatever program last invoked it.

Some people like to think of CICS itself as the highest program level in this process, with the first program in the transaction as the next level down, and so on. If you look at it from this point of view, CICS links to the program named in the list of installed transaction definitions when it initiates the transaction (see Figure 5-1). When the transaction is complete, this program (or another one operating at the same level) returns control to the next higher level, which happens to be CICS itself.

Figure 5-1. Transferring control between programs (after an ABEND)

The LINK command is used to link to another program expecting return. The syntax of the LINK command looks like this:

EXEC CICS LINK PROGRAM(name)
               COMMAREA(data-area) LENGTH(data-value)
               RESP(data-area) RESP2(data-area)
END-EXEC

The XCTL command is used to transfer control from one program to another:

EXEC CICS XCTL PROGRAM(name)
               COMMAREA(data-area) LENGTH(data-value)
               RESP(data-area) RESP2(data-area)
END-EXEC

The parameters are the same as for the LINK command.

The RETURN command returns control to the previous program within a transaction. The syntax is simply:

EXEC CICS RETURN
END-EXEC

When the program at the highest level for the transaction returns control to CICS, however, there are two additional options that you can specify:

In this case the RETURN command is slightly longer:

EXEC CICS RETURN TRANSID(nextid)
                 COMMAREA(data-area) LENGTH(data-value)
END-EXEC

As well as passing control to other programs by means of LINK and XCTL commands, a CICS COBOL program can invoke another program with a COBOL CALL statement. Although there’s somewhat less system overhead (in other words, a shorter path length) with this method, there are some considerations that may count against it. For example:

Now, the answer to that problem we met earlier—whether and how to break up a large routine. For single-task efficiency, generally inline code is best, PERFORM next, straight CALL third, XCTL next, and LINK last. However, any of the first three choices may make for a long load module, and that can impact future understanding as to how the whole thing works when it comes to fixing bugs in later years.

Always use XCTL if it will do, of course, rather than LINK. In the NACT01 program there is one use of XCTL. That’s just a program logic issue; you either need control back or you don’t. In the example, as you’ll see, we’ve broken our own rule and used a LINK (rather than an XCTL) to the error handling program. However, we do have an excuse ready. See Handling Errors, earlier in this chapter.

The probability of the code being re-used is another issue. If you have a long complex routine for calculating withholding tax for veterans in a payroll system, but you use it only if salary or dependents change and you have hardly any veterans, then by all means put it in a separate routine and LINK to it.

The previous sections provide the background about passing data from one transaction to another; you may be wondering how the receiving program accesses this data. When the sample application meets an error from which it cannot recover, it transfers control to the general-purpose error program, NACT04. We pass three items of information to the NACT04 program:

The copybooks used to pass this information to the error handling program by the other modules in the COBOL application are shown in Example 5-7.

*
* This is the working storage version of the interface to the
* Error Handler program.
*
     05  WS-ERRH-ERROR-COMMAREA.
*
* This is an "Eyecatcher" and integrity check field.
*
         10  WS-ERRH-VERSION             PIC XXX VALUE SPACES.
             88  WS-ERRH-CORRECT-VERSION VALUE 'V1A'.
         10  FILLER                      PIC X   VALUE SPACES.
*
* The error field is designed to conform to the CICS EIBRESP
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* various programs in the applications suite.
*
         10  WS-ERRH-ERROR               PIC 9(4) VALUE ZERO.
         10  WS-ERRH-ERROR-X REDEFINES WS-ERRH-ERROR
                                         PIC X(4).
*
* The reason field is designed to conform to the CICS EIBRESP2
* characteristics which always contains a numeric value. There
* are also architected values to indicate errors detected by the
* various programs in the applications suite.
*
         10  WS-ERRH-REASON              PIC 9(4) VALUE ZERO.
         10  WS-ERRH-REASON-X REDEFINES WS-ERRH-REASON
                                         PIC X(4).
*
* If the response contains a numeric value, this contains the
* character representation of the EIBFN value giving rise to
* the exception condition.
*
         10  WS-ERRH-CICS-FUNCTION       PIC 9(5) VALUE ZERO.
         10  WS-ERRH-CICS-FUNCTION-X
                 REDEFINES WS-ERRH-CICS-FUNCTION
                                         PIC X(5).
*
* Since the Error Handler can be LINKed or XCTLed to as well as
* being entered via CICS ABEND handling, this field allows the
* program trapping the error to identify itself.
*
         10  WS-ERRH-PROGRAM             PIC X(8) VALUE SPACES.
*
* This is set by the Error Handler to indicate the number of
* messages it generated from the error information. This is
* intended to allow a program which has LINKed to the Error
* Handler to use the information in a manner it deems suitable.
*
         10  WS-ERRH-NUMBER              PIC 9(4) VALUE ZERO.
*
* The array of messages generated.
*
         10  WS-ERRH-MESSAGES.
             15  WS-ERRH-MESSAGE         PIC X(120) OCCURS 3.

The data is passed to the NACT04 program using the XCTL command:

EXEC CICS XCTL PROGRAM(ABEND-PROGRAM)
               COMMAREA(WS-ERRH-ERROR-COMMAREA)
               RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC

The LINK command is used to connect the NACT01 program to the CRUD (NACT02) program and also to the BRWS (NACT05) program:

EXEC CICS LINK PROGRAM(CRUD-PROGRAM)
               COMMAREA(WS-CRUD-COMMAREA)
               RESP(RESPONSE) RESP2(REASON-CODE)
END-EXEC

LINKAGE SECTION
01 DFHCOMMAREA
    COPY NACCCRUD

EXEC CICS RETURN
END-EXEC

EXEC CICS RETURN TRANSID(EIBTRNID)
                 COMMAREA(DFHCOMMAREA)
END-EXEC

CICS recognizes these exceptional conditions on program control commands:

There are two other program control commands that we’ll mention here, but not cover in detail.

The LOAD command brings a program (any phase (VSE) or load module (MVS) in the list of installed program definitions or in the DFHRPL concatenation) into main storage but doesn’t give it control. This is useful for tables of the type that are assembled and stored in a program library, but doesn’t contain executable code.

The RELEASE command tells CICS that you’ve finished using such a program.

Temporary storage is a set of sequential files, implemented using a VSAM data set on a disk, an area of main storage, or a coupling facility.

The CICS temporary storage facilities allow a task to create a queue of items, stored under a name (16 characters long in CICS TS for OS/390 Version 1.3 and 8 characters in all previous releases) selected by the user program. Each queue, which you can think of as a minature sequential file, exists until some task deletes it. The task that deletes it isn’t usually the same task that created it, although it could be. The queue can contain up to 32,767 items and any number of different tasks can add to it, read it from any point within it, or change the contents of any items in it.

When there is just one item in a queue, we think of this facility as a scratchpad; when there is more than one, we think of it as a queuing facility. The items can be of almost any length up to 32,767 bytes, and they can be of different lengths within the same queue. If you are using the queue as a temporary sequential file, you can think of each item in it as a record.

The simplest use of temporary storage is:

EXEC CICS READQ TS QUEUE(name)
           INTO(data-area)
           RESP(response) RESP2(reason)

There are options to allow you to start where you like, read the next, and find out how many items there are in the queue.

There is another facility in CICS, called transient data, which comes in two flavors—intrapartition and extrapartition:

The WRITEQ TD command writes transient data to a predefined symbolic destination. The syntax is as follows:

EXEC CICS WRITEQ TD QUEUE(name)
                    FROM(data-area)
                    RESP(data-area) RESP2(data-area)
END-EXEC

The options for this command are:

MOVE 2 TO WS-ERRH-NUMBER
EXEC CICS WRITEQ TD QUEUE(LO-ERROR-QUEUE)
                    FROM(MA-STD-INFO)
                    RESP(MA-RESP) RESP2(MA-REASON)
END-EXEC

The CICS ASSIGN command requests values from outside the application program’s local environment. The syntax is as follows:

EXEC CICS ASSIGN ABCODE(data-area)
                 ABPROGRAM(data-area)
                 ASRAINTRPT(data-area)
                 ASRAKEY(cvda)
                 ASRAPSW(data-area)
                 ASRAREGS(data-area)
                 ASRASPC(cvda)
                 ASRASTG(cvda)
                 FCI(data-area)
                 INVOKINGPROG(data-area)
                 NETNAME(data-area)
                 PROGRAM(data-area)
                 RETURNPROG(data-area)
                 STARTCODE(data-area)
                 TERMCODE(data-area)
                 RESP(data-area) RESP2(data-area)
END-EXEC

The options in this command are:

EXEC CICS ASSIGN ABCODE(AA-ABCODE)
                 ABPROGRAM(AA-ABPROGRAM)
                 ASRAINTRPT(AA-ASRAINTRPT)
                 ASRAKEY(AA-ASRAKEY)
                 ASRAPSW(AA-ASRAPSW)
                 ASRAREGS(AA-ASRAREGS)
                 ASRASPC(AA-ASRASPC)
                 ASRASTG(AA-ASRASTG)
                 FCI(AA-FCI)
                 INVOKINGPROG(AA-INVOKINGPROG)
                 NETNAME(AA-NETNAME)
                 PROGRAM(AA-PROGRAM)
                 RETURNPROG(AA-RETURNPROG)
                 STARTCODE(AA-STARTCODE)
                 TERMCODE(AA-TERMCODE)
                 RESP(AA-RESP)
END-EXEC

Having determined how the error handling program received control (through the LINK or XCTL command), the EXEC CICS INQUIRE PROGRAM is used in two ways: one to confirm that this was the program where the error occurred, and secondly, if it is not, then to browse the other programs to see if it can find the culprit.

The syntax of the EXEC CICS INQUIRE PROGRAM is as follows:

EXEC CICS INQUIRE PROGRAM(name)
                  LOADPOINT(ptr-ref) ENTRYPOINT(ptr-ref)
                  LENGTH(data-area)
END-EXEC

IF AA-ASRAKEY = DFHVALUE(USEREXECKEY)

EXEC CICS INQUIRE PROGRAM(AA-ABPROGRAM)
                  ENTRYPOINT(WF-ENTRY-POINT) LOADPOINT(WF-LOAD-POINT)
                  LENGTH(WF-LENGTH)
                  RESP(WF-RES)
END-EXEC

EXEC CICS INQUIRE PROGRAM START
                  RESP(WF-RES)
END-EXEC
PERFORM UNTIL (MA-ABPROGRAM NOT = '*UNKNOWN')
         OR   (WF-RESP = DFHRESP(END))
   EXEC CICS INQUIRE PROGRAM(AA-ABPROGRAM) NEXT
                     ENTRYPOINT(WF-ENTRY-POINT) LOADPOINT(WF-LOAD-POINT)
                     LENGTH(WF-LENGTH)
                     RESP(WF-RES)
   END-EXEC
    ADD WF-LENGTH TO     WF-LOAD-POINT
                  GIVING WF-END-POINT
    IF  AA-ASRAPSW-NSI < WF-END-POINT
    AND AA-ASRAPSW-NSI > WF-LOAD-POINT
        MOVE AA-ABPROGRAM   TO MA-ABPROGRAM
    END-IF
END-PERFORM
EXEC CICS INQUIRE PROGRAM END
                  RESP(WF-RES)
END-EXEC

The DUMP TRANSACTION command dumps all, a series, or any single main storage area related to a task, any or all of the CICS resource definitions (DCT, FCT, SIT, or TCT), or all of these together.

If there is no entry in the system dump table for the specified DUMPCODE, a temporary entry is made. This entry is lost on the next CICS start. The system dump table is described in the CICS Problem Determination Guide. The syntax for this command is:

EXEC CICS DUMP TRANSACTION DUMPCODE(name)
          RESP(data-area)
END-EXEC

The option in this command is:

EXEC CICS DUMP TRANSACTION DUMPCODE(DUMP-CODE)
          RESP(AA-RESP)
END-EXEC

The SYNCPOINT ROLLBACK command backs out any updates to protected resources and returns them to a state they were in before this transaction began. The syntax is as follows:

EXEC CICS SYNCPOINT ROLLBACK
END-EXEC

ROLLBACK specifies that all changes to recoverable resources made by the task since its last syncpoint are to be backed out. This option can be used to tidy up protected resources in a HANDLE ABEND routine, or to revoke database changes after the application program finds irrecoverable errors in its input data.

EXEC CICS SYNCPOINT ROLLBACK
END-EXEC

The WRITE OPERATOR command enables an application to write a message to one or more system consoles and, if necessary, wait for a reply. The command can specify route codes. This is of particular use to application packages that need to issue their own system operator messages.

As a result of a change in the way CICS handles messages sent to the console, text lengths of greater than 113 characters are split into two lines:

EXEC CICS WRITE OPERATOR
          TEXT(data-value)
END-EXEC

The option for this command is:

EXEC CICS WRITE OPERATOR
          TEXT(MA-STD-INFO)
END-EXEC

In addition to the previous commands, the error handling program also uses a number of other commands including those which enable you to add a date and time stamp in a variety of formats to the messages. They are EXEC CICS ASKTIME and EXEC CICS FORMATTIME. Finally, the command EXEC CICS ISSUE DISCONNECT is used when you need to drop the session of the end user’s terminal. For the details of these commands, look in the CICS Application Programming Reference.