Previous Page | Next Page

Using SAS Libraries

Assigning SAS Libraries

Overview of Assigning SAS Libraries

To use a particular SAS library within a SAS program, the library must be identified to SAS. This process, termed assigning a library, involves the following steps:

Under z/OS, you can assign a new or existing SAS library in the following ways:

internally (within a SAS session)

using a LIBNAME statement, LIBNAME function, SAS Explorer New Library Assignment dialog box, or a reference that is explicitly assigned to members using quoted name syntax (see Accessing SAS Data Sets without a Libref Using Quoted References). See Assigning SAS Libraries Internally for more information.

externally

using a JCL DD statement or a TSO ALLOCATE command. See Assigning SAS Libraries Externally for more information.

In addition to describing how to assign a SAS library internally and externally, this section also discusses the following topics:

Allocating the Library Data Set

Assigning a direct or sequential access bound library or a DIV library involves allocating the z/OS data set in which the library resides. This z/OS process includes the following actions:

You can allocate the z/OS data set external to SAS using z/OS facilities such as JCL or the TSO ALLOCATE command. In most cases, SAS uses the external allocation to process the library. SAS always uses the external allocation if the ddname of the allocation is specified as the libref. However, if SAS does not find an external allocation of the library data set, it dynamically allocates the library data set when assigning a library internally. When this dynamic allocation is necessary, SAS allocates a library with a disposition status of OLD, unless a different status has been specified. The ddname used for this allocation is the same as the libref unless the libref is not a valid ddname or is a ddname that matches the libref that is already allocated. In those cases, SAS must let the operating system generate a unique ddname, which would be in the format SYSnnnnn.

Once SAS has allocated a library data set, it uses that allocation to process the library, regardless of how many librefs are assigned to the library and provided that the same disposition status is specified (or implied) on all the assignments. See Assigning Multiple Librefs to a Single SAS Library for more information. However, if a library is assigned with a disposition status of SHR and later, an additional assignment is made with a status of OLD, SAS will attempt to dynamically allocate the library data set a second time using a disposition status of OLD and a system-generated ddname. If successful, this second allocation is used for all subsequent processing of the library until all librefs associated with the library have been deassigned. Note that in this case SAS does not (and cannot) release exclusive access to the library even when you release the assignment that specified a status of OLD.

Assigning SAS Libraries Internally


Overview of Assigning SAS Libraries Internally

SAS provides two methods for assigning SAS libraries internally, that is, via SAS statements without relying on operating environment facilities such as JCL:


Advantages of Allocating SAS Libraries Internally

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


Accessing SAS Data Sets without a Libref Using Quoted References

As an alternative to the libref.member syntax, it is possible to refer to some SAS files directly by merely specifying the library and member name. This alternative is supported even in cases in which the library has not yet been assigned (such as via external allocation or a LIBNAME statement). SAS automatically assigns the library, if necessary, when the first reference to the library is made. The engine is determined by default according to the rules described in How SAS Assigns an Engine.

Note:   This method of identifying SAS files should be used only for SAS files that are residing in libraries that can be allocated internally via a LIBNAME statement or function and for which no LIBNAME options need to be specified. SAS determines which engine to use by following the rules described in How SAS Assigns an Engine. However, for SAS files in UFS libraries, it is possible also to specify the file extension and thus control which engine should be used. This technique is described below.  [cautionend]


Members of Direct Access and Sequential Access Bound Libraries

Members of existing direct access bound libraries and sequential access bound libraries can be identified without a libref using the syntax below:

'<z/OS-data-set-name>(member)'

For example: 

data 'user489.test.saslib(member1)'; x=1; run;
proc print data='user489.test.saslib(member1)'; run;

If the value of the SYSPREF= system option was USER489, the following equivalent syntax could have been used: 

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

Although the syntax is similar to the notation used for partitioned data set (PDS) members, a SAS library is not a PDS, and only SAS files can be accessed in this manner.


