%INCLUDE

The %INCLUDE control directive inserts, at compilation time, REXX code contained in z/OS® data sets or in CMS files into the REXX source program.

The %INCLUDE control directive is contained in a comment; it is recognized as a control directive only by the Compiler (it is treated as a normal comment by the interpreter): 
/*%INCLUDE file1 */
For a %INCLUDE directive to be recognized as such, the following must be true:
  • The directive immediately follows a /* comment delimiter.
  • The directive is not part of another %INCLUDE directive or of a %COPYRIGHT directive.
  • The name of the file to be included starts with the first nonblank character following /*%INCLUDE and must not contain any blank characters.
  • The z/OS data-set identifiers member and ddname and the CMS file identifiers filename and ddname are restricted to 8 characters in length.
Note:
  1. The word %INCLUDE can be in mixed case.
  2. You can only specify nested comments following the file name.
  3. Files that are included by means of %INCLUDE directives can contain %INCLUDE directives.
This is an example of how %INCLUDE directives can be specified: 
/*%INCLUDE file1 */
Say 'Hello 1'
/*%INCLUDE file2 */ Say 'Hello 2'
The contents of file1 will be inserted before Say 'Hello 1'. The last line in the example is split into two parts, forming two lines.
  1. /*%INCLUDE file2 */
  2.                     Say 'Hello 2'
The contents of file2 will be inserted between the first part and the second part, immediately following the */ delimiter. In the compiler listing and IEXEC output, the first line is truncated. The second part of the line is not reformatted. However, the space previously occupied by the %INCLUDE directive and any statements preceding it, is replaced by blanks. If the IEXEC option has been specified, the IEXEC output will have, in this case, variable length format (see IEXEC).
Note:
  1. At the end of the first part of a split line, a line end is implied.
  2. The built-in function SOURCELINE() returns the line number of the final line in the expanded program, or 0 if the program was compiled with the NOSLINE option.
The naming convention for included files is as follows:
  • Under z/OS:
    • /*%INCLUDE member */

      Search for member:

      1. In the concatenation with ddname SYSLIB, if it is allocated
      2. In the same partitioned data set as the source, if the source is in a partitioned data set
    • /*%INCLUDE ddname(member) */

      Search for member in the concatenation with ddname.

  • Under z/VM®:
    • /*%INCLUDE filename */

      Search for a file with file name filename and file type COPY on all accessed disks. If it does not exist, search for a file with file name filename and file type REXXINCL on all accessed disks. If it also does not exist, search for a file with file name filename and file type EXEC on all accessed disks.

      If more than one file is found for a specific file type, the one on the minidisk which comes earlier in the search order is included.

    • /*%INCLUDE ddname(filename) */
      1. FILEDEF ddname DISK fn ft [fm]

        can be used to specify a collection of files.

        Note: ft must be COPY, REXXINCL, or EXEC, otherwise the file will not be found.

        Search for a file with file name fn and file type COPY within the specified collection. If it does not exist, search for a file with file name fn and file type REXXINCL within the specified collection. If it also does not exist, search for a file with file name fn and file type EXEC within the specified collection.

        If more than one file is found for a specific file type, the one on the minidisk which comes earlier in the search order is included.

      2. CREATE NAMEDEF fm ddname ( FILEMODE
        or 
        CREATE NAMEDEF dirid ddname
        followed by: 
        ACCESS dirid fm
        can be used to identify a specific minidisk. Search for a file with file name filename, file type COPY, and file mode fm. If it does not exist, search for a file with file name filename, file type REXXINCL, and file mode fm. If it also does not exist, search for a file with file name filename, file type EXEC, and file mode fm.

        If a file is found for a specific file type, it is included.

      3. Members of MACLIBs can be included. If ddname is SYSLIB, all MACLIBs established with the command GLOBAL MACLIB are searched until a member with name filename is found and included.

        If ddname is not SYSLIB, search within the MACLIB with name ddname for a member with name filename and include it.

The names of the data sets or files that have been included are contained in the compiler listing.