The OPERATE Procedure

Library Management Commands

For Version 7 and later releases, multiple users can define different SAS data libraries with the same libref name. Version 7 and later release enhancements enable the server engine to differentiate among multiple user sessions that may use the same libref and to manage them appropriately.

Allocating a Library to a Server That Is Already Running

You define a SAS data library to a server that is already running by using the ALLOCATE LIBRARY command. The syntax for this command is

ALLOCATE LIBRARY libref <'SAS-data-lib'> <RENGINE=engine-name> <engine/host options>;

You may use the abbreviation ALLOC or AL in place of ALLOCATE.

You can define one SAS data library in each ALLOCATE LIBRARY command. The following arguments and options may be specified in the ALLOCATE LIBRARY command:

libref

is used by the server to refer to the SAS data library that is specified in the SAS-data-lib argument.

'SAS-data-lib'

is the physical name of the SAS data library that is being defined to the server. The name is host-specific and must be enclosed in either single or double quotes. See Specifying a Host-Specific SAS Data Library for host-specific examples.

RENGINE=engine-name

specifies the engine to be used to process the SAS data library in the server's SAS execution. Specify this option only to override the SAS default for a library in the server's execution or to reduce search time while the server determines which engine to use to access a particular SAS library. Ordinarily, this option should not be specified because the server determines which engine to use to process the data library.

engine/host-options

are options that apply to the SAS data library. You can specify any option that is valid in the LIBNAME statement for a particular operating system and engine. One or more options in the form keyword=value may be specified. You can specify as many options as you need. 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. See the SAS documentation for your operating environment for a complete list of the options that are available for your operating environment and engine.

Displaying Information about a Library

You display information about one or more libraries by using the DISPLAY LIBRARY command. The syntax for this command is

DISPLAY LIBRARY libid-1<. . . libid-n>;

DISPLAY LIBRARY _ALL_ ;

You may use the abbreviation DISP or D in place of DISPLAY.

This command displays 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.

The DISPLAY LIBRARY command reports summary information for a server library that is defined by a host-specific external method 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 Pre-Defining SAS Data Libraries to the Server.

The libid argument is either a libref for a pre-defined server library or a physical name for a server library. If the _ALL_ argument is specified, the DISPLAY LIBRARY command provides summary information about each server library that is currently defined to the server.

For example, the following

proc operate serverid=share1;
   display library _all_;

produces a table such as this:

                            NUMBER
LIBREF          STATUS      OF USERS  LIBRARY NAME
------------------------------------------------------
DATALIB        QUIESCED       1       SAS-data-lib
POINT          ACTIVE         6       SAS-data-lib
POINTS         ACTIVE         4       SAS-data-lib
MAIN           STOPPED        0       SAS-data-lib
MAPS           INACTIVE       0       SAS-data-lib

If you specify one or more libids instead of _ALL_, the DISPLAY LIBRARY command displays summary information that is followed by detailed information for each libref that is active or quiesced. For example, the following

display library 'SAS-data-lib';

produces information such as this:

                        NUMBER
LIBREF      STATUS      OF USERS    LIBRARY NAME
------------------------------------------------------
POINTS      ACTIVE         4        SAS-data-lib

These users are accessing library 'SAS-data-lib ':

USER              USER LIBREF
-----------------------------
JOHN(1)           SPACE
MARY(2)           ROW
IAN(5)            FEES
NORMAN(11)        JOBS

These data sets in library 'SAS-data-lib' are active:

MEMBER   TYPE     STATUS   USER    OPEN MODE   USER
                                             LIBREF
---------------------------------------------------
USAGE    DATA     ACTIVE   JOHN(1)  UPDATE    SPACE
USAGE    DATA     ACTIVE   MARY(2)  INPUT     ROW
PROD     DATA     ACTIVE   IAN(5)   INPUT     FEES
MODULE   CATALOG  ACTIVE   JOHN(1)  OUTPUT    SPACE

The column LIBREF (in the first of the three screens) contains the server libref for a Version 7 or Version 8 server. The server libref is the name a server administrator assigns to the library by using one of the following methods:

a LIBNAME statement specified before the PROC SERVER statement
an ALLOCATE LIBNAME command in a PROC OPERATE statement
a host-dependent external allocation.

A library that is not defined using one of these methods does not have a server libref. Therefore, admininistrative commands that subsequently refer to that library must use the host-specific library name instead of, for example, a UNIX pathname. However, a Version 6 server always reports a server-defined libref that is valid for references to libraries in subsequent commands.

