CDF - Compiler Directing Facility

The Compiler Directing Facility, or CDF, is a means of controlling the compilation of GnuCOBOL programs. CDF provides a mechanism for dynamically setting or resetting certain compiler switches, introducing new source code from one or more source code libraries, making dynamic source code modifications and conditionally processing or ignoring source statements altogether. This is accomplished via a series of special CDF statements and directives that will appear in the program source code. When the compiler is operating in Fixed Format Mode, all CDF statements must begin in column seven (7) or beyond.

There are two types of supported CDF statements in GnuCOBOL — Text Manipulation Statements and Compiler Directives.

The CDF text manipulation statements COPY and REPLACE are used to introduce new code into programs either with or without changes, or may be used to modify existing statements already in the program. Text manipulation statements are always terminated with a period.

CDF compiler directives, denoted by the presence of a >> character sequence as part of the statement name itself, influence the process of program compilation. CDF compiler directives are never terminated with a period.

The compiler command-line option -D offers additional control (see cobc - The GnuCOBOL Compiler).

+-------------------------------------------------------------------------------------+
| TEXT MANIPULATION STATEMENTS                                                        |
+-----------------------+-------------------------------------------------------------+
| COPY                  | Import copybooks (source code) into a program               |
| REPLACE               | Change all or part of program source code elements          |
+-----------------------+-------------------------------------------------------------+
| COMPILER DIRECTIVES                                                                 |
+-----------------------+-------------------------------------------------------------+
| >>CALL-CONVENTION     | How to treat references to program names and other details  |
|                       | for interacting with a function or program                  |
| >>COBOL-WORDS         | Allows a new word to be recognised by the compiler          |
| >>D                   | Mark floating debug lines that will be compiled or not      |
| >>DEFINE              | Create CDF variable for other CDF statements or a constant  |
| >>DISPLAY             | Display a text message during compilation                   |
| >>IF                  | Causes the compiler to process or ignore COBOL source       |
|                       | statements, CDF text manipulation statements or CDF         |
|                       | directives based on CDF variables                           |
| >>LEAP-SECONDS        | Syntactically recognized but is otherwise non-functional    |
| >>LISTING             | Allows the program listing to be de-activated               |
| >>PAGE                | Page ejection and documentation for the source listing      |
| >>REF-MOD-ZERO-LENGTH | Specifies whether resultant data items may have zero-length |
| >>SET                 | Provides an alternate means of performing the actions of    |
|                       | >>DEFINE and >>SOURCE directives, as well as a means of     |
|                       | controlling the compiler's -free switch, -fixed switch and  |
|                       | -ffold-copy switch from within program source code          |
| >>SOURCE              | Puts the compiler into FIXED / FREE source-code format mode |
| >>TURN                | The directive will activate or de-activate exception checks |
+-----------------------+-------------------------------------------------------------+

COPY

CDF COPY Statement Syntax

=======================================================================

{ COPY     }   copybook-name
{ ~~~~     }
{ INCLUDE  }
{ ~~~~~~~  }

      [ IN|OF library-name ]
        ~~ ~~
      [ SUPPRESS PRINTING ]
        ~~~~~~~~
      [ REPLACING { Phrase-Clause | String-Clause }... ] .
        ~~~~~~~~~

=======================================================================

CDF COPY Phrase-Clause Syntax

=======================================================================

 { ==pseudo-text-1== } BY { ==pseudo-text-2== }
 { identifier-1      } ~~ { identifier-2      }
 { literal-1         }    { literal-2         }
 { word-1            }    { word-2            }

=======================================================================

CDF COPY String-Clause Syntax

