Chapter 18: Compiler-directing Statements

Compiler-directing statements control the processing of a compilation group. The following compiler-directing facilities are provided:

• Compiler-directing statements for specifying source text manipulation

• Compiler directives for specifying standard compilation options

• The BASIS mechanism

• The ++INCLUDE/ -INC mechanisms

• Conditional compilation

• The listing control statements

• Compiler directives that specify options specific to your COBOL system

18.1 Source Text Manipulation

18.1.1 The COPY Statement

Function

The COPY statement incorporates text into a COBOL compilation group.

Examples

General Format

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
   • COPYEXT - specifies the filename extension to be used for locating copy files.

   • COPYLBR - specifies that library-names are equivalent to .lbr files.

   • COPYLIST - causes the result of a COPY statement to be included in the listing file.

   • FOLD-COPY-NAME - allows the Compiler to find a copy library member when the library name on disk and the text-name in the COPY statement do not use the same upper-case and lower-case letters for the library member name.

   • OLDCOPY - changes the handling of COPY statements to match the ANS'68 and OS/VS COBOL LANGLVL(1) rules.

Syntax Rules

1. If more than one COBOL library is available while the source is passed through the COBOL system, text-name must be qualified by the library-name identifying the COBOL library in which the text associated with text-name resides. See your COBOL system documentation for details of libraries.

   This restriction is removed.

2. The COPY statement must be preceded by a space and terminated by the separator period.

3. Pseudo-text-1 must not be null, nor can it consist solely of either the character space(s) or comment lines.

4. Pseudo-text-2 can be null.

5. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued. However, both characters of a pseudo-text delimiter must be on the same line. (See the section Continuation of Lines in the chapter Language Fundamentals.)

6. Word-1 or word-2 can be any single COBOL word.

7. A COPY statement can occur in the compilation group anywhere a character-string or a separator can occur except that a COPY statement must not occur within another COPY statement.

8. Text-name defines a unique external file-name which conforms to the rules for user-defined words.

   External-file-name-literal is an alphanumeric literal that conforms to the operating system rules for file-names. It can be specified with or without enclosing quotation marks.

   Text-names and unquoted external-file-name-literals are always converted to upper case.

9. Library-name-literal is an alphanumeric literal that conforms either to the operating system rules for file-names or to the operating system rules for device identifiers. It can be specified with or without enclosing quotation marks.

   Library-name-literals not inside quotation marks are always converted to upper case.

10. The SUPPRESS phrase is used to suppress the printing of the contents of the copy member on the source listing.

11. If the word COPY appears in a comment-entry or in the place where a comment entry can appear, it is considered part of the comment-entry.

    A COPY statement that appears in a comment-entry is processed.

12. External-file-name-literal and library-name-literal, when enclosed in quotation marks, may contain the $, #, and @ characters.

13. Partial-word-1 must consist of one text word.

14. Partial-word-2 must consist of zero or one text word.

15. Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.

16. Library text must conform to the rules for COBOL reference format.

General Rules

1. The compilation of a compilation group containing COPY statements is logically equivalent to the processing of all COPY statements before the processing of the resultant compilation group.

2. The effect of processing a COPY statement is that the library text associated with text-name is copied into the source text, logically replacing the entire COPY statement, beginning with the reserved word COPY and ending with the punctuation character period, inclusive.

3. If the REPLACING phrase is not specified, the library text is copied unchanged.

   If the REPLACING phrase is specified, the library text is copied and each properly matched occurrence of pseudo-text-1, identifier-1, literal-1, word-1 and partial-word-1 in the library text is replaced by the corresponding pseudo-text-2, identifier-2, literal-2, word-2 or partial-word-2.

4. For purposes of matching, identifier-1, literal-1 and word-1 are treated as pseudo-text containing only identifier-1, literal-1 or word-1, respectively.

