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 . [cautend]

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 #. [cautend]

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:

V7	specifies the engine for accessing Version 7 SAS files in disk format. BASE is an alias for the V7 engine.
V7TAPE	specifies the engine for accessing Version 7 SAS files in sequential format, either on tape or on disk. TAPE and V7SEQ are aliases for V7TAPE.
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 an physical file, which can be a standard OS/390 data set or an HFS directory in UNIX System Services, using the following syntax:

a fully qualified data set name. For example:
```
'myid.raw.datax'
```
an HFS directory in UNIX System Services:
```
'/u/userid/mylib'
```
or
```
'HFS:mylib'
```
The HFS prefix needed when the directory does not contain a "/" to indicate an HFS file. This information can also be provided by default by setting the FILESYSTEM= system option. For information on the FILESYSTEM= system option, see FILESYSTEM=.

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 an physical file to be created by way of a LIBNAME statement and include the 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 V7 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=1998/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 1998. 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.

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