LIBNAME Statement

In a client session, associates a libref (a shortcut name) with a SAS library that is located on the server for client access. In a server session, predefines a server library that clients are permitted to access.

Valid in:	client and server sessions
Category:	Data Access
Operating environment:	LIBNAME Statement: UNIX in SAS Companion for UNIX Environments, LIBNAME Statement: Windows in SAS Companion for Windows, and LIBNAME Statement: z/OS in SAS Companion for z/OS.
See:	Base SAS LIBNAME Statement in SAS Statements: Reference.

Syntax

Details

Examples

Example 1: Client Using the Server's Libref

Example 2: Client Assigning a Libref to a Physical Path

Example 3: Assigning a Server Host to a Macro Variable

Example 4: Using a Server Password to Access a Server Library

Example 5: Specifying a Prompt for a Password to Access a Server Library

Example 6: Specifying an Encoded Password in a LIBNAME Statement

Example 7: Associating a User Libref with a Server Libref

Example 8: Duplicating a Server Libref

Example 9: Server Inheritance of User Librefs That Are Associated with Server Librefs

Syntax

LIBNAME libref <engine> < 'SAS-data-library'> SERVER=<server-node.>
server-name | _ _ port-number <options> ;

Required Arguments

libref: For a server, specifies the name of a library reference (predefines a library) for client access. One or more LIBNAME statements may be issued before the server is started. If you predefine server libraries and want to limit client access to only the predefined server libraries, use the NOALLOC option in the PROC SERVER statement. Specifying the ALLOC option in the PROC SERVER statement permits clients to assign server libraries for use after a server is started.

For a client, specifies the name of a server library for client access.

CAUTION:

A client's ability to access a SAS/SHARE server library depends on the permissions granted at server start-up.

If PROC SERVER ALLOC is specified, clients can access both predefined libraries and libraries that have not already been allocated at server start-up. If PROC SERVER NOALLOC is specified, client access is limited to predefined server libraries. For details about the PROC SERVER statement, see The SERVER Procedure.

The libref that you specify is presumed to be the server libref for an existing server library unless you specify the SLIBREF= option or the physical name of the data library.

The libref that you specify must be a valid SAS name, and it must be the first argument in the LIBNAME statement.

engine: specifies the name of a valid SAS engine for a client to use to access the server library. Usually, you should not use this option because the client automatically determines which engine to use for accessing a SAS/SHARE server. Specify this option only to override the SAS default for a specific server, or to reduce the time that is needed to determine which engine to use to access a specific server.

For example, if the server library is located on a SAS/SHARE server that is running SAS 9.3, you could specify REMOTE9. Specifying an explicit engine might improve performance slightly.

Examples of engines include REMOTE, REMOTE8, and REMOTE9. For a list of valid engines, see the SAS documentation for your operating environment. For background information about engines, see SAS Language Reference: Concepts.

The engine parameter is positional. If you use it, it must follow the libref.

Note:Do not confuse the engine positional parameter with the RENGINE= option. An engine is used by a client to access a server. An RENGINE is used by the server to access its SAS library.

'SAS-library': specifies the physical name for the SAS library (on the server) that the client will access. If you specify a server library either as the libref or as the value for the SLIBREF= option, you must omit the physical name.

If you specify 'SAS-library', the name must be a valid SAS name, and it must be enclosed in single or double quotation marks. For details about specifying a SAS library, see the documentation that is appropriate to your operating environment.

SERVER=<server-node.>server-name | _ _port-number

specifies the location and identity of the SAS/SHARE server session that administers the SAS library.

server-node

specifies the node name (machine name or IP address) of the server where the SAS library is located. The node name must be a valid SAS name that is 8 or less characters in length. Specifying server-node is necessary when using the TCP/IP communications access method and the client session is on a different machine from the server.

If the node name exceeds eight characters, you can either specify the node name by defining it as a macro variable or you can use the HOSTNAME= option to specify the node name as a quoted string. The following example shows how to use the macro statement %LET to assign the node name MYHOST.MY.NET.WORK to the macro variable, MYRLIB, and then use that variable in place of the invalid node name in the LIBNAME statement.

%let myrlib=myhost.my.net.work;
libname refserv server=myrlib._2323;

See Assigning a Server Host to a Macro Variable for another example of how to use a macro variable with an invalid SAS name.

