Chapter Contents
Previous
Next
LIBNAME

LIBNAME


Assigns a SAS libref and an engine to a SAS data library

Valid: anywhere
OS/390 specifics: libref, engine, physical-filename, engine/host-options

Syntax
Details
Assigning Librefs
See Also

Syntax

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;

Details

The LIBNAME statement assigns a libref to a SAS data library. The LIBNAME function provides similar functionality. See LIBNAME.

Note:   The LIBNAME statement is also used to list the attributes of a SAS data library and to clear a libref. For more information, see Listing Your Current Librefsand Deallocating SAS Data Libraries .  [cautionend]

Assigning Librefs

Assigning a libref associates a SAS data library with an engine and with engine/host options. Use the following form of the LIBNAME statement to assign a libref.

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

You can use this form to assign a libref to either a permanent SAS data library or a temporary one. The following statement allocates a temporary SAS data library, assigns the libref ABC to it, and associates it with the V6 engine: 

libname abc v6 '&mytemp' disp=new;

The physical file name for this temporary SAS data library is a specially formatted name chosen by the operating environment; it includes your user prefix and the temporary name that you specify (MYTEMP in this example).

You can use the following arguments with this form of the LIBNAME statement:

libref
is a one- to eight-character name that conforms to the rules for both SAS names and DDnames. That is, the first character must be a letter; subsequent characters can be either letters or numbers.

Note:   Unlike filerefs, librefs cannot include the national characters $, @, and #.  [cautionend]

engine
specifies which engine to use to access the SAS data library. The following engines can be specified in the LIBNAME statement under OS/390:
V8 specifies the engine for accessing Version 8 SAS files in disk format. BASE is an alias for the V8 engine.
V78TAPE specifies the engine for accessing Version 8 SAS files in sequential format, either on tape or on disk. TAPE and V8SEQ are aliases for V8TAPE.
V7 specifies the engine for accessing Version 7 SAS files in disk format.
V7TAPE specifies the engine for accessing Version 7 SAS files in sequential format, either on tape or on disk.
V6 specifies the engine for accessing Version 6 SAS files in disk format. V609, V608, V607, and are aliases for the V6 engine.
V6TAPE specifies the engine for accessing Version 6 SAS files in sequential format, either on tape or on disk. V6SEQ is an alias for V6TAPE.
V5 specifies the engine for read-only access to Version 5 SAS files on disk.
V5TAPE specifies the engine for read-only access to Version 5 SAS files in sequential format, either on tape or on disk.
XPORT specifies the engine for accessing SAS files in transport format.
BMDP specifies the engine for (read-only) access to BMDP files.
DB2 specifies the engine for accessing DB2 database tables.
ORACLE specifies the access engine to ORACLE database tables.
OSIRIS specifies the engine for (read-only) access to OSIRIS files.
REMOTE specifies the engine that SAS/CONNECT and SAS/SHARE use to access remote files.
SPSS | SPSSX specifies the engine for (read-only) access to SPSS files.

If you do not specify an engine, then SAS attempts to assign an engine according to the rules described in How SAS Assigns an Engine When No Engine Is Specified . See the discussion of engines in SAS Language Reference: Dictionary for more information about the library engines.

'physical-filename'
specifies a physical file, which can be a standard OS/390 data set or an HFS directory in UNIX System Services, using the following syntax:

See Specifying Physical Files for more information about partially qualified data set names.

For some engines, the physical-filename may begin with a single or double ampersand (& or &&), followed by a one- to eight-character value. If the physical-filename begins with &, a temporary physical file is allocated. Such engines are those that can cause a physical file to be created by way of a LIBNAME statement and include the V8, V8TAPE, V7, V7TAPE, V6, and V6TAPE engines. The first character after the & must be alphabetic; others may be alphanumeric or the national characters $, #, or @.

The physical-filename argument is optional. If you specify it, it must follow the engine name. If you did not specify an engine, then it must follow the libref.

engine/host-options
are host-specific options that apply to the SAS data library. Each option is identified by a keyword, and most keywords assign a specific value to that option. You may specify one or more of these options using the following forms:

keyword=value | keyword

When you specify more than one option, use a blank space to separate each option. The specific options that are available depend on which engine you have specified. See Engine/Host Options for the V8 Engine for details about specific engine/host-options, and about the values that you specify with the various engines.

The complete list of options is presented here:

DATACLAS=data-class-name
specifies the data class for an SMS-managed data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The data class is predefined and controls the DCB attributes for a data set.

The implementation of the DATACLAS= option is compatible with the SMS DATACLAS= JCL parameter. For complete information about this parameter, see OS/390 JCL Reference by IBM. Ask your system administrator which data-class names are used for SAS data libraries at your site.

DISP= status | (< status >,< normal-termination-disp>,< abnormal-termination-disp>)
specifies the status of the data set at the beginning and ending of a job, as well as what to do if the job step terminates abnormally. If you are specifying only status, you can omit the parentheses.

status
specifies the status of the physical file at the beginning of a job. Valid values are
NEW a new data set is to be created.
OLD the data set exists and is not to be shared.
SHR the data set exists and may be shared.

The default for status is OLD.

normal-termination-disp
specifies disposition for the data set if the job using the data set terminates normally. If you omit the normal termination disposition value, the default is CATLG for new data sets or KEEP for existing data sets. Valid values are
DELETE the data set is deleted at the end of the step.
KEEP the data set is to be kept.
CATLG the system should place an entry in the system catalog or user catalog.
UNCATLG the system is to delete the entry in the system catalog or user catalog.

