|
Purpose |
Instruct the compiler to read a text file from disk and treat it as an integral part of the source code. |
|
Syntax |
#INCLUDE "FileSpec" #INCLUDE ONCE "FileSpec" #INCLUDE THIS ONCE |
|
Remarks |
Use #INCLUDE to compile the text of another file along with the current file. The first form causes FileSpec to be included in every case it is encountered. The second form causes FileSpec to be included only once, the first time it is encountered. This is particularly useful when including common declaration files like WIN32API.INC to avoid redundant code, and the resulting errors. To be effective, the ONCE option must appear on every #INCLUDE of a particular file. Effectively, #INCLUDE ONCE means: "Include this file only if it has not already been included." The third form (#INCLUDE THIS ONCE) is placed in the file to be included, and produces an end result similar to form two. It tells the compiler to "Include me only one time, no matter how many times it is requested". Depending upon the content and context, this may be a simpler and more readable method to achieve the desired result. FileSpec is a string constant that follows normal LFN file-naming conventions, and which names a PowerBASIC source code file. If FileSpec does not include an extension, the compiler looks for that file name with the default extension of .BAS. If FileSpec does not include a path, the compiler scans the search path for each #INCLUDE file before checking the current (default) directory. For the IDE, the search path can be set in the Compiler Preferences tab in the Options dialog. The search path can also be specified when compiling from the command-line by using the /I Include option. The search path can contain one path or multiple paths to scan. If multiple paths are used, they are separated by a semicolon (;). When the compiler encounters an #INCLUDE metastatement, it reads FileSpec from disk and continues compilation with the source code in FileSpec. When the end of FileSpec is reached, compilation continues with the statement immediately following the #INCLUDE in the original source file. The result is the same as if the contents of the included file were physically present within the original text. This allows large source files to be broken into smaller sections that are more manageable. #INCLUDE metastatements can be nested as many as twelve levels deep. That is, an included file can have #INCLUDE metastatements of its own, including files that also have #INCLUDE metastatements, and so on, for a total of twelve levels of files (including the primary file). Note that macros count as #include files for nesting purposes. |
|
See also |
|
|
Example |
' MYHELLO.BAS #INCLUDE ONCE "WIN32API.INC" 'include Windows API calls FUNCTION PBMAIN MessageBox 0, "Hello World!", "PowerBASIC", %MB_OK END FUNCTION |