Members of UFS Libraries

Members of new or existing UFS libraries can be identified without a libref using the syntax below:

'<directory-path>'/member

If the library directory (that is, the lowest level directory in the specified path) does not exist, SAS creates it automatically, if possible.

The directory path can be fully qualified, as in the following example: 

data '/u/user905/MyProject/Member1'; x=51; run;        
proc print data='/u/user905/MyProject/Member1'; run;

A partially qualified directory path can also be specified, in which the path specified is relative to the current working directory. For example, if the current working directory is /u/user905, the example below would be equivalent to the example above: 

data 'MyProject/Member1'; x=51; run;        
proc print data='MyProject/Member1'; run;

It is not necessary to specify the SAS file extension to a member if the member type is implied by the context, and if the default engine is the desired engine. However, if you wanted to access TAPE engine files that exist in the same directory as BASE engine files, you would need to specify the extension as shown below: 

proc print data='NewProject/member1.sas7sdat'; run;

Assigning SAS Libraries Externally


Overview of Assigning SAS Libraries Externally

SAS libraries can be assigned externally by first allocating a ddname to the library via JCL or a TSO command. Assignment of the library is then completed by specifying the ddname as a libref within SAS. At that point, SAS selects an engine for the library according to the rules detailed in the section How SAS Assigns an Engine. However, if the reference to the libref is in a LIBNAME statement that explicitly specifies which engine should be used, SAS uses the rules described in Specifying an Engine for Externally Allocated SAS Libraries.

Despite the advantages of assigning SAS libraries internally, assigning SAS libraries externally also has advantages, which might be important in some cases.

Note:   

  [cautionend]

JCL DD Statement Examples


TSO ALLOCATE Command Examples


Using a ddname as a Libref

Even though a library has been allocated to a ddname externally to SAS, the assignment process is not complete until the library has been referred to within a SAS program or feature that specifies the ddname as a libref. At that point SAS completes the assignment process and adds the ddname to its table of active librefs. 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 library.

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


Specifying an Engine for Externally Allocated SAS Libraries

In most cases, SAS can identify the proper engine to use for existing libraries. However, when creating new libraries that were allocated externally, you might need to use the LIBNAME statement or LIBNAME function to override the engine that SAS would use by default. For example, suppose you used an X statement to submit the following TSO ALLOCATE command, which allocates the SAS library QUARTER1.MAILING.LIST: 

x alloc f(mail) da('quarter1.mailing.list') new
   dsorg(ps) space(10 1) cyl;

You could instruct SAS to use the V9TAPE engine for this new library with the following statement: 

libname mail tape;

This LIBNAME statement does not need to specify the name of library data set or any other options, because that information was supplied on the external allocation referenced by the ddname mail.

How SAS Assigns an Engine

In some cases, you might choose not to specify an engine name in the LIBNAME statement or LIBNAME function, or you might choose not to issue a LIBNAME statement or function for a library that was allocated externally. The following information describes how SAS determines which engine to use when you do not specify one. The engine that SAS selects depends on the type of library you are accessing. See Library Implementation Types for Base and Sequential Engines for more information about libraries.

If the library that you specify corresponds to a new or empty z/OS data set, SAS assigns the default engine specified by the ENGINE= system option unless a sequential engine must be used. Sequential engines are used for the following situations:

If a sequential engine is used, SAS assigns the engine specified by the SEQENGINE= system option. For empty UFS libraries, SAS assigns the engine specified by the ENGINE= system option.

If the library data set has already been initialized, or, for UFS, if the library directory already contains members, SAS generally assigns the engine that has been used to process the library in the past. The following list contains details about how SAS assigns engines for the different types of libraries:

direct access bound library

SAS automatically assigns the V5 engine if the library data set has the DCB characteristic DSORG=DA. Otherwise, SAS reads the library header and assigns the engine that was originally used to initialize the library.

sequential access bound library

