COBOL with embedded SQL and CICS

Much COBOL is not plain COBOL. Programs that use a database or a transaction monitor carry blocks that start with EXEC and end with END-EXEC. COBOL itself has no idea what is inside: a precompiler or translator reads the source first, replaces each block by CALL statements and data items, and hands ordinary COBOL to the compiler. (IBM’s newer compilers integrate that step as a coprocessor, with options such as SQL and CICS.) Files for the precompilers often use their own extension: .pco for Oracle’s Pro*COBOL. The viewer names such a file “COBOL program with embedded SQL” or “with CICS commands” from its text.

EXEC SQL

       WORKING-STORAGE SECTION.
           EXEC SQL INCLUDE SQLCA END-EXEC.
           EXEC SQL BEGIN DECLARE SECTION END-EXEC.
       01  HV-ID       PIC S9(9) COMP.
       01  HV-NAME     PIC X(30).
       01  HV-NAME-IND PIC S9(4) COMP.
           EXEC SQL END DECLARE SECTION END-EXEC.
           EXEC SQL DECLARE C1 CURSOR FOR
               SELECT ID, NAME FROM CUSTOMER WHERE REGION = :HV-REGION
           END-EXEC.
       PROCEDURE DIVISION.
           EXEC SQL WHENEVER SQLERROR GO TO SQL-ERROR END-EXEC.
           EXEC SQL OPEN C1 END-EXEC.
           PERFORM UNTIL SQLCODE NOT = 0
               EXEC SQL FETCH C1 INTO :HV-ID, :HV-NAME :HV-NAME-IND END-EXEC
               IF SQLCODE = 0 DISPLAY HV-NAME END-IF
           END-PERFORM.
           EXEC SQL CLOSE C1 END-EXEC.
           EXEC SQL COMMIT END-EXEC.

Host variables are ordinary COBOL items named with a colon in the SQL text: :HV-ID. An indicator variable follows (:HV-NAME :HV-NAME-IND or :HV-NAME INDICATOR :HV-NAME-IND) and holds -1 for null. Group items can stand for a list of columns.
The SQL communication area SQLCA (or SQLCODE and SQLSTATE on their own) is brought in with EXEC SQL INCLUDE SQLCA END-EXEC. SQLCODE is 0 for success, +100 for no row and negative for an error.
EXEC SQL INCLUDE name END-EXEC reads a member (often one generated by the DB2 DCLGEN tool, holding a table declaration and its host structure); a plain COPY reads text the precompiler does not see.
Statements: SELECT … INTO, INSERT, UPDATE, DELETE, DECLARE … CURSOR, OPEN, FETCH, CLOSE, COMMIT, ROLLBACK, CONNECT, PREPARE, EXECUTE [IMMEDIATE], DESCRIBE, CALL, LOCK TABLE, WHENEVER (SQLERROR, SQLWARNING, NOT FOUND, each to CONTINUE or GO TO).
SQL comments are -- to the end of the line; the SQL text may use its own quote rules and the usual COBOL continuation in fixed format.
Tools: IBM Db2 precompiler or coprocessor; Oracle Pro*COBOL (.pco); Micro Focus OpenESQL; the GnuCOBOL add-ons ocesql and Gix-IDE; PostgreSQL has its own ecpg for C only.
The viewer colours the words of the SQL list (SELECT, FROM, WHERE, FETCH…) as keywords, a :name as a variable and a -- remark as a comment; it does not parse the SQL.

EXEC CICS

       WORKING-STORAGE SECTION.
       01  WS-RESP     PIC S9(8) COMP.
       01  WS-RECORD.
           05  WS-KEY     PIC X(8).
           05  WS-DATA    PIC X(72).
       LINKAGE SECTION.
       01  DFHCOMMAREA PIC X(100).
       PROCEDURE DIVISION.
           EXEC CICS RECEIVE MAP('MAP1') MAPSET('MAPS1') INTO(MAP1I)
                RESP(WS-RESP) END-EXEC.
           EXEC CICS READ FILE('CUSTFILE') INTO(WS-RECORD)
                RIDFLD(WS-KEY) LENGTH(LENGTH OF WS-RECORD) RESP(WS-RESP)
           END-EXEC.
           IF WS-RESP = DFHRESP(NOTFND)
               MOVE 'NOT FOUND' TO MSGO
           END-IF.
           EXEC CICS RETURN TRANSID('CUST') COMMAREA(WS-KEY) END-EXEC.

CICS is IBM’s online transaction monitor. A command is EXEC CICS verb option(value)… END-EXEC; the options are words with a value in parentheses (MAP('M1'), FROM(X), LENGTH(N)).
The translator adds the execute interface block DFHEIBLK (fields such as EIBTRNID, EIBCALEN, EIBAID, EIBRESP), the area DFHCOMMAREA for data passed between runs of a transaction, and the CICS call to DFHEI1.
Command groups: terminal (SEND MAP, RECEIVE MAP, SEND TEXT, CONVERSE), files (READ, WRITE, REWRITE, DELETE, STARTBR, READNEXT, READPREV, ENDBR), program control (LINK, XCTL, RETURN, ABEND, HANDLE CONDITION, HANDLE ABEND), storage and queues (GETMAIN, FREEMAIN, READQ TS, WRITEQ TD), time and syncpoint (ASKTIME, FORMATTIME, SYNCPOINT), and many more.
Error handling: RESP(item) and RESP2 return codes tested against the translator functions DFHRESP(NORMAL) and DFHRESP(NOTFND); NOHANDLE suppresses the default abend. DFHVALUE turns names such as RED into numbers.
Screen layouts come from BMS map assembly, which also writes COBOL copybooks (MAP1I, MAP1O) that the program includes with COPY.
COBOL features CICS programs may not use: ACCEPT from console, normal file I/O verbs (use the CICS commands), STOP RUN (use RETURN), SORT; some are rules of the monitor, not of the language.
IMS databases use EXEC DLI or CALL 'CBLTDLI'. The viewer colours EXEC DLI like CICS and any other EXEC as generic text between the markers.

.CBL File Format – Embedded SQL and CICS

EXEC SQL

EXEC CICS