LIBNAME Statement: UNIX

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; implicitly concatenates SAS catalogs; turns off file locking.
Valid in: anywhere
UNIX specifics: engine, library, and engine/host-options
See: LIBNAME Statement in SAS Statements: Reference
Syntax
Details
Types of Engines
Omitting Engine Names from the LIBNAME Statement
Engine and Host Options
See Also

Syntax

LIBNAME libref <engine> 'SAS-library' <options> <engine/host-options> ;
LIBNAME libref <engine> ('library-1'<,...'library-n'> ) <options> ;
LIBNAME libref ('library-1'|libref-1,...,'library-n'|libref-n);
LIBNAME libref CLEAR | _ALL _ CLEAR;
LIBNAME libref LIST | _ALL _ LIST;

Required Argument

libref
is any valid libref as documented in LIBNAME Statement in SAS Statements: Reference. SAS reserves some librefs for special system libraries. For more information about reserved librefs, see Librefs Assigned by SAS in UNIX Environments.

Optional Arguments

engine
is one of the library engines supported under UNIX. For a description of the engines, see Details. If no engine name is specified, SAS determines which engine to use as described in Omitting Engine Names from the LIBNAME Statement.
'SAS-library'
differs based on the engine that you specify and based on your current working directory. Engine Names and Descriptions describes what each engine expects for this argument. Specify directory pathnames as described in Specifying Pathnames in UNIX Environments. You cannot create directories with the LIBNAME statement. The directory that you specify must already exist, and you must have permissions to it. Enclose the library name in quotation marks. Remember that UNIX pathnames are cases sensitive.
'library-n'|libref-n
are pathnames or librefs (that have been assigned) for the libraries that you want to access with one libref. Use these forms of the LIBNAME statement when you want to concatenate libraries. Separate the pathnames with either commas or blank spaces. Enclose library pathnames in quotation marks. Do not enclose librefs in quotation marks. For more information about concatenating libraries, see Assigning a Libref to Several Directories (Concatenating Directories).
options
are LIBNAME statement options that are available in all operating environments. For information about these options, see LIBNAME Statement in SAS Statements: Reference.
engine/host-options
can be any of the options described in Engine and Host Options.
_ALL_
refers to all librefs currently defined. You can use this keyword when you are listing or clearing librefs.
CLEAR
clears the specified libref, or, if you specify _ALL_, clears all librefs that are currently defined. 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. You can still reuse it, either as a libref or a fileref. For more information, see Using Environment Variables as Librefs in UNIX Environments.
SAS automatically clears the association between librefs and their respective libraries at the end of your job or session. If you want to associate an existing libref with a different SAS library during the current session, you do not have to end the session or clear the libref. SAS automatically reassigns the libref when you issue a LIBNAME statement for the new SAS library.
LIST
writes to the SAS log the engine, pathname, file format, access permissions, and so on, that are associated with the specified libref, or, if you specify _ALL_, prints this information for all librefs that are currently defined. Librefs defined as environment variables appear only if you have already used those librefs in a SAS statement.
NOSETPERM
specifies that permission settings are not inherited from one library member to another when the library members are opened with the same libref. If you have two assignments to a path, one with the NOSETPERM option and the other without, the two assignments are treated as if the paths do not match. The LIBNAME statement with the NOSETPERM option does not inherit permission settings.
Once the NOSETPERM option is used to turn off permission settings for a libref, the option is in effect whenever you use the libref. There is no option that turns off the NOSETPERM option. To turn off the NOSETPERM option, submit the following statement:
libname libref clear;

Details

Types of Engines