5. The comparison operation to determine text replacement occurs in the following manner:
   1. The leftmost library text word which is not a separator comma or a separator semicolon is the first text word used for comparison. Any text word or space preceding this text word is copied into the source text. Starting with the first text word for comparison and first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 that was specified in the REPLACING phrase, the entire REPLACING phrase operand that precedes the reserved word BY is compared to an equivalent number of contiguous library text words.

   2. Pseudo-text-1, identifier-1, word-1, or literal-1 match the library text if, and only if, the ordered sequence of text words that forms pseudo-text-1, identifier-1, word-1, or literal-1 is equal, character for character, to the ordered sequence of library text words.

   3. When the LEADING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of a library text-word. When the TRAILING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of a library text-word.

   4. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the library text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.

      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.

      3. Text words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.

   5. If no match occurs, the comparison is repeated with each next successive pseudo-text-1, identifier-1, word-1, literal-1, or pseudo-text-1, if any, in the REPLACING phrase until either a match is found or there is no next successive REPLACING operand.

   6. When all the REPLACING phrase operands have been compared and no match has occurred, the leftmost library text word is copied into the source text. The next successive library text word is then considered as the leftmost library text word, and the comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1, or partial-word-1 specified in the REPLACING phrase.

   7. Whenever a match occurs between pseudo-text-1, identifier-1, word-1, or literal-1 and the library text, the corresponding pseudo-text-2, identifier-2, word-2, or literal-2 is placed into the source text.

      When a match occurs between partial-word-1 and the library text-word, the library text-word is placed into the resultant text with the matched characters either replaced by partial-word-1 or deleted when partial-word-2 consists of zero text-words.

      The library text word immediately following the rightmost text word that participated in the match is then considered as the leftmost text word. The comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 specified in the REPLACING phrase.

   8. The comparison operation continues until the rightmost text word in the library text has either participated in a match or been considered as a leftmost library text word and participated in a complete comparison cycle.

6. A comment line occurring in either the library text or pseudo-text-1 is interpreted, for purposes of matching, as a single space. Comment lines appearing in either pseudo-text-2 or library text are copied into the source text unchanged.

7. The text produced as a result of the complete processing of a COPY statement must not contain a COPY statement.

   This text can contain a COPY statement provided neither this contained COPY nor the already expanded COPY includes the REPLACING phrase. However, recursive COPY statements (where a library-text is referred to by a COPY statement within it) are not allowed.

   COPY statements may be nested in this way to any level. One of the COPY statements in this structure may include the REPLACING phrase, and the replacements specified are in effect for all subsidiary COPY statements.

8. The syntactic correctness of the library text cannot be independently determined.

   Except for COPY statements,

   the syntactic correctness of the entire COBOL compilation group cannot be determined until all COPY statements have been completely processed.

9. If the REPLACING phrase is specified, the library text must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.

10. Each text word copied from the library but not replaced, or only partially replaced, is copied so as to start in the same area of the line in the resultant source text as it begins in the line within the library. However, if a text word copied from the library begins in area A but follows another text word, which also begins in area A of the same line, and if replacement of a preceding text word in the line by replacement text of greater length occurs, the following text word begins in area B if it cannot begin in area A. Each text word in pseudo-text-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as it appears in pseudo-text-2. Each identifier-2, literal-2, and word-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as the leftmost library text word that participated in the match would appear if it had not been replaced.

    If additional lines are introduced into the source text as a result of a COPY statement, each text word introduced appears on a debugging line if the copy statement begins on a debugging line, or if the text word being introduced appears on a debugging line in library text. When a text word specified in the BY phrase is introduced, it appears on a debugging line if the first library text word being replaced is specified on a debugging line. Except in the preceding cases, only those text words that are specified on debugging lines where the debugging line is within pseudo-text-2 appear on debugging lines in the resultant source text. If any literal specified as literal-2 or within pseudo-text-2 or library text is of too great a length to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced which contain the remainder of the literal. If replacement requires that the continued literal be continued on a debugging line, the compilation group is in error.

11. For purposes of compilation, text-words after replacement are placed in the source text according to the rules for reference format as described in the section Reference Format in the chapter Language Fundamentals.

12. If the unit identifier is not explicitly specified, the default drive is used. (The default is operating system-dependent.)

13. The OLDCOPY Compiler directive causes the entire entry to be replaced by the information identified by text-name, except that the data-name preceding the COPY statement replaces the corresponding data-name in the text-name.

14. If certain conventions are followed in library text, parts of names, for example the prefix portion of data-names, can be changed with the REPLACING phrase.

    To use this type of "partial word replacement" the portion of the words to be modified must be enclosed in one of the following ways:

    1. In pairs of left and right parentheses. For example, (ABC)

    2. Within colons. For example :XYZ:

