Line and File Directives

Line and file directives are comment strings that a preprocessor uses to pass information to the next preprocessor in the sequence. The information may include directory paths and filenames for the following preprocessor to access or specific instructions to be carried out. See Using Directives and Directive Syntax for more information on directives.

Every preprocessor that follows the first one invoked must scan its input for directives, and every preprocessor must put directives at the appropriate places in its output.

A directive always begins with an asterisk (*), which is placed in column 7 if the file is in ANSI format or in column 1 if the file is in Terminal format. The asterisk indicates a COBOL comment. A preprocessor should accept directives in either ANSI or Terminal format.

A directive of the following form indicates that subsequent input lines came from the specified source code file:

*(( PREPROC PPNAME FILE "<file specification>" ))

A preprocessor should replace the letters PPNAME in a directive with its own name (or any other name containing at most six alphanumeric characters). This field is used only for diagnostic purposes.

The file specification must be abbreviated if necessary, so that the directive will fit into a line of ANSI format without encroaching on the Identification Area.

Note:

In the ANSI format, code is limited to columns 1-72. Everything beyond this is part of the Identification Area and is not used, except for conditional compilation. If the directive is too long, it will extend into this area, possibly triggering spurious conditional compilation.
Examples in this section of the help show single spaces between items in directives. Actually, any reasonable number of spaces is acceptable.

The first preprocessor writes a directive of the preceding kind at the very beginning of its output file. Each subsequent preprocessor will read a directive of this kind at the very beginning of its input file and will write it at the beginning of its output file with only the preprocessor name changed.

Directives of this kind also appear whenever a preprocessor honors a COPY statement or its equivalent in other languages. There will usually be one such directive at the beginning of the copied code and another at its end.

Within each source file, the lines are numbered consecutively, beginning with line 1. If a preprocessor always produced one line of output for each line of input, it would need no other directives for line numbers. However, that is not usually the case and most preprocessors do need other directives.

A directive of the following form indicates that, until line numbering is changed by a subsequent directive, every line that follows came from the line whose number is embedded in the directive.

*(( PREPROC PPNAME LINE BEGIN <line number in decimal> ))

Normally, the embedded line number will be the number of the next line in the current source file. However, it might be larger if a previous preprocessor generated nothing from one or more lines in the source file.

When there are two or more lines following this directive, it is presumed that all of them were generated from the same line of source code. Although this is not always true, it is a necessary convention because preprocessors that do a lot of parsing and translation cannot always assign a specific source code line to each line of output.

A directive of the following form restores regular line numbering; that is, it indicates that the first line following the directive came from the line after the one whose number is embedded in the directive, and that until line numbering is changed by a subsequent directive for the same source file, every subsequent line came from the line after the previous line.

*(( PREPROC PPNAME LINE END <line number in decimal>))

These two directives normally come in matching pairs (although this is not required). For example, the source file may contain the following code (line number in parentheses):

(55)   display "Making connection".
(56)   EXEC SQL CONNECT TO :dsn-name as C1
(57)      END-EXEC.
(58)   display "Connection made".

The output may be as follows:

     display "Making Connection".
*(( PREPROC ACUSQL LINE BEGIN 56 )) 
     PERFORM CALL "SQL$START" END-CALL CALL "SQL$CONNECT" USING
     dsn-name 'C1' END-CALL IF SQLCODE OF SQLCA < 0 THEN GO TO
     Error-Exit END-IF END-PERFORM
*(( PREPROC ACUSQL LINE END 57 ))
     display "Connection made".

Preprocessors that process COBOL code may also use two other directives to indicate places where the source code format (ANSI or Terminal) may change.

The following directive indicates that subsequent lines may be in a different format because they were taken from a COPY file (or its equivalent in modified COBOL):

*(( PREPROC PPNAME INCLUDE BEGIN "<file specification>" ))

The following directive indicates that the code in the new format has ended and the format reverts to the one that prevailed before the matching INCLUDE BEGIN directive.

*(( PREPROC PPNAME INCLUDE END "<file specification>" ))

The file specification must be abbreviated, if necessary, so each directive will fit into a single line of ANSI format without encroaching on the Identification Area.

In the above examples the INCLUDE directives are necessary to tell the compiler that the format may have changed, while the FILE directives are necessary to tell the compiler that a new file has begun and error messages should refer to it.

Note: In the ANSI format, code is limited to columns 1-72. Everything beyond this is part of the Identification Area and is not used, except for conditional compilation. If the directive is too long, it will extend into this area, possibly triggering spurious conditional compilation.

Preprocessors that do not distinguish between COBOL formats should pass such directives along.