Chapter Contents

Previous

Next

Using Data Libraries

The libref is a label or alias that is temporarily assigned to a folder so that the storage location (the full path, including drive and folder) is in a form that is recognized by the SAS System. A libref exists only during the session in which it is created. It is a logical concept describing a physical location, rather than something physically stored with the file. A libref follows the same rules of syntax as any SAS name. See the SAS language rules section in SAS Language Reference: Dictionary for more information on SAS naming conventions.

There are several ways to specify a libref:

• Use the New Library dialog box which is described in SAS System Help.

• Use the LIBNAME statement or function as described in Assigning SAS Libraries Using the LIBNAME Statement or Function

• Define an environment 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 library name within quotes. An example follows:

data "d:\a";

Accessing the New Library Dialog Box Using the Graphical-User Interface

You can assign librefs using the graphical-user interface (GUI) either with the New Library toolbar icon (the file cabinet), the LIBASSIGN command, or from within Explorer. All of these options open the New Library dialog box where you can specify librefs and engines for multiple folders.

To open the New Library dialog box using the toolbar, click on the New Library icon which looks like a file cabinet.

To open the New Library dialog box using a command, type libassign in the command box.

To open the New Library dialog box using Explorer:

1. Select the Library folder.

2. Select New... from the File menu or right-mouse click the Library folder and select New... from the pop-up menu to open the New... dialog box.

3. Select the Library folder and click OK.

Note:   When a second Explorer window is open on the right side of the SAS workspace, you can by-pass the New... dialog box to open the New Library dialog box if you right-mouse click on the Libraries folder and select New....  

For more information on the New Library window and Explorer, see the SAS System Help.

Assigning SAS Libraries Using the LIBNAME Statement or Function

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 on the LIBNAME function, see SAS Language Reference: Dictionary.

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 LIBNAME and SAS Language Reference: Dictionary.

You can also use the LIBNAME function within your SAS programs to assign librefs. For more information about the LIBNAME function, see SAS Language Reference: Dictionary.

CAUTION:

The words 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 you have Version 8 SAS data sets stored in the C:\MYSASDIR folder, you can submit the following LIBNAME statement to assign the libref TEST to that folder:

libname test V8 'c:\mysasdir';

Assigning a Libref to the Working Folder

If you want to assign the libref MYCURR to your current SAS System working folder, use the following LIBNAME statement:

libname mycurr '.';

Assigning a Libref to Multiple Folders

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

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

Furthermore, you may concatenate multiple libraries by specifying only their librefs, as in the following example:

libname sales (income revenue);

For more information, see Understanding How Concatenated SAS Data Libraries Are Accessed and SAS Language Reference: Dictionary.

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

Assigning Engines

If you want to use another access method, or engine, instead of the Version 8 engine, you can specify another engine name in the LIBNAME statement. For example, if you want to access Release 6.10 SAS data sets from your Version 8 SAS session, you can specify the V6 engine in the LIBNAME statement, as in the following example:

libname oldlib V6 'c:\sas610';

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

libname lib6 V6 'c:\sas6';

The V6 engine is particularly useful in your Version 8 SAS session if you are going to be accessing the same SAS files from a Release 6 SAS session. Remember that while Version 8 can read Release 6 SAS data sets, Release 6 cannot read Version 8 SAS data sets.

For more information about using engine names in the LIBNAME statement, see Using SAS Files from Other Releases with Version 8 for Windows and Reading BMDP, OSIRIS and SPSS Files. You can also refer to the LIBNAME statement in SAS Language Reference: Dictionary.

Using the LIBNAME Statement in SAS Autoexec Files

If you prefer, you can store LIBNAME statements in your SAS autoexec file so that the librefs are available as soon as the SAS System initializes. For example, your SAS autoexec file may contain the following statements:

libname test 'c:\mysasdir';
libname mylib ('c:\mydata','d:\tempdata');
libname oldlib V6 'c:\sas6';

For more information about how to create and use a SAS autoexec file, see SAS Autoexec File.

Assigning Multiple Librefs and Engines to a Folder

If a folder contains SAS files created by several different engines, only those SAS files created with the engine assigned to the given libref can be accessed using that libref. 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 V8 'c:\mydir';

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

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

Assigning SAS Libraries Using Environment Variables

You can also assign a libref to a SAS data library using environment variables instead of the LIBNAME statement or function. An environment variable equates one string to another within the Windows environment. The SAS System recognizes two kinds of environment variables: SAS environment variables and Windows environment variables. When you use a libref in a SAS statement, the SAS System first looks to see if that libref has been assigned to a SAS data library by a LIBNAME statement. If it has not, the SAS System searches first for any defined SAS environment variables and then for any Windows environment variables that match the specified libref. There are two ways of defining an environment variable to the SAS System:

• Use the SET system option. This defines a SAS (internal) environment variable.

• Issue a Windows SET command. This defines a Windows (external) environment variable. Alternatively under Windows NT, you can define environment variables using the System Properties dialog box accessed from the Control Panel, or by right-clicking on My Computer and selecting Properties from the pop-up menu.

CAUTION:

