Chapter Contents


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:

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_ LIST;

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

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.

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:

('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 '';

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 ('', '/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' 
   unit=3380 vol=xyz828 space=(cyl,(10,3))

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:


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; x=1; run;
proc print; 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:

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:
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. [arrow]

Chapter Contents



Top of Page

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