Chapter Contents

Previous

Next
%INCLUDE

%INCLUDE



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

Valid: anywhere
Category: Program Control
Alias: %INC


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> <host-options>>;

Arguments

source
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 terminal

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:   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 "mycode." 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");
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 complete details on specifying external files, see the SAS documentation for your operating environment.  [cautionend]

Operating Environment Information:   The character length that is allowed for filenames is operating environment specific. For information on accessing files from a storage location that contains several files, see the SAS documentation for your operating environment.  [cautionend]

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 may 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. 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 terminal. 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 terminal.

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 terminal. 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 the S= system option in S=, and the S2= system option in S2=.

host-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:


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 may 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


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


Example 2: Including Previously Submitted Lines

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

%include 1 5 9-12 13:16;

Example 3: Including Input from the Keyboard

CAUTION:
The method shown in this example is valid only when you run SAS in noninteractive mode or interactive line mode.   [cautionend]
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 terminal. 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);

See Also

Statements:

%LIST
%RUN


Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.