abnormal-termination-disp
specifies what to do if the job step terminates abnormally. The default is to take the action that is specified or implied by normal-termination-disp. Valid values are
DELETE the data set is deleted at the end of the step.
KEEP the data set is to be kept.
CATLG the system should place an entry in the system catalog or user catalog.
UNCATLG the system is to delete the entry in the system catalog or user catalog.

DLTRUNCHK | NODLTRUNCHK
overrides the system option DLTRUNCHK for this LIBNAME statement assignment only.

EXTEND
specifies that when SAS allocates this library, it will allocate it with a volume count that is one greater than the current number of DASD volumes on which the library resides. With this option, a single-volume library can be converted to a multivolume library, and existing multivolume libraries can be extended to another volume.

HFS
specifies that the library is in the hierarchical file system of UNIX System Services. It is unnecessary to specify this option if the 'physical-filename' on the LIBNAME statement contains a "/" or if the 'HFS:data-set-name' syntax is used.

HIPERSPACE
specifies that the SAS data library be placed in a hiperspace rather than on disk. HIP is an alias for the HIPERSPACE option. For more information about this option, see Optimizing I/O

LABEL=(subparameter-list)
enables you to specify for a tape or direct access data set the type and contents of the label of the tape or disk data set, as well as other information such as the retention period or expiration date for the data set.

The LABEL= option is identical to the JCL LABEL= parameter. Here is a simple example: 

label=(3,SL,,,EXPDT=1999/123)

This label specification indicates the data set sequence number is 3, that it uses standard labels, and that it expires on the 123rd day of 1999. See OS/390 JCL Reference by IBM for complete information about how to use the LABEL= option, including which subparameters you can specify in subparameter-list.

LIKE='physical-filename'
when allocating a new library, tells SAS to set the DCB attributes of the new library to the same values as those in the specified data set.

LINEAR
specifies that this new library should be allocated as a VSAM linear data set. This will then be a permanent library, which uses the HIPERSPACE access method by way of the DIV (Data In Virtual) facility.

MGMTCLAS=management-class-name
specifies a management class for an SMS data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The management class is predefined and controls how your data set is managed, such as how often it is backed up and how it is migrated.

The implementation of the MGMTCLAS= option is compatible with the SMS MGMTCLAS= JCL parameter. For complete information about this parameter, see OS/390 JCL Reference by IBM. Ask your system administrator which management class names are used at your site.

NOPROMPT
for this assignment, specifies that even if the system option FILEPROMPT is in effect and if the library does not already exist, that no requestor window is displayed to ask if you want to create the library.

SPACE=(unit,(primary<,secondary>), <RLSE>,<type>, <ROUND>)
specifies how much disk space to provide for a data set that is being created. The space can be requested in terms of tracks, cylinders, or blocks, as follows:

unit
may be any of the following:
TRK specifies that the space is to be allocated in tracks.
CYL specifies that the space is to be allocated in cylinders.
blklen specifies that the space is to be allocated in blocks whose block length is blklen bytes. The system computes how many tracks are allocated.

primary
specifies how many tracks, cylinders, or blocks to allocate.

secondary
specifies how many additional tracks, cylinders, or blocks to allocate if more space is needed. The system does not allocate additional space until it is needed.

RLSE
causes unused space that was allocated to an output data set to be released when the data set is closed. Unused space is released only if the data set is opened for output and if the last operation was a write operation.

type
can be any of the following:
CONTIG means that the space to be allocated must be contiguous.
MXIG means that the maximum contiguous space is required.
ALX means that different areas of contiguous space are needed.

ROUND
specifies that the allocated space must be equal to an integral number of cylinders when the unit specified was a block length. If unit was specified as TRK or CYL, the system ignores ROUND.

If SPACE is not defined, its values are taken from the SAS system options FILEUNIT=, FILESPPRI=, and FILESPSEC=, in the following form: 

SPACE=(FILEUNIT,(FILESPPRI,FILESPSEC))

The default specifications are as follows: 

SPACE=(CYL,(1,1))

STORCLAS=storage-class-name
specifies a storage class for an SMS data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The storage class is predefined and controls which device your SMS data set is stored on, such as disk or tape.

The implementation of the STORCLAS= option is compatible with the SMS STORCLAS= JCL parameter. For full details on this parameter, refer to OS/390 JCL Reference by IBM. Ask your system administrator which storage class names are used at your site.

UNIT=value | (value, n)
where n is the number of units for multivolume data libraries; can name one of several different devices. Some likely values are DISK and SYSDA. Additional valid values may be defined at your site.

VOLSER=value | (value-1, ..., value-n)
specifies up to 5 disk volume serial numbers. If VOLSER= is not specified, its value is taken from the SAS system option FILEVOL= (see FILEVOL= for details).

WAIT=n
specifies how long the SAS System waits for a data set that is held by another job or user before the LIBNAME statement fails. The value n specifies a length of time in clock minutes. If the data set becomes free before n minutes expire, then the LIBNAME statement is processed as usual. The dynamic allocation request is retried internally every 15 seconds.

When you use the WAIT= option, you must also specify the engine name in the LIBNAME statement if you are accessing uncataloged data libraries or libraries that do not reside on disk. Otherwise, you do not have to specify the engine name.

For batch jobs using WAIT=, also specify the FILEMSGS option (see FILEMSGS), which causes a message to be written to the system log for each allocation attempt, thus allowing system operators to determine why the job is waiting.

See Also


Chapter Contents
Previous
Next
Top of Page

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