Statements

%INCLUDE Statement

Brings a SAS programming statement, data lines, or both, into a current SAS program.

Valid:	anywhere
Category:	Program Control
Alias:	%INC
See:	%INCLUDE Statement under Windows UNIX OpenVMS z/OS

Syntax
Arguments
Details
	What %INCLUDE Does
	Three Sources of Data
	When Useful
	Rules for Using %INCLUDE
Comparisons
Examples
	Example 1: Including an External File
	Example 2: Including Previously Submitted Lines
	Example 3: Including Input from the Keyboard
	Example 4: Using %INCLUDE with Several Entries in a Single Catalog
See Also

Syntax

%INCLUDE source(s)
</<SOURCE2> <S2=length> <operating-environment-options>>;

Arguments

source(s)

describes the location of the information that you want to access with the %INCLUDE statement. There are three possible sources:

Source		Definition
file-specification		specifies an external file
internal-lines		specifies lines that are entered earlier in the same SAS job or session
keyboard-entry		specifies statements or data lines that you enter directly from the keyboard

file-specification

identifies an entire external file that you want to bring into your program.

Restriction:	You cannot selectively include lines from an external file.
Tip:	Including external sources is useful in all types of SAS processing: batch, windowing, interactive line, and noninteractive.

Operating Environment Information: The character length allowed for filenames is operating environment specific. For complete details on specifying the physical names of external files, see the SAS documentation for your operating environment. [cautionend]

File-specification can have these forms:

'external-file'

specifies the physical name of an external file that is enclosed in quotation marks. The physical name is the name by which the operating environment recognizes the file.

fileref

specifies a fileref that has previously been associated with an external file.

Tip:	You can use a FILENAME statement or function or an operating environment command to make the association.

fileref (filename-1 <, "filename-2.xxx", ... filename-n>)

specifies a fileref that has previously been associated with an aggregate storage location. Follow the fileref with one or more filenames that reside in that location. Enclose the filenames in one set of parentheses, and separate each filename with a comma, space.

This example instructs SAS to include the files "testcode1.sas", "testcode2.sas" and "testcode3.txt." These files are located in aggregate storage location "mylib." You do not need to specify the file extension for testcode1 and testcode2 because they are the default .SAS extension. You must enclose testcode3.txt in quotation marks with the whole filename specified because it has an extension other than .SAS:

%include mylib(testcode1, testcode2,
               "testcode3.txt");

Note: A file that is located in an aggregate storage location and has a name that is not a valid SAS name must have its name enclosed in quotation marks. [cautionend]

Tip:	You can use a FILENAME statement or function or an operating environment command to make the association.

Operating Environment Information: Different operating environments call an aggregate grouping of files by different names, such as a directory, a MACLIB, a text library, or a partitioned data set. For information about accessing files from a storage location that contains several files, see the SAS documentation for your operating environment. [cautionend]

Tip:	You can verify the existence of file-specification by using the SYSERR macro variable if the ERRORCHECK option is set to STRICT.

internal-lines

includes lines that are entered earlier in the same SAS job or session.

To include internal lines, use any of the following:

n	includes line n.
n-m or n:m	includes lines n through m.

Tip:	Including internal lines is most useful in interactive line mode processing.
Tip:	Use a %LIST statement to determine the line numbers that you want to include.
Tip:	Although you can use the %INCLUDE statement to access previously submitted lines when you run SAS in a windowing environment, it might be more practical to recall lines in the Program Editor with the RECALL command and then submit the lines with the SUBMIT command.

Note: The SPOOL system option controls internal access to previously submitted lines when you run SAS in interactive line mode, noninteractive mode, and batch mode. By default, the SPOOL system option is set to NOSPOOL. The SPOOL system option must be in effect in order to use %INCLUDE statements with internal line references. Use the OPTIONS procedure to determine the current setting of the SPOOL system option on your system. [cautionend]

keyboard-entry

is a method for preparing a program so that you can interrupt the current program's execution, enter statements or data lines from the keyboard, and then resume program processing.