Note: The LEADING and TRAILING phrases can also be used for partial word replacement. The LEADING and TRAILING phrases are supported by the MF dialect and the next COBOL standard, however, they are not included in the ANSI '85 COBOL standard.

18.1.2 The REPLACE Statement

Function

The REPLACE statement modifies source text in a compilation group.

General Formats

Format 1

Format 2

Syntax Rules

1. A REPLACE statement can be specified anywhere in source text or in library text that a character-string or a separator, other than the closing delimiter of a literal, can appear. It must be preceded by a separator space except when it is the first statement in a compilation group.

2. A REPLACE statement must be terminated by a separator period.

3. Pseudo-text-1 must contain one or more text words.

4. Pseudo-text-2 can contain zero, one, or more text words.

5. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued.

6. A text word within pseudo-text must be between 1 and 322 characters long.

7. Pseudo-text-1 must not consist entirely of a separator comma or a separator semicolon.

8. If the word REPLACE appears in a comment-entry or in the place where a comment-entry can appear, it is considered part of the comment-entry.

9. Partial-word-1 must consist of one text-word.

10. Partial-word-2 must consist of zero or one text-word.

11. Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.

General Rules

1. Pseudo-text-1 specifies the source text to be replaced by pseudo-text-2.

2. Partial-word-1 specifies the text to be replaced by partial-word-2.

3. The Format 2 REPLACE statement specifies that any text replacement currently in effect is discontinued.

4. A given occurrence of the REPLACE statement is in effect from the point at which it is specified until the next occurrence of the REPLACE statement or the end of the compilation unit, respectively.

5. Any REPLACE statements contained in a source unit are processed after the processing of any COPY statements contained in that source unit.

6. The text produced as a result of the processing of a REPLACE statement must contain neither a COPY statement nor a REPLACE statement.

7. The comparison operation to determine text replacement begins with the text immediately following the REPLACE statement and occurs in the following manner:
   1. Starting with the leftmost source text word and the first pseudo-text-1 or partial-word-1, pseudo-text-1 or partial-word-1 is compared to an equivalent number of contiguous source text words.

   2. Pseudo-text-1 matches the source text if, and only if, the order sequence of text words that forms pseudo-text-1 is equal, character for character, to the ordered sequence of source text words.

      When the LEADING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of that source text-word. When the TRAILING phrase is specified, partial-word-1 matches the source text-word only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of that source text-word.

   3. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the source text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.

      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.

      3. Text words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.

   4. If no match occurs, the comparison is repeated with each next successive occurrence of pseudo-text-1 or partial-word-1, until either a match is found or there is no next successive occurrence of pseudo-text-1 or partial-word-1.

   5. When all occurrences of pseudo-text-1 or partial-word-1 have been compared and no match has occurred, the next successive source text-word is then considered as the leftmost source text-word, and the comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.

   6. Whenever a match occurs between pseudo-text-1 and the source text, the corresponding pseudo-text-2 replaces the matched text in the source text.

      When a match occurs between partial-word-1 and the source text-word, the matched characters of that source text-word are either replaced by partial-word-2 or deleted when partial-word-2 consists of zero text-words.

      The source text word immediately following the rightmost text word that participated in the match is then considered as the leftmost source text word. The comparison cycle starts again with the first occurrence of pseudo-text-1 or partial-word-1.

   7. The comparison operation continues until the rightmost text word in the source text which is within the scope of the REPLACE statement has either participated in a match or been considered as a leftmost source text word and participated in a complete comparison cycle.

8. Comment lines or blank lines occurring in either the source text or pseudo-text-1 are ignored for purposes of matching; and the sequence of text words in the source text and in pseudo-text-1 is determined by the rules for reference format. See the section Reference Format Representation in the chapter Language Fundamentals. Comment lines or blank lines in pseudo-text-2 are placed into the resultant source text unchanged whenever pseudo-text-2 is placed into the source text as a result of text replacement. A comment line or blank line in source text is not placed into the resultant source text if that comment line or blank line appears within the sequence of text words that match pseudo-text-1.

9. Only after all COPY and REPLACE statements have been completely processed, can the syntactical correctness of the rest of the source code be determined.

