/COPY or /INCLUDE

The /COPY and /INCLUDE directives have the same purpose and the same syntax, but are handled differently by the SQL precompiler. If your program does not have embedded SQL, you can freely choose which directive to use. If your program has embedded SQL, see Using /COPY, /INCLUDE in Source Files with Embedded SQL for information about which directive to use.

The /COPY and /INCLUDE compiler directives cause records from other files to be inserted, at the point where the directive occurs, with the file being compiled. The inserted files may contain any valid specification including /COPY and /INCLUDE up to the maximum nesting depth specified by the COPYNEST keyword (32 when not specified).

The following is a restriction on the implementation of the /COPY and /INCLUDE compiler directives when using the Program Verifier:
  • /COPY or /INCLUDE of the main source member is not allowed. This will result in an error message, indicating that it was unable to open /COPY or /INCLUDE file.
/COPY and /INCLUDE files can be either physical files or IFS files. To specify a physical file, code your /COPY and /INCLUDE statement in the following way :
  • /COPY or /INCLUDE followed by exactly one space followed by the file name or path
  • when specifying a physical file, the library, file, and member name, can be in one of these formats:
    libraryname/filename,membername
    filename,membername
    membername
    
    • A member name must be specified.
    • If a file name is not specified, QRPGLESRC is assumed.
    • If a library is not specified, the library list is searched for the file. All occurrences of the specified source file in the library list are searched for the member until it is located or the search is complete.
    • If a library is specified, a file name must also be specified.
  • When specifying an IFS (Integrated File System) file, the path can be either absolute (beginning with /) or relative.
    • The path can be enclosed in single or double quotes. If the path contains blanks, it must be enclosed in quotes.
    • If the path does not end with a suffix (for example ".txt"), the compiler will search for the file as named, and also for files with suffixes of ".rpgle" or ".rpgleinc".
    • See the Rational® Development Studio for i: ILE RPG Programmer's Guide for information on using IFS /COPY files.
  • Optionally, at least one space and a comment.
Tip:

To facilitate application maintenance, you may want to place the prototypes of exported procedures in a separate source member. If you do, be sure to place a ?COPY or ?INCLUDE directive for that member in both the module containing the exported procedure and any modules that contain calls to the exported procedure.

Figure 1 shows some examples of the /COPY and /INCLUDE directive statements.

Figure 1. Examples of the /COPY and /INCLUDE Compiler Directive Statements
C/COPY MBR1  1 

I/INCLUDE SRCFIL,MBR2  2 

O/COPY SRCLIB/SRCFIL,MBR3  3 

O/INCLUDE "SRCLIB!"/"SRC>3","MBR¬3"  4 

O/COPY /dir1/dir2/file.rpg  5 

O/COPY /dir1/dir2/file  6 

O/COPY dir1/dir2/file.rpg  7 

O/COPY "ifs file containing blanks"   8 

O/COPY 'ifs file containing blanks'   8 



 1 
Copies from member MBR1 in source file QRPGLESRC. The current library list is used to search for file QRPGLESRC. If the file is not found in the library list, the search will proceed to the IFS, looking for file MBR1, MBR1.rpgle or MBR1.rpgleinc in the include search path. See the Rational Development Studio for i: ILE RPG Programmer's Guide for information on using IFS source files.
 2 
Copies from member MBR2 in file SRCFIL. The current library list is used to search for file SRCFIL. Note that the comma is used to separate the file name from the member name. If the file is not found in the library list, the search will proceed to the IFS, looking for file SRCFIL, MBR1 in the include search path, possibly with the .rpgle or .rpgleinc suffixes.
 3 
Copies from member MBR3 in file SRCFIL in library SRCLIB or from the IFS file SRCFIL, MBR3 in directory SRCLIB.
 4 
Copies from member "MBR¬3" in file "SRC>3" in library "SRCLIB!"
 5 
Copies from the IFS file file.rpg in directory /dir1/dir2.
 6 
Copies from file, or file.rpgleinc or file.rpgle in directory /dir1/dir2
 7 
Copies from the IFS file file.rpg in directory dir1/dir2, searching for directory dir1/dir2 using the IFS search path.
 8 
Copies from a file whose name contains blanks.