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 in: Anywhere
Category: Data Access
See: LIBNAME Statement under Windows, UNIX, and z/OS
Syntax
Details
Associating a Libref with a SAS Library (Form 1)
Disassociating a Libref from a SAS Library (Form 2)
Writing SAS Library Attributes to the SAS Log (Form 3)
Concatenating SAS Libraries (Form 4)
Concatenating SAS Catalogs (Form 4)
Rules for Library Concatenation
Automatically Creating the Library Directory
Metadata-Bound Libraries
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

Form 1:

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

Form 2:

LIBNAME libref CLEAR | _ALL_ CLEAR ;

Form 3:

LIBNAME libref LIST | _ALL_ LIST;

Form 4:

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 bytes
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:For details about specifying the physical names of files, see the SAS documentation for your operating environment.
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.
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 more background information, see SAS Engines in 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.

LIBNAME 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:Some operating environments support LIBNAME statement options that have similar functions to the ACCESS= option. See the SAS documentation for your operating environment.
AUTHADMIN= YES | NO
specifies whether an administrator can access a metadata-bound library for which corresponding metadata is corrupted, misconfigured, or missing.
Default:NO
Restriction:This LIBNAME option can be used only by administrators of metadata-bound libraries.
Interactions:If the administrator specifies AUTHADMIN=YES in a LIBNAME statement and knows the password (or passwords) for the target data, the administrator can access that data by explicitly supplying the password (or passwords).

An administrator can choose to specify the AUTHPW= option on the LIBNAME statement as an additional method for making the metadata-bound library password available to later requests.

Note:The use of AUTHADMIN=YES is intended for the administrator to correct misaligned location and metadata information. To ensure that the user who is issuing the LIBNAME statement has administrator rights to correct the misalignments, the user must have the same permissions that are needed to run the AUTHLIB procedure statements and must supply the metadata-bound data passwords when accessing the data sets.
Tip:The AUTHLIB REPAIR statement is preproduction. It is recommended that you use AUTHADMIN=YES when performing any AUTHLIB REPAIR action.. As a best practice, do not use AUTHADMIN=YES in any other circumstance.

Metadata-Bound Libraries

SAS Guide to Metadata-Bound Libraries

PROC AUTHLIB in Base SAS Procedures Guide

AUTHALTER=alter-password
Specifies an ALTER password to use only in data access requests where both of these conditions exist:
  • AUTHADMIN=YES is specified in the LIBNAME statement that is referenced in the request.
  • The correct password for the target metadata-bound data set or library is not otherwise available or is invalid.
Requirement:The AUTHADMIN option must be set to YES for this option to have an effect.
Interaction:You can use the AUTHALTER= option in the same way as the AUTHPW= option if all three of the passwords (ALTER, READ, and WRITE) are the same.
See:SAS Guide to Metadata-Bound Libraries
AUTHPW=password
Specifies a password to use only in data access requests where both of these conditions exist:
  • AUTHADMIN=YES is specified in the LIBNAME statement that is referenced in the request or is invalid.
  • The correct password for the target metadata-bound library is not otherwise available.
Requirement:The AUTHADMIN option must be set to YES for this option to have an effect. However, the use of AUTHAMDIN=YES does not require that you use AUTHPW. You are not required to specify metadata-bound library passwords in a LIBNAME statement.
Interactions:If the metadata-bound library has two or three distinct passwords, you must specify each individual password with the AUTHALTER=, AUTHREAD=, and AUTHWRITE= options as appropriate instead of using the AUTHPW= option on its own.

You can use the AUTHALTER= option in the same way as the AUTHPW= option if all three of the passwords (ALTER, READ, and WRITE) are the same and you are in a SAS language context where ALTER= can be used.

Tip:An error occurs if the AUTHPW password does not match the password that is within the referenced secured library object.
See:SAS Guide to Metadata-Bound Libraries
AUTHREAD=read-password
Specifies a READ password to use only in data access requests where both of these conditions exist:
  • AUTHADMIN=YES is specified in the LIBNAME statement that is referenced in the request.
  • The correct password for the target metadata-bound library is not otherwise available or is invalid.