10. Text words inserted into the source text as a result of processing a REPLACE statement are placed in the source text according to the rules for reference format. See the section Reference Format in the chapter Language Fundamentals. When inserting text words of pseudo-text-2 into the source text, additional spaces can be introduced only between text words where a space (including the assumed space between source lines) already exists.

11. If additional lines are introduced into the source text as a result of the processing of REPLACE statements, the indicator area of the introduced lines contains the same character as the line on which the text being replaced begins, unless that line contains a hyphen, in which case the introduced line contains a space.

    If any literal within pseudo-text-2 is of a length too great to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced to contain the remainder of the literal. If replacement requires the continued literal to be continued on a debugging line, the compilation unit is in error.

12. The source text for which a REPLACE statement is in effect must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.

18.2 Compiler Directives

A compiler directive specifies options or compilation variables for use by the compiler.

General Format

>>compiler-instruction

Syntax Rules

1. A compiler directive must be specified on one line, except for the EVALUATE and the IF directives for which there are specific rules.

2. A compiler directive must be preceded only by zero, one, or more space characters.

3. When the reference format is fixed format, a compiler directive must be specified in the program-text area and may be followed only by space characters.

4. When the reference format is free format, a compiler directive can be followed only by space characters and an optional in-line comment.

5. A compiler directive is composed of the two contiguous COBOL characters >>, optionally followed by the COBOL character space, followed by compiler-instruction. >> is treated as though it were followed by a space if no space is specified after >>.

6. Compiler-instruction is composed of the compiler-directive words defined in the specific syntax for each directive.

7. A compiler-directive word is reserved within the context of the compiler directive in which it is specified and may be used elsewhere as any type of COBOL word.

8. A compiler directive can be specified anywhere in a compilation group except
   1. As restricted by the rules for the specific compiler directive,

   2. Within a source text manipulation statement,

   3. Between the lines of a continued character string,

   4. On a debugging line.

9. Compiler directive lines can be specified within library text.

10. A literal in a compiler directive must not be specified as a concatenation expression or a figurative constant.

General Rules

1. A compiler directive is treated as a single blank line during the matching operation of a COPY or REPLACE statement. A directive will not match any pseudo-text or partial-word and therefore is not affected by the replacing action.

2. A compiler directive is processed before, during, or after the processing of COPY and REPLACE statements as indicated in the specific rules for each directive.

3. The compiler directives >>EVALUATE, and >>IF, when specified in the source-text of >>IF and >>EVALUATE directives take effect when encountered during conditional compilation. All other compiler directives are processed when the source code resulting from conditional compilation is processed.

18.2.1 Conditional Compilation

The use of certain compiler directives provides a means of including or omitting selected lines of source code. This is called conditional compilation. The compiler directives that are used for conditional compilation are the EVALUATE directive and the IF directive. The EVALUATE and IF directives are used to select lines of code that are to be compiled or are to be omitted during compilation.

18.2.2 Arithmetic Expressions in Directives

An arithmetic expression can be specified in the EVALUATE directive and in a constant conditional expression. The formation, the order of precedence, and the rules for evaluation of these arithmetic expressions are shown in the section Arithmetic Expressions in the chapter Procedure Division. The following addition rules apply:

1. All operands must be fixed-point numeric literals or arithmetic expressions in which all operands are fixed-point numeric literals.

   ---

   Note: This includes constants that are equated to a fixed-point numeric literal.

   ---

2. After each arithmetic operation, the result is truncated to the integer part of the value and the resultant value is considered to be an integer.

3. After the arithmetic expression is evaluated, the resulting value is considered to be a numeric literal.

4. An arithmetic expression must not result in a size error condition.

18.2.3 Constant Conditional Expression

A constant conditional expression is a conditional expression in which all the operands are literals or arithmetic expressions containing only literal terms. A special form of condition known as a defined condition may also be used as part of a constant conditional expression.

Syntax Rules

1. A constant conditional expression must be one of the following:
   1. A simple relation condition in which both operands are either literals or arithmetic expressions containing only literal terms and which is formed according to the rules in the section Relation Condition in the chapter Procedure Division. The following rules also apply:
      1. The operands on both sides of the relational operator must be the same category. An arithmetic expression is of the category numeric.

      2. If literals are specified and they are not numeric literals, the relational operator must be "IS [ NOT ] EQUAL TO" or "IS [ NOT ] =".

   2. A defined condition.

   3. A complex condition as specified in the section Complex Conditions in the chapter Procedure Division which is formed by combining the above forms of simple conditions into complex conditions. Abbreviated combined relation conditions must not be specified.

