In this chapter:
You are now ready to write the COBOL code of the sample application. This chapter describes:
Writing CICS programs in COBOL
Dealing with file handling in CICS programs
Saving data using a scratchpad facility
Moving control from one program to another in the application
The queuing facilities of temporary storage and transient data
Handing errors in you programs
The source programs are listed on the CD-ROM that is packaged with this book. They include a step-by-step description of what the code does. This chapter is about programming the business logic component, other services including Basic Mapping Support (BMS), the CICS supplied services for formatting a green screen, are described in “Programming the 3270 Presentation Logic Component” in Chapter 11.
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 CICSfunction[option(argument)][option...]... [terminator]
The options for this command are:
The terminator is language dependent. For COBOL, the reserved word is either END-EXEC or a period (full stop). The full stop option should be avoided since it ends a COBOL sentence. In PL/I, C, and REXX it is the semicolon.
This way of obtaining a CICS service is identical for PL/I, C, System/390 Assembler, and REXX. However a different approach is used for C++ and Java—for more information see Chapter 7.
The function is the thing you want to do. For example, reading a file is READ, writing to a terminal is SEND. It must be the first value after EXEC CICS.
An option or parameter is some specification that’s associated with the function. The word option is slightly misleading since some of the options are mandatory. Options are expressed as keywords, some need an argument in parentheses after the keyword. The syntax is free format after the function; that is, the parameters (options) may appear in any sequence and layout in the code as shown in the following example:
EXEC CICS READ FILE(filename) RIDFLD(data-area)* Resources[INTO(data-area) SET(ptr-ref)] LENGTH(data-area)* StorageKEYLENGTH(data-value) [GENERIC]* KeysSYSID(systemname) [RBA RRN DEBKEY DEBREC]* OptionsCONSISTENT REPEATABLE* OptionsUNCOMITTED UPDATE [TOKEN(data-area)]* Options[EQUAL GTEQ]* OptionsNOSUSPEND* ConditionsEND-EXEC* Terminator
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)* ResourceRIDFLD(ACCTC)* KeyINTO (ACCTREC)* StorageUPDATE* OptionEND-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-EXECinstead 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:
You cannot use the entries in the ENVIRONMENT DIVISION and the DATA DIVISION that are normally associated with files. In particular, the entire FILE SECTION is omitted from the DATA DIVISION. Put the record formats that usually appear there in either the WORKING-STORAGE or LINKAGE sections. (WORKING-STORAGE is recommended because most COBOL programmers prefer it that way.)
You should not use the COBOL file processing verbs (such as READ, WRITE, OPEN, and CLOSE). Requests for operating system services are all made through CICS, so CICS takes care of opening and closing files for everyone using the system.
You should not use the COBOL console I/O verbs: ACCEPT and DISPLAY, because they interact with the operating system without CICS getting control.
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:
Certain COBOL compiler options (for example, DYNAM, NOLIB, NORENT and NORES), should not be used. Use your installation’s standard setup.
You must take care with some functions (for example, SORT) which, if used, will stop the shared system being shared. There is a full list of the functions to be avoided in the CICS Application Programming Guide.
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.