VMS Help CC, /INCLUDE_DIRECTORY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

     /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