The external text specified by a %INCLUDE statement is included into the preprocessor input at the point at which the %INCLUDE statement is executed. Such text, once included, is called included text and can consist of preprocessor statements, listing control statements, and PL/I source.
The syntax for the %INCLUDE statement is described under %INCLUDE directive.
Each dataset and member name pair identifies the external text to be incorporated into the source program.
The scan continues with the first character in the included text. The included text is scanned in the same manner as the preprocessor input. Hence, included text can contribute to the preprocessor output being formed.
%INCLUDE statements can be nested. In other words, included text can contain %INCLUDE statements.
A %GO TO statement in included text can transfer control only to a point within the same include file. The target label in the %GOTO statement must not precede the %GOTO.
Preprocessor statements, DO-groups, SELECT-groups and procedures in included text must be complete. For example, it is not allowable to have half of a %IF statement in an included text and half in another portion of the preprocessor input.
If the preprocessor input and the included text contain no preprocessor statements other than %INCLUDE, execution of the preprocessor can be omitted. (This necessitates the use of the INCLUDE compile-time option.)
For example, assume that PAYRL is a member of the data set SYSLIB and contains the following text (a structure declaration):
DECLARE 1 PAYROLL,
2 NAME,
3 LAST CHARACTER (30) VARYING,
3 FIRST CHARACTER (15) VARYING,
3 MIDDLE CHARACTER (3) VARYING,
2 CURR,
3 (REGLAR, OVERTIME) FIXED DECIMAL (8,2),
2 YTD LIKE CURR;
Then the following preprocessor statements:
%DECLARE PAYROLL CHARACTER; %PAYROLL='CUM_PAY'; %INCLUDE PAYRL; %DEACTIVATE PAYROLL; %INCLUDE PAYRL;
generate two structure declarations in the preprocessor output text. The only difference between them is their names, CUM_PAY and PAYROLL.
Execution of the first %INCLUDE statement incorporates the text in PAYRL into the preprocessor input. When the preprocessor scan encounters the identifier PAYROLL in this included text, it replaces it with the current value of the active preprocessor variable PAYROLL, namely, CUM_PAY. Further scanning of the included text results in no additional replacements. The preprocessor scan then encounters the %DEACTIVATE statement and deactivates the preprocessor variable PAYROLL. When the second %INCLUDE statement is executed, the text in PAYRL once again is incorporated into the preprocessor input. This time, however, scanning of the included text results in no replacements whatsoever.