General Rules

1. Complex conditions are evaluated according to the rules in the section Complex Conditions in the chapter Procedure Division.

2. For a simple relation condition where the operands are not numeric, no collating sequence is used for the comparison. A character by character comparison for equality is used.

Note: This means that upper-case and lower-case letters are not equivalent.

18.2.4 Defined Condition

General format

compilation-variable-name-1 IS [ NOT ] DEFINED

General Rules

1. A defined condition using the IS DEFINED syntax evaluates TRUE if compilation-variable-name-1 is currently defined.

2. A defined condition using the IS NOT DEFINED syntax evaluates TRUE if compilation-variable-name-1 is not currently defined.

18.2.5 EVALUATE Directive

The EVALUATE directive provides for multi-branch conditional compilation.

General Format

Format 1

Format 2

Syntax Rules

All Formats

1. Each pair of contiguous COBOL characters >> and the succeeding compiler-directive words and operands up to, but not including, source-text-1 and source-text-2 must be specified on a new line and be specified entirely on that line. The first text-word of source-text-1 and the first text-word of source-text-2 must each begin on a new line.

2. Source-text-1 and source-text-2 can be any kind of source text, including compiler directives. Source-text-1 and source-text-2 can span multiple lines.

Format 1

3. All operands of one EVALUATE directive must be of the same category. For this rule, an arithmetic expression is of category numeric.

4. If the THROUGH phrase is specified, all selection subjects and selection objects must be of category numeric.

5. The words THROUGH and THRU are equivalent.

General Rules

All Formats

1. The EVALUATE directive is processed during the processing of COPY and REPLACE statements.

Format 1

2. Literal-1 or arithmetic-expression-1, referred to as the selection subject, is compared against the values specified in each WHEN phrase in turn as follows:
   1. If the THROUGH phrase is not specified, a TRUE result is returned if the selection subject is equal to literal-2 or arithmetic-expression-2.

   2. If the THROUGH phrase is specified, a TRUE result is returned if the selection subject lies in the inclusive range determined by literal-2 or arithmetic-expression-2 and literal-3 or arithmetic-expression-3.

   As soon as a WHEN phrase is found that yields a TRUE result, the associated source-text-1 is compiled and all remaining lines up to and including the >>END-EVALUATE line are ignored. If no WHEN phrase yields a TRUE result, the source-text-2 associated with the >>WHEN OTHER phrase, if specified, is compiled.

Format 2

3. For each WHEN phrase in turn, the constant-conditional-expression is evaluated.

   As soon as a WHEN phrase is found that yields a TRUE result, the associated source-text-1 is compiled and all remaining lines up to and including the >>END-EVALUATE line are ignored. If no WHEN phrase yields a TRUE result, the source-text-2 associated with the >>WHEN OTHER, if specified, is compiled.

18.2.6 IF Directive

The IF directive provides for one-way or two-way conditional compilation.

General Format

>>IF constant-conditional-expression-1 [source-text-1]
  [ >>ELSE [source-text-2] ]
   >>END-IF

Syntax Rules

1. Each pair of contiguous COBOL characters >> and the succeeding compiler-directive words and operands up to, but not including, source-text-1 and source-text-2 must be specified on a new line and be specified entirely on that line. The first text-word of source-text-1 and the first text-word of source-text-2 must each begin on a new line.

2. Source-text-1 and source-text-2 may be any kind of source text, including compiler directives. Source-text-1 and source-text-2 may span multiple lines.

General Rules

1. The IF directive is processed during the processing of COPY and REPLACE statements.

2. If constant-conditional-expression-1 evaluates to TRUE, then source-text-1 is compiled as part of the source text, and source-text-2 is ignored.

3. If constant-conditional-expression-1 evaluates to FALSE, then source-text-1 is ignored and source-text-2, if specified, is compiled as part of the source text.

18.2.7 REPOSITORY Directive

The REPOSITORY directive specifies whether information is added to the external repository. It also specifies whether prototypes and definitions are checked against the interface information in the external repository.

General Format

Directives

1. In addition to the Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
   • RDFPATH - specifies the location of the library for the repository files.

Syntax Rules

