SAS Companion for the CMS Environment

Identifying SAS Data Libraries

Under other operating environments, a typical method of identifying a SAS data library (or an individual file in a SAS data library) is to first use the SAS LIBNAME statement or function within a SAS session or program to assign a libref to the data library. (See LIBNAME for complete information about using the LIBNAME statement under CMS.) The libref identifies the library and some of its characteristics to the SAS System. Thereafter, you can use the libref as a convenient way of referring to the library in your SAS programs.

However, keep in mind the following points when you identify SAS data libraries under CMS:

Under CMS, you often do not need to assign a libref to disk-format data libraries. (For sequential files on tape or on disk, a libref is always required. A libref is also required for disk-format files that are stored in an unaccessed SFS directory.) See Working with SAS Files on Disk for an explanation of how SAS locates disk-format data libraries.
Under CMS, you can also use the CMS FILEDEF command to assign a DDname to the data library. Thereafter, you can use the DDname just as you would use a libref. However, see Advantages of Using the LIBNAME Statement or Function for some important considerations. For information about the CMS FILEDEF command, see Using the CMS FILEDEF Command .
In DMS mode, which is accessible through the SAS Explorer or the LIBASSIGN command, is the "New Library" dialog for assigning librefs.

Using the LIBNAME Statement or Function

Advantages of Using the LIBNAME Statement or Function

Although you can use the CMS FILEDEF statement to assign DDnames to your SAS data libraries, there are several reasons for using the LIBNAME statement or function (and librefs) instead:

The CMS FILEDEF command is not portable to other operating environments. The LIBNAME statement or function is portable with minor changes to the physical name 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 "free" (deallocate) it. By contrast, DDnames that are allocated externally remain allocated for the duration of the SAS session or job. (The LIBNAME CLEAR statement clears an externally allocated libref, but it does not deallocate the file. See Clearing Librefs and DDnames .)
DDnames that are allocated externally cannot be reassigned later by a LIBNAME statement or function. You receive an error message in the SAS log that states that the DDname is currently assigned.
By using macro statements and the LIBNAME statement or function, you can conditionally allocate files.
You cannot assign an engine when you allocate a file externally. SAS uses the procedure described in How SAS Assigns an Engine When No Engine Is Specified to determine which engine to use. It is more efficient to specify an engine explicitly in a LIBNAME statement or function. Also, the following SAS engines must be specified in a LIBNAME statement or function because they are not assigned by default: XPORT, BMDP, SPSS, SPSSX, OSIRIS, V5TAPE, V6TAPE, V7TAPE, V8TAPE, and REMOTE.
DDnames that are allocated externally are not included in the list that is produced by the LIBNAME LIST statement or in the LIBNAME window until after they have been used as librefs in your SAS session. (See Listing Your Current Librefs .)

LIBNAME Statement Syntax

This section provides an overview of the LIBNAME statement. For complete information about the LIBNAME statement see LIBNAME.

The general form of the LIBNAME statement is

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

libref

is the logical name by which the library is referenced during your SAS session. The libref must begin with a letter and must contain one to eight characters consisting of letters or numbers.

When choosing a libref, follow the rules for SAS names, but do not use underscores. Also observe the restrictions listed in Restrictions on Librefs .

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

engine

tells SAS which engine to use for accessing the library. See SAS Library Engines for CMS for information about valid engine names. 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-name'

enclosed in quotation marks, describes the physical location of the library. The physical-name can be specified in the following ways:

'filemode': specifies the disk-mode letter or the disk-mode letter and optional filemode access number. Use this form for physical-name when you want to use a filemode other than the default. If you specify the filemode as a pair of single quotation marks ( `') or as an asterisk surrounded by single quotation marks ( `*'), SAS uses the standard CMS search order to locate an existing SAS library. If the library exists on more than one minidisk, then SAS stops searching as soon as it finds a member. Consequently, only the member on that minidisk is used. Otherwise, if the library does not exist, the assignment defaults to the first R/W accessed disk.
'filetype filemode': specifies the filetype to be used for the library and the disk-mode letter. filemode can also include a filemode access number. Use this form for physical-name when you want to use the libref as an alias for the filetype.
'filetype sfs-dir': specifies an SFS directory to be used as a SAS library. Use this form for physical-name when you want to use the libref as an alias for the filetype.
'sfs-dir': specifies an SFS directory to be used as a SAS library.
'filename filetype filemode': specifies the complete CMS fileid. Use this form for physical-name with the BMDP, OSIRIS, SPSS, and XPORT engines.
('filetype-1 <filemode-1 | SFS-directory-1>' . . .'filetype-n <filemode-n | SFS-directory-n'>): specifies a concatenation of more than one library that will be accessed by SAS in order of specification using a single fileref. See Concatenating SAS Data Libraries for more information on concatenation of SAS data libraries.
'TAPn': specifies the tape device for a sequential library. n is a hex character from 0 through F.

engine/host-options

are options that apply to the SAS data library.

Note: The libref remains valid for the duration of the SAS job or session unless you clear it. See Clearing Librefs and DDnames for information about clearing a libref. [cautionend]

Restrictions on Librefs

Under CMS, you should observe the following restrictions on librefs:

Do not use a libref that is reserved for use by the SAS System, as described in CMS Filetypes Used by SAS.
Do not use SAS as a libref; it is reserved as the filetype for files that contain SAS programming statements in noninteractive SAS programs and in the %INCLUDE statement.
Do not use as a libref a filetype that is reserved by CMS. (See the VM/ESA CMS User's Guide for a list of filetypes that are reserved by CMS.)
Do not use the filetype of an external file as the libref of a SAS file.
Librefs that begin with TAPE are reserved for SAS files that are written in the Version 5 tape format. Use a libref that begins with TAPE only for Version 5 tape format files.
Specify the SAS system option NOREPLACE to prevent existing SAS data sets from being replaced.

Using the CMS FILEDEF Command

There are several advantages to using the LIBNAME statement or function to make your SAS data libraries available to your SAS programs. (See Advantages of Using the LIBNAME Statement or Function .) However, in most cases you can also use the CMS FILEDEF command for this purpose.

Note: You cannot use the CMS FILEDEF command to assign a DDname to a SAS data library that resides on an unaccessed SFS directory. [cautionend]

If you choose to issue a CMS FILEDEF command for a SAS data library, then use the following form of the command:

FILEDEF DDname DISK dummy filemode

DDname: is the libref that you want to use for the data library.
dummy: specifies any valid character string for the filename and filetype positions in the command. You can use the same value in both positions, and SAS will substitute the correct filename and filetype. Thus, you need to issue only one FILEDEF command per libref, regardless of the number of SAS data libraries that have or will have that libref.
filemode: references the correct minidisk for the data library.

Remember, though, that if you choose to issue your own CMS FILEDEF command, you cannot subsequently issue a LIBNAME statement or function that uses the DDname that is assigned by the FILEDEF command as a libref.

Using a DDname as a Libref

After a DDname has been assigned, you can use it in a SAS job in the same way you would use a libref. For example:

proc contents data=books._all_;
run;

The first time that the DDname BOOKS is used in this manner, SAS assigns it as a libref for the SAS data library.

When a DDname is allocated externally, it is not listed by the LIBNAME LIST statement or in the LIBNAME window until after you have used it as a libref in your SAS session. (See Listing Your Current Librefs .)

FOOTNOTE 1: An exception is a SAS file in the WORK or 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