Using the %INCLUDE statement

%INCLUDE statements are used to include additional PL/I files at specified points in a compilation unit.

For information about how to use the %INCLUDE statement to incorporate source text from a library into a PL/I program, see the PL/I Language Reference.

For a batch compilation
A library is an z/OS® partitioned data set that can be used to store other data sets called members. Source text that you might want to insert into a PL/I program using a %INCLUDE statement must exist as a member within a library. For further information about the process of defining a source statement library to the compiler, see Source Statement Library (SYSLIB).

The statement %INCLUDE DD1 (INVERT); specifies that the source statements in member INVERT of the library defined by the DD statement with the name DD1 are to be inserted consecutively into the source program. The compilation job step must include appropriate DD statements.

If you omit the ddname, the ddname SYSLIB is assumed. In such a case, you must include a DD statement with the name SYSLIB. (The IBM-supplied cataloged procedures do not include a DD statement with this name in the compilation procedure step.)

For a z/OS UNIX compilation
The name of the actual include file must be lowercase, unless you specify UPPERINC. For example, if you use the include statement %include sample, the compiler can find the file sample.inc but cannot find the file SAMPLE.inc. Even if you use the include statement %include SAMPLE, the compiler still looks for sample.inc.

The compiler looks for INCLUDE files in the following order:

  1. Current® directory
  2. Directories specified with the –I flag or with the INCDIR compiler option
  3. /usr/include directory
  4. PDS specified with the INCPDS compiler option

The first file found by the compiler is included into your source.

A %PROCESS statement in source text included by a %INCLUDE statement results in an error in the compilation.

Table 1 shows the use of a %INCLUDE statement to include the source statements for FUN in the procedure TEST. The library HPU8.NEWLIB is defined in the DD statement with the qualified name PLI.SYSLIB, which is added to the statements of the cataloged procedure for this job. Because the source statement library is defined by a DD statement with the name SYSLIB, the %INCLUDE statement need not include a ddname.

It is not necessary to invoke the preprocessor if your source program and any text to be included do not contain any macro statements.

Table 1. Including source statements from a library 
 //OPT4#9     JOB
 //STEP3      EXEC IBMZCBG,PARM.PLI='INC,S,A,X,NEST'
 //PLI.SYSLIB DD DSN=HPU8.NEWLIB,DISP=OLD
 //PLI.SYSIN  DD *
    TEST: PROC OPTIONS(MAIN) REORDER;
      DCL ZIP PIC '99999';           /* ZIP CODE                      */
      DCL EOF BIT INIT('0'B);
      ON ENDFILE(SYSIN) EOF = '1'B;
      GET EDIT(ZIP) (COL(1), P'99999');
      DO WHILE(¬EOF);
        PUT SKIP EDIT(ZIP, CITYFUN(ZIP)) (P'99999', A(16));
        GET EDIT(ZIP) (COL(1), P'99999');
      END;
      %PAGE;
      %INCLUDE FUN;
    END;                             /* TEST                          */
 //GO.SYSIN DD *
 95141
 95030
 94101
 //