Statements under UNIX

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:	anywhere
UNIX specifics:	engine, library, and engine/host-options
See:	LIBNAME Statement in SAS Language Reference: Dictionary

Syntax
Details
	Omitting Engine Names from the LIBNAME Statement
	Engine/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;

libref

is any valid libref as documented in SAS Language Reference: Dictionary. SAS reserves some librefs for special system libraries. See the SAS Companion for UNIX Environments for information about reserved librefs.

engine

is one of the library engines supported under UNIX. See Details for a description of the engines. 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 casesensitive.

'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. See the SAS Companion for UNIX Environmentsfor more information about concatenating libraries.

options

are LIBNAME statement options that are available in all operating environments. See SAS Language Reference: Dictionary for information about these options.

engine/host-options

can be any of the options described in Engine/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. See Using Environment Variables as Librefs in UNIX Environments for more information. [cautionend]

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

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

Details

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. See the following table and Accessing BMDP, OSIRIS, or SPSS Files in UNIX Environments for more information.

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: Dictionary.	is the pathname of the directory containing the library.
sequential	V9TAPE V8TAPE	enables you to access SAS files that were created in a sequential format, whether on tape or on disk. requires less overhead than the default engine because sequential access is simpler that random access. This engine is also documented in SAS Language Reference: Dictionary.	is the name of the special file (see Introduction to External Files and Devices in UNIX Environments) associated with the sequential device, such as /dev/rmt/0mn.
	V6TAPE	accesses V6 SAS data files that were created in a sequential format. This engine is read-only.	is the name of the special file that is associated with the sequential device, such as /dev/rmt/Omn.
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	SPDS	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 Scalable Performance Data Server User's Guide for more information.	is the logical LIBNAME domain name for a Scalable Performance Data Server (SPDS) 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. See the SAS MDDB Server Software: Administration Guide for more information.
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. See ENGINE System Option: UNIX for a discussion of the ENGINE= system option.

Note: The ENGINE= system option specifies the default engine for libraries on disk only. [cautionend]

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. See Using Multiple Engines for a Library in UNIX Environments for more information.
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/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.

Tip:

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.

Tip:

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;

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.

Tip:	For the FILELOCKS statement option, RESET is not a valid value as it is when you use the FILELOCKS system option.
Tip:	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: The FILELOCKS option in the LIBNAME statement overrides the FILELOCKS system option. [cautionend]

See FILELOCKS System Option: UNIX for more information.

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 support.sas.com 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. 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. In addition, see 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 blocks of data in units of kilobytes or megabytes.

Requirement:

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 file 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/Host Options.)

Requirement:

Use USEDIRECTIO= with the ENABLEDIRECTIO statement option to turn on direct file I/O.