Using Data Libraries :: SAS® 9.4 Companion for Windows, Fifth Edition

Data Libraries

The following sections provide information about data libraries, Librefs, Multi-Folder libraries, SAS user libraries, and Work data Libraries.

Specifying a Libref

The libref is a label or alias that is assigned to a folder so that the storage location (the full path, including drive and folder) is in a form that is recognized by SAS. It is a logical concept describing a physical location, rather than something physically stored with the file.

If a libref is created from within a SAS program, it exists only during the session in which it is created. If a libref is created interactively, by using the New Library dialog box, you can select Enable at Start up to make it a permanent libref.

A libref follows the same rules of syntax as any SAS name. See the SAS language rules section in SAS Language Reference: Concepts for more information about SAS naming conventions.

There are several ways to specify a libref:

Use the New Library dialog box that is described in SAS Help and Documentation.
Use the LIBNAME statement or function as described in Assigning SAS Libraries Using the LIBNAME Statement or Function .
Define a variable as described in Assigning SAS Libraries Using Environment Variables .

Note: You can eliminate the LIBNAME statement by directly specifying the drive name and the DATA set name within quotation marks. An example follows:

data "d:\mydata";

Assigning SAS Libraries Using the Graphical User Interface

To assign librefs and specify engines using the graphical user interface (GUI), use either the New Library toolbar button

, the LIBASSIGN command, or Explorer to open the New Library dialog box.

From the toolbar, click the New Library icon.
In the command bar, type either libassign or libname.

When the LIBNAME window appears, click the New toolbar button.
Within Explorer
1. Select the Library folder.
2. Select FileNew or right-click the Library folder and select New from the menu.
Note: When a second Explorer window is open on the right side of the SAS workspace, you can open the New Library dialog box if you right-click the Libraries folder and select New.

For more information about the New Library dialog box and Explorer, see the SAS Help and Documentation.

Assigning SAS Libraries Using the LIBNAME Statement or Function

LIBNAME Statement Syntax

You can use the LIBNAME statement or function to assign librefs and engines to one or more folders, including the working folder. The examples in this section use the LIBNAME statement. For information about the LIBNAME function, see SAS Functions and CALL Routines: Reference.

The LIBNAME statement has the following basic syntax:

LIBNAME libref <engine-name> 'SAS-data-library'

An explanation of all the arguments in this statement can be found in SAS Statements: Reference.

Note: The words AUX, CON, NUL, LPT1 - LPT9, COM1 - COM9, and PRN are reserved words under Windows. Do not use these reserved words as librefs.

Assigning a Libref to a Single Folder

If SAS 9.4 data sets are stored in the C:\MYSASDIR folder, you can submit the following LIBNAME statement to assign the libref TEST to that folder:

libname test V9 'c:\mysasdir';

This statement indicates that the libref TEST accesses SAS 9.4 files stored in the folder C:\MYSASDIR. Remember that the engine specification is optional.

Assigning a Libref to the Working Folder

The current working folder is shown in the status bar of the main SAS window. If you want to assign the libref MYCURR to your current SAS working folder, use the following LIBNAME statement:

libname mycurr '.';

Assigning a Libref to Multiple Folders

If SAS files are located in multiple folders, you can treat these folders as a single SAS library by specifying a single libref and concatenating the folder locations, as in the following example:

libname income ('c:\revenue' 'd:\costs');

This statement indicates that the two folders, C:\REVENUE and D:\COSTS, are to be treated as a single SAS library. When you concatenate SAS libraries, SAS uses a protocol for accessing the libraries, depending on whether you are accessing the libraries for read, write, or update.

You can concatenate multiple libraries by specifying only their librefs, as in the following example:

libname sales (income revenue);

This statement indicates that two libraries that are identified by librefs INCOME and REVENUE are treated as a single SAS library whose libref is SALES.

For more information, see Understanding How Multi-Folder SAS Libraries Are Accessed .

Note: The concept of library concatenation also applies when specifying system options, such as the SASHELP and SASMSG options. For information about how to specify multiple folders by using system options, see Syntax for Concatenating Libraries in SAS System Options .

Assigning Engines

If you want to use another access method, or engine, instead of the V9 engine, you can specify another engine name in the LIBNAME statement. For example, if you want to access only Version 6.12 SAS data sets from your SAS 9.4 session, you can specify the V612 engine in the LIBNAME statement, as in the following example:

libname oldlib V612 'c:\sas612';

Another example is if you plan to share SAS files between SAS 9.4 under Windows and Version 6 under Windows, use the V6 engine when assigning a libref to the SAS library. Here is an example of specifying the V6 engine in a LIBNAME statement:

