The Power of "The FILENAME" Statement

Home , Filename, Temporary folder, Write (system call)

The Power of “The FILENAME” Statement Megha Agarwal, Gilead Sciences, Foster City, CA, USA

ABSTRACT The FILENAME statement has been around a long time. It has been traditionally used to reference an external file on disk. However, there are many “not so well-known” functionalities, for which the FILENAME statement is a boon. This paper discusses, with the help of relevant examples, some of the those unusual features like - how a FILENAME statement can be used to reference temporary and dummy files, access clipboards, read the output of external commands, access catalogs, clear file references, send e-mails, access external URLs, and perform file transfers through FTP. The intended audience is all levels of SAS® users.

INTRODUCTION

The FILENAME statement specifies a file reference (commonly called as fileref), that serves as a link to an external file, device or an access method. It doesn’t do any type of data processing but still in the world of SAS, this is one of the most commonly and frequently used statements. The device/access methods are the main ammunitions, because of which the FILENAME statement is used across domains.

SYNTAX The syntax for the most basic usage of filename statement is as follows:

FILENAME fileref 'external-file' ;

Fileref is any valid sas name of length 8 for file reference.

External file is the physical name (recognized by the OS), of an external file.

Encoding: It indicates that the external file has a different encoding from the current session’s encoding. While reading the data from encoded file, sas transcodes the data.If the file you want to read (inp_fl in the example below) is in UTF-8 encoding and your session is in Wlatin1 encoding, you need to explicitly specify the encoding of the input file, as SAS assumes that an external file is in the same encoding as the session encoding. For example:

filename inp_fl "physical location of file" encoding="utf-8" ; data xcoding; infile inp_fl; input patient aeseverity $ ; run;

Device-type/access methods: It specifies the type of device or the access method that is used if the fileref points to an input/output device or location that is not a physical file. Note that there is a distinction to be made between a device and an access method. A device is a physical computer component whereas an access method can be defined as an interface to a storage medium. DEVICE TYPES: Some of the interesting device types are discussed in detail below: DISK By default, the files referenced in the filename statement are considered to be on the DISK. So you don’t have to explicitly mention it in the SAS code. For example:

filename inp_fl "C:\intemp\inp_fl.sas"; filename out_fl "C:\outtemp\out_fl.sas";

data _null_; infile inp_fl; file out_fl; input; put _infile_; run; Note that in above statement, DISK hasn’t been used (though the device type used is DISK).

The Power of “The FILENAME” Statement, continued

PIPE Unnamed pipes enable you to invoke a program outside of SAS and redirect the program's input, output, and error messages to SAS. This capability enables you to capture data from a program external to SAS without creating an intermediate data file. For example, if you want to get the list of all the files in a particular folder, as SAS data set (for further processing), you can use the following:

*here temp is temporary folder which contains files; filename DIRLIST pipe 'c:\temp';

The directory specified by the above location can have any type of file. If you want to output just the SAS files, then use the code below:

filename DIRLIST pipe 'c:\temp\*.sas/b'; data dirlist; length filename $200; infile dirlist length=reclen; input buffer $varying200. reclen; run;

TEMP Many times, you want to refer to temporary files which are active only for the current SAS session. You don’t have to worry about their name, location, deletion etc (as you want a temporary file). The temporary file can be accessed only through the logical name and is available only while the logical name exists. For example, if you want to create a small code inside a program and then include the same in your code, then you can use the following:

filename code temp; data _null_; file code; put ‘proc sort;’; put ‘run’; run; %include code;

Or suppose you want to generate a SAS output in both RTF and PDF format, then you can assign a temporary fileref to the output and pass this temp file to respective macros:

filename in_fl TEMP; proc printto new print = in_fl; run; proc report … … …; … … … … run;

proc printto ;run; %out2rtf(tmpfl=in_fl); *here this macros generates rtf outputs. %out2pdf(tmpfl=in_fl); *here this macros generates pdf outputs.

DUMMY While programming, you frequently create dummy data sets and dummy variables. They are mostly used for testing or troubleshooting purposes. Similarly, DUMMY device can be used to provide as input, an empty file or to discard an output file. For example, suppose you have a macro test.sas, in which a fileref is a mandatory macro parameter. In this case, you can create a dummy fileref as:

filename mand_par dummy; Now you can pass this to the test macro to avoid unnecessary error.

PRINTER/TERMINAL These device types enable you to send output directly to a printer or computer terminal. For example, if you want to see a source program stored in the catalog directly on the TERMINAL (screen), or you want to send it 2

The Power of “The FILENAME” Statement, continued

to the PRINTER, then use the following:

filename incat catalog 'sasuser.profile.sasinp.source'; filename test terminal ; *for displaying on the terminal; filename test printer ; *for printing it directly;

data _null_; FILE test; infile incat missover; input; put _infile_; run;

Some other device types (not discussed in this paper) are GTERM, PLOTTER, TAPE, UPRINTER.

ACCESS METHODS: As mentioned, access methods acts as an interface to different media. Some of them are discussed in detail below:

CLIPBOARD This access method enables us to read text data from and write text data to the clipboard on the host computer. For example an entire data set can be written to the clipboard and then can be read from there.

This example writes 2 lines to the clipboard and then writes it into the test dataset.

filename clip1 clipbrd;

data _null_; file clip1; put 'test 1'; put 'test 2'; run;

data test; infile clip1; input; put _infile_; run;

