Search sequences for include files
The search path is a list of include paths, each of which may form the start of a fully qualified file name. The include path can be specified through the -I option. For the z/OS® XL C/C++ compiler, it can also be specified through the SEARCH and LSEARCH options.
The compiler searches all paths that are specified in all -I
options to find the header file that is referenced in the #include
directive until
it finds the header file.
If the same z/OS UNIX System Services directory
is specified in the search path multiple times, then only the first
one is used. For example, /usr/include
and /usr/include/sys/..
resolve
to the same z/OS UNIX System Services directory, therefore only
the first path will be used in the final search path.
For the z/OS XL C/C++ compiler, if the same data set name is specified multiple times, then only the first one is used. For example, the data set names //'MYHLQ.SCEEH' and //'MYHLQ.SCEEH' are the same, therefore only the first data set will be used in the final search path. The data set names //'MYHLQ.SCEEH' and //SCEEH are different, therefore both data sets will be used in the final search path. This reduction is an optimization which applies only to the include paths within the same or equivalent search option. A default search path is not merged.
The search order is effected by USERLIB concatenation normally found in JCL. It can contain multiple data sets, which are searched to find any user header files included in the source. All data sets specified on USERLIB concatenation are treated as one entry in the search sequence for the #include_next directive.
test.h
directive,
then, DSN=JONES.LIB2.H will not be searched to find test.h
but
rather the next entry in the search sequence for user include files.
The search will continue using the search order for system include
files. //USERLIB DD DSN=JONES.LIB1.H,DISP=SHR
// DD DSN=JONES.LIB2.H,DISP=SHR
This restriction can be easily avoided by using the LSEARCH or
SEARCH compiler option instead of USERLIB concatenation. In this example,
specifying the LSEARCH(LIB1.+) LSEARCH(LIB2.+) compiler options will cause the
DSN=JONES.LIB2.H data set to be searched to find the include
file test.h
.
The same restriction applies to SYSLIB concatenation as well and it can be avoided by using SEARCH option.
The status of the OE option affects the search sequence.
With the NOOE option
Search sequences for include files are used when the include file is not in absolute form. Determining whether the file name is in absolute form describes the absolute form of include files.
If the include filename is not absolute, the compiler performs the library search as follows:
- For system include files:
- The search order as specified on the SEARCH option, if any
- The libraries specified on the SYSLIB DD statement
- For user include files:
- The libraries specified on the USERLIB DD statement
- The search order for system include files
JONES
:
//COMPILE EXEC PROC=EDCC,
// CPARM='SEARCH(''''BB.D'''',BB.F),LSEARCH(CC.X)'
//SYSLIB DD DSN=JONES.ABC.A,DISP=SHR
// DD DSN=ABC.B,DISP=SHR
//USERLIB DD DSN=JONES.XYZ.A,DISP=SHR
// DD DSN=XYZ.B,DISP=SHR
//SYSIN DD DSN=JONES.ABC.C(D),DISP=SHR
.
.
.
The search sequence that results from the preceding JCL statements is:
Order of Search | For System Include Files | For User Include Files |
---|---|---|
First | BB.D | JONES.CC.X |
Second | JONES.BB.F | JONES.XYZ.A |
Third | JONES.ABC.A | XYZ.B |
Fourth | ABC.B | BB.D |
Fifth | JONES.BB.F | |
Sixth | JONES.ABC.A | |
Seventh | ABC.B |
With the OE option
Search sequences for include files are used when the include file is not in absolute form. Determining whether the file name is in absolute form describes the absolute form of an include file.
If the include filename is not absolute, the compiler performs the library search as follows:
- For system include files:
- The search order as specified on the SEARCH option, if any
- The libraries specified on the SYSLIB DD statement
- For user include files:
- If you specified OE with a file name and the including file is a z/OS UNIX file and a main source file, the directory of the file name specified with the OE option; otherwise, the directory of the including file
- The search order as specified by the LSEARCH option, if any
- The libraries specified on the USERLIB DD statement
- The search order for system include files
/r/you/cproc.c
that contains the following #include
directives:
#include "/u/usr/header1.h"
#include "//aa/bb/header2.x"
#include "common/header3.h"
#include <header4.h>
OE(/u/crossi/myincs/cproc)
SEARCH(//V.+, /new/inc1, /new/inc2)
LSEARCH(//(*.x)=(lib(AAA)), /c/c1, /c/c2)
The include files would be searched as follows:
#include Directive
Filename |
Files in Search Order |
---|---|
Example 1. This is an absolute pathname, so no search is performed. | |
#include "/u/usr/header1.h" |
|
Example 2. This is a data set (starts with //) and is treated as such. | |
"//aa/bb/header2.x" |
|
Example 3. This is a user include file with a relative path name. The search starts with the directory of the parent file or the name specified on the OE option if the parent is the main source file (in this case the parent file is the main source file so the OE suboption is chosen i.e. /u/crossi/myincs). | |
"common/header3.h" |
|
Example 4. This is a system include file with a relative path name. The search follows the order of suboptions of the SEARCH option. | |
<header4.h> |
|
Compiling z/OS XL C source code using the SEARCH option
- CEE.SCEEH.H (standard header files)
- CEE.SCEEH.SYS.H (standard system header files)
- CEE.SCEEH.ARPA.H (standard internet operations headers)
- CEE.SCEEH.NET.H (standard network interface headers)
- CEE.SCEEH.NETINET.H (standard internet protocol headers)
SEARCH('CEE.SCEEH.+')
/usr/include
.
To specify that the compiler search this directory, code the option:
SEARCH(/usr/include/)
This option is
the default for the c89 utility.IBM supplies this option as input to the Installation and Customization of the compiler. Your system programmer can modify it as required for your installation.
- CEE.SCEEH.H (standard header files)
- CEE.SCEEH.SYS.H (standard system header files)
They are supplied for compatibility with previous releases, and will be overridden if SEARCH() is used.
Compiling z/OS XL C++ source code using the SEARCH option
- CEE.SCEEH (standard C++ header files)
- CEE.SCEEH.H (standard header files)
- CEE.SCEEH.SYS.H (standard system header files)
- CEE.SCEEH.ARPA.H (standard internet operations headers)
- CEE.SCEEH.NET.H (standard network interface headers)
- CEE.SCEEH.NETINET.H (standard internet protocol headers)
- CEE.SCEEH.T (standard template definitions)
- CBC.SCLBH.H (class library header files)
SEARCH('CEE.SCEEH.+','CBC.SCLBH.+')
/usr/include
and /usr/lpp/cbclib/include
.
To specify that the compiler search these directories, code the option:
SEARCH(/usr/include/,/usr/lpp/cbclib/include/)
This
option is the default for the cxx z/OS
UNIX System
Services command.IBM supplies this option as input to the installation and customization of the compiler. Your system programmer can modify it as required for your installation.