.CBL File Format – Compiler directives

COPY

           COPY CUSTREC.
           COPY CUSTREC OF MYLIB.
           COPY "orders.cpy" SUPPRESS.
           COPY ACCOUNT REPLACING ==:PFX:== BY ==WS==
                                  LEADING ==OLD-== BY ==NEW-==.

• Syntax: COPY name [{OF | IN} library] [SUPPRESS [PRINTING]] [REPLACING …] . The final full stop is required.
• The text of the copybook replaces the statement, may itself hold COPY statements, and may appear anywhere that text could appear (in the data division for record layouts, in the procedure division for code).
• REPLACING takes pairs of ==pseudo-text== BY ==pseudo-text==, or words, identifiers and literals on either side, and in 2002 LEADING / TRAILING to change the start or end of words. The common idiom is a record copybook with a tag such as :TAG: that each program replaces so one layout can be used twice.
• Finding the copybook. GnuCOBOL: the directories of the -I option and the COB_COPY_DIR environment variable, trying the extensions .cpy, .CPY, .cbl, .cob (-ffold-copy or >>SET FOLDCOPYNAME controls name case). Micro Focus: COPYPATH and the COPYEXT directive. IBM z/OS: the library named on SYSLIB in JCL, with the member name as written; the OF library phrase names a DD (COPY X OF MYLIB reads DD MYLIB).
• IBM also has BASIS, INSERT and DELETE (library maintenance with changes by sequence number) and COPY of an SQL include via EXEC SQL INCLUDE.
• A copybook can hold *> and >> lines; in fixed format it has its own column layout, which must match the surrounding source unless a directive switches it.

REPLACE

REPLACE ==a== BY ==b== ==c== BY ==d==. turns on text replacement for every later source line, up to the next REPLACE or REPLACE OFF.. Both sides are pseudo-text (or LEADING/TRAILING partial words). REPLACE ALSO adds to the active set and REPLACE LAST OFF removes the most recent addition (2002, GnuCOBOL). Replacement works on text before parsing, so it can build statements or change a prefix throughout a program; a replaced word does not rescan.

       REPLACE ==:MAX:== BY ==500==
               ==DEBUG-PRINT== BY ==DISPLAY==.
       01  TBL.  05 E OCCURS :MAX: TIMES PIC 9.
       REPLACE OFF.

The >> directives (2002 and later)

A compiler directive starts with >> in column 8 or later (fixed) or anywhere (free) and takes the rest of the line. The ISO set has >>SOURCE, >>DEFINE, >>IF, >>ELSE, >>ELIF, >>END-IF, >>EVALUATE, >>WHEN, >>END-EVALUATE, >>CALL-CONVENTION, >>TURN, >>PAGE, >>LISTING and >>LEAP-SECONDS. The table is what GnuCOBOL documents:

GnuCOBOL predefines compilation variables, among them DEBUG, EXECUTABLE, MODULE, GNUCOBOL, OPENCOBOL, GCCOMP, IBMCOMP, TRUNC, NOTRUNC, STICKY-LINKAGE, HOSTSIGNS and P64. A definition ends at END PROGRAM.

       >>DEFINE DEBUG-MODE AS 1
       >>IF DEBUG-MODE IS DEFINED
           DISPLAY "trace: entering MAIN"
       >>ELSE
           CONTINUE
       >>END-IF
       >>IF GNUCOBOL IS DEFINED
       >>DISPLAY compiled with GnuCOBOL
       >>END-IF

IBM Enterprise COBOL: CBL, PROCESS and listing statements

• CBL and PROCESS cards come before the IDENTIFICATION DIVISION and carry compiler options: CBL LIB,APOST,NOSEQ,XREF,TEST(NONE), PROCESS ARITH(EXTEND),TRUNC(BIN). Several cards may follow one another, and they sit in the first 72 columns. They are the same as the options in the JCL PARM.
• *CBL and *CONTROL in column 7 switch listing options (*CBL NOSOURCE) in the middle of a program.
• EJECT, SKIP1, SKIP2, SKIP3, TITLE "text" control the listing (page eject, blank lines, header). TITLE is a card, not a word users may name items with, when it is the first word of a line.
• BASIS, INSERT, DELETE change a library member by sequence number before compiling (older style).
• Recent IBM Enterprise COBOL 6 releases accept >>SOURCE FORMAT and conditional-compilation directives of the 2002 kind (check the release notes of the version you use). The IBM names for options (ARITH, CODEPAGE, DYNAM, NUMPROC, OPTIMIZE, RENT, SQL, TRUNC…) are listed in IBM’s Programming Guide; they are not described on these pages.

CBL LIB,APOST,NOSEQ
       PROCESS DYNAM,NUMPROC(PFD)
       IDENTIFICATION DIVISION.
       PROGRAM-ID. PAYROLL.

Micro Focus: $SET and $IF

A line with $ in column 1 (or column 7 in fixed format) is a directive: $SET ANS85 MF NOTRUNC, $SET SOURCEFORMAT"FREE", $SET COPYEXT"cpy,cbl", $SET REMOVE(ENTRY). Conditional compilation is $IF name SET / DEFINED … $ELSE … $END (also $ELIF, $ELSE-IF), with $DEFINE and $DISPLAY. A @OPTIONS line is read as more directives. GnuCOBOL accepts a good part of these ($SET, $IF, $DEFINE, $DISPLAY, $END, $ELSE, $ELIF) and a few more with warnings, among them ADDRSV, ADDSYN, ASSIGN, BOUND, CALLFH, COMP1, FOLDCOPYNAME, MAKESYN, OVERRIDE, REMOVE, SOURCEFORMAT and SSRANGE. The complete directive list of Micro Focus is in its Compiler Directives reference, which I could not read.

Other dialects

• Tandem (HP NonStop) COBOL85 has ? in column 1 for compiler directives: ?SOURCE $SYSTEM.LIB.COPYBK, ?SECTION name, ?SYMBOLS, ?NOLIST, ?SETTOG, ?IF…?ENDIF.
• ACUCOBOL-GT is driven from the compiler’s command line and a configuration file; I did not find its directive list in a source I could read.
• Pro*COBOL and the CICS translator read EXEC SQL INCLUDE and EXEC CICS text before the compiler does (see Embedded SQL and CICS).