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 name, 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 that describes a physical location, rather than something that is physically stored with the file. To name a libref, follow the rules for user-supplied SAS names. See the section about SAS language rules in SAS Language Reference: Dictionary for more information. For detailed information about using SAS data libraries. For detailed information about using SAS data libraries see SAS Language Reference: Concepts.

There are several ways to specify a libref:

• Use the New Library dialog box, which is described in SAS Online 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 data set name within quotes. An example follows:

data "d:\a";

Accessing the New Library Dialog Box Using the Graphical User Interface

You can assign librefs by using the graphical user interface (GUI) either with the New Library toolbar icon (the file cabinet), the LIBASSIGN command, or from within the Explorer window. 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 by using the toolbar, click on the New Library icon.

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

To open the New Library dialog box by using the Explorer window:

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 on OK.

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

For more information about using the New Library window and the Explorer, see the SAS online 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 about the LIBNAME function, see SAS Language Reference: Dictionary.

The LIBNAME statement has the following syntax:

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

For details about the LIBNAME statement see LIBNAME and SAS Language Reference: Dictionary.

CAUTION:

The words CON, NUL, KBDS, PRN, COM1 - COM3, and LPT1 - LPT3 are reserved words under OS/2. Do not use these reserved words as librefs.  

Assigning a Libref to a Single Folder

If you have Version 8 SAS data sets that are 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 that are 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');

libname sales (income revenue);

Note:   The concept of library concatenation also applies when you are specifying system options, such as the SASHELP and SASMSG options. See Syntax for Concatenating Libraries in SAS System Options for information.  

Assigning Engines

If you want to use another access method or another engine instead of the Version 8 engine, you can specify the 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';

Similarly, if you plan to share SAS files between Version 8 under OS/2 and Version 6 under OS/2, you should use the V6 engine when you are 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 access the same SAS files from a Version 6 SAS session. Remember that while Version 8 can read Version 6 SAS data sets, Version 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 OS/2 and Reading BMDP, OSIRIS, and SPSS Files. You can also see the section about 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 that were created by several different engines, only those SAS files that were created with the engine that is assigned to the given libref can be accessed by 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 that are referenced by the libref ONE are created and accessed by using the compatibility engine (V6), whereas data sets that are 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 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 by using environment variables instead of the LIBNAME statement or function. An environment variable equates one string to another within the OS/2 environment. The SAS System recognizes two kinds of environment variables: SAS environment variables and OS/2 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 OS/2 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 to define a SAS (internal) environment variable.

• Issue an OS/2 SET command to define an OS/2 (external) environment variable.

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 misspelling a folder name, you do not receive an error message until you use the environment variable in a SAS statement.

Because OS/2 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 you specify the SET system option. If you use SET in an OPTIONS statement, you must use quotation marks around the filename. For the complete syntax of the SET system option, see SET.

Any environment variable name that you use with a system option in your SAS configuration file must be defined as an environment variable before it is used. For example, in the following example the SET system 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 an OS/2 shadow.

OS/2 SET Command

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

Operating Environment Information for OS/2 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 OS/2 CONFIG.SYS file that runs when OS/2 starts (thus creating a global variable), or define the variable in an OS/2 window from which you then start SAS.

If you define an environment variable in an OS/2 window, and then start SAS from a desktop shortcut, SAS will not recognize the environment variable.  

The environment variables that you define with the SET command can be used later within the SAS System as librefs. In the following example, the OS/2 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 that is assigned with the OS/2 SET command) in your SAS programs (such as in a DATA or MERGE statement or in a SAS command), a note that informs you that 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 in the Libraries dialog box or in the LIBNAME window until then.

Listing Libref Assignments

If you need to find out which file a libref points to, 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 that are active for your current SAS session, along with the engine and the physical path for each libref. Any environment variables that you have defined as librefs are listed, provided that 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 open the LIBNAME window, which lists the active 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 the following form of the LIBNAME statement:

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. (SASUSER, SASHELP, and WORK remain assigned.)

Note:   When you clear a libref that is defined by an environment variable, the variable remains defined, but it is no longer considered a libref. (That is, it is no longer listed in the Libraries dialog box). 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.

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 to determine which folder is accessed. The protocol that these examples illustrate 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 that is 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;

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) and replaces 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

However, when you use the DATA and SET statements to access data sets with the same name, a different behavior occurs. For example, suppose that you submit the following statements, and suppose that TEST.SPECIES 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 then 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 OS/2, the SASUSER libref points to a folder called SASUSER that is 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. See SASUSER for more information about the SASUSER system option. The SAS System stores other files besides the profile catalog in the SASUSER folder. For example, the sample data sets that are provided with SAS/ASSIST software are stored in this folder.

CAUTION:

You cannot change the engine that is 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 OS/2, 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 that are 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 on the Libraries folder icon and then double-clicking on the Work folder icon. From the Active Libraries (LIBNAME) window, double-click on the Work folder icon to see the temporary data sets.

CAUTION:

You cannot change the engine that is 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 that was described earlier using 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

The SET option associates the MYVAR environment variable with the C:\TEMPDIR folder. Then the WORK system option tells the SAS System to use that folder for the SAS WORK data library.

Note:   Do not assign an environment variable named TEMP or TMP, as these variable names are usually already used by OS/2.  

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 on the USER system option, refer to USER and the section about the USER system option in 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.