1. The REPOSITORY directive must be specified only before the first Identification Division of a compilation unit and must not be specified within a compilation unit.

2. The REPOSITORY directive applies to the remainder of the compilation group or until another REPOSITORY directive is encountered.

General Rules

1. If no REPOSITORY directive is specified, the result is as if the directive had been specified as:

              >>REPOSITORY UPDATE OFF WITH CHECKING.

2. If the ON phrase is specified explicitly or implicitly, the information for a compilation unit is added to the external repository before the next compilation unit is compiled or at the end of the compilation group if there is no next compilation unit.

3. If the OFF phrase is specified, the external repository is not updated by the compiler.

4. If the CHECKING phrase is specified, a warning mechanism flags a class-definition or interface-definition that differs from the information about that source unit in the external repository. Details on the information in the external repository are specified in the section External Repository in the chapter Language Fundamentals.

18.3 The BASIS Mechanism

The BASIS mechanism provides support to allow an entire COBOL source file to be non-interactively edited, temporarily, and the result of this edit to be submitted to your COBOL system. The COBOL source file referenced as the source of the temporary edit (the "subject program") remains unchanged, and there is no record of the result of the edit other than the files output by your COBOL system (listing, and so on). The resulting code file cannot be animated since there is no source file for reference.

The BASIS mechanism is valid for fixed-format source only.

The program submitted to your COBOL system consists of two files: an edit control file (containing the BASIS statement and editing information) and the COBOL source file (the subject program as described above).

Three special statements are associated with the BASIS mechanism:

1. BASIS

2. INSERT

3. DELETE.

These special statements are not part of the COBOL language. Each one must, in its entirety, be contained on a single line and must be in upper case.

If you use INSERT or DELETE statements to modify a COBOL source program specified in a BASIS statement, the sequence field of the COBOL source program must contain numeric sequence numbers in ascending order.

1. A DELETE statement wholly within area B of the source-program line, not followed by a valid subject-sequence or subject-sequence-range, is treated as a COBOL DELETE statement by your COBOL system.

2. Within the BASIS mechanism DELETE statement, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.

3. Within the edit control file, all subject-sequence and subject-sequence-range numbers must be in ascending numeric order.

18.3.1 The BASIS Statement

Function

The BASIS statement identifies that the program (the edit control file and the COBOL source file) is to be submitted to your COBOL system under the BASIS mechanism rules.

General Format

Syntax Rules

1. The BASIS statement must be the first line of the edit control file.

2. The BASIS reserved word can commence anywhere between columns 1 and 66 of the statement line.

3. Sequence numbers can be included anywhere in columns 1 through 6 of the statement and must be followed by a space.

4. Text-name defines a unique external file-name which conforms to the rules for user-defined words. Lower case is translated into upper case. External-file-name-literal is an alphanumeric literal enclosed in quotation marks, which conforms to the operating system rules for file-names.

General Rules

1. Text-name or external-file-name-literal determines the COBOL source file to be edited by the control file.

2. The editing of the COBOL source file is determined by the INSERT and DELETE statements in the edit control file.

18.3.2 The DELETE Statement - BASIS Control

Function

The DELETE statement (under the BASIS mechanism) identifies lines of the COBOL source file to be ignored by your COBOL system. Any COBOL statements that follow the DELETE statement (up to the next BASIS mechanism INSERT or DELETE statement in the edit control file) are included.

General Format

Syntax Rules

1. The DELETE reserved word can commence anywhere between columns 1 and 66 of the statement line.

2. Sequence numbers can be included anywhere in columns 1 through 6 of the statement and must be followed by a space.

3. Subject-sequence-1, subject-sequence-2, and so on, must be 6-digit positive integers (following the rules for integer numeric-literals).

4. Subject-sequence-range-1, subject-sequence-range-2, and so on, must consist of two subject-sequence numbers (as above) separated by a hyphen (-).

5. The comma between subject-sequences and/or subject-sequence ranges is mandatory.

General Rules

1. Subject-sequence-1, subject-sequence-2, and so on, refer to sequence numbers of those statements within the COBOL source file which are to be ignored by your COBOL system.

2. Subject-sequence-range-1, subject-sequence-range-2, and so on, refer to inclusive ranges of statement sequence numbers within the COBOL source file, all of which statements are to be ignored when the intermediate code is produced.

