Compiler Directives and Conditional Compilation

The word "directive" is used loosely, so it helps to separate the three things a compiler can obey outside the ordinary language statements.

IBM’s manuals add a fourth group, the compiler-directing statements: EJECT, SKIP1/SKIP2/SKIP3, TITLE, ENTER, READY/RESET TRACE, PROCESS/CBL and COPY/REPLACE. They are written like ordinary statements (no >>) but have no run-time effect.

The "not documented" cells mean that the chapter "Compiler directives" in the 6.5 Language Reference lists CALLINTERFACE, DATA, INLINE, DEFINE, EVALUATE, IF, JAVA-CALLABLE, JAVA-SHAREABLE, PUSH and POP and nothing else. The table therefore says what the manuals document, not what an unlisted IBM release might accept. The GnuCOBOL cells were verified by compiling.

A compilation variable exists only while the compiler runs. It has a name, and either a value (a number, a string or, on IBM, a boolean) or no value. It is never a data item: it does not exist in WORKING-STORAGE and there is no storage for it at run time.

>>IF selects, before the program is parsed, which source lines are compiled. Lines in a branch that is not selected are not even checked for syntax, and the branches may contain COBOL statements, COPY and REPLACE statements and further directives.

The condition is one of these:

The first example uses the Circulation nightly program. It is a build that differs between the main building and the annex.

The output shows the three outcomes: LOAN-LIMIT was set by the first >>IF (5 is above 3), the AUDIT-TRAIL variable that was defined OFF is not defined, and the BRANCH test chose the first branch.

Source: GnuCOBOL Programmer’s Guide, CDF - Compiler Directing Facility

>>SET CONSTANT name literal defines a variable that can also be used in the DATA DIVISION and PROCEDURE DIVISION as if the literal had been typed. This is the way to give a business rule such as the loan limit one name that appears in the source exactly once. The same example uses >>DISPLAY, a GnuCOBOL directive that prints a message while the program is being compiled.

Source: GnuCOBOL Programmer’s Guide, >>SET

The other forms of >>SET in the manual are SOURCEFORMAT AS FIXED|FREE (the same as >>SOURCE FORMAT IS FIXED|FREE, covered on the format page), FOLDCOPYNAME AS UPPER|LOWER and NOFOLDCOPYNAME, which match the -ffold-copy option and decide how the copybook name is case-folded when a file is looked up. IBM does not document >>SET.

GnuCOBOL defines compiler switches that the program can test with IS SET. The manual calls them predefined compilation variables, and says a variable is defined only when its condition is true. The most useful ones are GNUCOBOL (the compiler is GnuCOBOL), EXECUTABLE and MODULE (the unit contains the main program or does not), DEBUG (the -d flag), TRUNC and NOTRUNC, IBMCOMP and GCCOMP (how the size of a COMP item follows from its PICTURE), HOSTSIGNS, STICKY-LINKAGE and P64. Despite the manual’s wording "defined", the tests that worked in 3.2 are the IS SET ones: IS DEFINED was false for all of them, including GNUCOBOL. The example follows.

The default build selects the GnuCOBOL sizes and TRUNC. With -std=ibm the dialect file turns on IBMCOMP and NOTRUNC, and with -d the DEBUG switch appears.

Output of the same program built with -std=ibm:

Output of the same program built with -d:

Source: GnuCOBOL Programmer’s Guide, Predefined compilation variables

GnuCOBOL: cobc -D name=value (and -D name alone) defines a compilation variable on the command line. The variable can be tested by >>IF and compared with a string or a number. The next program has no definitions of its own.

Built without -D, the program reports that no branch was given.

Built with cobc -x -DBRANCH=ANNEX -DLIMIT=5:

Source: GnuCOBOL manual, cobc options

Two rules were observed in 3.2.

Enterprise COBOL has no -D. The compiler option DEFINE(name=literal) (abbreviation DEF, default NODEFINE) assigns a value to a variable that the program has declared with >>DEFINE name AS PARAMETER; if no such directive exists the option is ignored. An option without a value, DEFINE(name), sets the variable to B'1'. Several can be given and the last wins, NODEFINE after them cancels them all, and when written in a CBL statement the DEFINE options are accepted only for the first program of a batch compile, applying to every program of the file. The = cannot be used with the cob2 command on z/OS UNIX. The following example shows the program and the step that sets the value (z/OS; not run here).

With MAX-LOANS=3 the variable LIMIT is 5, with no option it is also 5. The point of the example is that the program works with and without the option.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide, DEFINE and CONDCOMP compiler options

>>EVALUATE is the multi-branch version of >>IF, in two formats. Format 1 compares one literal or arithmetic expression with each >>WHEN value (a value, or a range with THRU); all operands must be of the same category and THRU needs numeric operands. Format 2 is >>EVALUATE TRUE with a constant conditional expression in each >>WHEN. The first branch that matches is included, >>WHEN OTHER is the last resort, and if nothing matches no branch is included. A string comparison is character by character on the binary value and strings of different lengths are never equal. The following z/OS-only fragment selects the housekeeping of the nightly run from a numeric level that comes from the DEFINE option (z/OS; not run here).

Source: Enterprise COBOL for z/OS 6.5 Language Reference, EVALUATE directive

GnuCOBOL 3.2 does not implement the directive. Run through cobc, a program with >>EVALUATE compiles with four warnings and both branches are compiled, which is rarely what the author wanted. This is a deliberately wrong example for GnuCOBOL.

The first warning is shown (the other three directive lines produce the same message); the program then printed both branches.

Source: GnuCOBOL Programmer’s Guide, CDF - Compiler Directing Facility