libname lib6 V6 'c:\sas6';

Remember that while SAS 9.4 can read Version 6 SAS data sets, Release 6 cannot read SAS 9.4 data sets. For methods of regressing a SAS 9.4 data set to a version 6 data set, see information in the Migration focus area at http:\\support.sas.com\migration\planning\files\regression.html.

For more information about using engine names in the LIBNAME statement, see Using SAS Files from Other Versions with SAS 9.4 for Windows and Reading BMDP, OSIRIS, and SPSS Files . You can also see the LIBNAME statement in SAS Statements: Reference.

Making Librefs Available When SAS Starts

Instead of assigning the same librefs each time you start SAS, you can specify a libref each time that SAS starts. In the New Library dialog box, select Enable at start-up. The libref is available as soon as SAS initializes. Libraries that are enabled at start-up are stored in the SAS Registry under the entry [CORE\OPTIONS\LIBNAMES].

Assigning Multiple Librefs and Engines to a Folder

If a folder contains SAS files that were created by several engines, only those SAS files that were created with the V6 engine that is assigned to the given libref can be accessed by using that libref. SAS files created with the V7, V8, and V9 engines can all access each other, but those engines cannot access files created with the V6 engine. You must specify the V6 engine to see those files. You can assign multiple librefs with different engines to a folder. For example, the following statements are valid:

libname one V6 'c:\mydir';
libname two V9 'c:\mydir';

Data sets that are referenced by the libref ONE are created and accessed using the compatibility engine (V8), whereas data sets that are referenced by the libref TWO are created and accessed using the default engine (V9). You can also have multiple librefs (using the same engine) for the same SAS library. For example, the following two LIBNAME statements assign the librefs MYLIB and INLIB (both using the V9 engine) to the same SAS library:

libname mylib V9 'c:\mydir\datasets';
libname inlib V9 'c:\mydir\datasets';

Because the engine names and the Windows pathnames are the same, the librefs MYLIB and INLIB are identical and can be used interchangeably.

Assigning SAS Libraries Using Environment Variables

Types of Environment Variables

You can also assign a libref using variables instead of the LIBNAME statement or function. A variable equates one string to another within the Windows . SAS recognizes two types of variables:

SAS variables
Windows variables.

When you use a libref in a SAS statement, SAS resolves libref assignments in this order:

a libref assigned by a LIBNAME statement, a LIBNAME function, or by using the New Library dialog box, with the last assignment that takes precedence
a libref assigned by a SAS variable
a libref assigned by a Windows variable.

For example, if the Windows variable TEMP is assigned to C:\Windows\TEMP and you use the following LIBNAME statement:

libname temp c:\public

the LIBNAME resolves to c:\public.

There are two ways of defining a variable to SAS:

Use the SET system option. This option defines a SAS (internal) variable.
Issue a Windows SET command. This command defines a Windows (external) variable. Alternatively, under Windows, you can define variables using the System Properties dialog box accessed from the Control Panel, or by right-clicking My Computer and selecting Properties from the menu.

CAUTION:

You cannot assign engines to variables.

If you use variables as librefs, you must accept the default engine.

The availability of variables makes it simple to assign resources to SAS before invocation.

Using a SAS Environment Variable as a Libref

You can use the SET system option to define a SAS variable. For example, if you store your permanent SAS data sets in the C:\SAS\MYSASDATA folder, you can use the following SET option in the SAS command when you start SAS or in your SAS configuration file to assign the variable TEST to this SAS library:

-set test c:\sas\mysasdata

When you assign a variable, SAS does not resolve the reference until the variable name is actually used. For example, if the TEST variable is defined in your SAS configuration file, the variable TEST is not resolved until it is referenced by SAS. Therefore, if you make a mistake in your SET option specification, such as misspelling a folder name, you do not receive an error message until you use the variable in a SAS statement.

Because Windows filenames can contain spaces or single quotation marks as part of their names, you should enclose the name of the physical path in double quotation marks when specifying the SET option. If you use the SET option in an OPTIONS statement, you must use quotation marks around the filename. For complete syntax of the SET system option, see SET System Option: Windows .

Any variable name that you use as a value for a system option in your SAS configuration file must be defined as a variable before it is used. For example, the following SET option must appear before the SASUSER option that uses the variable TEST:

-set test "d:\mysasdir"
-sasuser "!test"

In the following example, variables are used with concatenated libraries:

-set dir1 "c:\sas\base\sashelp"
-set dir2 "d:\sas\stat\sashelp"
-sashelp (!dir1 !dir2)

Note that when you reference variables in your SAS configuration file or in a LIBNAME statement in your SAS programs, you must precede the variable name with an exclamation point (!).

