What is #include directive ?
#include
Include a file into the current source file
Syntax :
#include “<headerFileSpec>”
Arguments
<headerFileSpec> specifies the name of another source file to include in the current source file. As indicated in the syntax, the name must be enclosed in double quotation marks.
<headerFileSpec> may contain an explicit path and file name as well as a file extension. If, however, no path is specified, the preprocessor searches the following places:
. Source file directory
. Directories supplied with the /I option
. Directories specified in the INCLUDE environment variable
#include directives may be nested up to 15 levels deep–that is, a file that has been included may contain #include directives, up to 15 levels.
Description
#include inserts the contents of the specified file in place of the #include directive in the source file. By convention, the file inserted is referred to as a header file. Header files should contain only preprocessor directives and external declarations. By convention header files have a .ch extension.
When deciding where to locate your header files, you have two basic choices. You can place them in the source file directory where they are local to the current system; or, you can make them globally available by placing them in the directory specified in the INCLUDE environment variable. A list of one or more directories can be specified.
Header files overcome the one major drawback of defining constants or inline functions–the #define directive only affects the file in which it is contained. This means that every program which needs access to these statements must have a list of directives at the top. The solution to this problem is to place #define statements in a separate file and use the #include directive to tell the preprocessor to include that file before compiling.
For example, suppose the file “Inkey.ch” contains a list of #define directives assigning key values to constants. Instead of including these directives at the top of each program file (.prg) requiring access to them, you can simply place the following line at the top of each program file:
#include “Inkey.ch”
This causes the preprocessor to look for Inkey.ch and place all the directives contained within it at the top of this program.
Another advantage of using the #include directive is that all the #define statements are contained in one file. If any modifications to these statements are necessary, only the #include file need be altered; the program itself remains untouched.
Note that the scope of definitions within an included header file is the current program file unless the header file is included on the compiler command line with the /U option. In this case, the scope is all the program files compiled in the current invocation of the compiler.
Notes
Supplied header files: The compiler provides a number of header files containing manifest constants for common operations.
Std.ch–the standard header file: Std.ch is the standard header file provided with compiler. Std.ch contains the definitions of all compiler commands and the standard functions specified as pseudofunctions. It is strongly recommended that no changes be made to Std.ch. If changes are desired, it is advisable to copy Std.ch to a new name, make the changes, and compile with /U.
This header file differs somewhat from a header file you might #include in that everything defined in Std.ch, with #define, #translate, or #command, has a scope of the entire compile rather than the current source file.
Examples
This example uses #include to insert Inkey.ch, a file of common keyboard definitions, into a key exception handler called by an interface function:
#include "Inkey.ch"
FUNCTION GetEvent()
LOCAL nKey, nResult
nKey = INKEY(0)
DO CASE
CASE nKey = K_F10
nResult := DoMenu("Browse")
CASE nKey = K_ESC
nResult := DoQuit()
.
. <statements>
.
CASE nKey = K_CTRL_RIGHT
nResult := DoNextRec()
ENDCASE
RETURN nResult