There are two main types of engines:
View engines
enable SAS to read SAS views that are described by SAS/ACCESS software, the SQL procedure, and DATA step views. The use of SAS view engines is automatic because the name of the view engine is stored as part of the descriptor portion of the SAS data set.
Library engines
control access at the SAS library level. Every SAS library has an associated library engine, and the files in that library can be accessed only through that engine. There are two types of library engines:
native engines
access SAS files created and maintained by SAS. See the following table for a description of these engines.
interface engines
treat other vendors' files as if they were SAS files. For more information, see the following table and Accessing BMDP, OSIRIS, or SPSS Files in UNIX Environments.
Engine Names and Descriptions
Engine Type
Name (Alias)
Description
SAS Library
default
V9 (BASE)
V8
enables you to create new SAS data files and to access existing SAS data files that were created with Version 8 or SAS 9. The V8 and V9 engines are identical. This engine enables Read access to data files that were created with some earlier releases of SAS, but this engine is the only one that supports SAS 9 catalogs. This engine allows for data set indexing and compression, and is also documented in SAS Language Reference: Concepts.
is the pathname of the directory containing the library.
compatibility
V6
accesses any data file that was created by Releases 6.09 through 6.12. This engine is read-only.
is the pathname of the directory containing the library.
servers
SPD Server
enables communication between a client session and a data server. You must have the Scalable Performance Data Server licensed on your client computer to use this engine. See the SAS Scalable Performance Data Server: User's Guide for more information.
is the logical LIBNAME domain name for a SAS Scalable Performance Data Server (SPD Server) library on the server. The name server resolves the domain name into the physical path for the library.
MDDB
enables communication between a client session and an MDDB server. You must have SAS/MDDB Server licensed on your client computer or on your server to use this engine.
transport
XPORT
accesses transport data sets. This engine creates computer-independent SAS transport files that can be used under all hosts running Release 6.06 or later of SAS. This engine is documented in Moving and Accessing SAS Files.
is the pathname of either a sequential device or a disk file.
XML
XML
generates (writes) and processes (reads) any XML document, which is an application- and computer-independent file.
is the pathname of the XML document.
interface
BMDP
provides Read-Only access to BMDP files. This engine is available only on AIX, HP-UX, and Solaris.
is the pathname of the data file.
OSIRIS
provides Read-Only access to OSIRIS files.
is the pathname of the data file.
SPSS
provides Read-Only access to SPSS files.
is the pathname of the data file.

Omitting Engine Names from the LIBNAME Statement

It is always more efficient to specify the engine name than to have SAS determine the correct engine. However, if you omit an engine name in the LIBNAME statement or if you define an environment variable to serve as a libref, SAS determines the appropriate engine.
If you have specified the ENGINE= system option, SAS uses the engine name that you specified. For a discussion of the ENGINE= system option, see ENGINE= System Option: UNIX.
Note: The ENGINE= system option specifies the default engine for libraries on disk only.
If you did not specify the ENGINE= system option, SAS looks at the extensions of the files in the given directory and uses these rules to determine an engine:
  • If all the SAS data sets in the library were created by the same engine, the libref is assigned using that engine.
    Note: If the engine used to create the data sets is not the same as the default engine, then you will not be able to create a view or stored program. For more information, see Using Multiple Engines for a Library in UNIX Environments.
  • If there are no SAS data sets in the given directory, the libref is assigned using the default engine.
  • If there are SAS data sets from more than one engine, the system issues a message about finding mixed engine types and assigns the libref using the default engine.

Engine and Host Options

The LIBNAME statement accepts the following options:
ENABLEDIRECTIO
specifies that direct file I/O can be available for all files that are opened in the library that is identified in the LIBNAME statement.
A libref that is assigned to a directory with the ENABLEDIRECTIO option will not match another libref that is assigned to the same directory without ENABLEDIRECTIO. The two librefs will point to the same directory, but the files that are opened using one libref will be read from and written to using Direct I/O. Files that are opened using the other libref will be read from and written to using the regular disk I/O calls.
You must use the ENABLEDIRECTIO option with the USEDIRECTIO= option to turn on direct I/O for the file or files whose libref is listed in the LIBNAME statement. The following example uses the ENABLEDIRECTIO and USEDIRECTIO= LIBNAME options. In this case, all files that are referenced with libref test will be opened for direct I/O: 
LIBNAME test '.' ENABLEDIRECTIO USEDIRECTIO=yes;
Tip
The following example uses the ENABLEDIRECTIO LIBNAME option to enable files that are associated with the libref test to be opened for direct I/O. The USEDIRECTIO= data set option opens test.file1 for direct I/O. test.file2 is not opened for direct I/O, although it is enabled for direct I/O:
LIBNAME test'.'ENABLEDIRECTIO;
data test.file1(USEDIRECTIO=yes); 
   ... more SAS statements ...
run;
data test.file2; 
   ... more SAS statements ...
