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.

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.

In the following USERLIB concatenation example, if an including file is located in data set DSN=JONES.LIB1.H and it contains a #include_next 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:
1. The search order as specified on the SEARCH option, if any
2. The libraries specified on the SYSLIB DD statement
For user include files:
1. The libraries specified on the USERLIB DD statement
2. The search order for system include files

Example: This example shows an excerpt from a JCL stream, that compiles a C program for a user whose user prefix is 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:

Table 1. Order of search for include files
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:
1. The search order as specified on the SEARCH option, if any
2. The libraries specified on the SYSLIB DD statement
For user include files:
1. 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
2. The search order as specified by the LSEARCH option, if any
3. The libraries specified on the USERLIB DD statement
4. The search order for system include files

Example: The following shows an example where you are given a file /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>

And the following options:

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:

Table 2. Examples of search order for z/OS UNIX
`#include` Directive Filename	Files in Search Order
Example 1. This is an absolute pathname, so no search is performed.
`#include "/u/usr/header1.h"`	/u/usr/header.h
Example 2. This is a data set (starts with //) and is treated as such.
"//aa/bb/header2.x"	userid.AAA(HEADER2) DD:USERLIB(HEADER2) userid.V.AA.BB.X(HEADER2) DD:SYSLIB(HEADER2)
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"	/u/crossi/myincs/common/header3.h /c/c1/common/header3.h /c/c2/common/header3.h DD:USERLIB(HEADER3) userid.V.COMMON.H(HEADER3) /new/inc1/common/header3.h /new/inc2/common/header3.h DD:SYSLIB(HEADER3)
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>	userid.V.H(HEADER4) /new/inc1/common/header4.h /new/inc2/common/header4.h DD:SYSLIB(HEADER4)

Compiling z/OS XL C source code using the SEARCH option

The following data sets contain the commonly-used system header files for C: ¹

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)

To specify that the compiler search these data sets, code the option:

     SEARCH('CEE.SCEEH.+')

These header files are also in the z/OS UNIX System Services directory /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.

The cataloged procedures, REXX EXECs, and panels that are supplied by IBM for C specify the following data sets for the SYSLIB ddname by default:

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

The following data sets contain the commonly-used system header files for z/OS XL C++: ¹

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)

To specify that the compiler search these data sets, code the option:

      SEARCH('CEE.SCEEH.+','CBC.SCLBH.+')

These header files are also in the z/OS UNIX System Services directories /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.

¹ The high-level qualifier may be different for your installation.