| SAS Companion for the Microsoft Windows Environment |
To access external files, you must tell the SAS System
how to find the files. Use the following statements to access external files:
-
FILENAME
-
associates a fileref with an external file
that is used for input or output.
-
FILE
-
opens an external file for writing data
lines. Use the PUT statement to write lines.
-
INFILE
-
opens an external file for reading data
lines. Use the INPUT statement to read lines.
-
%INCLUDE
-
opens an external file and reads SAS statements
from that file. (No other statements are necessary.)
These statements are discussed in
SAS Statements under Windows, and in the SAS statements
section in SAS Language Reference: Dictionary.
You can also specify external files in various SAS dialog
entry fields (for example, as a file destination in the Save As dialog), the
FILENAME function, and in SAS commands, such as FILE and INCLUDE.
Depending on the context, SAS can reference an external
file by using:
The following sections discuss these methods of specifying
external files.
Because there are several ways to specify external files
in the SAS System, the SAS System uses a set of rules to resolve an external
file reference and uses this order of precedence:
-
Check for a standard Windows file specification
enclosed in quotes.
-
Check for a fileref defined by a FILENAME statement
or function.
-
Check for an environment variable fileref.
-
Assume the file is in the working
directory.
In other words, the SAS System assumes an external file
reference is a standard Windows file specification. If it is not, SAS checks
to see if the file reference is a fileref (defined by either a FILENAME statement,
FILENAME function, or an environment variable). If the file reference is
none of these, SAS assumes it is a filename in the working directory. If
the external file reference is not valid for one of these choices, SAS issues
an error message indicating that it cannot access the external file.
One way to reference external files is with a fileref. A fileref is a logical name associated with an external file. You
can assign a fileref with a File Shortcut in the SAS Explorer window, the
My Favorite Folders window, the FILENAME statement, the FILENAME function,
or you can use a Windows environment variable to point to the file. This
section discusses the different ways to assign filerefs and also shows you
how to obtain a listing of the active filerefs and clear filerefs during your
SAS session.
In an interactive
SAS session, you can use the SAS Explorer window or the My Favorite Folders
window to create filerefs. The SAS Explorer File Shortcuts folder contains
a listing of active filerefs. To create a new fileref from SAS Explorer:
-
Select the File Shortcuts folder and then select
| File |
![[arrow]](../common/images/arrow.gif) |
New... |
-
In the New... dialog box, select File Shortcuts
and click [OK].
-
In the New File Shortcut window, enter the name
of the shortcut (fileref) and the path to the SAS file that the shortcut represents.
To assign a file shortcut using the My Favorite Folders
window:
-
Open the folder that contains the file.
-
Position the cursor over the file, right mouse
click and select Create File Shortcut.
-
In the Create File Shortcut dialog box, type the
name of the file shortcut and click [OK].
You can then use these file shortcuts in your SAS
programs.
Note:
File Shortcuts are active only during the current
SAS session. ![[cautend]](../common/images/cautend.gif)
The
FILENAME statement provides a means to associate a logical
name with an external file, directory, or device.
Note:
The syntax of the FILENAME function is similar to the FILENAME statement.
For information on the FILENAME function, see SAS Language Reference: Dictionary.
The simplest
syntax of the FILENAME statement is as follows:
|
FILENAME fileref
"external-file";
|
For example, if you want to read the file C:\MYDATA\SCORES.DAT,
you can issue the following statement to associate the fileref MYDATA with
the file C:\MYDATA\SCORES.DAT:
filename mydata "c:\mydata\scores.dat";
Then you can use this fileref in your SAS programs.
For example, the following statements create a SAS data set named TEST, using
the data stored in the external file referenced by the fileref MYDATA:
data test;
infile mydata;
input name $ score;
run;
- CAUTION:
- The words CON, NUL, PRN, LPT0 - LPT9, and COM1 - COM9
are reserved words under Windows.
Do not
use these words as filerefs.
You can also use the FILENAME statement
to concatenate directories
of external files and to concatenate multiple individual external files into
one logical external file. These topics are discussed in Assigning a Fileref to Concatenated Directories and
Assigning a Fileref to Concatenated Files .
The * and ? wildcards can be used in either the external
file name or file extension for matching input file names. Use * to match
one or more characters and the ? to match a single character. Wildcards are
supported for input only in the FILENAME and INFILE statements, and in member
name syntax (aggregate syntax). Wildcards are not valid in the FILE statement.
The following filename statement reads input from every file in the current
directory that begins with the string wild and
ends with .dat:
filename wild 'wild*.dat';
data;
infile wild;
input;
run;
The following example reads all files in the current working directory:
filename allfiles '*.*';
data;
infile allfiles;
input
run;
The FILENAME statement accepts various options that
enable you to associate device names, such as printers, with external files
and to control file characteristics, such as record format and length. Some
of these options are illustrated in Advanced External I/O Techniques. For the complete syntax of the FILENAME
statement, refer to FILENAME.
Just as you
can define an environment variable to serve as a
logical name for a SAS data library (see Assigning SAS Libraries Using Environment Variables), you can also use an environment variable
to refer to an external file. You can choose either to define a SAS environment
variable using the SET system option or to define a Windows environment variable
using the Windows SET command. Alternatively under Windows NT, you can define
environment variables using the System dialog box, accessed from the Control
Panel.
- CAUTION:
- The words CON, NUL, PRN, LPT0 - LPT9, and COM1 - COM9
are reserved words under Windows.
Do not
use these words as an environment variable.
The availability of environment variables makes it simple
to assign resources to the SAS System prior to invocation. However, the environment
variables you define (using the SET system option) for a particular SAS session
are not available to other applications.
For example, to define a SAS environment variable that points
to the external file C:\MYDATA\TEST.DAT, you can use the following SET option
in your SAS configuration file:
-set myvar c:\mydata\test.dat
Then, in your SAS programs, you can use the environment
variable MYVAR to refer to the external file:
data mytest;
infile myvar;
input name $ score;
run;
It is recommended that you use the SET system option
in your SAS configuration file if you invoke the SAS System through a program
group window.
An alternative to using
the SET system option to define
an environment variable is to use the Windows SET command. For example, the
Windows SET command that equates to the previous example is
SET MYVAR=C:\MYDATA\TEST.BAT
(In Windows NT, you can also select System
in the Control Panel to define your SET commands.)
You must issue all the SET commands that define your
environment variables before you invoke the SAS System.
Note:
Under Windows 95, SAS can recognize environment
variables only if they have been assigned in the same context that invokes
the SAS session. That is, you must either define the environment variable
in the Windows AUTOEXEC.BAT file that is invoked when Windows starts (thus
creating a global variable), or define the variable in an MS-DOS window from
which you then start SAS.
If you define an environment variable in an MS-DOS window,
and then start SAS from the Start menu, SAS will not recognize the environment
variable.
When you reference an external environment variable
(one assigned with the Windows SET command) in your SAS programs (such as
in a FILE statement), a note informing you the environment variable has been
used and the fileref has been assigned is written to the SAS log.
You can assign a fileref to a directory
and then access individual
files within that directory using member name syntax (also called aggregate
syntax).
For example, if all your regional sales data for January
are stored in the directory C:\SAS\MYDATA, you can issue the following FILENAME
statement to assign the fileref JAN to this directory:
filename jan "c:\sas\mydata";
Now you can use this fileref with a member name in your
SAS programs. In the following example, you reference two files stored in
the JAN directory:
data westsale;
infile jan(west);
input name $ 1-16 sales 18-25
comiss 27-34;
run;
data eastsale;
infile jan(east);
input name $ 1-16 sales 18-25
comiss 27-34;
run;
When you use member name syntax, you do not have to specify
the file extension for the file you are referencing, as long as the file extension
is the expected one. For instance, in the previous example, the INFILE statement
expects a file extension of .DAT. Default File Extensions for Referencing External Files with Member Name Syntax lists the expected file extensions for
the various SAS statements and commands:
For example, the following
program submits the file
C:\PROGRAMS\TESTPGM.SAS to the SAS System:
filename test "c:\programs";
%include test(testpgm);
The SAS System searches for a file named TESTPGM.SAS
in the directory C:\PROGRAMS.
If your file has a file extension different from the
default file extension, you can use the file extension in the filename, as
in the following example:
filename test "c:\programs";
%include test(testpgm.xyz);
If your file has no file extension, you must enclose
the filename in quotes, as in the following example:
filename test "c:\programs";
%include test("testpgm");
To further illustrate the default file extensions the
SAS System uses, here are some more examples using member name syntax. Assume
the following FILENAME statement has been submitted:
filename test "c:\mysasdir";
The following example opens the file C:\MYSASDIR\PGM1.DAT
for output:
file test(pgm1);
The following example opens the file C:\MYSASDIR\PGM1.DAT
for input:
infile test(pgm1);
The following example reads and submits the file C:\MYSASDIR\PGM1:
%include test("pgm1");
These examples use SAS statements. SAS commands, such
as the FILE and INCLUDE commands, also accept member name syntax and have
the same default file extensions as shown in Default File Extensions for Referencing External Files with Member Name Syntax.
Another feature of member name syntax is that it
enables
you to reference a subdirectory in the working directory without using a fileref.
As an example, suppose you have a subdirectory named PROGRAMS that is located
beneath the working directory. You can use the subdirectory name PROGRAMS
when referencing files within this directory. For example, the following
statement submits the program stored in working-directory\PROGRAMS\PGM1.SAS:
%include programs(pgm1);
The next example uses the FILE command to save the contents
of the active window to working-directory\PROGRAMS\TESTPGM.DAT:
file programs(testpgm)
Note:
If a directory name is the same as a previously
defined fileref, the fileref takes precedence over the directory name.
Member name syntax
is also handy when you use the FILENAME statement to concatenate directories
of external files. For example, suppose you issue the following FILENAME statement:
filename progs ("c:\sas\programs",
"d:\myprogs");
This statement tells the SAS System that the fileref
PROGS refers to all files stored in both the C:\SAS\PROGRAMS and the D:\MYPROGS
directories. When you use the fileref PROGS in your SAS program, the SAS
System looks in these directories for the member you specify. When you use
this concatenation feature, you should be aware of the protocol the SAS System
uses, which depends on whether you are accessing the files for read, write,
or update. For more information, see Understanding How Concatenated Directories Are Accessed.
The SAS
System resolves an external file reference that uses
member name syntax by using a set of rules. For example, suppose your external
file reference in a SAS statement or command is the following:
progs(member1)
The SAS System uses the following set of rules to resolve
this external file reference. This list represents the order of precedence:
-
Check for a fileref named PROGS defined by a FILENAME
statement.
-
Check for a SAS or Windows environment variable
named PROGS.
-
Check for a directory named PROGS beneath the
working directory.
The member name must be a valid physical filename.
If no extension is given (as in the previous example), the SAS System uses
the appropriate default extension, as given in Default File Extensions for Referencing External Files with Member Name Syntax. If the extension is given or the member
name is quoted, the SAS System does not assign an extension, and it looks
for the filename exactly as it is given.
You can specify concatenations of files when reading external
files from within the SAS System. Concatenated files consist of two or more
file specifications (which may contain wildcard characters) separated by blanks
or commas. Here are some examples of valid concatenation specifications:
When you use this concatenation feature, you should
be aware of the protocol the SAS System uses, which depends on whether you
are accessing the files for read, write, or update. For more information,
see Understanding How Concatenated Files Are Accessed.
Note:
Do not confuse concatenated file specifications
with concatenated directory specifications, which are also valid and are illustrated
in Assigning a Fileref to Concatenated Directories.
The SAS System supports the use of long filenames. (For more information about
valid long filenames, see your Windows operating system documentation.) You
can use long filenames whenever you specify a filename as an argument to a
dialog, command, or any aspect of the SAS language.
When specifying external filenames with the SAS language,
such as in a statement or function, you should enclose the filename in double
quotes to reduce ambiguity (since a single quote is a valid character in a
long filename). When you need to specify multiple filenames, enclose each
filename in double quotes and delimit the names with a blank space.
Here are some examples of valid uses of long filenames
within SAS:
The SAS System supports the use of the Universal Naming Convention
(UNC) paths. UNC paths let you connect your computer to network devices without
having to refer to a network drive letter. SAS supports UNC paths to the extent
that Windows and your network software support them. In general, you can refer
to a UNC path anywhere in SAS where you would normally refer to a network
drive.
UNC paths have the following syntax:
|
\\SERVER\SHARE\FOLDER\FILEPATH
|
where
-
SERVER
-
is the network file server name.
-
SHARE
-
is the shared volume on the server.
-
FOLDER
-
is one of the directories on the shared
volume.
-
FILEPATH
-
is a continuation of the file path, which
might reference one or more subdirectories.
For example, the following command includes a file from
the network file server ZAPHOD:
include "\\zaphod\universe\galaxy\stars.sas"
If you have assigned several filerefs during a SAS session and need to refresh
your memory as to which fileref points where, you can use either the SAS Explorer
window or the FILENAME statement to list all the assigned filerefs.
To use the SAS Explorer window to list the active filerefs,
double-click on File Shortcuts. The Explorer window lists all the filerefs
active for your current SAS session. Any environment variables you have defined
as filerefs are listed, provided you have used them in your SAS session.
If you have defined an environment variable as a fileref but have not used
it yet in a SAS program, the fileref is not listed in the Explorer window.
If you are invoking the SAS System in batch mode, you
can use the following FILENAME statement to write the active filerefs to the
SAS log:
filename _all_ list;
You can clear a fileref by using the following syntax of the FILENAME statement:
|
FILENAME fileref|_ALL_
<CLEAR>;
|
If you specify a fileref, only that fileref is cleared.
If you specify the keyword _ALL_, all the filerefs you have assigned during
your current SAS session are cleared.
To clear filerefs using the SAS Explorer File Shortcuts:
-
select the File Shortcuts you want
to delete.
To select all File Shortcuts, select
| Edit |
|
Select All |
-
press the Delete key or select
| Edit |
|
Delete |
-
Click [OK] in the message box to
confirm deletion of the File shortcuts.
Note:
When you clear a fileref defined by an environment
variable, the variable remains defined, but it is no longer considered a fileref.
(That is, it is no longer listed in the SAS Explorer window). You can use
the variable in another FILENAME statement to create a new fileref.
The SAS System automatically clears the association
between filerefs and their respective files at the end of your job or session.
If you want to associate the fileref with a different file during the current
session, you do not have to end the session or clear the fileref. The SAS
System automatically reassigns the fileref when you issue a FILENAME statement
for the new file.
When you associate a fileref with more than
one physical directory, which file is accessed depends upon whether it is
being accessed for input, output, or update.
If the file is opened for input or update, the first
file found that matches the member name is accessed. For example, if you
submit the following statements, and the file PHONE.DAT exists in both the
C:\SAMPLES and C:\TESTPGMS directories, the one in C:\SAMPLES is read:
filename test ("c:\samples","c:\testpgms");
data sampdat;
infile test(phone.dat);
input name $ phonenum $ city $ state $;
run;
When you open a file for output, the SAS System writes to the
file in the first directory listed in the FILENAME statement, even if a file
by the same name exists in a later directory. For example, suppose you input
the following FILENAME statement:
filename test ("c:\sas","d:\mysasdir");
Then, when you issue the following FILE command, the
file SOURCE.PGM is written to the C:\SAS directory, even if a file by the
same name exists in the D:\MYSASDIR directory:
file test(source.pgm)
When you associate a fileref with more than one physical file,
the behavior of SAS statements and commands depends on whether you are accessing
the files for input, output, or update.
Note:
You should not use concatenated files with some
procedures, such as the FSLIST procedure.
If the file is opened for input, data from all files are input.
For example, if you issue the following statements, the %INCLUDE statement
submits 4 programs for execution:
filename mydata ("qtr1.sas","qtr2.sas",
"qtr3.sas","qtr4.sas");
%include mydata;
If the file is opened for output or
update, data are written
to the first file in the concatenation. For example, if you issue the following
statements, the PUT statement writes to MYDAT1.DAT:
filename indata "dogdat.dat";
filename outdata ("mydat1.dat","mydat2.dat",
"mydat3.dat","mydat4.dat");
data _null_;
infile indata;
input name breed color;
file outdata;
put name= breed= color=;
run;
Instead of using a fileref to refer to external files, you can use a quoted
Windows filename. For example, if the file C:\MYDIR\ORANGES.SAS contains
a SAS program you want to invoke, you can issue the following statement:
%include "c:\mydir\oranges.sas";
When you use a quoted Windows filename in a SAS statement,
you can omit the drive and directory specifications if the file you want to
reference is located in the working directory. For instance, if in the previous
example the working directory is C:\MYDIR, you can submit this statement:
%include "oranges.sas";
You can use several reserved names as quoted physical filenames.
Reserved operating system physical names enable you to do a variety of things,
such as read data directly from the communications port (such as COM1).Reserved Windows Physical Names lists these
physical names and their corresponding device-type keywords:
You can specify operating system physical names with
or without a colon. For example, you can specify either COM1: or COM1. For
additional information, see your Windows documentation.
The following example demonstrates how to capture data
from an external device or application which is transmitting data via a serial
(RS-232C port).
options noxwait sxync;
data _null_;
if symget("sysscpl") = "Windows" then
rc = system("mode COM1:9600,n,8,1,xon=on");
stop;
run;
filename commdata commport "COM1:";
data fruit;
keep num type;
infile commdata unbuffered;
file commdata;
put "ready";
input totrecs records $;
if totrecs = . or records ne "RECORDS" then
do;
file log;
put "ERROR: Unable to determine
number of records to read.";
stop;
end;
do i = 1 to totrecs;
input num type $;
output;
put "NEXT";
end;
stop
run;
Note the use of the device-type keyword COMMPORT in
the FILENAME statement in this example. Because the access protocols for
devices are slightly different from the access protocols for files, you should
always use the appropriate device-type keyword in combination with the reserved
physical name in the FILENAME statement. If you do not use a device-type
keyword, the SAS System defaults to using the access protocols for files,
not for devices.
For more information about available device-type keywords
in the FILENAME statement, see SAS Statements under Windows. Reading Data from the Communications Port discusses the
access protocols for using a communications port device.
If you store
the external files you need to access in your working
directory and they have the expected file extensions (see Default File Extensions for Referencing External Files with Member Name Syntax), you can simply refer
to the filename, without quotes or file extensions, in a SAS statement. For
example, if you have a file named ORANGES.SAS stored in your working directory
and ORANGES is not defined as a fileref, you can submit the file with the
following statement:
%include oranges;
Remember, though, that using this type of file reference
requires that
For more information about how to determine
and change
the SAS System working directory, see Setting the Working Directory and
Changing the SAS Working Folder.
Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