3. Any COBOL statements following the DELETE statement in the edit control file up to the next BASIS mechanism DELETE or INSERT statement are included in the source submitted to your COBOL system. These COBOL source statements are inserted in place of the last statement omitted by this BASIS mechanism DELETE statement.

18.3.3 The INSERT Statement - BASIS Control

Function

The INSERT statement (under the BASIS mechanism) lists lines of COBOL source to be included in the program submitted to your COBOL system.

General Format

Syntax Rules

1. The INSERT reserved word can commence anywhere between columns 1 and 66 of the statement line.

2. Subject-sequence must be a positive numeric integer (following the rules for integer numeric literals).

General Rules

1. Subject-sequence refers to that statement within the COBOL source file after which the COBOL statement(s) is to be included.

2. All the COBOL statements following the INSERT statement in the edit control file up to the next BASIS mechanism DELETE or INSERT statement are included in the source submitted to your COBOL system. At least one COBOL statement must immediately follow the BASIS mechanism INSERT statement.

18.4 The ++INCLUDE and -INC Mechanisms

The ++INCLUDE and -INC mechanisms provide an IBM-mainframe compatible means whereby a COBOL program source file or portion of source code can be included in a file to be compiled.

18.4.1 The -INC Statement

Function

The -INC statement is used to include all of the data records of one source file in another source file at compilation time.

General Format

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
   • LIBRARIAN - enables the use of -INC syntax.

Syntax Rules

1. -INC must begin in column 1 and be followed by one or more spaces.

2. Text-name defines a unique external file-name which conforms to the rules for user-defined words.

3. This special statement is not part of the COBOL language. It must, in its entirety, be contained on a single line and must be in upper case.

General Rules

1. Text-name determines the COBOL source file to be included at this specific place in the source code.

2. Any other text appearing on the line is treated as a comment.

18.4.2 The ++INCLUDE Statement

Function

The ++INCLUDE statement is used to include all of the data records of one source file in another source file at compilation time.

General Format

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or the semantics described in this section.
   • PANVALET - enables the use of ++INCLUDE syntax.

Syntax Rules

1. ++INCLUDE must begin in column 8, must be in upper case and must be followed by one or more spaces.

2. Text-name defines a unique external file-name which conforms to the rules for user-defined words.

3. This special statement is not part of the COBOL language. It must, in its entirety, be contained on a single line and must be in upper case.

General Rules

1. Text-name determines the COBOL source file to be included at this place in the source code.

2. Any other text appearing on the line is treated as a comment.

18.5 Conditional Compilation

The COBOL system provides a mechanism for selectively compiling part or all of the COBOL source. To benefit fully from the advantages of conditional compilation the use of level 78 (see the section Level Number in the chapter Data Division - File and Data Description) and the CONSTANT Compiler directive is recommended. Conditional compilation is controlled by $IF, $ELSE, $END constructs, which behave in a similar way to the COBOL IF construct. Conditional compilation also supplies the $DISPLAY statement, which can be used to display a message during compilation or include a version number in the object file.

Syntax Rules

1. Conditional compilation statements are indicated by a dollar ($) in column 7 in fixed-format source, or column 1 in free-format source of the COBOL source line followed by one of the key words IF, DISPLAY, ELSE, END.

2. Conditional compilation should not be used to split a COBOL character string; that is, continuation lines should not be split by conditional compilation controls.

18.5.1 $DISPLAY Statement

Function

The $DISPLAY statement displays a message on the standard output device during compilation or includes a version number in the object file.

General Format

Format 1

Format 2

Syntax Rules

1. The whole $DISPLAY statement must appear on a single line.

General Rules

1. If a $DISPLAY statement is encountered on a source line that is ignored by conditional compilation, there is neither a compile-time nor a runtime effect.

Format 1

2. Text-data is displayed on the standard output device during compilation.

Format 2

3. Version-number is the content of the entire source line following the "=", excluding leading and trailing spaces.

4. The character string formed by concatenating "@(#)", version-number and a null character (binary zero) is included in the object file, no matter which type of object file is created. If version-number begins with the characters "@(#)", the system does not concatenate these characters when forming the character string..

Notes:

• Version-number can be any text string, however, it is intended to contain a version number for which a pattern matching tool, such as the UNIX sccs "what" utility, can search the object file.