It is recommended that you use the SET system option in your SAS configuration file if you invoke SAS through a Windows shortcut.

Using Windows Environment Variables

You can execute a Windows SET command before invoking SAS to create a Windows variable. You must define the variable before invoking SAS; you cannot define variables for SAS use from a Command Prompt window from within a SAS session.

SAS can recognize variables only if they have been assigned in the same context that invokes the SAS session. You must define the variable in the Windows AUTOEXEC.BAT file that runs when Windows starts (thus creating a global variable), or define the variable in either a Command Prompt window from which you then start SAS or from the System Properties dialog box.

If you define a variable in a Command Prompt window, and then start SAS from the Start menu (or with another shortcut), SAS does not recognize the variable.

The variables that you define with the SET command can be used later within SAS as librefs. In the following example, the Windows SET command is used to define the variables PERM and BUDGET:

SET PERM=C:\MYSASDIR
SET BUDGET=D:\SAS\BUDGET\DATA

Listing Libref Assignments

Listing Librefs Using the Explorer Window

If you are running SAS interactively, use the Explorer window to view the active librefs. The Explorer window lists all the librefs that are active for your current SAS session, along with the engine and the physical path for each libref. Any variables that you have defined as librefs are listed, provided you have used them in your SAS session. If you have defined a variable as a libref but have not used it yet in a SAS program, the Explorer window does not list it.

Listing Librefs Using the LIBNAME Command

In any SAS session, you can use the LIBNAME command to invoke the LIBNAME window. The Explorer window lists the active libraries. Using the LIBNAME window, you can view the contents of all your libraries.

Listing Librefs Using the LIBNAME Statement

The following LIBNAME statement writes the active librefs to the SAS log:

libname _all_ list;

Clearing Librefs

Overview of Clearing Librefs

You can clear a libref by using one of the following methods:

SAS automatically clears the association between librefs and their respective libraries at the end of your job or session. If you want to associate the libref with a different SAS library during the current session, you do not have to end the session or clear the libref. SAS automatically reassigns the libref when you use it to name a new library.

SAS Explorer Window

To clear a libref by using the Explorer window:

Right-click on the node of the libref that you want to clear.
Select Delete.

For more information about using the Explorer window to manage libraries, see The Little SAS Book or the SAS Help and Documentation.

LIBNAME Window

To clear a libref by using the LIBNAME window:

Issue the LIBNAME command in the command bar. The LIBNAME window appears.
Right-click on the node of the libref that you want to clear.
Select Delete.

LIBNAME Statement

To clear a libref by using the LIBNAME statement, submit a LIBNAME statement using this syntax:

LIBNAME libref|_all_ <clear>;

If you specify a libref, only that libref is cleared. If you specify the keyword _all_, all the librefs that you have assigned during your current SAS session are cleared. (Maps, Sasuser, Sashelp, and Work remain assigned.)

Note: When you clear a libref defined by a variable, the variable remains defined, but it is no longer considered a libref, and it is not listed in the Explorer window. You can use the variable in another LIBNAME statement to create a new libref.

LIBNAME Function

To clear a libref by using the LIBNAME function, the only argument to the function is the libref:

libname(libref);

Understanding How Multi-Folder SAS Libraries Are Accessed

Protocols for Accessing Folders

When you use the concatenation feature to specify more than one physical folder for a libref, SAS uses the following protocol for determining which folder is accessed:

Input and Update access
Output access
Accessing data sets with the same name.

The protocol illustrated by the following examples applies to all SAS statements and procedures that access SAS files, such as the DATA, UPDATE, and MODIFY statements in the DATA step and the SQL and APPEND procedures.

Input and Update Access

When a SAS file is accessed for input or update, the first SAS file found by that name is the one that is accessed. For example, if you submit the following statements and the file OLD.SPECIES exists in both folders, the one in the C:\MYSASDIR folder is printed:

libname old ('c:\mysasdir','d:\saslib');
proc print data=old.species;
run;

The same would be true if you opened OLD.SPECIES for update with the FSEDIT procedure.

Output Access

If the data set is accessed for output, it is always written to the first folder, provided that the folder exists. If the folder does not exist, an error message is displayed. For example, if you submit the following statements, SAS writes the OLD.SPECIES data set to the first folder (C:\MYSASDIR), replacing any existing data set with the same name:

libname old ('c:\mysasdir','d:\saslib');
data old.species;
   x=1;
   y=2;
run;

If a copy of the OLD.SPECIES data set exists in the second folder, it is not replaced.

Accessing Data Sets with the Same Name

One possibly confusing case involving the access protocols for SAS files occurs when you use the DATA and SET statements to access data sets with the same name. For example, suppose you submit the following statements and TEST.SPECIES originally exists only in the second folder, D:\MYSASDIR:

