SAS Companion for the OS/390 Environment

Allocating SAS Data Libraries Internally

The LIBNAME statement or LIBNAME function allocates the operating environment data set, associates it with an engine, and assigns a libref to it. The assignment lasts for the duration of the SAS job or session unless you clear it. (See Deallocating SAS Data Libraries for information about clearing a libref.)

Advantages of Allocating SAS Data Libraries Internally

Although you can use a JCL DD statement or a TSO ALLOCATE command to allocate SAS files externally, the LIBNAME statement or LIBNAME function can do much more. Here are several reasons why it is better to allocate SAS data libraries internally with the LIBNAME statement or function:

The LIBNAME statement or function provides an easy way to do dynamic allocation in the batch environment. SAS programs that have LIBNAME statements or functions instead of external allocations can be executed either in the TSO environment or in the batch environment.
In the batch environment, the LIBNAME statement or function provides the only means of creating a new SAS data library in the hierarchical file system of UNIX System Services.
The JCL DD statement and the TSO ALLOCATE command are not portable to other operating environments. The LIBNAME statement or function is portable with minor changes to the physical-filename and options parameters.
If you use the LIBNAME statement or function, you can allocate your data library for only as long as you need it, and then deassign and deallocate it. By contrast, DDnames that are allocated externally remain allocated for the duration of the SAS session or job. (The LIBNAME CLEAR statement deassigns an externally allocated libref, but it does not deallocate the file. See Deallocating SAS Data Libraries.)
DDnames that are allocated externally cannot be reassigned later by a LIBNAME statement or LIBNAME function. You would receive an error message in the SAS log stating that the DDname is currently assigned.
By using macro statements and the LIBNAME statement or function, you can conditionally allocate files.
Using a LIBNAME statement or LIBNAME function allows you to specify an engine explicitly. Also, the following SAS engines must be specified in a LIBNAME statement or function because they are not assigned by default: XPORT, BMDP, SPSS, OSIRIS, and REMOTE.
DDnames that are allocated externally are not included in the list that is produced by the LIBNAME LIST statement nor in the SAS Explorer window until after they have been used as librefs in your SAS session. (See Listing Your Current Librefs.)

LIBNAME Statement Syntax

This section provides a brief overview of LIBNAME statement syntax. For complete information about the LIBNAME statement, see LIBNAME.

The general form of the LIBNAME statement is:

LIBNAME libref <engine > <'physical-filename'> < engine/host-options>;

LIBNAME libref <engine> <('physical-filename-1', ..., 'physical-filename-n')>

LIBNAME libref | _ALL_ CLEAR;

LIBNAME libref | _ALL_ LIST;

libref

is a logical name by which the library is referenced during your SAS session. The libref must begin with a letter and must contain 1-8 characters consisting of letters or numbers. SAS reserves some names as librefs for special system libraries. See SAS System Files for more information.

When choosing a libref, follow the rules for SAS names, but do not use underscores. To read, update, or create files that belong to a permanent SAS data library, you must include the libref as the first part of a two-level SAS member name in your program statements, as follows:(footnote 1)

libref.member

libref could also be a DDname that was specified in a JCL DD statement or in a TSO ALLOCATE command. The first time the DDname of a SAS data library is used in a SAS statement or procedure, SAS assigns it as a libref for the SAS data library.

engine

tells SAS which engine to use for accessing the library. Valid engine names for OS/390 include V8 (or its alias, BASE), V8TAPE, V7, V7TAPE, V6, V6TAPE, V5, V5TAPE, XPORT, REMOTE, BMDP, OSIRIS, and SPSS. See SAS Library Engines for more information. If you do not specify an engine, SAS uses the procedures described in How SAS Assigns an Engine When No Engine Is Specified to assign an engine for you. If the engine name that you supply does not match the actual format or attributes of the data library, then any attempt to access the library will fail.

'physical-filename'

is the OS/390 operating environment data set name or the HFS directory name of the SAS data library, enclosed in quotes. See Specifying Physical Files. You can omit this argument if you are merely specifying the engine for a previously allocated DDname. Examples:

'userid.v8.library'
'MVS:userid.v8.library'
'HFS:/u/userid/v8/library'
'/u/userid/v8/library'

('physical-filename-1', ..., 'physical-filename-n')

is used to allocate an ordered concatenation of SAS data libraries and associate that concatenation with a single LIBREF. The concatenation can include direct-access bound libraries, UNIX System Services directories, and sequential libraries, as long as all of the libraries in the concatenation can be accessed with the specified engine.

When accessing a member of a concatenated series of libraries, SAS searches through the concatenation in the order that it was specified. SAS accesses the first member that matches the specified name. SAS will not access any members with the same name that are positioned after the first occurrence in the concatenation.

engine/host options

are options that apply to the SAS data library. The host-specific options that are available depend on which engine you are using to access the data library. See SAS Library Engines for more information about SAS engines. Specify as many options as you need. Separate them with a blank space. For a complete list of available options, see LIBNAME.