Use >>IF and >>ELIF in GnuCOBOL, which are portable to the standard text.

>>TURN exception-name CHECKING ON [WITH LOCATION] and >>TURN exception-name CHECKING OFF switch the run-time checking of an exception class for the statements that follow. It is the source-level counterpart of options such as -debug and, on z/OS, SSRANGE. In this example only one statement is checked; the exception name EC-BOUND-SUBSCRIPT covers subscripts outside the table. The write at slot 5 of a three-element table is stopped by the run-time library, and the second DISPLAY is never reached. (An unchecked write to the same subscript would silently overwrite neighbouring storage, which is why the example does not do that.)

Source: GnuCOBOL Programmer’s Guide, >>TURN

A name that is not a valid exception name is rejected at compile time: spelling it EC-BOUNDARY-SUBSCRIPT while preparing this page produced "invalid exception-name". IBM does not document >>TURN; in Enterprise COBOL the corresponding behaviour is the SSRANGE compiler option for the whole program, so switch it on in the CBL statement or the step PARM.

>>CALL-CONVENTION (GnuCOBOL) chooses how program names in CALL are treated. COBOL (the default) maps the name as a COBOL program name, EXTERN treats it as an external reference, STATIC calls it as an included element, and STDCALL is listed without an explanation of its effect. The example calls the C library function getpid as an external function and returns to the default convention.

Source: GnuCOBOL Programmer’s Guide, >>CALL-CONVENTION

Enterprise COBOL names the same idea >>CALLINTERFACE with the suboptions DLL, DYNAMIC and STATIC; it affects CALL and function/procedure-pointer SET statements until the next >>CALLINTERFACE, overrides the DLL and DYNAM compiler options while it has a suboption, can appear in the PROCEDURE DIVISION only, and has no effect on CANCEL. Written without a suboption it returns control to the compiler options.

A debugging line is a source line that is compiled only in a debugging build. In the standard it is a line with a D in the indicator column (column 7), active when WITH DEBUGGING MODE is written in the SOURCE-COMPUTER paragraph; the 6.5 Language Reference describes exactly that and has no >>D. GnuCOBOL accepts the same D line, and also the free-floating directive >>D, which makes the rest of the line a debugging line. They are active when cobc is run with -fdebugging-line. Without it the line is a comment. That is why a debug DISPLAY costs nothing in production.

Built normally, the debug line is ignored.

Built with -fdebugging-line:

Source: GnuCOBOL Programmer’s Guide, >>D

On z/OS the equivalent is a D in column 7 plus WITH DEBUGGING MODE in SOURCE-COMPUTER; there is no compile-time switch other than that clause in the program.

IBM’s compiler-directing statements affect only the source listing. EJECT starts the next source statement on a new page, SKIP1, SKIP2 and SKIP3 insert one, two or three blank lines, and TITLE literal prints a title at the top of every page (without it the compiler prints its own identification and release). They must stand alone on a line, may end in a period, must come after the CBL statements, and have no effect on the compiled program. GnuCOBOL accepts the same words only in the IBM dialect (the manual describes >>PAGE as the directive that allows these IBM paging controls); in the default dialect EJECT is an unknown statement. This deliberately wrong example (same source, two dialects) shows the difference.

With the default dialect, cobc rejects it.

With -std=ibm the same file compiles and runs:

Source: Enterprise COBOL for z/OS 6.5 Language Reference, Compiler-directing statements

>>LISTING ON|OFF is a GnuCOBOL directive that turns the program listing on and off; it compiled without a warning in the test and is only meaningful when a listing is requested.

A PROCESS statement, or its synonym CBL, gives compiler options inside the source. It is placed before the IDENTIFICATION DIVISION header of the outermost program and before any comment lines or compiler-directing statements. It may start in column 1 or later, or in column 8 or later if there is a six-character sequence field; it must end at or before column 72; options are separated by a comma or a blank and nothing may be put between an option and its suboption; several statements may follow each other, with nothing between them, but one statement cannot be continued onto the next. The installation can inhibit them through the default options module, in which case the compiler issues an error. The example sets the options of the nightly update (z/OS; not run here).

CONDCOMP(SKIPSRC) (abbreviation CC(SKIPS)) tells the compiler not to show, and not to write to the MDECK output or SYSMDECK, the source lines in the branches that were not selected; the default CONDCOMP(NOSKIPSRC) shows them in the listing as comments. The Programming Guide has a worked listing of both. A DEFINE option written on a CBL statement applies to every program of a batch compile only if it is on the first program.

GnuCOBOL has no equivalent statement. cobc meets CBL at the start of a file, prints "ignoring unknown directive" and goes on, so options placed there are silently not applied. This example shows the real message, with the program compiling and running anyway.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide, PROCESS (CBL) statement

The 6.5 Language Reference documents four more directives that have no counterpart in GnuCOBOL: >>DATA 31|64 (storage location of WORKING-STORAGE items under LP(64)), >>INLINE ON|OFF (whether PERFORM of a procedure may be inlined by the optimizer), and >>JAVA-CALLABLE and >>JAVA-SHAREABLE for non-object-oriented COBOL and Java interoperability. They are listed here so the table above is complete and are not exercised on this page.

The two diagnostics that need their sources are the duplicate definition and the use of a -D name in code. The first is the file with a >>DEFINE BRANCH AS "MAIN" plus a following test of BRANCH, built with -DBRANCH=OTHER:

The second is a data description that refers to LOAN-LIMIT while the name was only given on the command line as -DLOAN-LIMIT=5:

And the failed AND:

Source: GnuCOBOL Programmer’s Guide, CDF - Compiler Directing Facility