LIBNAME Statement

Associates or disassociates a SAS data library with a libref (a shortcut name ); clears one or all librefs; lists the characteristics of a SAS data library; concatenates SAS data libraries; implicitly concatenates SAS catalogs.

Valid: Anywhere

Category: Data Access

See: LIBNAME Statement in the documentation for your operating environment

Syntax

 [  1]

LIBNAME libref < engine > SAS-data-library < options >< engine/host-options >;

 [  2]

LIBNAME libref CLEAR _ALL_ CLEAR;

 [  3]

LIBNAME libref LIST _ALL_ LIST;

 [  4] [   5]

LIBNAME libref < engine >( library-specification-1 < . . . library-specification-n >) < options >;

Arguments

libref

is a shortcut name or a nickname for the aggregate storage location where your SAS files are stored. It is any SAS name when you are assigning a new libref. When you are disassociating a libref from a SAS data library or when you are listing attributes, specify a libref that was previously assigned.
Tip: The association between a libref and a SAS data library lasts only for the duration of the SAS session or until you change it or discontinue it with another LIBNAME statement.

SAS-data-library

must be the physical name for the SAS data library. The physical name is the name that is recognized by the operating environment. Enclose the physical name in single or double quotation marks.
Operating Environment Information: For details about specifying the physical names of files, see the SAS documentation for your operating environment.

library-specification

is two or more SAS data libraries that are specified by physical names, previously assigned librefs, or a combination of the two. Separate each specification with either a blank or a comma and enclose the entire list in parentheses.
SAS-data-library
- is the physical name of a SAS data library, enclosed in quotation marks.

libref
- is the name of a previously assigned libref.

Restriction: When concatenating libraries, you cannot specify options that are specific to an engine or an operating environment.
Featured in: Example 2 on page 1290
See Also: Rules for Library Concatenation on page 1289

engine

is an engine name.
Tip: Usually, SAS automatically determines the appropriate engine to use for accessing the files in the library. If you want to create a new library with an engine other than the default engine, then you can override the automatic selection.
See: For a list of valid engines, see the SAS documentation for your operating environment. For background information about engines, see SAS Language Reference: Concepts .

CLEAR

disassociates one or more currently assigned librefs.
Tip: Specify libref to disassociate a single libref. Specify _ALL_ to disassociate all currently assigned librefs.

_ALL_

specifies that the CLEAR or LIST argument applies to all currently assigned librefs.

LIST

writes the attributes of one or more SAS data libraries to the SAS log.
Tip: Specify libref to list the attributes of a single SAS data library. Specify _ALL_ to list the attributes of all SAS data libraries that have librefs in your current session.

Options

ACCESS=READONLYTEMP

READONLY

assigns a read-only attribute to an entire SAS data library. SAS will not allow you to open a data set in the library in order to update information or write new information.

TEMP

indicates that the SAS data library be treated as a scratch library. That is, the system will not consume CPU cycles to ensure that the files in a TEMP library do not become corrupted.

Tip: Use ACCESS=TEMP to save resources only when the data is recoverable.

Operating Environment Information: Some operating environments support LIBNAME statement options that have similar functions to the ACCESS= option. See the SAS documentation for your operating environment.

COMPRESS=NO YES CHAR BINARY

controls the compression of observations in output SAS data sets for a SAS data library.
- NO
  - specifies that the observations in a newly created SAS data set be uncompressed (fixed-length records).
- YES CHAR
  - specifies that the observations in a newly created SAS data set be compressed (variable-length records) by SAS using RLE (Run Length Encoding). RLE compresses observations by reducing repeated consecutive characters (including blanks) to two-byte or three-byte representations.
  - Tip: Use this compression algorithm for character data.
- BINARY
  - specifies that the observations in a newly created SAS data set be compressed (variable-length records) by SAS using RDC (Ross Data Compression). RDC combines run-length encoding and sliding-window compression to compress the file.
  - Tip: This method is highly effective for compressing medium to large (several hundred bytes or larger) blocks of binary data (numeric variables ). Because the compression function operates on a single record at a time, the record length needs to be several hundred bytes or larger for effective compression.

CVPBYTES= bytes

specifies the number of bytes to expand character variable lengths when processing a SAS data file that requires transcoding.
See: CVPBYTES=, CVPENGINE=, and CVPMULTIPLIER= Options in SAS National Language Support (NLS): User s Guide

CVPENGINECVPENG= engine

specifies the engine to use in order to process the SAS file.
See: CVPBYTES=, CVPENGINE=, and CVPMULTIPLIER= Options in SAS National Language Support (NLS): User s Guide

CVPMULTIPLIERCVPMULT= multiplier

specifies a multiplier value in order to expand character variable lengths when processing a SAS data file that requires transcoding.
See: CVPBYTES=, CVPENGINE=, and CVPMULTIPLIER= Options in SAS National Language Support (NLS): User s Guide

INENCODING=ANY ASCIIANY EBCDICANY encoding-value

overrides the encoding when you are reading (input processing) SAS data sets in the SAS data library.
See: INENCODING= and OUTENCODING= Options in SAS National Language Support (NLS): User s Guide