• Unreachable procedural code is eliminated by the Compiler during the optimization phase and the literals used only in that code are discarded. The practice of including version numbers in Procedure Division statements by using the following technique does not work:

   filename-what section.
       move "@(#)filename %I%>" to what-string 
       perform filename-what 

• Since the $DISPLAY statement can be specified anywhere in the source code, each text-name (copybook) can have its own version number.

• Older compilers treat a format 2 $DISPLAY statement as a format 1 $DISPLAY statement.

18.5.2 $ELSE Statement

Function

General Format

Syntax Rules

1. The whole statement must appear on a single line.

18.5.3 $END Statement

Function

General Format

Syntax Rules

1. The whole statement must appear on a single line.

18.5.4 $IF Statement

Function

A $IF statement provides the means whereby selected parts of the source text are not included in the compilation.

Examples

1. An example of using conditional compilation is provided in the section $IF Statement (Conditional Compilation) in the chapter Examples in your Language Reference - Additional Topics.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

1. Constant-name-1 is defined by a level 78 entry or a CONSTANT Compiler directive.

2. If literal-1 is numeric, it must be zero or a positive integer.

3. Directive-setting is specified in the same format as it is given in a $SET statement and may be preceded by NO. However, the format used in the $IF statement differs from the format used in the $SET statement as follows:
   1. No spaces are permitted between the NO and directive name

   2. Hyphens in the directive must be specified exactly

   3. If the directive has a parameter it may be omitted

4. Only directives used in the syntax-check phase and produced in the directive settings list (see compiler directive SETTINGS) may be specified for directive-setting

5. The whole statement must appear on a single line.

6. $IF can be nested within another $IF.

General Rules

1. Constant-name-2 is DEFINED if it is the subject of a level 78 entry or a CONSTANT Compiler directive, otherwise it is NOT DEFINED.

2. Directive-setting SET evaluates true if the given setting matches the actual directive setting. If a parameter is specified then it must also match.

3. The comparison between Directive-setting and the actual directive setting is not case sensitive.

4. If the condition evaluates true the source lines following the $IF statement are processed. If the condition evaluates false, COBOL source lines are ignored until the next conditional compilation line is encountered.

18.6 The Listing Control Statements

The listing control statements provide a control for producing output file listings during the compile process.

Three statements are associated with the listing control statements:

1. EJECT

2. SKIP1, SKIP2 AND SKIP3

3. TITLE.

18.6.1 The EJECT Statement

Function

The EJECT statement tells your COBOL system to print the next line of source code at the top of the next page.

General Format

Syntax Rules

1. EJECT may begin either in area A or in area B, must be the only statement on the line and may optionally be followed by a period.

General Rules

1. The EJECT statement itself is not printed.

18.6.2 The SKIP1, SKIP2 and SKIP3 Statements

Function

The SKIP1, SKIP2 and SKIP3 statements control the vertical spacing of the source code listing produced by your COBOL system. They specify the lines to be skipped in the source code listing.

General Format

Syntax Rules

1. The statement can begin in area A or in area B, must be the only statement on the line

   and can optionally be followed by a period.

General Rules

1. SKIP1 tells your COBOL system to skip one line (double spacing). SKIP2 tells your COBOL system to skip two lines (triple spacing). SKIP3 tells your COBOL system to skip three lines (quadruple spacing).

2. The SKIP statement itself is not printed.

18.6.3 The TITLE Statement

Function

The TITLE statement tells your COBOL system what title to print on the first line of all subsequent pages of the listing.

General Format

Syntax Rules

1. Literal-1 must be nonnumeric and can be followed by a period. It cannot be a figurative constant.

2. The word TITLE can begin either in Area A or Area B and must be the only statement on the line.

3. The TITLE statement can appear anywhere in the compilation group.

General Rules

1. Literal-1 is used as a title on all subsequent pages of the listing. The default title, which is used until a TITLE directive is encountered, identifies your COBOL system and its current release level.

2. The chosen or default title occupies the left-hand side of the first line of each page. The remainder of the line gives the date and time the intermediate code is produced and a page number.

3. A second title line is also output containing the name of the main source file and of the current text-name (copybook).

4. The TITLE statement causes an immediate new page.

5. The TITLE statement itself is not printed.

Copyright © 2002 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.