SAS reads the first member header record and assigns the engine that was used to write the first member of the library.

UFS library

SAS examines the extension of each SAS file in the library directory, because the extension indicates the engine with which the library member was created. If all of the SAS files in the directory were created with the same engine, that engine is assigned to the library. If the SAS files were created using a mix of different engines, SAS assigns the engine specified by the ENGINE= system option.

hiperspace library

SAS automatically assigns the V9 engine without reading the library header if the library is a permanent hiperspace library, that is, a library that is backed by a VSAM linear data set. To access a V6 hiperspace library, you must use the LIBNAME statement and specify the V6 engine.

Note:   Identifying the engine with the LIBNAME statement or function saves system resources.  [cautionend]

Assigning Multiple Librefs to a Single SAS Library

You can assign more than one libref to the same SAS library.

For example, suppose that in two different programs you used different librefs for the same libraries. Later you develop a new program from parts of the two old programs, or you include two different programs with the %INCLUDE statement. In the new program, you could simply assign the two original librefs to each library and proceed.

Any assigned libref can be used to access the library with the following exception: if ACCESS=READONLY was specified or implied (by DISP=SHR) for one assignment, then that libref can be used only to read the library, even though update access is available to the library through another libref.

Listing Your Current Librefs

You can use either the LIBNAME command or a form of the LIBNAME statement to list your currently assigned librefs.

Deassigning SAS Libraries

Once a libref has been assigned to a library, it remains assigned until it is cleared by using the LIBNAME libref CLEAR statement. As noted inAssigning Multiple Librefs to a Single SAS Library, more than one libref can be assigned to a given library. A library remains assigned to SAS as long as at least one libref is currently assigned to the library. However, when the last libref assigned to a library is cleared, SAS releases the resources used to process this library. For bound libraries, the following actions are taken:

Note:   All libraries assigned during a SAS session are automatically deassigned at the end of the session.  [cautionend]

The method that you use to deallocate a SAS library depends on how the library was allocated.

Using Multivolume SAS Libraries


Overview of Multivolume SAS Libraries

A direct access bound library or sequential access bound library on disk can extend to more than one volume. The library data set might exist on multiple DASD volumes, but it is processed by SAS software as one logical entity. This capability greatly increases the storage capacity of a library. This section discusses two separate methodologies for creating and extending multivolume libraries:

Requesting Space As Needed

This approach is recommended for its simplicity, flexibility, and efficiency. With this methodology, you do not need to determine in advance the amount of storage that a library will require. SAS can request additional DASD extents (allocations of contiguous disk space) as the library needs to grow, meanwhile leaving more DASD space available for other applications. This approach allows storage management subsystem (SMS) and third-party DASD space management to automatically make the optimum decisions about volume selection, and so on.

PreAllocating Space

In some circumstances, such as when entire volumes have been set aside for use by a particular application, it is more convenient to preallocate the library data set. This approach allows more control, but it requires more effort in planning to estimate the size of the SAS data sets that will reside in the library.


General Guidelines

Here is a short summary of the main rules that govern allocation of space for SAS libraries on disk. This summary is not intended to address all points of this broad subject. For additional information, see IBM documentation as well as manuals for any third-party DASD space management software installed on z/OS at your site.

Both direct access and sequential access bound libraries reside in a data sets with the attribute DSORG=PS. On disk, these data sets can be extended to as many as 59 volumes. Each time space is requested for a library data set, the disk space is supplied in one or more chunks of contiguous space termed extents. A regular format DSORG=PS data set can have up to 16 extents per volume. Extended format DSORG=PS data sets can have as many as 123 extents per volume, but they can be used only for sequential access bound libraries.

