The OPERATE Procedure

Library Management Commands

Overview of Library Management Commands

Beginning with SAS 8, multiple users can define different SAS libraries with the same libref name. Enhancements to SAS enable the server engine to differentiate among multiple user sessions that might use the same libref and to manage them appropriately.

Defining a Library to a Server That Is Running

You use the ALLOCATE LIBRARY command to define a SAS library to a server that is already running. Each library that you define requires a separate ALLOCATE LIBRARY command. Here is the syntax for this command:
ALLOCATE LIBRARY libref <'SAS-data-lib'> <RENGINE=engine-name
>
<engine/environment options>;
libref
identifies the SAS library that is specified in the 'SAS-lib' argument.
'SAS-lib'
specifies the physical name of the SAS library that is being defined to the server. This name is specific to the operating environment and must be enclosed in single or double quotation marks. See Specifying a SAS Library for examples by operating environment.
RENGINE=engine-name
specifies the engine to be used to process the SAS library in the server's SAS execution. Usually, this option is not used because the server determines which engine to use to process the data library. Specify this option only if you want to override the SAS default or to reduce the search time that is required by the server to determine which engine to use to access a specific SAS library.
engine/environment options
are options that apply to the SAS library. You can specify any option that is valid in the LIBNAME statement for a specific operating environment and engine. You can specify one or as many options as you need by using the form keyword=value. Use a blank space to separate options. This argument is not required.
These options are effective in the server SAS session, not in the user SAS session. For a complete list of options that are available for your operating environment and engine, see the SAS documentation for your operating environment.
Alias ALLOC, AL

Displaying Information about a Library

You use the DISPLAY LIBRARY command to display information about one or more server libraries that are defined to the current server. The information includes the server libref, the physical name of the data library, its status, and the number of users that are accessing it. This information for a server library that is defined by an operating environment-specific external method is reported only after the library becomes active. A library becomes active after the user issues a LIBNAME statement to access a server library. For information about methods to define libraries to the server, see Predefining SAS Libraries to the Server. Here is the syntax for this command:
DISPLAY LIBRARY libid-1<...libid-n>;
DISPLAY LIBRARY _ALL_ ;
libid
specifies either a libref for a predefined server library or a physical name for a server library. Detailed information is displayed for the specified libid. For example, this command produces detailed information, as follows:
display library 'SAS-lib';
USER              USER LIBREF
----------------------------- 
IAN(5)            FEES
The column USER LIBREF contains the libref that is specified by the user in the LIBNAME statement. The user's libref is provided only to help communicate with the user, if necessary.
The following data set in library 'SAS-lib' is active:
MEMBER   TYPE     STATUS   USER    OPEN MODE   USER
                                             LIBREF
---------------------------------------------------
PROD     DATA     ACTIVE   IAN(5)   INPUT     FEES 
The column STATUS is always ACTIVE. The column OPEN MODE indicates whether the user is currently executing a SAS program step to read, update, or create the member.
_ALL_
provides summary information about each server library that is currently defined to the server. For example, this command produces this summary table, as follows:
proc operate serverid=share1;
    display library _all_;


                             NUMBER
 LIBREF          STATUS      OF USERS  LIBRARY NAME
------------------------------------------------------
DATALIB        QUIESCED       1       SAS-lib
POINT          ACTIVE         6       SAS-lib
POINTS         ACTIVE         4       SAS-lib
MAIN           STOPPED        0       SAS-lib
MAPS           INACTIVE       0       SAS-lib
The column LIBREF in the preceding example contains the server libref for a SAS server. The server libref is the name that a server administrator assigns to the library by using one of the following:
  • a LIBNAME statement specified before the PROC SERVER statement
  • an ALLOCATE LIBRARY command in a PROC OPERATE statement
  • an operating environment-dependent external allocation
A library that is not defined by using one of the preceding methods does not have a server libref. Therefore, administrative commands that subsequently refer to that library must use a library name that is specific to the operating environment, such as a UNIX pathname.
Alias DISP LIBRARY, D LIBRARY

Freeing a Library

You use the FREE LIBRARY command to free (or release) one or more server-defined libraries. When you issue the FREE LIBRARY command, a library that is not in use is freed immediately; a library that is in use is freed after it is no longer in use. Here is the syntax for this command:
FREE LIBRARY libid-1 <...libid-n>;
FREE LIBRARY _ALL_;
libid
specifies a libref for a predefined server library or a physical name for a server library.
_ALL_
frees all SAS libraries that were defined to the SAS/SHARE server by using an ALLOCATE LIBRARY command or the LIBNAME statement.
Note: To bring a library to a stopped status gradually, issue the QUIESCE LIBRARY command. To bring the library to a stopped status immediately, issue the STOP LIBRARY command. Descriptions of these commands are given later in this section.
Alias FR LIBRARY

Quiescing a Library

You use the QUIESCE LIBRARY command to move a library that is defined to the current server from an active status to a stopped status. This command gradually terminates access to a library by denying new requests to use the library. It immediately stops libraries that do not currently have members open. If the library is user-defined, after all users are released, the library is stopped and is no longer defined to the server. Here is the syntax for the QUIESCE LIBRARY command:
QUIESCE LIBRARY libid-1 <...libid-n>;
QUIESCE LIBRARY _ALL_;
libid
specifies a libref for a predefined server library or a physical name for a server library.
_ALL_
quiesces all the libraries that are defined to the server.
Alias QUI LIBRARY, Q LIBRARY

Restarting a Library

You use the START LIBRARY command to restart one or more server libraries that have been stopped or quiesced. Because server libraries are available by default, this command is necessary to undo the effect of a STOP LIBRARY or a QUIESCE LIBRARY command. Here is the syntax for this command:
START LIBRARY libid-1 <...libid-n>;
START LIBRARY _ALL_;
libid
specifies a libref for a predefined server library or a physical name for a server library.
_ALL_
restarts all server libraries that are quiesced or stopped.
Alias ST LIBRARY
If a library that was user-defined is stopped and then restarted with the START LIBRARY command, the library is no longer defined to the server.

Stopping a Library

You use the STOP LIBRARY command to immediately terminate user access to one or more server libraries and bring the libraries to a stopped status. Here is the syntax for this command:
STOP LIBRARY libid-1 <...libid-n>;
STOP LIBRARY _ALL_;
libid
specifies a libref for a predefined server library or a physical name for a server library.
_ALL_
stops all libraries that are defined to the server.
If users are in the process of updating a data set, updates might be lost. Subsequent attempts to access a stopped library are denied.

Specifying a SAS Library

The SAS-library argument is specified according to operating environment. For SAS-library in the library management command examples throughout this section, see the following list of examples for specific operating environments:
z/OS Specifics: 'DISK1:[AREA2.WEATHER.STATS]'
UNIX Specifics: '/area2/weather/stats'
Windows Specifics: 'G:\AREA2\WEATHER\STATS'