OUTENCODING=

OUTENCODING=ANY ASCIIANY EBCDICANY encoding-value overrides the encoding when you are creating (output processing) SAS data sets in the SAS data library.
See: The INENCODING= and OUTENCODING= Options in SAS National Language Support (NLS): User s Guide

OUTREP= format

specifies the default data representation for the SAS data library. New data sets that are stored in this SAS data library are written in the specified data representation. Data representation is the format in which data is represented in a computer architecture or in an operating environment. For example, on an IBM PC, character data is represented by its ASCII encoding and byte-swapped integers. Native data representation refers to an environment in which the data representation is comparable to the CPU that is accessing the file. For example, a file that is in Windows data representation is native to the Windows operating environment.
Specifying this option enables you to create files within the native environment by using a foreign environment data representation. For example, in a UNIX environment, you can create a SAS data set in Windows data representation. Existing data sets that are written to the library are given the new format.

Values for OUTREP= are listed in the following table:

Table 7.7: Data Representation Values for OUTREP= Option
OUTREP= Value	Alias ^{[ *]}	Environment
ALPHA_TRU64	ALPHA_OSF	Compaq Tru64 UNIX
ALPHA_VMS_32	ALPHA_VMS	OpenVMS Alpha on 32-bit platform
ALPHA_VMS_64		OpenVMS Alpha on 64-bit platform
HP_IA64	HP_ITANIUM	HP UX on Itanium 64-bit platform
HP_UX_32	HP_UX	HP UX on 32-bit platform
HP_UX_64		HP UX on 64-bit platform
INTEL_ABI		ABI UNIX on Intel 32-bit platform
LINUX_32	LINUX	Linux for Intel Architecture on 32-bit platform
MIPS_ABI		ABI UNIX on32-bit platform
MVS_32	MVS	z/OS on 32-bit platform
OS2		OS/2 on Intel 32-bit platform
RS_6000_AIX_32	RS_6000_AIX	AIX UNIX on 32-bit RS/6000
RS_6000_AIX_64		AIX UNIX on 64-bit RS/6000
SOLARIS_32	SOLARIS	Sun Solaris on32-bit platform
SOLARIS_64		Sun Solaris on64-bit platform
VAX_VMS		VAX VMS
WINDOWS_32	WINDOWS	Microsoft Windows on 32-bit platform
WINDOWS_64		Microsoft Windows 64-bit Edition
^{[ *]} It is recommended that you use the current values. The aliases are available for compatibility only.

REPEMPTY=YESNO

controls replacement of like-named temporary or permanent SAS data sets when the new one is empty.

YES

specifies that a new empty data set with a given name replace an existing data set with the same name. This is the default.

Interaction: When REPEMPTY=YES and REPLACE=NO, then the data set is not replaced .

specifies that a new empty data set with a given name not replace an existing data set with the same name.

Tip: Use REPEMPTY=NO to prevent the following syntax error from replacing the existing data set MYLIB.B with the new empty data set MYLIB.B that is created by mistake:

 libname  libref SAS-data-library  REPEMPTY=NO;  data mylib.a set mylib.b;

Tip: For both the convenience of replacing existing data sets with new ones that contain data and the protection of not overwriting existing data sets with new empty ones that are created by mistake, set REPLACE=YES and REPEMPTY=NO.

Comparison: For an individual data set, the REPEMPTY= data set option overrides the setting of the REPEMPTY= option in the LIBNAME statement.
See Also: REPEMPTY= Data Set Option on page 47

Engine Host Options

engine-host-options

are one or more options that are listed in the general form keyword = value .
Operating Environment Information: For a list of valid specifications, see the SAS documentation for your operating environment.
Restriction: When concatenating libraries, you cannot specify options that are specific to an engine or an operating environment.

Details

[ 1]	Associating a Libref with a SAS Data Library The association between a libref and a SAS data library lasts only for the duration of the SAS session or until you change the libref or discontinue it with another LIBNAME statement. The simplest form of the LIBNAME statement specifies only a libref and the physical name of a SAS data library: LIBNAME libref SAS-data-library ; See Example 1 on page 1290. An engine specification is usually not necessary. If the situation is ambiguous, SAS uses the setting of the ENGINE= system option to determine the default engine. If all data sets in the library are associated with a single engine, then SAS uses that engine as the default. In either situation, you can override the default by specifying another engine with the ENGINE= system option: LIBNAME libref engine SAS-data-library < options >< engine/host-options >; Operating Environment Information: Using the LIBNAME statement requires host-specific information. See the SAS documentation for your operating environment before using this statement.
[ 2]	Disassociating a Libref from a SAS Data Library To disassociate a libref from a SAS data library, use a LIBNAME statement by specifying the libref and the CLEAR option. You can clear a single, specified libref or all current librefs. LIBNAME libref CLEAR _ALL_ CLEAR;
[ 3]	Writing SAS Data Library Attributes to the SAS Log Use a LIBNAME statement to write the attributes of one or more SAS data libraries to the SAS log. Specify libref to list the attributes of one SAS data library; use _ALL_ to list the attributes of all SAS data libraries that have been assigned librefs in your current SAS session. LIBNAME libref LIST _ALL_ LIST;
[ 4]	Concatenating SAS Data Libraries When you logically concatenate two or more SAS data libraries, you can reference them all with one libref. You can specify a library with its physical filename or its previously assigned libref. LIBNAME libref < engine >( library “specification “1 < library-specification-n >) < options >; In the same LIBNAME statement you can use any combination of specifications: librefs, physical filenames, or a combination of librefs and physical filenames. See Example 2 on page 1290.
[ 5]	Implicitly Concatenating SAS Catalogs When you logically concatenate two or more SAS data libraries, you also implicitly concatenate the SAS catalogs that have the same name. For example, if three SAS data libraries each contain a catalog named CATALOG1, then when you concatenate them, you implicitly create a catalog concatenation for the catalogs that have the same name. See Example 3 on page 1290. LIBNAME libref < engine >( library “specification “1 < library-specification-n >) < options >;

