Statements

LIBNAME Statement

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

Valid:	Anywhere
Category:	Data Access
See:	LIBNAME Statement under Windows UNIX OpenVMS z/OS

Syntax
Arguments
Options
Engine Host Options
Details
	Associating a Libref with a SAS Library
	Disassociating a Libref from a SAS Library
	Writing SAS Library Attributes to the SAS Log
	Concatenating SAS Libraries
	Concatenating SAS Catalogs
	Rules for Library Concatenation
Comparisons
Examples
	Example 1: Assigning and Using a Libref
	Example 2: Logically Concatenating SAS Libraries
	Example 3: Concatenating SAS Catalogs
	Example 4: Permanently Storing Data Sets with One-Level Names
See Also

Syntax

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

LIBNAME libref CLEAR | _ALL_ CLEAR;

LIBNAME libref LIST | _ALL_ LIST;

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 library or when you are listing attributes, specify a libref that was previously assigned.

Range:	1 to 8 characters
Tip:	The association between a libref and a SAS library lasts only for the duration of the SAS session or until you change it or discontinue it with another LIBNAME statement.

'SAS-library'

must be the physical name for the SAS 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. [cautionend]

library-specification

is two or more SAS 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-library': is the physical name of a SAS 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:	Logically Concatenating SAS Libraries
See Also:	Rules for Library Concatenation

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 libraries to the SAS log.

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

Options

ACCESS=READONLY|TEMP

READONLY

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

TEMP

specifies that the SAS 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. [cautionend]

COMPRESS=NO | YES | CHAR | BINARY

controls the compression of observations in output SAS data sets for a SAS 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.

Interaction:

For the COPY procedure, the default value CLONE uses the compression attribute from the input data set for the output data set instead of the value specified in the COMPRESS= option. For more information about CLONE and NOCLONE, see the COPY statement. This interaction does not apply when using SAS/SHARE or SAS/CONNECT.

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 the SAS National Language Support (NLS): Reference Guide

CVPENGINE|CVPENG=engine

specifies the engine to use in order to process a SAS data file that requires transcoding.

See:	CVPBYTES=, CVPENGINE=, and CVPMULTIPLIER= Options in the SAS National Language Support (NLS): Reference Guide

CVPMULTIPLIER|CVPMULT=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 the SAS National Language Support (NLS): Reference Guide

INENCODING=ANY | ASCIIANY | EBCDICANY | encoding-value

overrides the encoding when you are reading (input processing) SAS data sets in the SAS library.

See:	INENCODING= and OUTENCODING= Options in the SAS National Language Support (NLS): Reference Guide

OUTENCODING=

OUTENCODING=ANY | ASCIIANY | EBCDICANY | encoding-value

overrides the encoding when you are creating (output processing) SAS data sets in the SAS library.

See:	The INENCODING= and OUTENCODING= Options in the SAS National Language Support (NLS): Reference Guide

OUTREP=format

specifies the data representation for the SAS library, which is the form in which data is stored in a particular operating environment. Different operating environments use different standards or conventions for storing floating-point numbers (for example, IEEE or IBM Mainframe); for character encoding (ASCII or EBCDIC); for the ordering of bytes in memory (big Endian or little Endian); for word alignment (4-byte boundaries or 8-byte boundaries); for integer data-type length (16-bit, 32-bit, or 64-bit); and for doubles (byte-swapped or not).

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.

By default, SAS creates a new SAS data set by using the native data representation of the CPU that is running SAS. Specifying the OUTREP= option enables you to create files within the native environment that use a foreign data representation. For example, in a UNIX environment, you can create a SAS data set that uses a Windows data representation. Existing data sets that are written to the library are given the new data representation.

