The #include directive inserts external text into the source stream delivered to the compiler. This directive is often used to include global definitions for use with DEC C functions and macros in the program text.
The #include directive is supported on all DEC C implementations, but the syntax and semantics vary. For example, the directory search algorithm for locating included files on OpenVMS systems differs from that on Digital UNIX systems, primarily because of differences in the native file systems and conventions on the two platforms. Nevertheless, by choosing the lowest common denominator of plain text files in directories to contain header files, you can define command-line options for both platforms to cause searching to be done in the same way. DEC C for OpenVMS Systems also provides a form of the #include directive specifically for including text modules from OpenVMS text library files. The following sections describe the #include directive as implemented on OpenVMS systems.
The #include directives may be nested to a depth determined by the FILLM process quota and by virtual memory restrictions. The DEC C compiler imposes no inherent limitation on the nesting level of inclusion.
OpenVMS and most UNIX style file specifications can be included in DEC C source programs.
The following sections describe the different forms of the #include directive.
The first form of the #include preprocessor directive uses angle brackets (<>) to delimit the file specification:
#include <file-spec>
The file-spec is a valid file specification or a logical name. A file specification may be up to 255 characters long.
If the file-spec contains "/" or "!" characters, it is assumed to be a UNIX style name, and the compiler attempts to combine it with other UNIX style names from the /INCLUDE_DIRECTORY command-line qualifier and translate the result to an OpenVMS file specification using RTL functions. Otherwise, the file-spec is treated as an OpenVMS file specification with defaults supplied from command-line qualifiers and logical names in a prescribed search order.
When specifying the names of files to be included in your source program, avoid directory specifications of the following form:
DBA0:[.dir-name . . . ]
Depending on device logical names is not good practice. Instead, try to use only simple file names complete with the .h file type, and use the /INCLUDE_DIRECTORY qualifier to specify the directories to search.
For the angle-bracket form of inclusion, the compiler searches directories in the following order for the file to be included:
Normally, the compiler installation does not put any files in these directories, but the compiler will search them if they exist.
You can define DECC$SYSTEM_INCLUDE to be a valid directory specification or a search list of valid directory specifications. Before each compilation of your program, you can redefine DECC$SYSTEM_INCLUDE to be any valid directory or list of directories you choose.
Avoid defining DECC$SYSTEM_INCLUDE to be a rooted directory or subdirectory of the following form:
DBA0:[dir-name.]
When defining DECC$SYSTEM_INCLUDE, use complete directory specifications.
If DECC$SYSTEM_INCLUDE translates to a directory or a search list of directories, and if the compiler cannot locate the specified file, the compiler generates an error message. If DECC$SYSTEM_ INCLUDE is undefined, the compiler then searches the DECC$LIBRARY_ INCLUDE or SYS$LIBRARY directory for the specified file; if the file cannot be found, the compiler generates an error message. For more information about search lists, see the DCL command DEFINE in the OpenVMS DCL Dictionary.
When porting programs to the OpenVMS environment, your programs may contain #include directives of the following form:
#include <sys/file.h>
The DEC C compiler translates this line, common in programs that run on UNIX systems, to the following UNIX style file specification:
/sys/file.h
The compiler then translates the UNIX style file specification to the OpenVMS file specification as follows:
SYS:FILE.H
If you port programs containing such directives, define the SYS logical to be the proper name of the OpenVMS directory containing the files to be included.
Another way to use UNIX style directories is to specify them on the /INCLUDE_DIRECTORY command-line qualifier. They must contain a "/" character and must, therefore, be in quotation marks.
The second form of the #include preprocessor directive uses quotation marks to delimit the file specification:
#include "file-spec"
The file-spec is a valid OpenVMS or UNIX style file specification.
For this form of file inclusion, the compiler searches directories in the following order for the file to be included:
Note that when /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is specified, the directory containing the top-level source file is not necessarily the current RMS default device and directory.
For example, given the current directory, DBA0:[CURRENT], and the following CC command line, the compiler searches DBA0:[OTHERDIR] for any included files delimited by quotation marks, even though the current RMS default is the directory, DBA0:[CURRENT]:
$ CC DBA0:[OTHERDIR]EXAMPLE.C<Return>
If the compiler cannot locate the specified file, it searches any directories specified by the /INCLUDE_DIRECTORY qualifier.
If the compiler still cannot locate the specified file, it translates the logical name DECC$USER_INCLUDE. If DECC$USER_INCLUDE translates to a valid directory specification or a search list of directories, the compiler searches that directory or directories for the specified file. Before each compilation of your program, you can redefine DECC$USER_INCLUDE to be any valid directory or list of directories you choose.
As with DECC$SYSTEM_INCLUDE, do not define DECC$USER_INCLUDE to be a rooted directory or subdirectory. Use complete directory specifications when defining DECC$USER_INCLUDE.
If you defined DECC$USER_INCLUDE, and the compiler cannot locate the specified file in that directory or search list of directories, the file-spec is treated as if it were enclosed in angle brackets instead of quotation marks.
The third form of the #include preprocessor directive is used for including module names:
#include module-name
The module-name is the name of a module in a text library.
This method of inclusion is not portable unless module-name is a macro that expands to either the angle-bracket or quoted form. This module-name syntax is provided for compatibility with VAX C and other OpenVMS compilers only, and should generally be avoided.
DEC C text libraries on OpenVMS systems are specified and searched in the following manner:
$ CC sourcea+mylib/LIBRARY, sourceb+mylib/LIBRARY
$ CC sourcea+mylib/LIBRARY+yourlib/LIBRARY
In this example, the compiler searches for modules referenced in #include directives first in MYLIB.TLB and then in YOURLIB.TLB.
For OpenVMS Alpha systems and for OpenVMS VAX systems Version 7.1 and higher, the compiler then searches the following location, which contains the STARLET header files:
DEC C allows macro substitution within the #include preprocessor directive.
For example, if you want to include a file name, you can use the following two directives:
#define macro1 "file.ext" #include macro1
If you use defined macros in #include directives, the macros must evaluate to one of the three following acceptable #include file specifications or the use generates an error message:
<file-spec> "file-spec" module-name