Assigning Libraries

Overview of Assigning Libraries

In Connecting to Common Data Sources, you learned how to register libraries in metadata and assigned the libraries to SAS servers. These libraries represented such things as the set of SAS data sets in a directory or the set of tables in a database schema. This chapter explains what assigning a library accomplishes and how to assign a library to SAS servers. By assigning a library to a SAS server, you are identifying the server that can access the libraries, controlling how the SAS server accesses the library, and making the library visible to users of the SAS server.

Assigning a library means letting a SAS session know that a libref--a shortcut name--is associated with the information that the SAS session needs to access a data library. For example, if you were writing a SAS program that needed to access a library of SAS data sets, your program might include the following statement:

LIBNAME ORGOLD BASE 'C:\SAS\SASConfig\Lev1\SASApp\Data\orgold'

In this case, the libref ORGOLD tells the SAS session that it should access data sets in the directory C:\SAS\SASConfig\Lev1\SASApp\Data\orgold using the Base SAS data-access engine.

SAS Intelligence Platform clients such as SAS Data Integration Studio, SAS OLAP Cube Studio, and SAS Information Map Studio generate SAS code that uses librefs. Before this code can execute, the corresponding library must be assigned, and the server that executes the code must know about that assignment.

Pre-assigning Libraries

There are two ways in which a server can find out about a library reference. One way is for you, as the administrator, to configure the environment so that the server finds out about the libref at server startup. This approach is referred to as pre-assigning the library, because the libref is established before any code that uses that libref is submitted. The other way is to let the client application define the libref for a server when it generates code for submission to that server.

Deciding whether to pre-assign a library or not has important consequences. One factor to keep in mind is that pre-assigning an excessive number of libraries can slow the execution of SAS jobs for all users. Other factors are described in Data-Access Engines and the Metadata Engine. SAS clients and stored processes can access a library using one of two engines:

the engine specified in the library's metadata. This is the Base SAS engine for libraries of SAS data sets, the ORACLE engine for Oracle libraries, and so forth.
the Metadata LIBNAME Engine.

Which engine you use affects security and determines what operations are possible.

Note: If you are defining a pre-assigned DBMS library, do not use the Pre-Assigned Library resource template. Register the library using the appropriate DBMS library template. Specify that the library is pre-assigned using the Advanced Options dialog box in the New Library wizard or the library Properties window. [cautionend]

If you pre-assign libraries, you control which engine is used to access the data. If you do not pre-assign a library, the client that needs to access that library decides which engine to use, and different clients use different strategies. For example, SAS Data Integration Studio and SAS OLAP Cube Studio always use the engine stored in the library's metadata, while SAS Enterprise Guide can use either the metadata engine or its native engine. For more information, see "Managing Libraries" in the chapter "Managing Metadata Objects" in SAS Management Console User's Guide.

Having the server process assign libraries upon start-up based on information in the metadata results in library assignments that are identical and guaranteed across all SAS client applications and servers. Some environments where this approach to assigning libraries is desirable include the following:

environments where users are executing stored processes, and you do not want programmers having to manage library assignments in their code or in autoexec files.
environments where the DATA Step Batch Server is used to execute jobs created by SAS Data Integration Studio, and library assignments for these jobs should be identical to assignments used when the process was created.
environments where SAS Enterprise Guide or SAS Add-In for Microsoft Office users will be running tasks that need to create tables in the library that is registered in metadata. When you register a client-assigned library (a library that is not pre-assigned), SAS Enterprise Guide and SAS Add-In for Microsoft Office assign the library to use the metadata engine by default. Metadata engine libraries do not update metadata after changes to the underlying data source. Metadata can be updated to reflect changes to the underlying data source with PROC METALIB or with the register tables function of SAS Management Console.

When libraries are assigned by the client application, each application can assign the library in a way that is most suitable for its intended user base, and library connections are established only if needed. When libraries are assigned by the server, each library is available to all back-end server processes and is allocated exactly the same way for all client applications. A mixture of some server-assigned and some client application-assigned libraries will most likely be required to meet the needs of all the users in your environment.

Data-Access Engines and the Metadata Engine

As mentioned previously, when you access the data in a data library, you can use the data-access engine stored in the metadata definition of the library, or you can use the metadata engine. As shown in the following figure, the metadata engine invokes the Base SAS engine stored in the metadata.

Metadata Engine Invocation of the Base SAS Engine

[Metadata Engine Invocation of the Base SAS Engine]

One of the key enhancements made in SAS®9 has been the introduction of the SAS Open Metadata Architecture authorization facility. This authorization facility gives you, the administrator, the ability to control which users can access which metadata objects, such as SASLibrary, PhysicalTable, and LogicalServer. You manage their access to metadata by setting ReadMetadata and WriteMetadata permissions on the object or on the repository.

As depicted in the previous figure, when SAS users expand a library that they have ReadMetadata access to and that has been assigned to use the metadata engine, the engine first sends a request to the SAS Metadata Server asking for the users' metadata permissions on the tables in the library. A list of tables for which the users have at least ReadMetadata access will be returned and presented to them for selection. If they then attempt to perform some action against one of those tables, such as opening it, the metadata engine sends a query to the metadata server for the users' metadata permission on the table. If the users or the group to which they belong have at least Read access to the table, the metadata engine will call upon the engine specified in the metadata to handle the request, and the table will be opened into the client application for reading.

In contrast, when client applications access a library that does not use the metadata engine, they first contact the metadata server and request access to a metadata object as the user. The metadata server then queries the SAS authorization facility to determine whether users have ReadMetadata, CheckInMetadata, or WriteMetadata permission to the object. These metadata-based permissions are the only permissions checked by the metadata server. Users attempting to access a table in a SAS metadata-based library that is pre-assigned by the server will be successful if they have ReadMetadata access to the library and, in the case of SAS Data Integration Studio, SAS OLAP Cube Studio, and SAS Information Map Studio, ReadMetadata access to the table. Notice that when the library does not use the metadata engine, the data-level authorizations of Read, Write, Create, and Delete are never checked.

If you want to use the SAS authorization facility to control Read, Write, Create, and Delete permissions, then you need to assign the server-side library to use the metadata engine in an autoexec file. When used with its default options, the metadata engine queries the metadata server for these metadata-based permissions. The SAS authorization facility must be queried for data-level permissions. When libraries are defined in an autoexec file through a LIBNAME statement, they are always pre-assigned.

The general form of a LIBNAME statement for the metadata engine is as follows:

LIBNAME libref META LIBID=id|LIBURI=URI-format|LIBRARY=name 
   <connection-options><engine-options>;

Therefore, a META LIBNAME statement for the Orion Gold Customers library that is registered in metadata would look something like the following:

LIBNAME ORGOLD META library="Orion Gold Customers";

This is the minimum information that you need to supply in the LIBNAME statement itself. However, this statement works only if the META* options that contain the information necessary to connect to the metadata server have already been specified. These options, METASERVER, METAPORT, METAREPOSITORY, and METAPROTOCOL, are configured in the sasv9.cfg file already if you used the SAS Deployment Wizard to set up your environment.

Having data requests flow through the metadata engine before they reach the engine that actually fulfills the request provides an important capability: the metadata engine enforces the data-level authorizations that are available in the SAS Authorization Manager. These include the Read, Write, Create, and Delete permissions. The other data-access engines ignore these permissions.

At the same time, using the metadata engine takes away some capabilities. Most important, the metadata engine does not automatically create, update, or delete metadata when changes are made to the underlying data source.

Top of Page