Previous Page

|

Next Page

Remote Library Services

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
See:	LIBNAME statement under Windows UNIX OpenVMS z/OS
See Also:	Base SAS LIBNAME Statement

---

Syntax
Arguments
Options
User ID and Password Naming Conventions
Examples
	Example 1: Client Using the Server's Libref
	Example 2: Client Assigning a Libref to a Physical Path
	Example 3: Using a Server Password to Access a Server Library
	Example 4: Specifying a Prompt for a Password to Access a Server Library
	Example 5: Specifying an Encoded Password in a LIBNAME Statement
	Example 6: Associating a User Libref with a Server Libref
	Example 7: Duplicating a Server Libref
	Example 8: Server Inheritance of User Librefs That Are Associated with Server Librefs

Syntax

LIBNAME libref <engine> <'SAS-data-library'> SERVER=server-spec <options>;

Arguments

libref

For a server, specifies the name of a library reference (predefines a library) for client access. One or more LIBNAME statements must 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.   

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.2, 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-ID | _ _port-number

specifies the identifier for the SAS/SHARE server session that runs on the computer where the SAS library is located.

server-ID

must be a valid SAS name that is 1 to 8 characters in length. For the value of server-ID, consult your server administrator.

Server naming is also affected by the operating environment and the access method that you specify for communication between a server and a client session. For example, if you use the TCP/IP communications access method, the server-ID must be a valid TCP/IP service as defined in the TCP/IP SERVICES file.

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 SERVICES file 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 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

Options

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.

Examples:

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

Requirement:	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.
Requirement:	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 Also:	For complete details about creating and using authentication domains, see the SAS Intelligence Platform: Security Administration Guide.
See Also:	SAS Management Console User's Guide 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.

Examples:

1  libname test hostname=sirlancelot server=shr1;  
2  libname test hostname='stones.unx.apex.com' server=shr1;
3  libname test server=d8433.shr1 hostname=defiant;  
4  libname test hostname=notused server=d8433.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.

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.

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

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 User ID and Password Naming Conventions.

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.

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, PW
Interaction:	If you specify PASSWORD=, do not also specify AUTHDOMAIN=.
See Also:	AUTHDOMAIN= option
See Also:	USERNAME=

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

Restriction:	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 Also:	For the client session FILELOCKWAIT= option in the LIBNAME statement, see SAS Companion for UNIX Environments and SAS Companion for the Microsoft Windows Environment.
See Also:	For the server session FILELOCKWAITMAX= system option, see SAS Companion for UNIX Environments and SAS Companion for the Microsoft Windows Environment.
See Also:	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 User ID and Password Naming Conventions.

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.

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.

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. CAUTION: Avoid using duplicated librefs. Even though duplicated librefs are valid and the resolution of duplicated librefs is logical, the practice can be confusing.
Featured In:	Associating a User Libref with a Server Libref
Featured In:	Duplicating a Server Libref
Featured In:	Server Inheritance of User Librefs That Are Associated with Server Librefs
See Also:	Methods for Predefining a Server Library

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 User ID and Password Naming Conventions.

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.

Aliases:	USERID, USER, UID
Interaction:	If you specify USERNAME=, do not also specify AUTHDOMAIN=.
See Also:	AUTHDOMAIN= option
See Also:	PASSWORD=

User ID and Password Naming Conventions

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: 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 4: Specifying a Prompt for a Password to Access a Server Library

Rather than hard-coding 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 5: 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 6: 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 7: 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.

libname glue slibref=blue server=shr1;    

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.

Example 8: 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                                                           

Previous Page

|

Next Page

|

Top of Page

Copyright © 2007 by SAS Institute Inc., Cary, NC, USA. All rights reserved.