Requirement:The AUTHADMIN option must be set to YES for this option to have an effect.
See:SAS Guide to Metadata-Bound Libraries
AUTHWRITE=write-password
Assigns a WRITE password to a metadata-bound library that prevents users from writing to a library, unless they enter the password.
Requirement:The AUTHADMIN option must be set to YES for this option to have an effect.
See:SAS Guide to Metadata-Bound Libraries
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 in the DATASETS procedure. 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:SAS Engines in SAS Language Reference: Concepts
CVPENGINE|CVPENG=engine
specifies the engine to use in order to process a SAS data file that requires transcoding.
See:SAS Engines in SAS Language Reference: Concepts
CVPMULTIPLIER|CVPMULT=multiplier
specifies a multiplier value in order to expand character variable lengths when processing a SAS data file that requires transcoding.
See:SAS Engines in SAS Language Reference: Concepts
EXTENDOBSCOUNTER=NO | YES
specifies whether to extend the maximum observation count in output SAS data files for a SAS library.
NO
specifies that the maximum observation count in a newly created SAS data file is determined by the long integer size for the operating environment. In operating environments with a 32-bit-long integer, the maximum number is 231–1 or approximately two billion observations (2,147,483,647). In operating environments with a 64-bit-long integer, the number is 263–1 or approximately 9.2 quintillion observations.
YES
requests an enhanced file format in newly created SAS data files that counts observations beyond the 32-bit-long limitation. For a SAS data file that is created for an operating environment that stores the number of observations with a 32-bit-long integer, the file behaves like a 64-bit file with respect to counters.
Restrictions:A SAS data file that is created with EXTENDOBSCOUNTER=YES is incompatible with releases prior to SAS 9.3.

Use with the BASE engine only.

Specify EXTENDOBSCOUNTER=YES only for an output SAS data file whose internal data representation stores the observation count as a 32-bit-long integer. For a table that lists the operating environments and OUTREP= values that are appropriate with EXTENDOBSCOUNTER=YES, see When to Use the EXTENDOBSCOUNTER=YES Option in SAS Language Reference: Concepts.

The extended observation count attribute cannot be inherited by a new file. If you want to create a file with an extended observation count from a file that contains the extended observation count attribute, you must specify the EXTENDOBSCOUNTER= option for the new file. For more information, see Extended Observation Count Behavior Considerations in SAS Language Reference: Concepts.

Tip:Specifying the EXTENDOBSCOUNTER= option in a LIBNAME statement is also useful to migrate a library with the MIGRATE procedure, which does not support SAS data set options.
See:Extending the Observation Count in a SAS Data File in SAS Language Reference: Concepts
Alias:EOC=
Default:NO
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 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:INENCODING= and OUTENCODING= Options in 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 (for example, ASCII or EBCDIC); for the ordering of bytes in memory (for example, big Endian or little Endian); for word alignment (for example, 4-byte boundaries or 8-byte boundaries); for integer data-type length (for example, 16-bit, 32-bit, or 64-bit); and for doubles (for example, byte-swapped or not).
By default, SAS creates a new SAS data set by using the data representation of the CPU that is running SAS. Specifying the OUTREP= option enables you to create a SAS data set with a different data representation. For example, in a UNIX environment, you can create a SAS data set that uses a Windows data representation. For more information about compatibility and data representation, see Processing Data Using Cross-Environment Data Access (CEDA) in SAS Language Reference: Concepts.
Data Representation Values for OUTREP= Option
OUTREP= Value
Alias1
Environment
ALPHA_TRU64
ALPHA_OSF
Tru64 UNIX
ALPHA_VMS_32
ALPHA_VMS
OpenVMS Alpha
ALPHA_VMS_64
OpenVMS Alpha
HP_IA64
HP_ITANIUM
HP-UX for the Itanium Processor Family Architecture
HP_UX_32
HP_UX
HP-UX for PA-RISC
HP_UX_64
HP-UX for PA-RISC, 64-bit
INTEL_ABI
ABI for Intel architecture
LINUX_32
LINUX
Linux for Intel architecture
LINUX_IA64
Linux for Itanium-based systems
LINUX_X86_64
Linux for x64
MIPS_ABI
MIPS ABI
MVS_32
MVS
31-bit SAS on z/OS
MVS_64_BFP
64-bit SAS on z/OS
OS2
OS/2 for Intel
RS_6000_AIX_32
RS_6000_AIX
AIX
RS_6000_AIX_64
AIX
SOLARIS_32
SOLARIS
Solaris for SPARC
SOLARIS_64
Solaris for SPARC
SOLARIS_X86_64
Solaris for x64
VAX_VMS
OpenVMS VAX
VMS_IA64
OpenVMS on HP Integrity
WINDOWS_32
WINDOWS
32-bit SAS on Microsoft Windows
WINDOWS_64
64-bit SAS on Microsoft Windows (for both Itanium-based systems and x64)
1It is recommended that you use the current values. The aliases are available for compatibility only.
Interactions:By default, PROC COPY uses the data representation of the file from the source library. If, instead, you want to use the data representation of the current SAS session, specify the NOCLONE option. If you want to use a different data representation, specify the NOCLONE option and the OUTREP= option. When you use PROC COPY with SAS/SHARE or SAS/CONNECT, the default behavior is to use the data representation of the current SAS session. For more information about CLONE and NOCLONE, see the COPY Statement in the Base SAS Procedures Guide.

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.