Another way to specify the node name when it is not a valid SAS name is to use the HOSTNAME= option (see HOSTNAME=node-name). In the example below, the server library, TEST, is defined in the server session SHR1, which runs on the node STONES.UNX.APEX.COM. The node name is specified as a quoted string that has a valid length.

Libname test hostname=’stones.unx.apex.com’ server=shr1;

Server naming is also affected by the operating environment and the access method that you specify for communication between server and client session.

For complete information about how to name servers by operating environment, see Communications Access Methods for SAS/CONNECT and SAS/SHARE. For details about the SERVICES file, see the topic on the TCP/IP SERVICES File in Communications Access Methods for SAS/CONNECT and SAS/SHARE. To get the value for the server-ID in your environment, consult your server administrator.

server-name

specifies the particular server session that administers the SAS library. The name must be a valid SAS name, 8 or less characters in length.

For the TCP/IP communications access method, this must be the name of a valid TCP/IP service as defined in the TCP/IP Services file.
For the XMS communications access method on z/OS, this name must be a unique identifier with respect to your cross-memory subsystem anchor. For details, see SAS/SHARE SUBSYSID= Option in Communications Access Methods for SAS/CONNECT and SAS/SHARE.

_ _port-number

If you are using the TCP/IP access method, you can specify the server's port number that corresponds to the server ID in the TCP/IP SERVICES file. Precede the port number with two consecutive underscores. (For details about the SERVICES file, see the topic on the TCP/IP SERVICES File in Communications Access Methods for SAS/CONNECT and SAS/SHARE ).

Note: Do not space after the first underscore or the second underscore.

Example:

_ _1025

Optional Arguments

ACCESS=READONLY: restricts a client's access to a SAS library via a multi-user SAS/SHARE server. If ACCESS=READONLY is specified in the client session, the client can read but not update data in the library. However, other clients might have read/write access to the library via the server.

If ACCESS=READONLY is specified in the server session, all clients are limited to read-only access to the library via the server. No clients will have update access.

AUTHDOMAIN=auth-domain | "auth-domain"

specifies the name of an authentication domain, which is a metadata object that manages the credentials (user ID and password) that are associated with the specified domain. Specifying the authentication domain is a convenient way to obtain the metadata-based user credentials rather than having to explicitly supply them during server sign-on.

An administrator can define an authentication domain using the User Manager in SAS Management Console. See SAS Management Console: Guide to Users and Permissions for information about adding an authentication domain.

Examples:

authdomain=DefaultAuth
authdomain="SAS/SHARE Auth Domain"

Requirements:The authentication domain and the associated credentials must be stored in a metadata repository, and the metadata server must be running in order to resolve the metadata object specification.

Enclose domain names that are not valid SAS names in double or single quotation marks.

Interaction:If you specify AUTHDOMAIN=, do not also specify USERNAME= and PASSWORD=.

See:For complete details about creating and using authentication domains, see SAS Intelligence Platform: Security Administration Guide.

SAS Management Console: Guide to Users and Permissions and SAS Management Console online Help

HOSTNAME=node-name

is used to specify the name of the node that the SAS/SHARE server runs on. The value for node-name can be specified as a quoted string that does not exceed 256 characters or as an unquoted SAS name that does not exceed 32 characters.

HOSTNAME= is used in conjunction with the SERVER= option, which specifies the name of the SAS/SHARE server that runs on the node. If a two-level node name (node.server-ID) is assigned to the SERVER= option, and the HOSTNAME= option is also specified, duplicate node names would result and seem to be ambiguous. However, to resolve the ambiguity, the value that is specified as the final option in the LIBNAME statement takes precedence.

HOSTNAME= Option Examples

Syntax	Description
libname test hostname=sirlancelot server=shr1;	A server library is defined in the server session SHR1 that runs on the node SIRLANCELOT. The node name is specified as an unquoted SAS name that has a valid length.
libname test hostname='stones. unx.apex.com' server=shr1;	A server library is defined in the server session SHR1 that runs on the node STONES.UNX.APEX.COM. The node name is specified as a quoted string that has a valid length.
libname test server=d8433.shr1 hostname=defiant;	A server library is defined in the server session SHR1 that runs on the node DEFIANT. The node name is specified as an unquoted string that has a valid length. If both the SERVER= option and the HOSTNAME= option specify the node name, the option that is specified last takes precedence. In this example, the value DEFIANT, which is assigned to the option HOSTNAME=, takes precedence over the value d8433 in the two-level name that is assigned to the option SERVER=.
libname test hostname=notused server=d8433.shr1;	A server library is defined in the server session SHR1 that runs on the node d8433. The node name is specified as an unquoted string that has a valid length.

