Include a file into the current source file
<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.
#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
Clipper 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
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.
. Supplied header files: Clipper provides a number of header
files containing manifest constants for common operations. Refer to
\CLIP53\INCLUDE for more information.
. Std.ch--the standard header file: Std.ch is the standard
header file provided with Clipper. Its default location is
\CLIP53\INCLUDE. Std.ch contains the definitions of all Clipper
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.
. This example uses #include to insert Inkey.ch, a file of
common keyboard definitions, into a key exception handler called by
an interface function:
LOCAL nKey, nResult
nKey = INKEY(0)
CASE nKey = K_F10
nResult := DoMenu("Browse")
CASE nKey = K_ESC
nResult := DoQuit()
CASE nKey = K_CTRL_RIGHT
nResult := DoNextRec()
See Also: #command #define