LIBNAME Function

Assigns or deassigns a libref for a SAS library.

Category:	SAS File I/O
See:	LIBNAME Function: Windows in SAS Companion for Windows

Syntax

LIBNAME(libref<,SAS-library<,engine<,options> > > )

Required Argument

libref

is a character constant, variable, or expression that specifies the libref that is assigned to a SAS library.

Tip	The maximum length of libref is eight characters.

Optional Arguments

SAS-library

is a character constant, variable, or expression that specifies the physical name of the SAS library that is associated with the libref. Specify this name as required by the host operating environment. This argument can be null.

engine

is a character constant, variable, or expression that specifies the engine that is used to access SAS files opened in the data library. If you are specifying a SAS/SHARE server, then the value of engine should be REMOTE. This argument can be null.

options

is a character constant, variable, or expression that specifies one or more valid options for the specified engine, delimited with blanks. This argument can be null.

Details

Basic Information about Return Codes

The LIBNAME function assigns or deassigns a libref from a SAS library. When you use the LIBNAME function with two or more arguments, SAS attempts to assign the libref. When you use one argument, SAS attempts to deassign the libref. Return codes are generated depending on the value of the arguments that are used in the LIBNAME function and whether the libref is assigned.

When assigning a libref, the return code will be 0 if the libref is successfully assigned. If the return code is nonzero and the SYSMSG function returns a warning message or a note, then the assignment was successful. If the SYSMSG function returns an error, then the assignment was unsuccessful.

If a library is already assigned, and you attempt to assign a different name to the library, the libref is assigned, the LIBNAME function returns a nonzero return code, and the SYSMSG function returns a note.

When LIBNAME Has One Argument

When LIBNAME has one argument, the following rules apply:

If the libref is not assigned, a nonzero return code is returned and the SYSMSG function returns a warning message.
If the libref is successfully assigned, a 0 return code is returned and the SYSMSG function returns a blank value.

When LIBNAME Has Two Arguments

When LIBNAME has two arguments, the following rules apply:

If the second argument is NULL, all blanks, or zero length, SAS attempts to deassign the libref.
If the second argument is not NULL, not all blanks, and not zero length, SAS attempts to assign the specified path (the second argument) to the libref.
If the libref is not assigned, a nonzero return code is returned and the SYSMSG function returns an error message.
If the libref is successfully assigned, a 0 return code is returned and the SYSMSG function returns a blank value.

When LIBNAME Has Three or Four Arguments

If the second argument is NULL, all blanks, or zero length, the results depend on your operating environment.
If the second argument is NULL and the libref is not already assigned, then a nonzero return code is returned and the SYSMSG function returns an error message.
If the second argument is NULL and the libref has already been assigned, then LIBNAME returns a value of 0 and the SYSMSG function returns a blank value.
If at least one of the previous conditions is not met, then SAS attempts to assign the specified path (second argument) to the libref.
If the engine is not a SAS engine (for example, ODBC), then the second argument, SAS-library, must be missing or empty and cannot contain “ or TRIMN(). If the SAS-library argument does contain a value, then the libname is not assigned.
These two examples use an ODBC engine to assign a libname:
```
rc3 = libname ('mylib3',  , 'ODBC', 'DSN=mySQLServer_11');
/**Argument2, SAS-library is missing**/
```
```
rc3 = libname ('mylib3',, 'ODBC', 'DSN=mySQLServer_11');
/** Argument2, SAS-library is missing**/
```
This example uses an ODBC engine but does not assign a libname because TRIMN is used:
```
rc3 = libname ('mylib3',TRIMN(&variable.), 'ODBC', 'DSN=mySQLServer_11'); 
```

Note: In the DATA step, a character constant that consists of two consecutive quotation marks without any intervening spaces is interpreted as a single space, not as a string with a length of 0. To specify a string with a length of 0, use the TRIMN Function.

Operating Environment Information: Some systems allow a SAS-library value of '' (a space between the single quotation marks) to assign a libref to the current directory. Other systems disassociate the libref from the SAS library when the SAS-library value contains only blanks. The behavior of LIBNAME when a single space is specified for SAS-library is dependent on your operating environment.Under some operating environments, you can assign librefs by using system commands that are outside the SAS session.

Examples

Example 1: Assigning a Libref

This example attempts to assign the libref NEW to the SAS library MYLIB. If an error or warning occurs, the message is written to the SAS log. Note that in a macro statement you do not enclose character strings in quotation marks.

%if (%sysfunc(libname(new,MYLIB))) %then
  %put %sysfunc(sysmsg());

Example 2: Deassigning a Libref

This example deassigns the libref NEW that was previously associated with the data library MYLIB in the preceding example. If an error or warning occurs, the message is written to the SAS log. In a macro statement, you do not enclose character strings in quotation marks.

%if (%sysfunc(libname(new))) %then
  %put %sysfunc(sysmsg());

Example 3: Compressing a Library

This example assigns the libref NEW to the MYLIB data library and uses the COMPRESS option to compress the library. This example uses the default SAS engine. In a DATA step, you enclose character strings in quotation marks.

data test;
   rc=libname('new','MYLIB',,'compress=yes');
run;