If both the SERVER= option and the HOSTNAME= option specify the node name, the option that is specified last takes precedence. In this example, the value d8433, in the two-level name that is assigned to the option SERVER=, takes precedence over the value NOTUSED, which is assigned to the option HOSTNAME=.

PASSWORD=password | "encoded-password" | _PROMPT_

executed in the client session, specifies a password that is valid on the server. This parameter is used by the server to validate the client on the server's operating environment (if authentication is enabled). For details about valid passwords, see Details .

password: must be a valid SAS name that is 1 to 8 characters in length. The value for this option is replaced by Xs in the log. To protect this password, you should use the security software at your site to limit access to the SAS program statements that create the server.

“encoded-password”

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement. For details, see the PWENCODE Procedure in the Base SAS Procedures Guide.

Here is an example of code for obtaining an encoded password:

proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=

The clear-text password srvmach is specified in the PROC PWENCODE statement. The output is generated in the form {key}encoded-password. sas001 is the key, which is used to decode the encoded password to its clear-text form when the password is needed.

Note: The encoded password is case-sensitive. Use the entire generated output string, including the key.

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.

Here is an example of using an encoded password in a LIBNAME statement:

      libname mylib server=shr1 user=jward password="{sas001}c2Vydm1hY2g=";

Aliases:PASSWD

PASS

PWD

Interaction:If you specify PASSWORD=, do not also specify AUTHDOMAIN=.

See:AUTHDOMAIN=auth-domain | "auth-domain".

USERNAME=user-ID | _PROMPT_

RENGINE=engine-name: executed in the server session, specifies the engine to be used to process the SAS library. Using this option is usually unnecessary because the server automatically determines which engine to use to process the data library. Specify this option only to override the SAS default for a specific library, or to reduce the time that is used by the server to determine which engine to use.

Note:Do not confuse the RENGINE= option with the engine positional parameter. An RENGINE is used by the server to access its SAS library. An engine is used by a client to access a server. Do not use the SPD engine as a remote engine.

RMTVIEW=YES | NO: specified in a client session, determines whether SAS data views are interpreted in the server or in the client SAS session. Where a data view is interpreted determines where the view engine is loaded and used. The default is YES.

SAS data views include DATA step views and PROC SQL views, which are created by using the SQL procedure and the ACCESS procedure (in SAS/ACCESS software). SAS data views are accessed through an engine just as other SAS data sets are. DATA step views use the SASDSV engine. PROC SQL views use the SQLVIEW engine. SAS/ACCESS views use a product-specific engine (supplied by SAS Institute) for each SAS/ACCESS interface product.

RMTVIEW= YES (the default) causes views to be interpreted in the server's SAS execution. This uses more processing time and might increase the amount of memory used. However, the amount of data transferred to the client SAS sessions might be reduced.

RMTVIEW=NO causes views to be interpreted in the client SAS session. This minimizes the processing time on the server but might increase the amount of data transferred between the server and client SAS sessions. Also, if you specify RMTVIEW=NO, there might be version incompatibilities when the client and server are running different versions of SAS. For example, SAS 6 and SAS 9.3 views are not always compatible. For details about view interpretation, see Interpreting SAS Data Views.

Default:YES

ROPTIONS="option=value <option=value>... ": executed in the server session, specifies remote options and options that are specific to an operating environment that the client passes to the engine on the server that will process the SAS library. Specify as many options as you need by using the form keyword=value. Use a blank space to separate options. You can specify options for either the default engine or an alternative engine that you specify by using the RENGINE= option. You can use the option ROPTIONS= to provide any valid option for the targeted engine. For information about the options that are supported by a specific engine, see the documentation for the engine that you will use. For details about options that are specific to an operating environment, see the documentation that is appropriate for the operating environment that you use.

CAUTION:

If allocating a library to a SAS/SHARE server, the DISP= host option is not allowed with ROPTIONS= for security reasons.

Restrictions:If one or more client sessions that run under UNIX or Windows use the FILELOCKWAIT= option in the ROPTIONS= statement to set the maximum time limit that SAS will wait for a file to be unlocked (available for use), the effect could cause the server session to stall. The SAS/SHARE server memory can become inadvertently consumed by multiple tasks that are waiting for the release of one or more locked files.