run;
FILELOCKS=NONE | FAIL | CONTINUE
specifies whether file locking is turned on or off for the files that are opened under the libref in the LIBNAME statement. The FILELOCKS statement option works like the FILELOCKS system option, except that it applies only to the files that are associated with the libref. The following values for the FILELOCKS statement option are available:
NONE
turns file locking off. NONE specifies that SAS attempts to open the file without checking for an existing lock on the file. NONE does not place an operating system lock on the file. These files are not protected from shared Update access.
FAIL
turns file locking on. FAIL specifies that SAS attempts to place an operating system lock on the file. Access to the file is denied if the file is already locked, or if it cannot be locked.
CONTINUE
turns file locking on. CONTINUE specifies that SAS attempts to place an operating system lock on the file. If the file is already locked by someone else, an attempt to open it fails. If the file cannot be locked for some other reason (for example, if the file system does not support locking), the file is opened and a warning message is sent to the log.
The FILELOCKS option in the LIBNAME statement applies to most (but not all) of the SAS I/O files (for example, data sets and catalogs) opened under the libref that is listed in the LIBNAME statement.
For the FILELOCKS statement option, RESET is not a valid value as it is when you use the FILELOCKS system option.
Use the FILELOCKS system option instead of the FILELOCKS statement option to set the locking behavior for your files. (The FILELOCKS statement option will be deprecated in a future release of SAS.) Note that the FILELOCK option in the LIBNAME statement overrides the LIBNAME system option. For more information, see the FILELOCKS system option in the UNIX operating environment. You can also specify any of the options supported by the Scalable Performance Data Server. Refer to Scalable Performance Data Server: User's Guide at the Technical Support Web site for a description of these options.
FILELOCKWAIT=n
specifies the number of seconds SAS will wait for a locked file to become available to another process.
If the locked file is released before the number of seconds specified by n, then SAS locks the file for the current process and continues. If the file is still locked when the number of seconds has been reached, then SAS writes a “Locked File” error to the log and the DATA step fails.
Interaction Specifying the FILELOCKWAIT= option can have an adverse effect on one or more SAS/SHARE server and client sessions that are waiting for the release of a SAS file that is locked by another process. One or more wait conditions could lead to failed processes for a SAS/SHARE server and clients.
Interaction To prevent the possibility of a failed SAS/SHARE process, you can set FILELOCKWAIT=0, which cancels the amount of time that a SAS/SHARE server and clients would wait for the release of a locked file. Canceling the wait time would prevent a failed process. For more information, see the FILELOCKWAITMAX system option. See also the FILELOCKWAITMAX system option in the section about predefining a server library by using the LIBNAME statement in the SAS/SHARE: User’s Guide.
Range 0–600
Default 0
TRANSFERSIZE=nK | nM
specifies the size of a large block of data that is read from a file that is opened.
n
specifies an integer value.
K
specifies the size of the block in kilobytes.
M
specifies the size of the block in megabytes.
To use the TRANSFERSIZE option, you must have files open for direct I/O. That is, both the ENABLEDIRECTIO and USEDIRECTIO= options must be in effect. If you use TRANSFERSIZE without the ENABLEDIRECTIO and USEDIRECTIO= options, the option is accepted, but it has no effect.
In the following example, 128k blocks of data are read from the test.file1 because this file is opened for direct I/O. test.file2 is not open for direct I/O, and the TRANSFERSIZE option has no effect on this file: 
LIBNAME test'.'ENABLEDIRECTIO TRANSFERSIZE=128k;
data test.file1(USEDIRECTIO=yes);
   ... more SAS statements ...
run;
data test.file2;
   ... more SAS statements ...
run;
In the following example, all the files that are listed in the DATA statements read 128k blocks of data because all the files are affected by the ENABLEDIRECTIO, USEDIRECTIO=, and TRANSFERSIZE options: 
LIBNAME test'.'ENABLEDIRECTIO USEDIRECTIO=yes TRANSFERSIZE=128k;
data test.file1;
   ... more SAS statements ...
run;
data test.file2;
   ... more SAS statements ...
run;
data test.file3;
   ... more SAS statements ...
run;
USEDIRECTIO= YES | NO
if used with the ENABLEDIRECTIO statement option, turns on or turns off direct file I/O for all the files associated with the libref listed in the LIBNAME statement. (See ENABLEDIRECTIO in Engine and Host Options.)
Requirement
Use USEDIRECTIO= with the ENABLEDIRECTIO statement option to turn on direct file I/O.

See Also

System Options:
FILELOCKS System Option: UNIX
Other References:
Introduction to SAS Files, Libraries, and Engines in UNIX Environments
Copyright © SAS Institute Inc. All rights reserved.