Transcoding could result in character data loss when encodings are incompatible. For more information, see the SAS National Language Support (NLS): Reference Guide.

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:If REPEMPTY=YES and REPLACE=NO, then the data set is not replaced.
NO
specifies that a new empty data set with a given name not replace an existing data set with the same name.
Tips: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;

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.

Note:For an individual data set, the REPEMPTY= data set option overrides the setting of the REPEMPTY= option in the LIBNAME statement.
See:REPEMPTY= Data Set Option in SAS Data Set Options: Reference

Engine Host Options

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

Details

Associating a Libref with a SAS Library (Form 1)

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

Disassociating a Libref from a SAS Library (Form 2)

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.
LIBNAME libref CLEAR | _ALL_ CLEAR;

Writing SAS Library Attributes to the SAS Log (Form 3)

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.
LIBNAME libref LIST | _ALL_ LIST;

Concatenating SAS Libraries (Form 4)

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.
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 (Form 4)

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.
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 the previous rule.)
  • 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.

Automatically Creating the Library Directory

You can set the DLCREATEDIR system option to create the directory for the SAS library that is specified in the LIBNAME statement if that directory does not exist. For more information, see the DLCREATEDIR System Option in SAS System Options: Reference.
z/OS Specifics: For more information, see the DLCREATEDIR System Option: z/OS in SAS Companion for z/OS.

Metadata-Bound Libraries

In the second maintenance release of SAS 9.3, the Base SAS LIBNAME engine can enforce permissions on a user and group basis to SAS data sets that are bound to secured table objects in the metadata server. Metadata-bound libraries provide enhanced protection for Base SAS data (SAS data sets and SAS views). A connection to the metadata server is required in order to access metadata-bound data.
For more information, see the SAS Guide to Metadata-Bound Libraries and the AUTHLIB procedure in Base SAS Procedures Guide.
If you have questions or need assistance accessing your data, contact your local SAS Administrator.

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 and enables 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 the 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;

See Also

How Many Characters Can I Use When I Measure SAS Name Lengths in Bytes? in SAS Language Reference: Concepts
Data Set Options:
ENCODING= Data Set Option in SAS National Language Support (NLS): Reference Guide
Statements:
CATNAME Statement for a discussion of concatenating SAS catalogs
FILENAME Statement
LIBNAME option character variable attributes used to transcode SAS files
LIBNAME Statement, SASEDOC in SAS Output Delivery System: User's Guide
LIBNAME Statement for SAS metadata
LIBNAME Statement for Scalable Performance Data (SPD)
LIBNAME statement for XML documents
LIBNAME Statement for SAS/ACCESS
LIBNAME Statement for SAS/CONNECT
LIBNAME Statement, SASESOCK Engine in SAS/CONNECT User's Guide
LIBNAME Statement for SAS/SHARE
System Options:
DLCREATEDIR System Option in SAS System Options: Reference
USER= System Option in SAS System Options: Reference
Copyright © SAS Institute Inc. All rights reserved.