/INCLUDE_DIRECTORY=(place[,...])
/NOINCLUDE_DIRECTORY (D)
Provides similar functionality to the -I option of the cc command
on DIGITAL UNIX systems. This qualifier allows you to specify
additional places to search for include files. A place can be one
of the following:
o OpenVMS file-spec to be used as a default file-spec to RMS file
services (example: DISK$:[directory])
o UNIX style pathname in quotation marks (example: "/sys")
o Empty string ("")
If one of the places is specified as an empty string, the compiler
is not to search any of its conventionally-named places
(DECC$USER_INCLUDE, DECC$SYSTEM_INCLUDE, DECC$LIBRARY_INCLUDE,
SYS$COMMON:[DECC$LIB.INCLUDE.*], DECC$TEXT_LIBRARY,
DECC$RTLDEF.TLB, SYS$STARLET_C.TLB). It searches only places
specified explicitly on the command line by the /INCLUDE_DIRECTORY
and /LIBRARY qualifiers (or by the location of the primary source
file, depending on the /NESTED_INCLUDE_DIRECTORY qualifier).
The basic search order depends on the form of the header-file name
(after macro expansion). Additional aspects of the search order
are controlled by other command-line qualifiers and the presence or
absence of logical name definitions.
All forms of header-file inclusion are affected:
o In quotes (example: "stdio.h")
o In angle brackets (example: <stdio.h>)
o An identifier to be treated as a text-module name (example:
stdio)
Except where otherwise specified, searching a "place" means that
the string designating the place is used as the default file-spec
in a call to an RMS system service (for example, $SEARCH/$PARSE),
with a file-spec consisting of the name in the #include directive
without enclosing delimiters. The search terminates successfully
as soon as a file can be opened for reading.
For the quoted form, the search order is:
1. One of the following:
o If /NESTED_INCLUDE_DIRECTORY=INCLUDE_FILE (the default) is
in effect, search the directory containing the file in
which the #include directive itself occurred. The meaning
of "directory containing" is: the RMS "resultant string"
obtained when the file in which the #include occurred was
opened, except that the filename and subsequent components
are replaced by the default file type for headers (".H", or
just "." if /ASSUME=NOHEADER_TYPE_DEFAULT is in effect).
The "resultant string" will not have translated any
concealed device logical.
o If /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is in effect,
search the default file type for headers using the context
of the primary source file. This means that just the file
type (".H" or ".") is used for the default file-spec but,
in addition, the chain of "related file-specs" used to
maintain the sticky defaults for processing the next
top-level source file is applied when searching for the
include file.
o If /NESTED_INCLUDE_DIRECTORY=NONE is in effect, this entire
step (Step 1) is bypassed.
2. Search the places specified in the /INCLUDE_DIRECTORY
qualifier, if any. A place that can be parsed successfuly as
an OpenVMS file-spec and that does not contain an explicit file
type or version specification is edited to append the default
header file type specification (".H" or ".").
A place containing a "/" character is considered to be a
UNIX-style name. If the name in the #include directive also
contains a "/" character that is not the first character and is
not preceded by a "!" character (that is, it is not an absolute
UNIX-style pathname), then the name in the #include directive
is appended to the named place, separated by a "/" character,
before applying the decc$to_vms pathname translation function.
3. If "DECC$USER_INCLUDE" is defined as a logical name, search
"DECC$USER_INCLUDE:.H", or just "DECC$USER_INCLUDE:." if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
4. If the file is not found, follow the steps for the
angle-bracketed form of inclusion.
For the angle-bracketed form, the search order is:
1. Search the place "/". This is a UNIX-style name that can
combine only with UNIX names specified explicitly in the
#include directive. It causes a specification like
<sys/types.h> to be considered first as /sys/types.h, which is
translated to SYS:TYPES.H.
2. Search the places specified in the /INCLUDE_DIRECTORY
qualifier, exactly as in Step 2 for the quoted form of
inclusion.
3. If "DECC$SYSTEM_INCLUDE" is defined as a logical name, search
"DECC$SYSTEM_INCLUDE:.H", or just "DECC$SYSTEM_INCLUDE:." if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
4. If "DECC$LIBRARY_INCLUDE" is defined as a logical name and
"DECC$SYSTEM_INCLUDE" is NOT defined as a logical name, search
"DECC$LIBRARY_INCLUDE:.H", or just "DECC$LIBRARY_INCLUDE:." if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
5. If neither "DECC$LIBRARY_INCLUDE" nor "DECC$SYSTEM_INCLUDE" are
defined as logical names, then search the default list of
places for plain text-file copies of compiler header files as
follows:
SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF]*.H
SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C]*.H
If the file is not found, perform the text library search
described in the next step.
6. Extract the simple filename and file type from the #include
specification and use the filename as the module name to search
a list of text libraries associated with that file type.
For any file type, the initial text libraries searched consist
of those named on the command line with /LIBRARY qualifiers.
If the /INCLUDE_DIRECTORY qualifier contained an empty string,
no further text libraries are searched. Otherwise,
DECC$TEXT_LIBRARY is searched for all file types.
If "DECC$LIBRARY_INCLUDE" is defined as a logical name, then no
further text libraries are searched. Otherwise, the subsequent
libraries searched for each file type are:
For ".H" or ".":
SYS$LIBRARY:DECC$RTLDEF.TLB
SYS$LIBRARY:SYS$STARLET_C.TLB
For any file type other then ".H" or ".":
SYS$LIBRARY:SYS$STARLET_C.TLB
7. If the previous step fails, search:
SYS$LIBRARY:.H
Under /ASSUME=NOHEADER_TYPE_DEFAULT, the default file type is
modified as usual.
For the text-module (non-portable) form of #include:
The name can only be an identifier. It, therefore, has no
associated "file type". The identifier is used as a module name to
search the following:
1. The text libraries named on the command line with /LIBRARY
qualifiers, in left-to-right order.
2. The following list of text libraries in the order shown
(unless the /INCLUDE_DIRECTORY qualifier contains an empty
string, in which case no further text libraries are
searched):
DECC$TEXT_LIBRARY
SYS$LIBRARY:DECC$RTLDEF.TLB
SYS$LIBRARY:SYS$STARLET_C.TLB