LIBNAME Statement Examples

Allocating an existing SAS data library:

The following LIBNAME statement allocates the existing SAS data library LIBRARY.CATALOG.DATA and assigns the libref BOOKS to it:

libname books 'library.catalog.data';

The following LIBNAME statement allocates the existing SAS data library contained in the UNIX System Services directory /corp/dev/test1:

libname results '/corp/dev/test1';

The following LIBNAME statement allocates a concatenation of SAS data libraries:

libname concatlb ('library.catalog.data', '/corp/dev/test1');

Allocating a new SAS data library:

The following LIBNAME statement allocates the new SAS data library prefix.NEW.SASDATA. The prefix will be taken from the value of the SYSPREF= system option, as explained in Specifying Physical Files. The LIBNAME statement assigns the libref NEWLIB to the data library.

libname newlib '.new.sasdata' 
disp=(new,catlg)
   unit=3380 vol=xyz828 space=(cyl,(10,3))
   blksize=23040;

Because the operating environment data set did not previously exist, appropriate values are specified for DISP=, UNIT=, and other engine/host options. The engine name is not specified explicitly, so SAS assigns the default engine to the libref. (The default engine is the engine that is specified by the SAS system option ENGINE=.) SAS uses these values to dynamically allocate the data set; then it assigns the libref to the data set.

Note: If you do not specify default values for DCB attributes when you allocate a new operating environment data set with the LIBNAME statement, the SAS System supplies default values. See Internal Allocation: V8 Engine and Internal Allocation: V8TAPE Engine for details. [cautionend]

Specifying additional options for a previously allocated SAS data set:

See Using the LIBNAME Statement or LIBNAME Function with Externally Allocated SAS Data Libraries.

Accessing SAS Data Sets Without a Libref Using Quoted References

You can access SAS data sets under OS/390 without the usual libref.member specification using any of the following alternatives:

'<MVS:><data-set-name>(member)'

<'MVS:'>member

'<HFS:><full-UNIX-path>member<.extension>'

'<HFS:><>member<.extension>'

Despite the similarity to partitioned data set (PDS) notation, the first syntax definition above refers to a member of a SAS data library, not to a PDS. The member is the name of the SAS data set.

The data-set-name could be either a direct or sequential access bound library. If the data-set-name is omitted, the parenthesis around the member name are also omitted. In this case, SAS assumes that the member is part of the WORK library or of a different default library, as specified by the USER= system option.

If the data-set-name begins with a period and if the file system is MVS, SAS adds the value of the SYSPREF= system option to the beginning of the data set name.

If a relative-UNIX-path is specified, SAS searches for the file starting in your default UNIX System Services directory.

MVS: or HFS: is required only if the value of the FILESYSTEM= system option is set to the opposing value. Use MVS: if FILESYSTEM=HFS, for example.

Examples of SAS File Access Without a Libref

The following example can be rewritten so that a LIBNAME statement is not needed.

libname test 'userid.test.saslib';
data test.one; x=1; run;
proc print data=test.one; run;

Here is the equivalent example, without the libref:

data 'userid.test.saslib(one)'; x=1; run;
proc print data='userid.test.saslib(one)'; run;

Note that the specified data set is a direct access bound library, as opposed to a partitioned data set.

Assuming that the value of the SYSPREF= system option is USERID, then the following example represents a second alternative:

data '.test.saslib(one)'; run;
proc print data='.test.saslib(one)'; run;

Files in UNIX System Services can also be specified without a libref. The following example specifies an HFS file using a relative path:

data 'saswork/two'; x=2; run;
proc print data='saswork/two'; run;
proc contents data='saswork/two'; run;

In this case, SAS generates an absolute path from the relative path by adding your default UNIX System Services directory to the start of the relative path. If your default directory is /u/userid/, then the absolute path generated by SAS would be /u/userid/saswork/two.

Note that the presence of a slash (/) in a specification always indicates an HFS file. If your specification does not contain a slash, then the value of the FILESYSTEM= system option becomes an issue and the HFS file name may require HFS: in front. The following example overrides FILESYSTEM=MVS to accesses an HFS file in your default UNIX System Services directory:

options FILESYSTEM=MVS;
data 'HFS:study03'; x=3; run;
proc print data='HFS:study03;
proc contents data='HFS:study03'; run;

The prefix HFS: is required because the specification does not contain a slash and because the value of the FILESYSTEM= system option is MVS. If FILESYSTEM=HFS, the prefix is not necessary. To avoid using HFS: and still override the value of FILESYSTEM=, use this alternative:

option FILESYSTEM=MVS;
data './study03'; x=3; run;
proc print data='./study03';
proc contents data='./study03'; run;

FOOTNOTE 1: An exception is a SAS file in the USER library. In this case, you can use a one-level name. See Directing Temporary SAS Data Sets to the USER Library for more information about the USER library.

Chapter Contents
Previous
Next
Top of Page