libname test ('c:\sas','d:\mysasdir');
data test.species;
   set test.species;
   if value1='y' then
      value2=3;
run;

In this case, the DATA statement opens TEST.SPECIES for output according to the output rules. That is, SAS opens a data set in the first of the concatenated libraries (C:\SAS). The SET statement opens the existing TEST.SPECIES data set in the second (D:\MYSASDIR) folder, according to the input rules. Therefore, the original TEST.SPECIES data set is not updated; rather, two TEST.SPECIES data sets exist, one in each folder.

Using the Sasuser Data Library

SAS automatically creates a SAS library with the libref Sasuser. This library contains, among other SAS files, your user Profile catalog.

By default under Windows, the Sasuser libref points to the following folders: C:\Users\user ID\Documents\My SAS Files\9.4

You can use the SASUSER system option to make the Sasuser libref point to a different SAS library. If a Sasuser folder does not exist, SAS creates one. If you use a folder other than the default folder, you can add the SASUSER system option to the sasv9.cfg configuration file.

SAS stores other files besides the Profile catalog in the Sasuser folder. For example, sample data sets are stored in this folder.

The Sasuser data library is always associated with the V9 engine. You cannot change the engine associated with the Sasuser data library. If you try to assign another engine to this data library, you receive an error message. Therefore, even if you have set the ENGINE system option to another engine, any SAS files that are created in the Sasuser data library are SAS 9.4 files.

For more information about your Profile catalog, see Profile Catalog . For more information about the SASUSER system option, see SASUSER System Option: Windows .

Using the Work Data Library

Using Temporary Files

The Work data library is the storage place for temporary SAS files. By default under Windows, the Work data library is created as a subfolder of !TEMP\SAS Temporary Files folder. This subfolder is named _TDnnnnnnnnnn_nodename_, as discussed in Work Data Library . Temporary SAS files are available only for the duration of the SAS session in which they are created. At the end of that session, they are deleted automatically. If SAS terminates abnormally, you might need to delete the temporary files.

By default, any file that is not assigned a two-level name is automatically considered to be a temporary file. A special libref of Work is automatically assigned to any temporary SAS data sets created. For example, if you run the following SAS DATA step to create the data set Sports, a temporary data set named Work.Sports is created:

data sports;
   input @1 sport $10. @12 event $20.;
   datalines;
volleyball co-recreational
swimming   100-meter freestyle
soccer     team
;

If you display the Explorer window now, you see the Sports data set in the Work folder.

You can display all the temporary data sets that are created during this session from these locations:

the Explorer window. Double-click the Libraries folder icon and then double-click the Work folder icon.
the LIBNAME window. Type libname in the command bar and double-click the Work folder icon.

The Work data library is always associated with the V9 engine. You cannot change the engine associated with the Work data library. If you try to assign another engine to this data library, you receive an error message. Therefore, even if you have set the ENGINE system option to a different engine, any SAS files that are created in the Work data library are SAS 9.4 files.

Using an Environment Variable

You can use a variable in your Work data library specification, similar to the method illustrated earlier with the SASUSER system option. Use this technique when you do not want to use the default location for your Work data library. You can put something similar to the following in your SAS configuration file to set up a variable to use for your Work data library:

-set myvar c:\ tempdir
-work !myvar

The SET option associates the MYVAR variable with the C:\TEMPDIR folder. Then the WORK option tells SAS to use that folder for the Work data library. When you exit your SAS session, the temporary folders and any files that they contain are removed.

Using the User Libref

Although by default SAS files with one-level names are temporary and are deleted at the end of your SAS session, you can use the User libref to cause SAS files with one-level names to be stored in a permanent SAS library. For example, the following statement causes all SAS files with one-level names to be permanently stored in the C:\MYSASDIR folder:

libname user 'c:\mysasdir';

When you set the User libref to a folder as in the previous example and you want to create or access a temporary data set, you must specify a two-level name for the data set, with Work as the libref.

Alternatively, you can assign the User libref when you invoke SAS by using the USER system option or by creating a Windows variable named USER. If you have a Windows variable named USER, the USER libref is automatically assigned when you invoke SAS. For more information about the USER system option, see USER System Option: Windows and SAS System Options: Reference.

Note: You can assign other engines to the User libref if you want the data sets that are saved with one-level names to be stored in a format for use with other releases of SAS.

Using Large Data Sets with Windows and NTFS

If you run SAS under Windows using the Windows NT file system (NTFS), SAS automatically takes advantage of the 64-bit file I/O features. Two terabytes is the practical limit for physical and logical volumes using NTFS.