When allocating a new library data set, you must specify the size of the initial (primary) disk space allocation as well as the size of the extent (secondary) to be obtained when the library data set needs to be enlarged. Each request to extend the size of the library data set is satisfied by a secondary extent on the current last volume until 16 extents are allocated for the data set on that volume, the volume does not contain enough free space to satisfy the request, or, for DSNTYPE=BASIC data sets, more than 64K tracks have been used on the last (or only) volume. If the space request cannot be satisfied, the system attempts to find space on the next volume, if any, that is allocated to the library data set. If no additional volumes are allocated to the data set, the system issues a system B37 abend, which SAS intercepts and reports as a library full condition.


Requesting Space As Needed

These examples show how to request space as needed for SAS direct access bound libraries.

The following LIBNAME statement allocates a temporary library of up to three volumes: 

libname tmp '&lib' unit=(sysda,3) space=(cyl,(300,100));

The following DD statement creates a direct access bound library. The unit count makes three volumes to be available for the job that creates the library. Note that there must be three available units in the system for this example to work, even if the library does not require space on all three volumes, because the system chooses the candidate volumes at allocation time. 

//WORK     DD  DSN=MY.MASTER.LIBRARY,DISP=(NEW,CATLG,DELETE),
//             UNIT=(DISK,3),SPACE=(CYL,(300,100))

To extend this library to as many as five volumes using another job, the following DD statement could be used. The secondary space allocation specified at library creation time is used to determine the size of the secondary extents added. 

//WORK     DD  DSN=MY.MASTER.LIBRARY,DISP=OLD,UNIT=(DISK,5)

If you want to extend an existing library, but only on the volumes that it already occupies, it is not necessary to specify the UNIT parameter.

As shown below, it is also possible extend an existing library (not SMS-managed) via the LIBNAME statement EXTEND option, which is equivalent to specifying UNIT=(,n), where n is one more than the current number of volumes in the existing library: 

libname payroll 'my.master.library' disp=old extend;

The following DD statement creates an SMS-managed library, which can extend to as many as four volumes. For SMS-managed libraries allocated without a specific list of volumes, the unit count specified when creating the library, specifies the volume count for the library data set. Note that the volume count can also be specified via the data class instead of the unit count. 

//TEST1    DD   DSN=MY.PROJECT.LIBRARY,DISP=(NEW,CATLG),
//         UNIT=(DISK,4),SPACE=(CYL,(200,200)),
//         STORCLAS=SASSTD,DATACLAS=SASSTD,DCB=(DSORG=PS,RECFM=FS)

The volume count represents the maximum number of volumes to which the data set can be extended in creating jobs as well as in subsequent jobs. Therefore, this library could be extended to as many as four volumes using the following DD statement: 

//TEST1    DD   DSN=MY.PROJECT.LIBRARY,DISP=OLD

The following LIBNAME statement could be used as well: 

libname project 'my.project.library';

Extending an existing SMS-managed library does not require a UNIT count, nor does it have any effect. To increase the volume count for an existing SMS-managed library, use the ADDVOL command of the IDCAMS utility.

Note:   An SMS storage class with the GUARANTEED SPACE attribute is not required as it is when you are preallocating libraries.  [cautionend]


Preallocating New Multivolume Libraries

The following examples illustrate a scenario in which several entire 3390-3 volumes have been dedicated to a single library. No secondary allocation is specified; consequently this library cannot be extended dynamically by SAS. These examples can also be adapted for libraries that use less than an entire volume.

The following JCL preallocates a three-volume 3390 library: 

//ALLOC   EXEC PGM=IEFBR14
//VOL1     DD  DSN=MY.PAYROLL.LIBRARY,DISP=(NEW,KEEP),
//             DCB=(DSORG=PS,RECFM=FS,LRECL=27648,
//             BLKSIZE=27648),UNIT=3390,
//             SPACE=(CYL,1113),VOL=SER=PR0001
//VOL2     DD  DSN=MY.PAYROLL.LIBRARY,DISP=(NEW,KEEP),
//             DCB=(DSORG=PS,RECFM=FS,LRECL=27648,
//             BLKSIZE=27648),UNIT=3390,
//             SPACE=(CYL,1113),VOL=SER=PR0002
//VOL3     DD  DSN=MY.PAYROLL.LIBRARY,DISP=(NEW,KEEP),
//             DCB=(DSORG=PS,RECFM=FS,LRECL=27648,
//             BLKSIZE=27648),UNIT=3390,
//             SPACE=(CYL,1113),VOL=SER=PR0003
//CATDD    DD  DSN=MY.PAYROLL.LIBRARY,
//             DISP=(OLD,CATLG),UNIT=3390,
//             VOL=SER=(PR0001,PR0002,PR0003)