Interaction:	For the COPY procedure, the default value CLONE uses the data representation from the input data set instead of the value specified in the OUTREP= option. For more information about CLONE and NOCLONE, see the COPY statement. This interaction does not apply when using SAS/SHARE or SAS/CONNECT.
Interaction:	The COPY procedure (with NOCLONE) and the MIGRATE procedure can use the LIBNAME option OUTREP= for DATA, VIEW, ACCESS, MDDB and DMDB member types. Otherwise, only DATA member types are affected by the OUTREP= LIBNAME option.
Interaction:	Transcoding could result in character data loss when encodings are incompatible. For information about encoding and transcoding, see SAS National Language Support (NLS): Reference Guide.

Values for OUTREP= are listed in the following table:

Data Representation Values for OUTREP= Option
OUTREP= Value	Alias*	Environment
ALPHA_TRU64	ALPHA_OSF	Compaq Tru64 UNIX
ALPHA_VMS_32	ALPHA_VMS	OpenVMS on Alpha
ALPHA_VMS_64		OpenVMS on Alpha
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
LINUX_IA64		Linux for Itanium-based system on 64-bit platform
LINUX_X86_64		LINUX on x64 64-bit platform
MIPS_ABI		ABI UNIX on 32-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	Solaris on SPARC 32-bit platform
SOLARIS_64		Solaris on SPARC 64-bit platform
SOLARIS_X86_64		Solaris on x64 64-bit platform
VAX_VMS		OpenVMS VAX
VMS_IA64		OpenVMS for HP Integrity servers 64-bit platform
WINDOWS_32	WINDOWS	Microsoft Windows on 32-bit platform
WINDOWS_64		Microsoft Windows 64-bit Edition (for both Itanium-based systems and x64)
* It is recommended that you use the current values. The aliases are available for compatibility only.

REPEMPTY=YES|NO

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-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

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. [cautionend]

Restriction:

When concatenating libraries, you cannot specify options that are specific to an engine or an operating environment.

Details

Associating a Libref with a SAS Library

The association between a libref and a SAS 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 library:

Syntax

LIBNAME libref 'SAS-library';

See Assigning and Using a Libref.

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:

Syntax

LIBNAME libref engine 'SAS-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. [cautionend]

Disassociating a Libref from a SAS Library

To disassociate a libref from a SAS library, use a LIBNAME statement by specifying the libref and the CLEAR option. You can clear a single, specified libref or all current librefs.

Syntax

LIBNAME libref CLEAR | _ALL_ CLEAR;

Writing SAS Library Attributes to the SAS Log

Use a LIBNAME statement to write the attributes of one or more SAS libraries to the SAS log. Specify libref to list the attributes of one SAS library; use _ALL_ to list the attributes of all SAS libraries that have been assigned librefs in your current SAS session.

Syntax

LIBNAME libref LIST | _ALL_ LIST;

Concatenating SAS Libraries

When you logically concatenate two or more SAS libraries, you can reference them all with one libref. You can specify a library with its physical filename or its previously assigned libref.

Syntax

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 Logically Concatenating SAS Libraries.

Concatenating SAS Catalogs

When you logically concatenate two or more SAS libraries, you also concatenate the SAS catalogs that have the same name. For example, if three SAS libraries each contain a catalog named CATALOG1, then when you concatenate them, you create a catalog concatenation for the catalogs that have the same name. See Concatenating SAS Catalogs.

Syntax

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 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 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 concatenate SAS catalogs. Use the LIBNAME statement to 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 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-library';

   data sales.quarter1;
      infile 'your-input-file';  
      input salesrep $20. +6 jansales febsales 
            marsales;
   run;

   proc print data=sales.quarter1;
   run;

Example 2: Logically Concatenating SAS Libraries

This example concatenates three SAS libraries by specifying the physical filename of each:
```
   libname allmine ('file-1' 'file-2'
                   'file-3');
 
```
This example assigns librefs to two SAS 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-SAS-library';
   libname v9 'v9-SAS-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: Concatenating SAS Catalogs

This example concatenates three SAS 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.

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-library';

   data quarter1;
      infile 'your-input-file';  
      input salesrep $20. +6 jansales febsales 
            marsales;
   run;

   proc print data=quarter1;
   run;