Tip:	Use this method when you run SAS in noninteractive or interactive line mode. SAS pauses during processing and prompts you to enter statements from the keyboard.
Tip:	Use this argument to include source from the keyboard:

*	prompts you to enter data from the keyboard. Place an asterisk () after the %INCLUDE statement in your code: proc print; %include ; run; To resume processing the original source program, enter a %RUN statement from the keyboard.

Restriction:	The asterisk (*) cannot be used to specify keyboard entry if you use the Enhanced Editor in the Microsoft Windows operating environment.
Tip:	You can use a %INCLUDE * statement in a batch job by creating a file with the fileref SASTERM that contains the statements that you would otherwise enter from the keyboard. The %INCLUDE * statement causes SAS to read from the file that is referenced by SASTERM. Insert a %RUN statement into the file that is referenced by SASTERM where you want SAS to resume reading from the original source.

Note: The fileref SASTERM must have been previously associated with an external file in a FILENAME statement or function or an operating environment command. [cautionend]

SOURCE2

causes the SAS log to show the source statements that are being included in your SAS program.

Tip:	The SAS log also displays the fileref and the filename of the source and the level of nesting (1, 2, 3, and so on).
Tip:	The SAS system option SOURCE2 produces the same results. When you specify SOURCE2 in a %INCLUDE statement, it overrides the setting of the SOURCE2 system option for the duration of the include operation.

S2=length

specifies the length of the record to be used for input. Length can have these values:

S	sets S2 equal to the current setting of the S= SAS system option.
0	tells SAS to use the setting of the SEQ= system option to determine whether the line contains a sequence field. If the line does contain a sequence field, SAS determines line length by excluding the sequence field from the total length.
n	specifies a number greater than zero that corresponds to the length of the line to be read, when the file contains fixed-length records. When the file contains variable-length records, n specifies the column in which to begin reading data.

Tip:	Text input from the %INCLUDE statement can be either fixed or variable length. Fixed-length records are either unsequenced or sequenced at the end of each record. For fixed-length records, the value given in S2= is the ending column of the data. Variable-length records are either unsequenced or sequenced at the beginning of each record. For variable-length records, the value given in S2= is the starting column of the data.
Interaction:	The S2= system option also specifies the length of secondary source statements that are accessed by the %INCLUDE statement, and it is effective for the duration of your SAS session. The S2= option in the %INCLUDE statement affects only the current include operation. If you use the option in the %INCLUDE statement, it overrides the system option setting for the duration of the include operation.
See Also:	For a detailed discussion of fixed- and variable-length input records, see S= System Option and S2= System Option.

operating-environment-options

Operating Environment Information: Operating environments can support various options for the %INCLUDE statement. See the documentation for your operating environment for a list of these options and their functions. [cautionend]

Details

What %INCLUDE Does

When you execute a program that contains the %INCLUDE statement, SAS executes your code, including any statements or data lines that you bring into the program with %INCLUDE.

Operating Environment Information: Use of the %INCLUDE statement is dependent on your operating environment. See the documentation for your operating environment for more information about additional software features and methods of referring to and accessing your files. See your documentation before you run the examples for this statement. [cautionend]

Three Sources of Data

The %INCLUDE statement accesses SAS statements and data lines from three possible sources:

external files
lines entered earlier in the same job or session
lines entered from the keyboard.

When Useful

The %INCLUDE statement is most often used when running SAS in interactive line mode, noninteractive mode, or batch mode. Although you can use the %INCLUDE statement when you run SAS using windows, it might be more practical to use the INCLUDE and RECALL commands to access data lines and program statements, and submit these lines again.

Rules for Using %INCLUDE

