%INCLUDE statements are used to include additional PL/I files at specified points in a compilation unit. The PL/I Language Reference describes how to use the %INCLUDE statement to incorporate source text from a library into a PL/I program.
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. Source Statement Library (SYSLIB) further describes the process of defining a source statement library to the compiler.
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.)
The name of the actual include file must be lowercase, unless you specify UPPERINC. For example, if you used the include statement %include sample, the compiler would find the file sample.inc, but would not find the file SAMPLE.inc. Even if you used the include statement %include SAMPLE, the compiler would still look for sample.inc.
The compiler looks for INCLUDE files in the following order:
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.
Figure 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. Since 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, does not contain any macro statements.
//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
//