@comment *********************************************************************
@comment ** 3. Compiler Directing Facility                                  **
@comment *********************************************************************
@newchapter{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 @code{COPY} and @code{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 @code{>>} character sequence as part of the statement name itself, influence the process of program compilation.

Compiler directives are @i{never} terminated with a period.

The compiler command-line option @option{-D} offers additional control (@pxref{cobc - The GnuCOBOL Compiler}).
@menu
* >>CALL-CONVENTION.
* COPY.
* REPLACE.
* >>DEFINE.
* >>IF.
* >>SET.
* >>SOURCE.
* >>TURN.
* >>D.
* >>DISPLAY.
* >>PAGE.
* >>LISTING.
* >>LEAP-SECONDS.
* $ Directives.
@end menu
@comment *********************************************************************
@comment ** 3.1 >>CALL-CONVENTION                                           **
@comment *********************************************************************
@page
@newsection{>>CALL-CONVENTION}
@diagram{CDF >>CALL-CONVENTION,CDF-CALL,CDF-CALL,None}
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.
@table @code

@item 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 @code{AS} phrase is specified.
(The is the default.)

@item EXTERN
The program name is treated as an external reference.

@item 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 @code{CALL}.  Subroutines written in GnuCOBOL do not need this option.

@item 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.

@end table
@comment *********************************************************************
@comment ** 3.2 COPY                                                        **
@comment *********************************************************************
@page
@newsection{COPY}
@diagram{CDF COPY Statement,CDF-COPY,CDF-COPY,None}
@diagram{CDF COPY Phrase-Clause,CDF-COPY-Phrase,CDF-COPY-Phrase,None}
@diagram{CDF COPY String-Clause,CDF-COPY-String,CDF-COPY-String,None}
@enumerate
@item
@code{COPY} statements are used to import copybooks (@pxref{Copybooks}) into a program.

@item
@code{COPY} statements may be used anywhere within a COBOL program where the code contained within the copybook would be syntactically valid.

@item
The optional
@syntaxidx{SUPPRESS} clause (with or without the optional
@syntaxidx{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.

@item
There is no difference between the use of the word @code{IN} and the word @code{OF} --- use the one you prefer.

@item
A period is absolutely mandatory at the end of every @code{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 @syntaxref{IF} statement.  This mandatory period at the end of the statement does not, however, affect the statement scope in which the @code{COPY} occurs.

@item
Both @var{pseudo-text-2} and @var{partial-word-2} may be null.

@item
All @code{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 @code{COPY} statement, the copybook insertion process will be repeated to resolve the embedded @code{COPY}.  This will continue until no unresolved @code{COPY} statements remain.  At that point, actual program compilation will begin.

@item
@xref{Locating Copybooks}, for the specific rules on how copybooks are located by the compiler.

@item
The optional
@syntaxidx{REPLACING} clause allows for one or more of either of the following kinds of text replacements to be made:
@table @asis
@item @var{Phrase-Clause}
Replacement of one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:
@itemize
@item
This option cannot be used to replace part of a word, identifier or literal.

@item
Whatever precedes the @code{BY} will be referred to here as the search string.

@item
Single-item search strings can be specified by coding the @code{@var{identifier-1}}, @code{@var{literal-1}} or @code{@var{word-1}} being replaced.

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

@item
The replacement string, which follows the @code{BY}, may be specified using any of the four options.

@item
If the replacement string is a multiple-item phrase or is to be deleted altogether, you must use the @code{==@var{pseudo-text-2}==} option.  If @code{@var{pseudo-text-2}} is null (in other words, the replacement text is specified as @code{====}), all encountered occurrences of the search string will be deleted.
@end itemize
@item @var{String-Clause}
Using this, you may replace character sequences that occur at the beginning (see
@syntaxidx{LEADING}) or end (see
@syntaxidx{TRAILING}) of reserved or user-defined words.  For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", code @code{LEADING ==0100-== BY ==020-==}.  To simply remove all "0100-" prefixes from words, code @code{LEADING ==0100-== BY ====}.
@end table
@end enumerate
@comment *********************************************************************
@comment ** 3.3 REPLACE                                                     **
@comment *********************************************************************
@page
@newsection{REPLACE}
@diagram{CDF REPLACE Statement (Format 1),CDF-REPLACE-1,CDF-REPLACE-1,None}
@diagram{CDF REPLACE Statement (Format 2),CDF-REPLACE-2,CDF-REPLACE-2,None}
@diagram{CDF REPLACE Phrase-Clause,CDF-REPLACE-Phrase,CDF-REPLACE-Phrase,None}
@diagram{CDF REPLACE String-Clause,CDF-REPLACE-String,CDF-REPLACE-String,None}
@enumerate 1
@item
The @code{REPLACE} statement provides a mechanism for changing all or part of one or more GnuCOBOL statements.

@item
A period is absolutely mandatory at the end of every @code{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 @syntaxref{IF} statement; the period will not, however, affect the statement scope in which the @code{REPLACE} occurs.

@item
The following points apply to Format 1 of the @code{REPLACE} statement:
@enumerate A
@item
Format 1 of the @code{REPLACE} statement can be used to make changes to program source code in much the same way as the
@syntaxidx{REPLACING} option of the @code{COPY} statement can, via these options:
@table @asis
@item @var{Phrase-Clause}
Replace one or more complete reserved words, user-defined identifiers or literals; the following points apply to this option:
@itemize @bullet
@item
This option cannot be used to replace part of a word, identifier or literal.

@item
Whatever precedes the @code{BY} will be referred to here as the search string.

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

@item
The replacement string, which follows the @code{BY}, is specified using the @code{==@var{pseudo-text-2}==} option.  If @code{@var{pseudo-text-2}} is null (in other words, the replacement text is specified as @code{====}), all encountered occurrences of the search string will be deleted.
@end itemize
@item @var{String-Clause}
Using this, you may replace character sequences that occur at the beginning (see
@syntaxidx{LEADING}) or end (see
@syntaxidx{TRAILING}) of reserved or user-defined words.  For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", code @code{LEADING ==0100-== BY ==020-==}.  To simply remove all "0100-" prefixes from words, code @code{LEADING ==0100-== BY ====}.
@end table

@item
Once a Format 1 @code{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.

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

@item
When a Format 1 @code{REPLACE} statement with the
@syntaxidx{ALSO} keyword is encountered without Replace Mode being currently active, the effect will be as if the @code{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.

@item
When a Format 1 @code{REPLACE} without the @code{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.

@item
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.
@end enumerate

@item
The following points apply to Format 2 of the @code{REPLACE} statement:
@enumerate A
@item
If Replace Mode is currently inactive, the Format 2 @code{REPLACE} statement will be ignored.

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

@item
If Replace Mode is currently active, a @code{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 @code{REPLACE OFF.} had been coded.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 3.4 >>DEFINE Directive                                          **
@comment *********************************************************************
@page
@newsection{>>DEFINE}
@diagram{CDF >>DEFINE Directive,CDF-DEFINE,CDF-DEFINE,None}
Use the @directive{>>DEFINE} to create CDF variables and (optionally) assign them either literal or environment variable values.
@enumerate
@item
The reserved word @code{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.

@item
CDF variables defined in this way become undefined once an @code{END PROGRAM} or @code{END FUNCTION} directive is encountered in the input source.

@item
The @directive{>>DEFINE} is one way to create CDF variables that may be processed by other CDF statements such as @syntaxref{>>IF}.  The @directiveref{>>SET} provides another way to create them.

@item
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
@syntaxidx{CONSTANT} option is not specified, but such names are not recommended.

@item
The @code{CONSTANT} option is valid only in conjunction with @var{literal-1}.  When @code{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
@syntaxidx{OFF} option is used to create a variable without assigning it any value.

@item
The
@syntaxidx{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.

@item
In the absence of the
@syntaxidx{OVERRIDE} option, @var{cdf-variable-1} must not yet have been defined.  When the @code{OVERRIDE} option is specified, @var{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.
@end enumerate
@comment *********************************************************************
@comment ** 3.5 >>IF Directive                                              **
@comment *********************************************************************
@page
@newsection{>>IF}
@diagram{CDF >>IF Directive,CDF-IF,CDF-IF,None}
@diagram{CDF-Conditional-Expression,CDF-Cond-Expr,CDF-Cond-Expr,None}
@diagram{CDF-RelOp,CDF-RelOp,CDF-RelOp,None}
The @directive{>>IF} 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.
@enumerate
@item
The reserved words @code{IS}, @code{THAN} and @code{TO} are optional and may be omitted.  The presence or absence of these words has no effect on the program.

@item
Each @code{>>IF} directive must be terminated by an
@syntaxidx{>>END-IF} directive.

@item
There may be any number of
@syntaxidx{>>ELIF} clauses following an @code{>>IF}, including zero.

@item
There may no more than one
@syntaxidx{>>ELSE} clause following an @code{>>IF}.  When @code{>>ELSE} is used, it must follow the @code{>>IF} and all @code{>>ELIF} clauses.

@item
Only one of the @var{Program-Source-Lines-n} block of statements that lie within the scope of the @code{>>IF} @dots{} @code{>>END-IF} may be processed by the compiler.  Which one (if any) that gets processed will be decided as follows:
@enumerate A
@item
Each @var{CDF-Conditional-Expression-n} will be evaluated, in turn, in the sequence in which they are coded in the >>IF statement and any @code{>>ELIF} clauses that may be present until one evaluates to @code{TRUE}.  Once one of them evaluates to @code{TRUE}, the @var{Program-Source-Lines-n} block of code that corresponds to the @code{TRUE} @var{CDF-Conditional-Expression-n} will be one that is processed.  All others within the @code{>>IF}-@code{>>END-IF} scope will be ignored.

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

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

@item
If the @var{Program-Source-Lines-n}> statement block selected for processing is empty, no error results --- there will just be no code generated from the @code{>>IF}-@code{>>END-IF} structure.
@end enumerate
@item
A @var{Program-Source-Lines-n} block may contain any valid COBOL or CDF code.

@item
The following points pertain to any @var{CDF-Conditional-Expression-n}:
@enumerate A
@item
The
@syntaxidx{DEFINED} option tests for whether @var{cdf-variable-1} has been defined, but not yet assigned a value (@code{>>DEFINE @dots{} OFF}); use the @code{NOT} option to test for the variable not being defined.

@item
The
@syntaxidx{SET} option tests for whether @var{cdf-variable-1} has been given a value, either via a @code{>>SET} statement or via a @code{>>DEFINE} without the @code{OFF} option.

@item
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 @statementref{IF}, multiple comparisons cannot be @code{AND}ed or @code{OR}ed together; you may nest a second @code{>>IF} inside the first, however, to simulate an @code{AND} and an @code{OR} may be simulated via the @code{>>ELIF} option.

@item
The @code{<>} symbol stands for @code{NOT EQUAL TO}.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 3.6 >>SET Directive                                             **
@comment *********************************************************************
@page
@newsection{>>SET}
@diagram{CDF >>SET Directive,CDF-SET,CDF-SET,None}
The @directive{>>SET} provides an alternate means of performing the actions of the @code{>>DEFINE} and @code{>>SOURCE} directives, as well as a means of controlling the compiler's
@switchidx{-free},
@switchidx{-fixed} and
@switchidx{-ffold-copy} from within program source code.
@enumerate
@item
The reserved word @code{AS} is optional (only on the @code{SOURCEFORMAT} and @code{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.

@item
CDF variables defined in this way become undefined once an @code{END PROGRAM} or @code{END FUNCTION} directive is encountered in the input source.

@item
The
@syntaxidx{FOLDCOPYNAME} option provides the equivalent of specifying the compiler @switch{-ffold-copy=@var{xxx}}, where @code{@var{xxx}} is either
@syntaxidx{UPPER} or
@syntaxidx{LOWER}.

@item
The
@syntaxidx{NOFOLDCOPYNAME} option turns off the effect of either the @code{>>SET FOLDCOPYNAME} statement or the compiler @switch{-ffold-copy=@var{xxx}}.

@item
If the
@syntaxidx{CONSTANT} option is used, @var{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.

@item
The remaining options of the @directive{>>SET} provide equivalent functionality to the @code{>>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 @code{>>SOURCE} directives, as follows:
@table @code
@item >>SET @var{cdf-variable-1}
@code{>>DEFINE @var{cdf-variable-1} AS OFF}

@item >>SET @var{cdf-variable-1} AS @var{literal-1}
@code{>>DEFINE @var{cdf-variable-1} AS @var{literal-1}}

@item >>SET CONSTANT @var{cdf-variable-1} @var{literal-1}
@code{>>DEFINE CONSTANT @var{cdf-variable-1} @var{literal-1}}

@item >>SET SOURCEFORMAT AS FIXED
@code{>>SOURCE FORMAT IS FIXED}

@item >>SET SOURCEFORMAT AS FREE
@code{>>SOURCE FORMAT IS FREE}

@item >>SET SOURCEFORMAT AS VARIABLE
@code{>>SOURCE FORMAT IS VARIABLE}

@item >>SET SOURCEFORMAT AS XOPEN
@code{>>SOURCE FORMAT IS XOPEN}

@item >>SET SOURCEFORMAT AS XCARD
@code{>>SOURCE FORMAT IS XCARD}

@item >>SET SOURCEFORMAT AS CRT
@code{>>SOURCE FORMAT IS CRT}

@item >>SET SOURCEFORMAT AS TERMINAL
@code{>>SOURCE FORMAT IS TERMINAL}

@item >>SET SOURCEFORMAT AS COBOLX
@code{>>SOURCE FORMAT IS COBOLX}

@item >>SET XFD literal-1
[See chapter 13]

@item >>SET Micro-Focus-Directive
[to do]
@end table
@end enumerate
@comment *********************************************************************
@comment ** 3.7 >>SOURCE Directive                                          **
@comment *********************************************************************
@page
@newsection{>>SOURCE}
@diagram{CDF >>SOURCE Directive,CDF-SOURCE,CDF-SOURCE,None}
The @directive{>>SOURCE} puts the compiler into @code{FIXED} or @code{FREE} source-code format mode.  This, in effect, provides yet another mechanism for controlling the compiler's
@switchidx{-free} and
@switchidx{-fixed}.
@idx{Fixed Format Mode}
@idx{Free Format Mode}
@idx{Source Line Format, Fixed}
@idx{Source Line Format, Free}
@enumerate
@item
The reserved words @code{FORMAT} and @code{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.

@item
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.

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

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

@item
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.

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

@item
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).

@item
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.

@item
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.

@item
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

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

@item
You may also use the @directive{>>SET} to perform this function.

@item
If the compiler is already in the specified mode, this statement will have no effect.
@end enumerate
@comment *********************************************************************
@comment ** 3.8 >>TURN Directive                                            **
@comment *********************************************************************
@page
@newsection{>>TURN}
@diagram{CDF >>TURN Directive,CDF-TURN,CDF-TURN,None}
The directive will (de-)activate exception checks.
@comment ********************************************************************
@comment ** 3.9 >>D Directive                                              **
@comment ********************************************************************
@page
@newsection{>>D}
@diagram{CDF >>D Directive,CDF-DEBUG,CDF-DEBUG,None}
The directive removes all floating debug lines if debug mode not active. Otherwise will ignore the directive part of the line.
@comment ********************************************************************
@comment ** 3.10 >>>DISPLAY Directive                                      **
@comment ********************************************************************
@page
@newsection{>>DISPLAY}
@diagram{CDF >>DISPLAY Directive,CDF-DISPLAY,CDF-DISPLAY,None}
The directive is a v1.0 extension and will display messages during compilation.
@comment ********************************************************************
@comment ** 3.11 >>PAGE Directive                                          **
@comment ********************************************************************
@page
@newsection{>>PAGE}
@diagram{CDF >>PAGE Directive,CDF-PAGE,CDF-PAGE,None}
The PAGE directive specifies page ejection and provides documentation for the source listing.
@enumerate
@item
Comment-Text may contain any character in the computers standard character coded set except for control characters.
@item
Comment-Text is not checked for syntax and only serves as documentation.
@item
if a source listing is being produced a PAGE directive shall cause page ejection followed by listing of the PAGE directive.
@item
If a listing is not being produced the directive will have no effect.
@end enumerate
@comment ********************************************************************
@comment ** 3.12 >>LISTING Directive                                       **
@comment ********************************************************************
@page
@newsection{>>LISTING}
@diagram{CDF >>LISTING Directive,CDF-LISTING,CDF-LISTING,None}
The directive allows the program listing to be de-(activated).
@comment ********************************************************************
@comment ** 3.13 >>LEAP-SECONDS Directive                                  **
@comment ********************************************************************
@page
@newsection{>>LEAP-SECONDS}
@diagram{CDF >>LEAP-SECONDS Directive,CDF-LEAP,CDF-LEAP,CDF-LEAP}
Allows for more than 60 seconds per minute.
@comment ********************************************************************
@comment ** 3.14 $ Directives                                                **
@comment ********************************************************************
@page
@newsection{$ Directives}
@diagram{CDF $ Directive,CDF-DOLLAR,CDF-DOLLAR,None}
Offers support for MF Compiler Directives.
@iftex
@sp 3
@center ------------------------------------------------------------
@center End of Chapter 3 --- CDF - Compiler Directing Facility
@end iftex