CATALOG This access method enables us to reference a SAS catalog as an external file. A catalog is a special type of file that allows SAS to store different types of information in partitions called catalog entries. Each entry type identifies the purpose of the entry to the SAS system. With this access method you can read any type of catalog entry, but you can write only to entries of type LOG, OUTPUT, SOURCE, and CATAMS. A source program can be directly read or created by referring it, using catalog access method.

*reading a source program: filename fileref1 catalog 'sasuser.profile.sasinp.source'; %include fileref1;

*Writing a source program to the catalog; filename incit catalog 'sasuser.profile.sasinp.source'; data _null_; file incit; put 'proc options; run;'; run; %include incit;

If you store an autocall macro in a SOURCE entry in a SAS catalog, you can point to that entry and invoke the macro in a SAS job using catalog access method as shown below. This example points to a SAS catalog named TEST.SAMPCAT. It then invokes a macro named SAMPLE, which is stored as a SAS catalog entry named TEST.SAMPCAT.SAMPLE.SOURCE:

filename mymac catalog 'test.sampcat'; 3

The Power of “The FILENAME” Statement, continued

*mautosource activates the autocall facility; options sasautos=mymac mautosource; %sample;

URL URL stands for Universal Resource Locator. The URL access method reads the source code of the WebPages (which are in HTML most of the times), which after being parsed (as per the requirements) can reflect useful data, which can then further be used for analysis. This method makes it easy to read data from web pages without having to understand how web browsers communicate with web servers.

filename test1 url 'www.google.com';

data _null_; infile test1 length=len; input xxx $varying200. len; put xxx; run;

*this statement accesses a document and requires a userid and password; filename test2 url 'https://www.bbb.com/test.html' user='megha' prompt;

EMAIL The email access method enables the users to send the customized emails, at desired frequency to intended people without any hassle. The emails can be sent in html or textual format, with or without attachments using a simple piece of code. A few examples of sending emails are shown below (with different syntaxes):

*defining the email attributes while defining the filename; filename emailout email TO = '[email protected]' subject = "Test email" cc = '[email protected]' from = '[email protected]' importance = 'high' attach = "c:/temp/test.xls"; data _null_; file emailout; put 'This is a test email'; run;

*defining the email attributes while referring the file; filename emailout email; data _null_; file emailout TO = '[email protected]' subject = "Test email" cc = '[email protected]' from = '[email protected]' importance = 'high' attach = "c:/temp/test.xls"; put 'This is a test email'; run;

*using email directives; filename emailout email;

data _null_; file emailout; put '!em_from! [email protected] '; put '!em_attach! c:/temp/test.xls '; put '!em_cc! [email protected]'; put '!EM_TO! [email protected]'; put '!em_subject! " Test email"'; put '!em_importance! high'; Put 'This is a test email'; run;

FTP FTP stands for File transfer protocol. The FTP access method allows you to use the FILENAME statement to alias a direct connection to an FTP channel. You instruct SAS to create an FTP connection by specifying the FTP file access method directly after the fileref and before the file specification. You also need to include a few FTP specific

The Power of “The FILENAME” Statement, continued

FILENAME options.

*getting the list of all files in the directory of remote server; filename dir ftp '' ls user='megha' host='host.name' prompt; data _null_; infile dir; input; put _INFILE_; run;

*reading the file from remote server through ftp; filename in ftp 'test.txt' lrecl=80 cd='c:\temp\' host='host.name' user='megha' pass='yourpassword' ; data gpa ; infile in ; input patid age height ; run;

DDE Dynamic Data Exchange (DDE) is an access method of dynamically exchanging information between Windows applications and SAS. DDE uses a client/server relationship to enable a client application to request information from a server application. SAS (who is a client in this case) requests data from server applications, sends data to server applications, or sends commands to server applications.

In the example shown below, DDE access method is used to write some text in excel through SAS.

options noxwait noxsync; x "c:\test\book1.xls"; filename fl1 DDE "EXCEL|sheet1!R6C1" notab; data _null_; file fl1; put "This is sample program"; run;

The example below saves book1.xls (opened via X common in above example), as try.xls at the specified location.

filename ddecmnd dde ‘EXCEL|SYSTEM’ ; data _null_; file ddecmnd; put '[save.as("C:\Documents and Settings\megha\Desktop\try.xls")]'; put '[Quit()]'; run;

Similarly, through DDE, you can create borders, custom formats, apply formulas in excel, and do a lot of other things to generate your own customized excel reports.

Some other access methods not discussed here are SFTP, SOCKET, and WebDAV.

CLEARING THE FILE REFERENCE

For clearing the filerefs, CLEAR option is used. It disassociates one or more currently assigned filerefs. Specify _ALL_ to disassociate all currently assigned filerefs. For example:

filename test clear; *to dissociate “test” fileref; filename _all_ clear; * to dissociate all the file references (filerefs);

CONCLUSION This paper discusses some of the capabilities of the FILENAME statement (with examples). The FILENAME statement in conjunction with the power of the DATA step provides a very flexible processing environment. The more you explore it, the more you unravel the power of THE FILENAME Statements.

Happy exploring!! 5

The Power of “The FILENAME” Statement, continued

REFERENCES

SAS(R) 9.2 Language Reference: Dictionary, Fourth Edition

CONTACT INFORMATION

Your comments and questions are valued and encouraged. Contact the author at: Megha Agarwal Gilead Sciences 300, Lakeside Drive Foster City, 94404 E-mail: [email protected] Web: www.gilead.com

SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration.

Other brand and product names are trademarks of their respective companies.