3 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 directives, denoted by the presence of a >> character sequence as part of the statement name itself, influence the process of program compilation.

Compiler directives are never terminated with a period.

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

3.1 >>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.

3.2 COPY

CDF COPY Statement Syntax

COPY copybook-name
~~~~
[ 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==
  ~~~~~~~ ~~~~~~~~                      ~~

COPY statements are used to import copybooks ( 2.1.6 Copybooks) into a program.
COPY statements may be used anywhere within a COBOL program where the code contained within the copybook would be syntactically valid.
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.
There is no difference between the use of the word IN and the word OF — use the one you prefer.
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 ( 7.8.23 IF) statement. This mandatory period at the end of the statement does not, however, affect the statement scope in which the COPY occurs.
Both <pseudo-text-2> and <partial-word-2> may be null.
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.
10.1.6 Locating Copybooks, for the specific rules on how copybooks are located by the compiler.
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 ====.

3.3 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==
  ~~~~~~~ ~~~~~~~~                      ~~

The REPLACE statement provides a mechanism for changing all or part of one or more GnuCOBOL statements.
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 ( 7.8.23 IF) statement; the period will not, however, affect the statement scope in which the REPLACE occurs.
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.
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.

3.4 >>DEFINE

CDF >>DEFINE Directive Syntax

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

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

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.
CDF variables defined in this way become undefined once an END PROGRAM or END FUNCTION directive is encountered in the input source.
The >>DEFINE CDF directive is one way to create CDF variables that may be processed by other CDF statements such as >>IF ( 3.5 >>IF). The >>SET CDF directive ( 3.6 >>SET) provides another way to create them.
CDF variable names follow the rules for standard GnuCOBOL user-defined names, and may not duplicate any CDF reserved word. CDF variable names may duplicate COBOL reserved words, provided the CONSTANT option is not specified, but such names are not recommended.
The CONSTANT option is valid only in conjunction with <literal-1>. When CONSTANT is specified, the CDF variable that is created may be used within your regular COBOL code as if it were a literal value. Without this option, the CDF variable may only be referenced on other CDF statements. The OFF option is used to create a variable without assigning it any value.
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.
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.

3.5 >>IF

CDF >>IF Directive Syntax

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

[ >>ELIF 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.

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.
Each >>IF directive must be terminated by an >>END-IF directive.
There may be any number of >>ELIF clauses following an >>IF, including zero.
There may no more than one >>ELSE clause following an >>IF. When >>ELSE is used, it must follow the >>IF and all >>ELIF clauses.
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 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.
A <Program-Source-Lines-n> block may contain any valid COBOL or CDF code.
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 ( 7.8.23 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.

3.6 >>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.

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.
CDF variables defined in this way become undefined once an END PROGRAM or END FUNCTION directive is encountered in the input source.
The FOLDCOPYNAME option provides the equivalent of specifying the compiler -ffold-copy=<xxx> switch, where <xxx> is either UPPER or LOWER.
The NOFOLDCOPYNAME option turns off the effect of either the >>SET FOLDCOPYNAME statement or the compiler -ffold-copy=<xxx> switch.
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.
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
- >>SET XFD literal-1
  
  [See chapter 13]
- >>SET Micro-Focus-Directive
  
  [to do]

3.7 >>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.

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.
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 72-80 as the reference area.
FREE : Source code text area starts in column 1 and continues till the end of line (to a maximum of 255 characters).
VARIABLE : Identical to FIXED format above except that it extends up to column 256 (in MF and some others, it is 252).
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.
XCARD : ICOBOL xCard format. Variable format with right margin set at column 255 instead of 250.
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).
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.
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.
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
You may switch between the various format modes as desired and it takes effect immediately.
You may also use the >>SET CDF directive to perform this function.
If the compiler is already in the specified mode, this statement will have no effect.

3.8 >>TURN

CDF >>TURN Directive Syntax

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

The directive will (de-)activate exception checks.

3.9 >>D

CDF >>D Directive Syntax

>>D
~~~

The directive removes all floating debug lines if debug mode not active. Otherwise will ignore the directive part of the line.

3.10 >>DISPLAY

CDF >>DISPLAY Directive Syntax

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

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

3.11 >>PAGE

CDF >>PAGE Directive Syntax

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

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

Comment-Text may contain any character in the computers standard character coded set except for control characters.
Comment-Text is not checked for syntax and only serves as documentation.
if a source listing is being produced a PAGE directive shall cause page ejection followed by listing of the PAGE directive.
If a listing is not being produced the directive will have no effect.

3.12 >>LISTING

CDF >>LISTING Directive Syntax

>>LISTING  {ON}
~~~~~~~~~  {OFF}

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

3.13 >>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.

3.14 $ Directives

CDF $ Directive Syntax

$ (Dollar) Directives - Active.

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

$DEFINE
$DISPLAY ON|OFF
$IF
$ELIF
$ELSE
$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 :

ADDRSV | ADD-RSV literal-1
ADDSYN | ADD-SYN literal-1 = literal-2
ASSIGN  "EXTERNAL" | "DYNAMIC"
BOUND
CALLFH  literal-1
COMP1  |  COMP-1  "BINARY" | "FLOAT"
FOLDCOPYNAME | FOLD-COPY-NAME  AS "UPPER" | "LOWER"
MAKESYN  |  MAKE-SYN
NOBOUND  |  NO-BOUND
NOFOLDCOPYNAME  |  NOFOLD-COPY-NAME  |  NO-FOLD-COPY-NAME
OVERRIDE  literal-1 = literal-2
REMOVE  literal-1
SOURCEFORMAT | SOURCE-FORMAT "FIXED" | "FREE" | "VARIABLE"
SSRANGE "2"
NOSSRANGE  |  NO-SSRANGE

Offers support for MF Compiler Directives.