INCLUDE Directive (Insert File Contents into Input Stream)

The INCLUDE directive "stacks" the current source file and begins reading tokens from the source file given by the FileName argument. If you use the INCLUDE directive, you need not repeat a sequence of statements that are common to several source files.

Syntax

INCLUDE FileName

Remarks

The assembler uses the following search order when attempting to open the INCLUDE file:

• If the FileName argument contains a fully qualified path name (one that begins with a back slash or forward slash), then the assembler attempts to open the file exactly as specified, and no other search is performed if the file is not found.

• If the FileName begins with a relative path name or contains no path information, the assembler begins searching for the INCLUDE file by looking in the directory of the source file that issued the INCLUDE directive.

• The assembler searches for FileName in the list of directories given by any -Fdi or -I options found on the command line.

• The assembler searches for FileName in the list of directories given by the <BaseEXE>_INCLUDE environment variable.

• The assembler searches for FileName in the list of directories given by the INCLUDE environment variable.

• Lastly, the assembler searches for FileName in the current directory. If the named file is not found, the assembler issues a fatal error message and the assembler is ended.
In no case does the assembler strip relative path information from the FileName when performing search steps 2 through 6.

When the file named in the INCLUDE directive is located, the assembler opens it and assembles all of the statements contained therein until the end of the file is reached. The file is then closed and assembler resumes in the original module at the line following the INCLUDE directive.

An INCLUDE file should not contain an END assembler directive to denote the end of the included module; the assembler closes the included module when its physical end of file is reached.

INCLUDE files may be nested to any reasonable level, and is limited only by the operating system's ability to provide the necessary resources.

Example

INCLUDE OS2.INC

---

[Back: ECHO Directive (Display Message on Standard Output Device)]
[Next: COMMENT Directive (Program Information Block)]