%INCLUDE (PL/I)

Purpose

Incorporates text from other files into the current source file during compilation.

Syntax

%INCLUDE filename[,filename]…;

Parameters

filename: One of the following: a character string, an Open PL/I name, or an Open PL/I name enclosed in parentheses.
The specified filename is used to locate a text file whose content is inserted into the program text in place of the %INCLUDE statement.

Description

The %INCLUDE statement incorporates text from other files into the current source file during compilation.

The %INCLUDE statement can appear in place of a name, constant, or punctuation symbol. The included text may contain additional %INCLUDE statements. %INCLUDE statements normally contain declarations that are common to more than one program module.

Open PL/I searches for a file to satisfy the %INCLUDE statement according to the following rules. (See the section Compiler Options in the chapter Using Open PL/I in your Open PL/I User's Guide).

In the following rules, we use the term "absolute directory path" for a path specifier beginning with a slash (/), such as /tmp/inc, and "relative directory path" for other path specifiers, such as sys/ or .. /.

When the %INCLUDE 'filename'; form is used; that is, the quoted filename form:
- filename may be more than just a simple PL/I identifier. For example, it may contain the commonly used "." (period) character, as in,
```
%INCLUDE 'fiiename.pl1.inc';
```
  It may also contain a directory path, as in,
```
%INCLUDE '/pl1/src/inc/filename';
```
- If the %INCLUDE statement specifies an absolute directory path, the indicated file will be sought in the specified directory and that directory only.
- If the %INCLUDE statement does not specify an absolute directory path and the -ipath option is not specified, the indicated file is sought in the current working directory.
- If the %INCLUDE statement does not specify an absolute directory path and the -ipath option is specified, the indicated file is sought in the directories specified by the -ipath option. These directories are searched in the order in which they are specified. If the file is not found in these directories, a final check is made for it in the current working directory.
- When the quoted filename form is used, the -isuffix option is never used.
- When the quoted filename form is used, Open PL/I searches for the file using the character case of each letter of filename exactly as specified. That is, the filename is not converted to uppercase, and no additional searches using other cases are conducted.
When the %INCLUDE filename; or the equivalent %INCLUDE (filename), form is used:
- If the -ipath option is not specified, the indicated file is sought in the current working directory.
- If the -ipath option is specified, the indicated file is sought in the directories specified by the -ipath option. These directories are searched in the order in which they are specified. If the file is not found in these directories, a final check is made for it in the current working directory.
- If the -isuffix option is used in the compiler invocation, the character string specified in the -isuffix option is appended to filename before the file search is conducted. For example, if -isuffix.inc is specified, the file to be searched for is filename.inc.
  In this case, with the filename not in quotes, Open PL/I first searches for the file with filename in uppercase characters; that is, FILENAME. If that search fails, Open PL/I tries again using lowercase letters.

Example

%INCLUDE 'FILE1.IN','FILE2.IN','FILE3.IN'; 

%INCLUDE FILE4,'FILE5',(FILE6),(FILE7); 

%INCLUDE 'TOTAL.IN';

In the previous examples, the contents of the files referenced by FILEn, and so on, and by 'TOTAL.IN' will be copied into the current file at compile time.

DECLARE I
%INCLUDE 'FDCL.IN'; STATIC INITIAL (0);

Assuming that the file referenced by ' FDCL.IN ' contains the single line FIXED BINARY (31) , this example is equivalent to the following:

DECLARE I FIXED BINARY (31) STATIC INITIAL (0);

Restrictions

None.