Note that IEFBR14 is an IBM utility program that returns immediately, allowing the system to perform job step allocation or deallocation processing.

The following JCL adds a fourth volume to the library that was allocated in the previous example. Notice that you must maintain the original sequence for the volume serial numbers when recataloging the library. 

//ALLOC   EXEC PGM=IEFBR14
//UNCATDD  DD  DSN=MY.PAYROLL.LIBRARY,
//             DISP=(OLD,UNCATLG)
//NEWVOL   DD  DSN=MY.PAYROLL.LIBRARY,
//             DISP=(NEW,KEEP_,DCB=(DSORG=PS,
//             RECFM=FS,LRECL=27648,
//             BLKSIZE=27648),UNIT=3390,
//             SPACE=(CYL,1113),VOL=SER=PR0004
//CATDD    DD  DSN=MY.PAYROLL.LIBRARY,
//             DISP=(OLD,CATLG),UNIT=3390,
//             VOL=SER=(PR0001,PR0002,PR0003,
//             PR0004)

The following JCL preallocates a three-volume library in an SMS environment. Note that the SMS STORCLAS specified must allow multi-unit allocations and have the GUARANTEED SPACE attribute. Your SMS system administrator needs to set up the specified storage class for you. The SASGUAR storage class name is used only as an example. 

//ALLOC   EXEC PGM=IEFBR14
//DD1      DD  DSN=MY.PAYROLL.LIBRARY,
//             DISP=(NEW,CATLG),DCB=(DSORG=PS,
//             RECFM=FS,LRECL=27648,
//             BLKSIZE=27648),SPACE=(CYL,1113),
//             UNIT=(DISK,3),STORCLAS=SASGUAR
//

The GUARANTEED SPACE attribute causes the system to allocate the primary space amount on each volume when the library is allocated.

Allocating a Multivolume Generation Data Group

A collection of SAS libraries, including multivolume libraries, can be stored and managed as a z/OS GDG. Before creating any libraries, you must first create the GDG base, as shown in the following example: 

//         JOB ...
//* ----------------------------------------------
//* CREATE GDG BASE FOR SAS LIBRARIES
//* ----------------------------------------------
//STEP01 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
   DEFINE GDG +
   ( +
      NAME(PROD.WEEKLY.PERFSTAT) +
      LIMIT(5) +
      SCRATCH +
   )
//* ----------------------------------------------

When the GDG base exists, libraries that are members of the GDG can be created using JCL, for example: 

//         JOB ...
//* -----------------------------------------------------------
//* CREATE MULTI-VOLUME SAS LIBRARY WHICH IS MEMBER OF GDG
//* -----------------------------------------------------------
//STEP01   EXEC SAS
//NEWLIB   DD   DSN=PROD.WEEKLY.PERFSTAT(+1),DISP=(NEW,CATLG),
//         UNIT=(DISK,2),SPACE=(CYL,(50,10)),
//         DCB=PROD.WEEKLY.MODEL
//SYSIN DD *
  DATA NEWLIB.MEMB01;
  ...
//* -----------------------------------------------------------

Each execution of the job above would create an entirely new library that is a member of the GDG named PROD.WEEKLY.PERFSTAT. The DD statement parameter DCB= is required to specify a data set from which the model DCB attributes for the library are copied.

Note:   

  [cautionend]

Previous Page | Next Page | Top of Page

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