=======================================================================

 [ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2==
   ~~~~~~~ ~~~~~~~~                      ~~

=======================================================================

  1. COPY statements are used to import copybooks (see Copybooks) into a program.

  2. COPY statements may be used anywhere within a COBOL program where the code contained within the copybook would be syntactically valid.

  3. The optional SUPPRESS clause (with or without the optional PRINTING reserved word) is valid syntactically but is non-functional. It is supported to facilitate compatibility with source code written for other versions of COBOL.

  4. There is no difference between the use of the word IN and the word OF — use the one you prefer.

  5. A period is absolutely mandatory at the end of every COPY statement, even if the statement occurs within the scope of another one where a period might appear disruptive, such as within the scope of an IF (see IF) statement. This mandatory period at the end of the statement does not, however, affect the statement scope in which the COPY occurs.

  6. Both <pseudo-text-2> and <partial-word-2> may be null.

  7. All COPY statements are located and the contents of the corresponding copybooks inserted into the program source code before the actual compilation process begins. If a copybook contains a COPY statement, the copybook insertion process will be repeated to resolve the embedded COPY. This will continue until no unresolved COPY statements remain. At that point, actual program compilation will begin.

  8. See Locating Copybooks, for the specific rules on how copybooks are located by the compiler.

  9. The optional REPLACING clause allows for one or more of either of the following kinds of text replacements to be made:

    <Phrase-Clause>

    Replacement of one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:

    • This option cannot be used to replace part of a word, identifier or literal.

    • Whatever precedes the BY will be referred to here as the search string.

    • Single-item search strings can be specified by coding the identifier-1, literal-1 or word-1 being replaced.

    • Multiple-item search strings can be specified using the ==pseudo-text-1== option. For example, to replace all occurrences of UPON PRINTER, you would specify ==UPON PRINTER==.

    • The replacement string, which follows the BY, may be specified using any of the four options.

    • If the replacement string is a multiple-item phrase or is to be deleted altogether, you must use the ==pseudo-text-2== option. If pseudo-text-2 is null (in other words, the replacement text is specified as ====), all encountered occurrences of the search string will be deleted.

    <String-Clause>

    Using this, you may replace character sequences that occur at the beginning (see LEADING) or end (see TRAILING) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", code LEADING ==0100-== BY ==020-==. To simply remove all "0100-" prefixes from words, code LEADING ==0100-== BY ====.

REPLACE

CDF REPLACE Statement (Format 1) Syntax

=======================================================================

 REPLACE [ ALSO ] { Phrase-Clause | String-Clause }... .
 ~~~~~~~   ~~~~

=======================================================================

CDF REPLACE Statement (Format 2) Syntax

=======================================================================

 REPLACE [ LAST ] OFF .
 ~~~~~~~   ~~~~   ~~~

=======================================================================

CDF REPLACE Phrase-Clause Syntax

=======================================================================

 { ==pseudo-text-1== } BY { ==pseudo-text-2== }
                       ~~

=======================================================================

CDF REPLACE String-Clause Syntax

=======================================================================

 [ LEADING|TRAILING ] ==partial-word-1== BY ==partial-word-2==
   ~~~~~~~ ~~~~~~~~                      ~~

=======================================================================

  1. The REPLACE statement provides a mechanism for changing all or part of one or more GnuCOBOL statements.

  2. A period is absolutely mandatory at the end of every REPLACE statement (either format), even if the statement occurs within the scope of another one where a period might appear disruptive (such as within the scope of an IF (see IF) statement; the period will not, however, affect the statement scope in which the REPLACE occurs.

  3. The following points apply to Format 1 of the REPLACE statement:

    1. Format 1 of the REPLACE statement can be used to make changes to program source code in much the same way as the REPLACING option of the COPY statement can, via these options:

      <Phrase-Clause>

      Replace one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:

      • This option cannot be used to replace part of a word, identifier or literal.

      • Whatever precedes the BY will be referred to here as the search string.

      • Search strings on REPLACE are always specified using the ==pseudo-text-1== option. For example, to replace all occurrences of UPON PRINTER, you would specify ==UPON PRINTER==.

      • The replacement string, which follows the BY, is specified using the ==pseudo-text-2== option. If pseudo-text-2 is null (in other words, the replacement text is specified as ====), all encountered occurrences of the search string will be deleted.

      <String-Clause>

      Using this, you may replace character sequences that occur at the beginning (see LEADING) or end (see TRAILING) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", code LEADING ==0100-== BY ==020-==. To simply remove all "0100-" prefixes from words, code LEADING ==0100-== BY ====.

    2. Once a Format 1 REPLACE statement is encountered in the currently-compiling source file, Replace Mode becomes active, and the change(s) specified by that statement will be automatically made on all subsequent source statements the compiler reads from the file.

    3. Replace Mode remains in-effect — continuing to make source code changes — until another Format 1 REPLACE is encountered, the end of currently compiling program source file is reached or a Format 2 REPLACE statement is encountered.

    4. When a Format 1 REPLACE statement with the ALSO keyword is encountered without Replace Mode being currently active, the effect will be as if the ALSO had not been specified. If Replace Mode already was in effect, the effect will be to “push” the current change specification(s) onto the top of a stack and add the specification(s) of the new statement to those that were already in effect.

    5. When a Format 1 REPLACE without the ALSO keyword is encountered, any stacked change specification(s), if any, will be discarded and the currently in-effect change specification(s), if any, will be replaced by those of the new statement.

    6. When the end of the currently-compiling source file is reached, Replace Mode is deactivated and any stacked replace specifications will be discarded — compilation of the next source file (if any) will begin with Replace Mode inactive and no change specification(s) on the stack.

  4. The following points apply to Format 2 of the REPLACE statement:

    1. If Replace Mode is currently inactive, the Format 2 REPLACE statement will be ignored.

    2. If Replace Mode is currently active, a REPLACE OFF. will deactivate Replace Mode and discard any replace specification(s) on the stack. The compiler will henceforth operate as if no REPLACE had ever been encountered, until such time as another Format 1 REPLACE is encountered.

    3. If Replace Mode is currently active, a REPLACE LAST OFF. will replace the current replace specification(s) with those popped off the top of the stack. If there were no replace specification(s) on the stack, the effect will be as if a REPLACE OFF. had been coded.

>>CALL-CONVENTION

CDF >>CALL-CONVENTION Syntax

=======================================================================

 >>CALL-CONVENTION    { COBOL   }
 ~~~~~~~~~~~~~~~~~    { EXTERN  }
                      { STDCALL }
                      { STATIC  } 

=======================================================================

This directive instructs the compiler how to treat references to program names and may be used to determine other details for interacting with a function or program. There are four options with COBOL being the default.

COBOL

The program name is treated as a COBOL word that maps to the externalised name program to be called, cancelled or referenced in the program-address-identifier, applying the same mapping rules as for a program name for which no AS phrase is specified. (The is the default.)

EXTERN

The program name is treated as an external reference.

STDCALL

Allows system standard calling conventions (as opposed to GnuCOBOL calling conventions) to be used when calling a subroutine. The definition of what constitutes “system standard” may vary from operating system to operating system. Use of this requires special knowledge about the linkage requirements of subroutines you are intending to CALL. Subroutines written in GnuCOBOL do not need this option.

STATIC

Causes the linkage to the subroutine to be performed in such a way as to require the subroutine to be statically-linked with the calling program. Note that this enables static-linking to be used on a subroutine-by-subroutine selective basis. Or in other words - The program name is called as a included element and not dynamically which is the normal default.

>>COBOL-WORDS

CDF >>COBOL-WORDS Directive Syntax

=======================================================================

 >>COBOL-WORDS { EQUATE keyword WITH alias      } 
 ~~~~~~~~~~~~~ { ~~~~~  ~~~~~~~ ~~~~ ~~~~~      }
               { UNDEFINE keyword               }
               { ~~~~~~~~ ~~~~~~~               }
               { SUBSTITUTE keyword BY new-word }
               { ~~~~~~~~~  ~~~~~~~ ~~ ~~~~~~~~ }
               { RESERVE new-word               }
                 ~~~~~~~ ~~~~~~~~ 

=======================================================================

The directive allows a new word to be recognised by the Cobol compiler and can be used multiple times.

  1. COBOL-WORDS EQUATE keyword WITH alias makes alias a synonym for keyword.

  2. COBOL-WORDS UNDEFINE keyword keyword is removed from the COBOL grammar (can then be a user-defined word). Use of it in a program as normal keyword will provoke a syntax error from the compiler, which may be used to enforce not using its syntax.

  3. COBOL-WORDS SUBSTITUTE keyword BY new-word keyword is deleted as a keyword from the grammar, replaced by new-word. keyword may thereafter be used as a user-defined word.

  4. COBOL-WORDS RESERVE new-word Treat new-word as a COBOL keyword. It cannot be used by the program, either as a keyword or as a user-defined word.

>>D

CDF >>D Directive Syntax

=======================================================================

 >>D  program-source-text-1
 ~~~

=======================================================================

The directive removes all floating debug lines if debug mode not active. Otherwise will ignore the directive part of the line. These debug lines will only be compiled if the compiler switch -fdebugging-line is used: ‘cobc yourprogram.cob -x -fdebugging-line’

Note that it will also be compiled if WITH DEBUGGING MODE is coded.

These debug lines will be compiled with at least one of the following ways:

if the compiler switch -fdebugging-line is used as following sample: ‘cobc yourprogram.cob -x -fdebugging-line’ by adding the WITH DEBUGGING MODE clause to the SOURCE-COMPUTER paragraph. if you set the run-time environment variable COB_SET_DEBUG.

A handy trick for those that like to write code that be compiled in both FIXED and FREE forms, is to place the directive in column 5, 6 and 7 meaning you write DEBUG line compiler directives with the >>D starting in column 5 (so the D ends up in column 7 useful for FIXED mode):

>>DEFINE

CDF >>DEFINE Directive Syntax

=======================================================================

Format 1

>>DEFINE cdf-variable-1 AS { { literal-1 } [ OVERRIDE ] }
~~~~~~~~                   { { PARAMETER }   ~~~~~~~~   }
                           {   ~~~~~~~~~                }
                           {   OFF                      }
                               ~~~                     

Format 2 (archaic)

>>DEFINE CONSTANT cdf-variable-1 AS literal-1
~~~~~~~~ ~~~~~~~~ 

=======================================================================

Use the >>DEFINE CDF directive to create CDF variables and (optionally) assign them either literal or environment variable values.

  1. The reserved word AS is optional and may be included, or not, at the discretion of the programmer. The presence or absence of this word has no effect upon the program.

  2. CDF variables defined in this way become undefined once an END PROGRAM or END FUNCTION directive is encountered in the input source.

  3. The >>DEFINE CDF directive is one way to create CDF variables that may be processed by other CDF statements such as >>IF (see >>IF). The >>SET CDF directive (see >>SET) provides another way to create them.

  4. CDF variable names follow the rules for standard GnuCOBOL user-defined names, and may not duplicate any CDF reserved word.

  5. The PARAMETER option is used to create a variable whose value is that of the environment variable of the same name. Note that this value assignment occurs at compilation time, not program execution time.

  6. In the absence of the OVERRIDE option, <cdf-variable-1> must not yet have been defined. When the OVERRIDE option is specified, <cdf-variable-1> will be created with the specified value, if it had not yet been defined. If it had already been defined, it will be redefined with the new value.

  7. The OFF option is used to create a variable without assigning it any value. Following a DEFINE directive in which the OFF phrase is specified, compilation-variable-name-1 shall not be used except in a defined condition [where it evaluates as not to be defined].

  8. GnuCOBOL also accepts the following "archaic" definition:

    >>DEFINE CONSTANT cdf-variable-1 AS literal-1 .

    In that case the <cdf-variable-1> that is created may be used within your regular COBOL code as if it were a literal value. Without this option, the <cdf-variable-1> may only be referenced on other CDF statements. Note: Using this archaic feature to define a constant in a program is not recommended. Instead, it is highly advisable to use the ISO Standard feature (see 01-Level Constants) or the common extension (see 78-Level Data Items).

  9. CDF variable names may duplicate COBOL reserved words, provided the CONSTANT option is not specified, but such names are not recommended.

>>DISPLAY

CDF >>DISPLAY Directive Syntax

=======================================================================

 >>DISPLAY source-text [ VCS = version-string ]
 ~~~~~~~~~               ~~~

=======================================================================

The directive is a v1.0 extension and will display messages during compilation.

>>IF

CDF >>IF Directive Syntax

=======================================================================

 >>IF CDF-Conditional-Expression-1
 ~~~~     [ Program-Source-Lines-1 ]

 [ >>ELIF | >>ELSE-IF CDF-Conditional-Expression-2
   ~~~~~~   ~~~~~~~~~     [ Program-Source-Lines-2 ] ]...

 [ >>ELSE
   ~~~~~~ [ Program-Source-Lines-3 ] ]

 >>END-IF
 ~~~~~~~~

=======================================================================

CDF-Conditional-Expression Syntax

=======================================================================

 { cdf-variable-1 } IS [ NOT ] { DEFINED                      }
 { literal-1      }      ~~~   { ~~~~~~~                      }
                               { SET                          }
                               { ~~~                          }
                               { CDF-RelOp { cdf-variable-2 } }
                               {           { literal-2      } }

=======================================================================

CDF-RelOp Syntax

=======================================================================

 >=    or    GREATER THAN OR EQUAL TO
             ~~~~~~~      ~~ ~~~~~
 >     or    GREATER THAN
             ~~~~~~~
 <=    or    LESS THAN OR EQUAL TO
             ~~~~      ~~ ~~~~~
 <     or    LESS THAN
             ~~~~
 =     or    EQUAL TO
             ~~~~~
 <>    or    EQUAL TO (with "NOT")
             ~~~~~

=======================================================================

The >>IF CDF directive causes the GnuCOBOL compiler to process or ignore COBOL source statements, CDF text-manipulation statements and CDF directives depending upon the value of one or more conditional expressions based upon CDF variables.

  1. The reserved words IS, THAN and TO are optional and may be omitted. The presence or absence of these words has no effect on the program.

  2. Each >>IF directive must be terminated by an >>END-IF directive.

  3. There may be any number of >>ELIF clauses following an >>IF, including zero.

  4. There may be no more than one >>ELSE clause following an >>IF. When >>ELSE is used, it must follow the >>IF and all >>ELIF clauses.

  5. Only one of the <Program-Source-Lines-n> block of statements that lie within the scope of the >>IF … >>END-IF may be processed by the compiler. Which one (if any) that gets processed will be decided as follows:

    1. Each <CDF-Conditional-Expression-n> will be evaluated, in turn, in the sequence in which they are coded in the >>IF statement and any >>ELIF clauses that may be present until one evaluates to TRUE. Once one of them evaluates to TRUE, the <Program-Source-Lines-n> block of code that corresponds to the TRUE <CDF-Conditional-Expression-n> will be the one that is processed. All others within the >>IF->>END-IF scope will be ignored.

    2. If no <CDF-Conditional-Expression> evaluates to TRUE, and there is an >>ELSE clause, the <Program-Source-Lines-3> block of statements following the >>ELSE clause will be processed by the compiler and all others within the >>IF->>END-IF scope will be ignored.

    3. If no <CDF-Conditional-Expression-n> evaluates to TRUE and there is no >>ELSE clause, then none of the <Program-Source-Lines-n> block of statements within the >>IF->>END-IF scope will be processed by the compiler.

    4. If the <Program-Source-Lines-n>> statement block selected for processing is empty, no error results — there will just be no code generated from the >>IF->>END-IF structure.

  6. A <Program-Source-Lines-n> block may contain any valid COBOL or CDF code.

  7. The following points pertain to any <CDF-Conditional-Expression-n>:

    1. The DEFINED option tests for whether <cdf-variable-1> has been defined, but not yet assigned a value (>>DEFINE … OFF); use the NOT option to test for the variable not being defined.

    2. The SET option tests for whether <cdf-variable-1> has been given a value, either via a >>SET statement or via a >>DEFINE without the OFF option.

    3. Two CDF variables, two literals or a single CDF variable and a single literal may be compared against each other using a relational operator. Unlike the standard GnuCOBOL IF statement (see IF), multiple comparisons cannot be ANDed or ORed together; you may nest a second >>IF inside the first, however, to simulate an AND and an OR may be simulated via the >>ELIF option.

    4. The <> symbol stands for NOT EQUAL TO.

Predefined Compilation Variables

GnuCOBOL defines compilation variables when certain conditions are true.
If the condition associated with a variable is false, the variable is not defined.

Name              Condition
----------------  ----------------------------------------------------------
GNUCOBOL          GnuCOBOL is compiling the source unit.
OPENCOBOL         GnuCOBOL is compiling the source unit.
DEBUG             The -d debug flag is specified.
EXECUTABLE        The module being compiled contains the main program.
HOSTSIGNS         A signed packed-decimal item’s value may be considered
                  NUMERIC if the sign has value X"F".
NOHOSTSIGNS       A signed packed-decimal item’s value may not be considered
                  NUMERIC if the sign has value X"F".
GCCOMP            The size of a COMP item is determined according to the
                  GnuCOBOL scheme, where for a PICTURE of length:
                  1-2,  the item has 1 byte
                  3-4,  the item has 2 bytes
                  5-9,  the item has 4 bytes
                  10-18,the item has 8 bytes.
OCCOMP            The size of a COMP item is determined according to the
                  GnuCOBOL scheme, where for a PICTURE of length:
                  1-2,  the item has 1 byte
                  3-4,  the item has 2 bytes
                  5-9,  the item has 4 bytes
                  10-18,the item has 8 bytes.
IBMCOMP           The size of a COMP item is determined according to the IBM
                  scheme, where for a PICTURE of length:
                  1-4,  the item has 2 bytes
                  5-9,  the item has 4 bytes
                  10-18,the item has 8 bytes.
NOIBMCOMP         The size of a COMP item is not determined according to the
                  IBM scheme.
MODULE            The module being compiled does not contain the main program.
P64               Pointers are greater than 32 bits long.
STICKY-LINKAGE    Sticky-linkage (linkage-section items remaining allocated
                  between invocations) is enabled.
NOSTICKY-LINKAGE  Sticky-linkage (linkage-section items remaining allocated
                  between invocations) is not enabled.
TRUNC             Numeric data items are truncated according to their PICTURE
                  clauses.
NOTRUNC           Numeric data items are truncated according to their internal
                  representation.


This can be used for handy things like bit size assumptions (with the
given cobc configuration, at time of the preprocessing phase of a COBOL
compile sequence;  that means these are compile time values).

>>IF P64 IS SET
    display "binary built assuming 8 byte pointers"
>>END-IF

>>IF GNUCOBOL IS SET
   display "free COBOL is pretty cool"
>>END-IF

There are also some testable values for native endian byte order, and
character set:

>>IF ENDIAN = "BIG" ...
>>IF ENDIAN = "LITTLE" ...

>>IF CHARSET = "ASCII" ...
>>IF CHARSET = "EBCDIC" ...
>>IF CHARSET = "UNKNOWN" ...

>>LEAP-SECONDS

CDF >>LEAP-SECONDS Directive Syntax

=======================================================================

 >>LEAP-SECONDS
 ~~~~~~~~~~~~~~

The >>LEAP-SECONDS CDF directive is syntactically recognized but is otherwise non-functional.

=======================================================================

Allows for more than 60 seconds per minute.

>>LISTING

CDF >>LISTING Directive Syntax

=======================================================================

 >>LISTING [ ON|OFF ]
 ~~~~~~~~~   ~~ ~~~

=======================================================================

The directive allows the program listing to be de-activated.

>>PAGE

CDF >>PAGE Directive Syntax

=======================================================================

 >>PAGE [ comment-text ]
 ~~~~~~

=======================================================================

The PAGE directive specifies page ejection and provides documentation for the source listing.

  1. Comment-Text may contain any character in the computers standard character coded set except for control characters.

  2. Comment-Text is not checked for syntax and only serves as documentation.

  3. if a source listing is being produced a PAGE directive shall cause page ejection followed by listing of the PAGE directive.

  4. If a listing is not being produced the directive will have no effect.

>>REF-MOD-ZERO-LENGTH

CDF >>REF-MOD-ZERO-LENGTH Directive Syntax

=======================================================================

 >>REF-MOD-ZERO-LENGTH [ ON|OFF ]
 ~~~~~~~~~~~~~~~~~~~~~   ~~ ~~~

=======================================================================

The >>REF-MOD-ZERO-LENGTH CDF directive specifies whether resultant data items may have zero-length or not.

  1. When this directive is omitted or is specified as off, then when reference-modification results in a zero-length data item, the exception condition EC-BOUND-REF-MOD is raised. The resultant data item may now have a length of zero, when the REF-MOD-ZERO-LENGTH compiler directive is in effect to allow it, otherwise the EC-BOUND-REF-MOD exception is raised.

  2. Previously, the consequence of this result was undefined, though it had been the intention that a zero-length result would always raise the EC-BOUND-REF-MOD exception.

    In most cases programmers intend that reference-modification does not result in a zero-length item and expect an exception when this is not the case. In cases where this is not true the REF-MOD-ZERO-LENGTH compiler directive may be specified.

>>SET

CDF >>SET Directive Syntax

=======================================================================

 >>SET { [ CONSTANT ] cdf-variable-1 literal-1 ]                             }
 ~~~~~ {   ~~~~~~~~                                                          }
       { SOURCEFORMAT AS FIXED|FREE|VARIABLE|XOPEN|XCARD|CRT|TERMINAL|COBOLX }
       { ~~~~~~~~~~~~    ~~~~~ ~~~~ ~~~~~~~~ ~~~~~ ~~~~~ ~~~ ~~~~~~~~ ~~~~~~ }
       { NOFOLDCOPYNAME                                                      }
       { ~~~~~~~~~~~~~~                                                      }
       { FOLDCOPYNAME AS UPPER|LOWER                                         }
         ~~~~~~~~~~~~    ~~~~~ ~~~~~

=======================================================================

The >>SET CDF directive provides an alternate means of performing the actions of the >>DEFINE and >>SOURCE directives, as well as a means of controlling the compiler’s -free switch, -fixed switch and -ffold-copy switch from within program source code.

  1. The reserved word AS is optional (only on the SOURCEFORMAT and FOLDCOPYNAME clauses) and may be included, or not, at the discretion of the programmer. The presence or absence of this word has no effect upon the program.

  2. CDF variables defined in this way become undefined once an END PROGRAM or END FUNCTION directive is encountered in the input source.

  3. The FOLDCOPYNAME option provides the equivalent of specifying the compiler -ffold-copy=xxx switch, where xxx is either UPPER or LOWER.

  4. The NOFOLDCOPYNAME option turns off the effect of either the >>SET FOLDCOPYNAME statement or the compiler -ffold-copy=xxx switch.

  5. If the CONSTANT option is used, <literal-1> must also be used. This option provides another means of defining constants that may be used anywhere in the program that a literal could be specified.

  6. The remaining options of the >>SET CDF directive provide equivalent functionality to the >>DEFINE [ how ever as this form is no longer in the Cobol standards and is classsed as archaic and wil be so flagged, the use of >>DEFINE should be used for all new programs ], and >>SOURCE directives, as follows:

    >>SET cdf-variable-1

    >>DEFINE cdf-variable-1 AS OFF

    >>SET cdf-variable-1 AS literal-1

    >>DEFINE cdf-variable-1 AS literal-1

    >>SET CONSTANT cdf-variable-1 literal-1

    >>DEFINE CONSTANT cdf-variable-1 literal-1

    >>SET SOURCEFORMAT AS FIXED

    >>SOURCE FORMAT IS FIXED

    >>SET SOURCEFORMAT AS FREE

    >>SOURCE FORMAT IS FREE

    >>SET SOURCEFORMAT AS VARIABLE

    >>SOURCE FORMAT IS VARIABLE

    >>SET SOURCEFORMAT AS XOPEN

    >>SOURCE FORMAT IS XOPEN

    >>SET SOURCEFORMAT AS XCARD

    >>SOURCE FORMAT IS XCARD

    >>SET SOURCEFORMAT AS CRT

    >>SOURCE FORMAT IS CRT

    >>SET SOURCEFORMAT AS TERMINAL

    >>SOURCE FORMAT IS TERMINAL

    >>SET SOURCEFORMAT AS COBOLX

    >>SOURCE FORMAT IS COBOLX

    Note that only FIXED and FREE are standard ISO Cobol options, all the others are GnuCOBOL vendor extensions. That means that moving to another compiler may well involve chages to your source code format wise.

    >>SET XFD literal-1

    [See chapter 13]

    >>SET Micro-Focus-Directive

    [to do]

>>SOURCE

CDF >>SOURCE Directive Syntax

=======================================================================

 >>SOURCE FORMAT IS { FIXED|FREE|VARIABLE|XOPEN|XCARD|CRT|TERMINAL|COBOLX }
 ~~~~~~~~             ~~~~~ ~~~~ ~~~~~~~~ ~~~~~ ~~~~~ ~~~ ~~~~~~~~ ~~~~~~

=======================================================================

The >>SOURCE CDF directive puts the compiler into FIXED or FREE source-code format mode. This, in effect, provides yet another mechanism for controlling the compiler’s -free switch and -fixed switch.

  1. The reserved words FORMAT and IS are optional and may be included, or not, at the discretion of the programmer. The presence or absence of these words has no effect upon the program.

  2. FIXED : Source code is divided into: columns 1-6, the sequence number area; column 7, the indicator area; columns 8-72, the program-text area; and columns 73-80 as the reference area.

  3. FREE : Source code text area starts in column 1 and continues till the end of line (to a maximum of 255 characters).

  4. VARIABLE : Identical to FIXED format above except that it extends up to column 256 (in MF and some others, it is 252).

  5. XOPEN : X/Open Free-form format. The program-text area may start in column 1 unless an indicator is present, and lines may contain up to 80 characters. Indicator for debugging lines is D instead of D or d.

  6. XCARD : ICOBOL xCard format. Variable format with right margin set at column 255 instead of 250.

  7. CRT : ICOBOL Free-form format (CRT). Similar to the X/Open format above, with lines containing up to 320 characters and single-character debugging line indicators (D or d).

  8. TERMINAL : ACUCOBOL-GT Terminal format. Similar to the CRT format above, with indicator for debugging lines being \D instead of D or d. This format is mostly compatible with VAX COBOL terminal source format.

  9. COBOLX : This format is similar to the CRT format above, except that the indicator area is always present in column 1; the program-text area starts in column 2 and extends up to the end of the record. Lines may contain up to 255 characters.

  10. Note that with source formats XOPEN, CRT, TERMINAL, and COBOLX, missing spaces are not inserted within continued alphanumeric literals that are truncated before the right margin

  11. You may switch between the various format modes as desired and it takes effect immediately.

  12. You may also use the >>SET CDF directive to perform this function.

  13. If the compiler is already in the specified mode, this statement will have no effect.

>>TURN

CDF >>TURN Directive Syntax

=======================================================================

 >>TURN { exception-name-1 [ file-name-1 ]... }...
 ~~~~~~
         CHECKING  { ON [ WITH LOCATION ] }
         ~~~~~~~~  {           ~~~~~~~~   }
                   { OFF                  }
                     ~~~

=======================================================================

The directive will activate or de-activate exception checks.

  1. The default TURN directive is ‘>>TURN EC-ALL CHECKING OFF’.

  2. If the ON phrase is specified or implied, checking for the exception condition associated with exception-name-1 is enabled for the procedure division statements and procedure division headers that follow in the compilation group; if file-name-1 is specified, checking is enabled only for exception conditions associated with that file-name. Checking remains enabled for every qualifying procedure division statement and procedure division header that follows in the compilation group until it is disabled by a TURN directive with the OFF phrase.

  3. If the LOCATION phrase is specified, all information necessary to identify a source statement for the EXCEPTION-LOCATION, EXCEPTION-LOCATION-N, and EXCEPTION-STATEMENT functions is made available to the run unit. If the LOCATION phrase is not specified, the implementor shall specify whether this information is made available or not.

  4. If the OFF phrase is specified, checking for the exception condition associated with exception-name-1 is disabled for all procedure division statements and procedure division headers that follow in the compilation group and remains disabled until another TURN directive for exception-name-1 with the ON phrase is encountered; if file-name-1 is specified, checking is disabled only for exception conditions associated with that file-name.

See also: the CBL_ERROR_PROC built-in system routine and EXCEPTION-STATUS, EXCEPTION-STATEMENT, EXCEPTION-LOCATION, EXCEPTION-FILE intrinsic functions. Note: the USE AFTER EC|EXCEPTION CONDITION of DECLARATIVES and the RAISE statement are not yet implemented.

        >>SOURCE FREE
IDENTIFICATION DIVISION.
PROGRAM-ID. TEST.  *> sample for EC-BOUND overflow
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TABLE01.
   05 ELEM OCCURS 4 TIMES PIC X(5).
01 IDX     pic 99 value 6.

PROCEDURE DIVISION.
DECLARATIVES.
DECLARATIVE-1 SECTION.
   USE AFTER EXCEPTION CONDITION EC-BOUND.
       DISPLAY "DECLARATIVE FOR EC-BOUND".
   EXIT PROGRAM.
END DECLARATIVES.

MAIN-SECTION SECTION.
DISPLAY "TURN EC-BOUND CHECKING ON".
>>TURN EC-BOUND CHECKING O
MOVE "ABCDE" TO ELEM(IDX).
STOP RUN.

Other Compiler Directives

There are other COBOL compiler directives (or options) that vary among vendors to accommodate the different architectures (Mainframe, Unix, Windows) and supported dialects. To insert directives directly into the source code, each vendor uses a specific "control statement" that must usually appear before the IDENTIFICATION DIVISION.

Here is a summary of the main "control statements" for main vendors. In addition to the CDF directives from the COBOL ISO standards, GnuCOBOL supports some of them for compatibility reasons.

+-------------------------------------------------------------------+
| COMMAND         VENDOR     EXAMPLE                                |
+-------------------------------------------------------------------+
| CBL or  PROCESS IBM        CBL OPT(2),SSRANGE,NODYNAM,XREF        |
|*CBL or *CONTROL IBM                                               |
|                                                                   |
| $               MICROFOCUS $SET SOURCEFORMAT"FIXED"               |
|                                                                   |
| @OPTIONS        ACUCOBOL                                          |
| @DIRECTIVES     ACUCOBOL                                          |
|                                                                   |
| @OPTIONS        FUJITSU    @OPTIONS FIXED,ALPHAL(WORD),CHECK(ALL) |
| @DIRECTIVES     FUJITSU                                           |
+-------------------------------------------------------------------+

*CBL Directive

CDF *CBL Directive Syntax

=======================================================================

 { *CBL     }  { | SOURCE   | } [ . ] 
 { ~~~~     }  { | ~~~~~~   | }  
 { *CONTROL }  { | NOSOURCE | }  
   ~~~~~~~~    { | ~~~~~~~~ | }   
               { | LIST     | }  
               { | ~~~~     | }        
               { | NOLIST   | }  
               { | ~~~~~~   | }  
               { | MAP      | }  
               { | ~~~      | } 
               { | NOMAP    | }  
                   ~~~~~         

=======================================================================

The *CBL (or *CONTROL) statement is used to specify compiler options directly within the source code to control compiler listings. The compiler detects and checks the syntax but, this option is currently not implemented, at least with GnuCOBOL v3.2.

It is usually placed before the IDENTIFICATION DIVISION statement. It allows you to enable/disable SOURCE, LIST and MAP options, even at specific points in the program. It can begin in any column starting with column 8. The line must contain *CBL (or *CONTROL) followed by options separated by spaces or commas. It must be the only statement on the line, and continuation onto subsequent lines is not permitted. The statement can end with a period.

  1. SOURCE - Source Code Listing

    Control the listing of the input source text lines. If a *CBL NOSOURCE statement is encountered and SOURCE has been requested as a compilation option, printing of the source listing is suppressed from this point on.

  2. LIST - Object Code Listing

    LIST compiler option produce a listing of the assembler-language expansion of your source code. Default is: NOLIST. Any *CBL (or *CONTROL) LIST or NOLIST statements that you code in the PROCEDURE DIVISION have no effect. They are treated as comments. The compiler always produces an object code listing. The LIST and NOLIST options of the *CONTROL (or *CBL) statement are syntax checked but have no effect on the object code listing.

  3. MAP - Storage Map Listing

    Control the listing of storage map entries occurring in the DATA DIVISION. If a *CBL NOMAP statement is encountered, and MAP has been requested as a compilation option, listing of storage map entries is suppressed from this point on. For example, either of the following sets of statements produces a storage map listing in which FIELD-A and FIELD-B will not appear:

    *CBL NOMAP
        01  FIELD-A
        02  FIELD-B
    *CBL MAP

$ and OPTIONS Directive

CDF $ Directive Syntax

=======================================================================

 $ (Dollar) Directives - Active.

 These directives are active and have the same function as ones starting with >>:

 $DEFINE
 $DISPLAY ON|OFF
 
 $IF
 $ELSE
 $ELIF
 $ELSE-IF
 
 $END
 $SET

 It is recommended to use the standard directives only instead of the MF
 directives (when possible) as these have a higher chance for being portable.

 $ (Dollar) Directives - Not Active.
 These are NOT active and will produce a warning message:

 $DISPLAY VCS ...

 Recognised but otherwise ignored.

 @OPTIONS options-text

 Additional Micro-Focus directives accepted :

+---------------------------------------------------------------------------+
| Explicit Reserved Word Control                                            |
+---------------------------------------------------------------------------+
| ADDRSV|ADD-RSV literal-1                              | Add reserved word | 
| ADDSYN|ADD-SYN literal-1 = literal-2                  | Add synonym       |
| MAKESYN|MAKE-SYN                                      | Make synonymous   |
| OVERRIDE  literal-1 = literal-2                       | Change meaning    |
| REMOVE  literal-1                                     | Make unreserved   |
+---------------------------------------------------------------------------+
| Choosing Run-time Behavior                                                |
+---------------------------------------------------------------------------+
| ASSIGN  "EXTERNAL"|"DYNAMIC"                       |                      | 
| FOLDCOPYNAME|FOLD-COPY-NAME  AS "UPPER"|"LOWER"    | Fold COPY-file names |  
| NOFOLDCOPYNAME|NOFOLD-COPY-NAME|NO-FOLD-COPY-NAME  |                      |
+---------------------------------------------------------------------------+
| Behavior Affecting Speed                                                  |
+---------------------------------------------------------------------------+
| BOUND                                      | Bound checking of subscripts | 
| NOBOUND|NO-BOUND                           |                              |  
+---------------------------------------------------------------------------+
| File handling 
+---------------------------------------------------------------------------+
| CALLFH  literal-1                          | External file handler        |
+---------------------------------------------------------------------------+
| Others
+---------------------------------------------------------------------------+
| COMP1|COMP-1 "BINARY"|"FLOAT"                      | Computational subset |
| SOURCEFORMAT|SOURCE-FORMAT "FIXED"|"FREE"|"VARIABLE"                      |
| SSRANGE "2"                                        |                      |
| NOSSRANGE|NO-SSRANGE                               |                      |
+---------------------------------------------------------------------------+

=======================================================================

Offers support for MF Compiler Directives.