Rules for Library Concatenation After you create a library concatenation, you can specify the libref in any context that accepts a simple (non- concatenated ) libref. These rules determine how SAS files (that is, members of SAS libraries) are located among the concatenated libraries:

When a SAS file is opened for input or update, the concatenated libraries are searched and the first occurrence of the specified file is used.
When a SAS file is opened for output, it is created in the first library that is listed in the concatenation.

Note: A new SAS file is created in the first library even if there is a file with the same name in another part of the concatenation.
When you delete or rename a SAS file, only the first occurrence of the file is affected.
Anytime a list of SAS files is displayed, only one occurrence of a filename is shown.

Note: Even if the name occurs multiple times in the concatenation, only the first occurrence is shown.
A SAS file that is logically connected to another file (such as an index to a data set) is listed only if the parent file resides in that same library. For example, if library ONE contains A.DATA, and library TWO contains A.DATA and A.INDEX, only A.DATA from library ONE is listed. (See rule 4.)
If any library in the concatenation is sequential, then all of the libraries are treated as sequential.
The attributes of the first library that is specified determine the attributes of the concatenation. For example, if the first SAS data library that is listed is read only, then the entire concatenated library is read only.
If you specify any options or engines, they apply only to the libraries that you specified with the complete physical name, not to any library that you specified with a libref.
If you alter a libref after it has been assigned in a concatenation, it will not affect the concatenation.

Comparisons

Use the LIBNAME statement to reference a SAS data library. Use the FILENAME statement to reference an external file. Use the LIBNAME, SAS/ACCESS statement to access DBMS tables.
Use the CATNAME statement to explicitly concatenate SAS catalogs. Use the LIBNAME statement to implicitly concatenate SAS catalogs. The CATNAME statement enables you to specify the names of the catalogs that you want to concatenate. The LIBNAME statement concatenates all like-named catalogs in the specified SAS data libraries.

Examples

Example 1: Assigning and Using a Libref

This example assigns the libref SALES to an aggregate storage location that is specified in quotation marks as a physical filename. The DATA step creates SALES.QUARTER1 and stores it in that location. The PROC PRINT step references it by its two-level name, SALES.QUARTER1.

 libname sales '  SAS-data-library  ';  data sales.quarter1;     infile '  your-input-file  ';     input salesrep . +6 jansales febsales           marsales;  run;  proc print data=sales.quarter1;  run;

Example 2: Logically Concatenating SAS Data Libraries

This example concatenates three SAS data libraries by specifying the physical filename of each:
```
 libname allmine ('  file-1  ' '  file-2  '                  '  file-3  '); 
```
This example assigns librefs to two SAS data libraries, one that contains SAS 6 files and one that contains SAS 9 files. This technique is useful for updating your files and applications from SAS 6 to SAS 9, while allowing you to have convenient access to both sets of files:
```
 libname v6 '  v6--data-library  ';  libname v9 '  v9--data-library  ';  libname allmine (v9 v6); 
```
This example shows that you can specify both librefs and physical filenames in the same concatenation specification:
```
 libname allmine (v9 v6 '  some-filename  '); 
```

Example 3: Implicitly Concatenating SAS Catalogs

This example concatenates three SAS data libraries by specifying the physical filename of each and assigns the libref ALLMINE to the concatenated libraries:

 libname allmine ('  file-1  ' '  file-2  '                  '  file-3  ');

If each library contains a SAS catalog named MYCAT, then using ALLMINE.MYCAT as a libref.catref provides access to the catalog entries that are stored in all three catalogs named MYCAT. To logically concatenate SAS catalogs with different names, see CATNAME Statement on page 1118.

Example 4: Permanently Storing Data Sets with One-Level Names

If you want the convenience of specifying only a one-level name for permanent, not temporary, SAS files, then use the USER= system option. This example stores the data set QUARTER1 permanently without using a LIBNAME statement first to assign a libref to a storage location:

 options user='  SAS-data-library  ';  data quarter1;     infile '  your-input-file  ';     input salesrep . +6 jansales febsales           marsales;  run;  proc print data=quarter1;  run;