The column USER LIBREF (in the final screen) contains the libref that is specified by the user in the LIBNAME statement. The user's libref is provided only as an aid for communicating with the user, if necessary.

The member 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.

Freeing a Library

You free (or release) one or more server-defined libraries by using either:

an ALLOCATE LIBRARY command
a LIBNAME statement that is specified before the PROC SERVER statement in the SAS program that created the SAS server.

The syntax for the FREE LIBRARY command is

FREE LIBRARY libid-1 <. . . libid-n>;

FREE LIBRARY _ALL_;

You may use the abbreviation FR in place of FREE.

The status of the library at the time that the FREE command is issued determines whether the library is freed immediately. When the FREE LIBRARY command is issued, 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.

The libid argument is either a libref for a pre-defined server library or a physical name for a server library. The command FREE LIBRARY _ALL_ frees all SAS libraries that are defined to the SAS server by using an ALLOCATE LIBRARY command or the LIBNAME statement.

In contrast, the QUIESCE LIBRARY and STOP LIBRARY commands curtail the use of an active library. 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. See descriptions of these commands elsewhere in this section.

Quiescing a Library

You quiesce a library with the QUIESCE LIBRARY command to gradually terminate access to a library by denying new requests to use the library. That is, you use the command to move the library from an active status to a stopped status. The syntax for the QUIESCE LIBRARY command is

QUIESCE LIBRARY libid-1 < . . . libid-n>;

QUIESCE LIBRARY _ALL_;

You may use the abbreviation QUI or Q in place of QUIESCE.

This command quiesces one or more of the libraries that are defined to the current server. It immediately stops libraries that do not currently have members open.

The libid argument is either a libref for a pre-defined server library or a physical name for a server library. The _ALL_ argument quiesces all the libraries that are defined to the server.

When a library is quiesced, users who are currently executing DATA or PROC steps are allowed to complete those steps. When a step finishes executing, the user cannot invoke another step to re-open the member that was closed in the previous step or to open another member in the quiesced library. When the user is closed out of all members, the server library is released.

If a user attempts to access a quiesced library by using a LIBNAME statement, the attempt fails.

After all users are released from a quiesced library, the library is stopped. If the library is user defined, after all users are released, the library is stopped and is no longer defined to the server.

Specifying a physical name for a library prevents the library from being accessed even though it is not defined to the server when the QUIESCE LIBRARY command executes.

Re-Starting a Library

You start a library by using the START LIBRARY command to re-start 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 previous STOP LIBRARY or a QUIESCE LIBRARY command. The syntax for the START LIBRARY command is

START LIBRARY libid-1 < . . . libid-n>;

START LIBRARY _ALL_;

You may use the abbreviation ST in place of START.

The libid argument is either a libref for a pre-defined server library or a physical name for a server library. Specifying the _ALL_ argument re-starts all server libraries that are quiesced or stopped.

If a library that was defined by a user has been stopped and is then re-started with the START LIBRARY command, the library becomes unknown to the server.

Stopping a Library

You stop a library by using the STOP LIBRARY command to immediately terminate access to a library. The syntax for the STOP LIBRARY command is

STOP LIBRARY libid-1 < . . . libid-n>;

STOP LIBRARY _ALL_;

This command immediately terminates all user access to one or more server libraries and brings the libraries to a stopped status. Subsequent attempts to access a stopped library by using a LIBNAME statement are denied.

The libid argument is either a libref for a pre-defined server library or a physical name for a server library. If the _ALL_ argument is specified, the server stops all libraries that are defined to the server.

If users are currently reading from and writing to members in the specified library, the server closes the members and releases each user's access to the library. If users are in the process of updating a data set, updates may be lost.

Specifying a physical name for a library prevents the library from being accessed, even though it is not defined to the server when the STOP LIBRARY command executes.

Specifying a Host-Specific SAS Data Library

Throughout this section are examples of library commands that contain the SAS-data-library argument, which is specified according to host type. In the library command examples, for each instance of the SAS-data-library argument, see the following list of host-specific examples:

CMS: 'STATS AREA2'
OpenVMS: 'DISK1:[AREA2.WEATHER.STATS]'
OS/2: 'G:\AREA2\WEATHER\STATS'
OS/390: 'AREA2.WEATHER.STATS'
UNIX: '/area2/weather/stats'
Windows: 'G:\AREA2\WEATHER\STATS'

Chapter Contents
Previous
Next
Top of Page