To prevent the server session from stalling, the SAS/SHARE server administrator, when invoking the SAS session from which the server session will run, can use the FILELOCKWAITMAX= system option to explicitly set the client wait time to zero. Negating the client's specified wait time prevents the server from stalling.

See:For the client session FILELOCKWAIT= option in the LIBNAME statement, see SAS Companion for UNIX Environments and SAS Companion for Windows.

For the server session FILELOCKWAITMAX= system option, see SAS Companion for UNIX Environments and SAS Companion for Windows.

Interaction between PROC SERVER and Other File-Locking Processes

SAPW=server-access-password | "encoded-password"

executed in the client session, specifies a server access password. This option is needed to access a SAS/SHARE server that is executing with the UAPW= option in PROC SERVER in effect. SAPW= establishes communication with the server that is used to access the library. Although this option is specified in the LIBNAME statement, it does not control access to the server library itself. For details about valid passwords, see Details .

password: must be a valid SAS name that is 1 to 8 characters in length. The value for this option is replaced by Xs in the log. To protect this password, you should use the security software at your site to limit access to the SAS program statements that create the server.

"encoded-password"

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement. For details, see the PWENCODE Procedure in the Base SAS Procedures Guide.

Here is an example of code for obtaining an encoded password:

proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=

Note: The encoded password is case-sensitive. Use the entire generated output string, including the key.

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.

SLIBREF=server-libref: executed in the client session, specifies an existing libref that was defined in the server session that you want to reference (or copy) in the client session. Use this option when you want to reference an existing server libref, but you want to use a different name for that libref in the client session.

Restriction:Do not assign the physical name for the SAS library on the server to SLIBREF=. SLIBREF=server-libref and 'SAS-data-library' are mutually exclusive.

Interaction:In a client session, if you define a user library whose libref duplicates a libref that has been predefined in the server session, the user libref overrides the server's predefined libref for the duration of the client session only. The server inherits the client's user libref.

See:Methods for Predefining a Server Library

Examples:Associating a User Libref with a Server Libref

Duplicating a Server Libref

Server Inheritance of User Librefs That Are Associated with Server Librefs

CAUTION:

Avoid using duplicated librefs.

Even though duplicated librefs are valid and the resolution of duplicated librefs is logical, the practice can be confusing.

USERNAME=user-ID | _PROMPT_: executed in the client session, specifies a user ID that is valid on the server. This parameter is used in two ways. The server uses it to validate the client on the server operating environment (if authentication is enabled). The server also uses it to verify access permission when the client accesses files on the server. For details about valid user IDs, see Details .

If USERNAME=_PROMPT_, a dialog box appears that contains a message that prompts the user to enter a valid user ID. This enables you to specify the value at program execution instead of coding it into the program. Using _PROMPT_ is a way to enforce security.

Alias:USERID, USER, UID

Interaction:If you specify USERNAME=, do not also specify AUTHDOMAIN=.

See:AUTHDOMAIN=auth-domain | "auth-domain"

PASSWORD=password | "encoded-password" | _PROMPT_

Details

Here are the general rules for creating user IDs and passwords:

Mixed case is allowed (for example, user=JoeBlack).
Quotation marks must enclose values that have the following characteristics:
- contain one or more spaces (for example, user='joe black').
- contain one or more special characters (for example, user='joe?black').
- contain one or more quotation marks (for example, password="It's mine").
- begin with a numeric value (for example, password='2BorNot2B').
- do not conform to rules for user-supplied SAS names.
- are NULL values (for example, user='').
  
  NULL values are sometimes used in a UNIX environment, when you want to use the local ID. See Communications Access Methods for SAS/CONNECT and SAS/SHARE for details.
- are user names that contain domain information (for example, user='apexdomain\joe').
  
  Domain information is sometimes included in the Windows environment.
The SAPW= option requires that you specify a password that is 1 to 8 characters in length.
Specify the value _PROMPT_ if you want SAS to prompt you for information (for example, password=_prompt_).

Using _PROMPT_ increases security by causing SAS to prompt you for a password instead of coding the password in the LIBNAME statement.

SAS limits each user name and password to 256 characters. The operating environment in which SAS is running might also impose restrictions on user names and passwords. For details, see Communications Access Methods for SAS/CONNECT and SAS/SHARE.

Examples

Example 1: Client Using the Server's Libref

The client uses the existing server libref SALES to point to a server library that is located on SERVER1.

libname sales server=server1;