You can specify any number of sources in a %INCLUDE statement, and you can mix the types of included sources. Note, however, that although it is possible to include information from multiple sources in one %INCLUDE statement, it might be easier to understand a program that uses separately coded %INCLUDE statements for each source.
The %INCLUDE statement must begin at a statement boundary. That is, it must be the first statement in a SAS job or must immediately follow a semicolon ending another statement. A %INCLUDE statement cannot immediately follow a DATALINES, DATALINES4, CARDS, or CARDS4 statement (or PARMCARDS or PARMCARDS4 statement in procedures that use those statements). However, you can include data lines with the %INCLUDE statement using one of these methods:
- Make the DATALINES, DATALINES4, or CARDS, CARDS4 statement the first line in the file that contains the data.
- Place the DATALINES, DATALINES4, or CARDS, CARDS4 statement in one file, and the data lines in another file. Use both sources in a single %INCLUDE statement.
The %INCLUDE statement can be nested within a file that has been accessed with %INCLUDE. The maximum number of nested %INCLUDE statements that you can use depends on system-specific limitations of your operating environment (such as available memory or the number of files you can have open concurrently).
Because %INCLUDE is a global statement and global statements are not executable, the %INCLUDE statement cannot be used in conditional logic.
The maximum line length is 32K bytes.

Comparisons

The %INCLUDE statement executes statements immediately. The INCLUDE command brings the included lines into the Program Editor window but does not execute them. You must issue the SUBMIT command to execute those lines.

Examples

Example 1: Including an External File

This example stores a portion of a program in a file and includes it in a program to be written later. This program is stored in a file named MYFILE:
```
data monthly;
   input x y month $;
   datalines;
1 1 January
2 2 February
3 3 March
4 4 April
;
```
This program includes an external file named MYFILE and submits the DATA step that it contains before the PROC PRINT step executes:
```
%include 'MYFILE';

proc print;
run;
```
To reference a file by using a fileref rather than the actual filename, you can use the FILENAME statement (or a command recognized by your operating environment) to assign a fileref:
```
filename in1 'MYFILE';
```
You can later access MYFILE with the fileref IN1:
```
%inc in1;
```
If you want to use many files that are stored in a directory, PDS, or MACLIB (or whatever your operating environment calls an aggregate storage location), you can assign the fileref to the larger storage unit and then specify the filename. For example, this FILENAME statement assigns the fileref STORAGE to an aggregate storage location:
```
filename storage 
   'aggregate-storage-location';
```
You can later include a file using this statement:
```
%inc storage(MYFILE);
```
You can also access several files or members from this storage location by listing them in parentheses after the fileref in a single %INCLUDE statement. Separate filenames with a comma or a blank space. The following %INCLUDE statement demonstrates this method:
```
%inc storage(file-1,file-2,file-3);
```
When the file does not have the default .SAS extension, you can access it using quotation marks around the complete filename listed inside the parentheses.

%inc storage("file-1.txt","file-2.dat",
             "file-3.cat");

Example 2: Including Previously Submitted Lines

This %INCLUDE statement causes SAS to process lines 1, 5, 9 through 12, and 13 through 16 as if you had entered them again from your keyboard:

%include 1 5 9-12 13:16;

Example 3: Including Input from the Keyboard

The method shown in this example is valid only when you run SAS in noninteractive mode or interactive line mode.

Restriction:

The asterisk (*) cannot be used to specify keyboard entry if you use the Enhanced Editor in the Microsoft Windows operating environment.

This example uses %INCLUDE to add a customized TITLE statement when PROC PRINT executes:

data report;
   infile file-specification;
   input month $ salesamt $;
run;

proc print;
   %include *;
run;

When this DATA step executes, %INCLUDE with the asterisk causes SAS to issue a prompt for statements that are entered at the keyboard. You can enter statements such as

where month= 'January';

title 'Data for month of January';

After you enter statements, you can use %RUN to resume processing by typing

%run;

The %RUN statement signals to SAS to leave keyboard-entry mode and resume reading and executing the remaining SAS statements from the original program.

Example 4: Using %INCLUDE with Several Entries in a Single Catalog

This example submits the source code from three entries in the catalog MYLIB.INCLUDE. When no entry type is specified, the default is CATAMS.

filename dir catalog 'mylib.include';
%include dir(mem1);
%include dir(mem2);
%include dir(mem3);