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==
~~~~~~~ ~~~~~~~~ ~~
=======================================================================
COPYstatements are used to import copybooks (see Copybooks) into a program.COPYstatements may be used anywhere within a COBOL program where the code contained within the copybook would be syntactically valid.The optional
SUPPRESSclause (with or without the optionalPRINTINGreserved 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
INand the wordOF— use the one you prefer.A period is absolutely mandatory at the end of every
COPYstatement, even if the statement occurs within the scope of another one where a period might appear disruptive, such as within the scope of anIF(see IF) statement. This mandatory period at the end of the statement does not, however, affect the statement scope in which theCOPYoccurs.Both <pseudo-text-2> and <partial-word-2> may be null.
All
COPYstatements 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 aCOPYstatement, the copybook insertion process will be repeated to resolve the embeddedCOPY. This will continue until no unresolvedCOPYstatements remain. At that point, actual program compilation will begin.See Locating Copybooks, for the specific rules on how copybooks are located by the compiler.
The optional
REPLACINGclause 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
BYwill be referred to here as the search string.Single-item search strings can be specified by coding the
identifier-1,literal-1orword-1being replaced.Multiple-item search strings can be specified using the
==pseudo-text-1==option. For example, to replace all occurrences ofUPON 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. Ifpseudo-text-2is 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 (seeTRAILING) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", codeLEADING ==0100-== BY ==020-==. To simply remove all "0100-" prefixes from words, codeLEADING ==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==
~~~~~~~ ~~~~~~~~ ~~
=======================================================================
The
REPLACEstatement provides a mechanism for changing all or part of one or more GnuCOBOL statements.A period is absolutely mandatory at the end of every
REPLACEstatement (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 anIF(see IF) statement; the period will not, however, affect the statement scope in which theREPLACEoccurs.The following points apply to Format 1 of the
REPLACEstatement:Format 1 of the
REPLACEstatement can be used to make changes to program source code in much the same way as theREPLACINGoption of theCOPYstatement 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
BYwill be referred to here as the search string.Search strings on
REPLACEare always specified using the==pseudo-text-1==option. For example, to replace all occurrences ofUPON PRINTER, you would specify==UPON PRINTER==.The replacement string, which follows the
BY, is specified using the==pseudo-text-2==option. Ifpseudo-text-2is 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 (seeTRAILING) of reserved or user-defined words. For example, to change all words of the form "0100-xxxxxx" to "020-xxxxxx", codeLEADING ==0100-== BY ==020-==. To simply remove all "0100-" prefixes from words, codeLEADING ==0100-== BY ====.
Once a Format 1
REPLACEstatement 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.Replace Mode remains in-effect — continuing to make source code changes — until another Format 1
REPLACEis encountered, the end of currently compiling program source file is reached or a Format 2REPLACEstatement is encountered.When a Format 1
REPLACEstatement with theALSOkeyword is encountered without Replace Mode being currently active, the effect will be as if theALSOhad 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.When a Format 1
REPLACEwithout theALSOkeyword 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.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
REPLACEstatement:If Replace Mode is currently inactive, the Format 2
REPLACEstatement will be ignored.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 noREPLACEhad ever been encountered, until such time as another Format 1REPLACEis encountered.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 aREPLACE 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
ASphrase 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.
COBOL-WORDS EQUATE keyword WITH alias makes alias a synonym for keyword.
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.
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.
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.
The reserved word
ASis 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 PROGRAMorEND FUNCTIONdirective is encountered in the input source.The
>>DEFINECDF directive is one way to create CDF variables that may be processed by other CDF statements such as>>IF(see >>IF). The>>SETCDF directive (see >>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.
The
PARAMETERoption 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
OVERRIDEoption, <cdf-variable-1> must not yet have been defined. When theOVERRIDEoption 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.The
OFFoption 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].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).
CDF variable names may duplicate COBOL reserved words, provided the
CONSTANToption 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.
The reserved words
IS,THANandTOare optional and may be omitted. The presence or absence of these words has no effect on the program.Each
>>IFdirective must be terminated by an>>END-IFdirective.There may be any number of
>>ELIFclauses following an>>IF, including zero.There may be no more than one
>>ELSEclause following an>>IF. When>>ELSEis used, it must follow the>>IFand all>>ELIFclauses.Only one of the <Program-Source-Lines-n> block of statements that lie within the scope of the
>>IF…>>END-IFmay be processed by the compiler. Which one (if any) that gets processed will be decided as follows:Each <CDF-Conditional-Expression-n> will be evaluated, in turn, in the sequence in which they are coded in the >>IF statement and any
>>ELIFclauses that may be present until one evaluates toTRUE. Once one of them evaluates toTRUE, the <Program-Source-Lines-n> block of code that corresponds to theTRUE<CDF-Conditional-Expression-n> will be the one that is processed. All others within the>>IF->>END-IFscope will be ignored.If no <CDF-Conditional-Expression> evaluates to
TRUE, and there is an>>ELSEclause, the <Program-Source-Lines-3> block of statements following the>>ELSEclause will be processed by the compiler and all others within the>>IF->>END-IFscope will be ignored.If no <CDF-Conditional-Expression-n> evaluates to
TRUEand there is no>>ELSEclause, then none of the <Program-Source-Lines-n> block of statements within the>>IF->>END-IFscope will be processed by the compiler.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-IFstructure.
A <Program-Source-Lines-n> block may contain any valid COBOL or CDF code.
The following points pertain to any <CDF-Conditional-Expression-n>:
The
DEFINEDoption tests for whether <cdf-variable-1> has been defined, but not yet assigned a value (>>DEFINE … OFF); use theNOToption to test for the variable not being defined.The
SEToption tests for whether <cdf-variable-1> has been given a value, either via a>>SETstatement or via a>>DEFINEwithout theOFFoption.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
IFstatement (see IF), multiple comparisons cannot beANDed orORed together; you may nest a second>>IFinside the first, however, to simulate anANDand anORmay be simulated via the>>ELIFoption.The
<>symbol stands forNOT 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.
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.
>>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.
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.
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.
The reserved word
ASis optional (only on theSOURCEFORMATandFOLDCOPYNAMEclauses) 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 PROGRAMorEND FUNCTIONdirective is encountered in the input source.The
FOLDCOPYNAMEoption provides the equivalent of specifying the compiler-ffold-copy=xxxswitch, wherexxxis eitherUPPERorLOWER.The
NOFOLDCOPYNAMEoption turns off the effect of either the>>SET FOLDCOPYNAMEstatement or the compiler-ffold-copy=xxxswitch.If the
CONSTANToption 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
>>SETCDF 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>>SOURCEdirectives, 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.
The reserved words
FORMATandISare 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 73-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
>>SETCDF directive to perform this function.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.
The default TURN directive is ‘>>TURN EC-ALL CHECKING OFF’.
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.
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.
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.
SOURCE- Source Code ListingControl 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.
LIST- Object Code ListingLIST 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.
MAP- Storage Map ListingControl 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.