You cannot assign engines to environment variables. If you use environment variables as librefs, you must accept the default engine.  

The availability of environment variables makes it simple to assign resources to the SAS System prior to invocation.

SET System Option

You can use the SET system option to define a SAS environment 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 or in your SAS configuration file to assign the environment variable TEST to this SAS data library:

-set test c:\sas\mysasdata

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

Because Windows filenames can contain spaces or single quotes as part of their names, you should enclose the name of the physical path in double quotes 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.

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

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

In the following example, environment 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 environment variables in your SAS configuration file or in a LIBNAME statement in your SAS programs, you must precede the environment variable name with an exclamation point (!).

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

Windows SET Command

You can execute a Windows SET command prior to invoking the SAS System to create a Windows environment variable. You must define the environment variable prior to invoking the SAS System; you cannot define environment variables for SAS System use from a command prompt window from within a SAS session.

Operating Environment Information for Windows 95 and Windows NT Users:    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 runs when Windows starts (thus creating a global variable), or define the variable in a Command Prompt window from which you then start SAS. Under Windows NT, you can also define the environment variable using the System Properties dialog box accessed from the System item in the Control Panel.

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

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

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

When you reference an external environment variable (one assigned with the Windows SET command) in your SAS programs (such as in a DATA or MERGE statement or in a SAS command), a note informing you the environment variable has been used is written to the SAS log. SAS does not recognize the environment variable as a libref until after you use it at least once during your SAS session, so the library name does not appear as a node in the SAS Explorer window until then.

Listing Libref Assignments

If you have assigned several librefs during a SAS session and need to refresh your memory as to which libref points where, you can use the SAS Explorer window, the LIBNAME command, or the LIBNAME statement to list all the assigned librefs.

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

Note:   You can use the LIBNAME command to invoke an 'Active Libraries' window which is a contents-only SAS Explorer that lists the active libraries, providing you with a quick view of your current libraries.  

You can use the following LIBNAME statement to write the active librefs to the SAS log:

libname _all_ list;

Clearing Librefs

You can clear a libref by using either the SAS Explorer window or a LIBNAME statement.

To clear a libref by using the SAS Explorer window, simply right-click on the node for the libref that you want to clear and select Delete. (For more information about using the SAS Explorer window to manage libraries, see The Little SAS Book.)

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 you have assigned during your current SAS session are cleared. (SASUSER, SASHELP, and WORK remain assigned.)

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

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

Understanding How Concatenated SAS Data Libraries Are Accessed

When you use the concatenation feature to specify more than one physical folder for a libref, the SAS System uses the following protocol for determining which folder is accessed. (The protocol illustrated by these 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 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;

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, the SAS System 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, the SAS System 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

The SAS System automatically creates a SAS data 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 a folder called "My SAS Files\V8", located under the working folder of your current SAS session. If a SASUSER folder does not exist, the SAS System creates one. You can use the SASUSER system option to make the SASUSER libref point to a different SAS data library. For more information about your profile catalog, see Profile Catalog. For more information about the SASUSER system option, see SASUSER. The SAS System stores other files besides the profile catalog in the SASUSER folder. For example, the sample data sets provided with SAS/ASSIST software are stored in this folder.

CAUTION:

You cannot change the engine associated with the SASUSER data library. The SASUSER data library is always associated with the V8 engine. 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 Version 8 SAS files.  

Using the WORK Data Library

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 the SASWORK folder. This subfolder is named #TDnnnnn, 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. 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.;
   cards;
volleyball co-recreational
swimming   100-meter freestyle
soccer     team
;

If you display the SAS Explorer window now, you will see the SPORTS data set in the WORK folder.

You can display all the temporary data sets that are created during this session from the SAS Explorer window by double-clicking the Libraries folder icon and then double-clicking the Work folder icon. From the Active Libraries (LIBNAME) window, double-click the Work folder icon to see the temporary data sets.

CAUTION:

You cannot change the engine associated with the WORK data library. The WORK data library is always associated with the V8 engine. 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 Version 8 SAS files.  

Using an Environment Variable

You can use an environment 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 an environment variable to use for your WORK data library:

-set myvar c:\ tempdir
-work !myvar use

The SET option associates the MYVAR environment variable with the C:\TEMPDIR folder. Then the WORK option tells the SAS System to use that folder for the SAS WORK data library. The USE suboption in the WORK option tells the SAS System to store temporary SAS files in the folder specified by the WORK option. If you do not specify the USE suboption, by default the SAS System creates a subfolder beneath the specified folder. This subfolder is named #TDnnnnn, where nnnnn is a unique number associated with your SAS session. When you exit your SAS session, these folders and any files they contain are removed.

Note:   If you specify the USE suboption in the default configuration file, you will not be able to run multiple SAS sessions on the same machine, since each SAS session requires a unique WORK folder.

Also, do not assign an environment variable named TEMP or TMP, as these variable names are usually already used by Windows.  

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 data 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, if 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. You can also assign the USER libref when you invoke the SAS System by using the USER system option. For more information about the USER system option, refer to USER and SAS Language Reference: Dictionary.

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 the SAS System.  

Chapter Contents

Previous

Next

Top of Page

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