Example 2: Client Assigning a Libref to a Physical Path

The client assigns the libref SQLDSLIB to the SAS library SASXYZ.VIEWLIB.SASDATA that is located in the SAS/SHARE session SERVER7. In this example, the client is permitted to access a server library that has not been predefined at the server.

libname sqldslib 'sasxyz.viewlib.sasdata' server=server7;

Example 3: Assigning a Server Host to a Macro Variable

The client assigns the libref REMNAME to the SAS server MYHOST.MY.NET.WORK The LIBNAME statement establishes the libref SCORCARD to point to a library on the server that is defined by REMNAME.

options comamid=tcp;
%let remnode=myhost.my.net.work; 
libname scorcard remote server=remnode._2323;

Example 4: Using a Server Password to Access a Server Library

The client associates the libref EDUCLIB with the SAS library SASDEMO.EDUCCATS.SCREENS that is located on the server ABCSERV. Users must specify the password DEMOPW in order to access this server.

libname educlib 'sasdemo.educcats.screens' server=abcserv sapw=demopw;

Example 5: Specifying a Prompt for a Password to Access a Server Library

Rather than hardcoding the user's password to access a server library, the client specifies that a prompt for password be displayed.

libname mygrade slibref=grades server=shr1 user=bass password=_prompt_;

Example 6: Specifying an Encoded Password in a LIBNAME Statement

To prevent the risk of exposing clear-text passwords in stored SAS programs, the client specifies an encoded password.

libname sales server=server1 userid="myuserid" password="{sas001}c2Vydm1hY2g=;

Example 7: Associating a User Libref with a Server Libref

The client associates the new user libref MKTDATA with an existing server libref MARKETD in the SAS/SHARE session SERVER1.The user libref MKDATA is a copy of the server libref MARKETD. For this client, the server inherits the client's user libref MKTDATA.

libname MKTDATA slibref=MARKETD server=server1;

Example 8: Duplicating a Server Libref

Two predefined libraries are created in a server session before the server session is started.These libraries are available to any client to access through the SAS/SHARE server session.

libname shoe 'C:\myshoe';
libname blue 'C:\myblue';
proc server id=shr1; 
run;

In the client session, the user defines a new libref BLUE, which is a copy of the server libref SHOE, which points to C:\MYSHOE.The client's user libref BLUE overrides the server libref BLUE in this client session only. For this client , the server has the server-defined libref SHOE, and the server has inherited the client's user libref BLUE. The user libref BLUE will override the server libref BLUE for this client only.

libname blue slibref=shoe server=shr1;

As another example, if the user defined a new user libref GLUE that referred to the server libref BLUE, would libref BLUE refer to the client's user libref BLUE or to the original server libref BLUE? In this example, because the server has already inherited the client's user libref BLUE, GLUE will refer to the client's user libref BLUE in this client session only. The order in which the library assignments occurs is important. If libref GLUE were assigned before libref BLUE, then libref GLUE would be assigned to C:\MYBLUE rather than to C:\MYSHOE.

libname glue slibref=blue server=shr1;

Example 9: Server Inheritance of User Librefs That Are Associated with Server Librefs

Here are two predefined libraries that are created in a server session:

libname zoo 'C:\blue';
libname zoo 'C:\glue';
proc server id=shr1; 
run;

In this example, the user libref MYLIB is assigned to the server libref ZOO.

libname mylib slibref=zoo server=hrhost.shr1;

Because the server performs work on behalf of the client, the server inherits the user libref MYLIB.The SAS logs, which can be viewed in the client and server sessions, indicate that the librefs of the client and the server are identical. Libref MYLIB points to two physical files C:\blue and C:\glue, which are concatenated.

34   libname mylib slibref=zoo server=hrhost.shr1;                          
NOTE: Libref MYLIB was successfully assigned as follows:                        
      Engine:        REMOTE                                                     
      Physical Name: ( 'C:\blue' 'C:\glue' )
35   proc datasets lib=mylib;                                                   
                                            Directory                           
Libref                                      MYLIB                    
Engine                                      REMOTE                              
Physical Name                               ( 'C:\blue' 'C:\glue' )             
Accessed through server                     HRHOST.SHR1                         
Server's libref                             MYLIB                    
Server's engine                             V9                                  
Server's SAS release                        9.02                                
Server's host type                          NET_SRV -                           
Server's versus user's data representation  SAME                                
Views interpreted in server's execution     YES                                 
File Name                                   C:\ blue