Assigning SAS Libraries :: SAS(R) 9.3 Companion for z/OS, Second Edition

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:

identifying the library to SAS. In most cases, this identification is accomplished by specifying a logical name, or libref, by which such items as SAS statements and procedures can refer to the library.
determining which engine is used to process the library. In some cases, you must specify the engine when you assign the library. In most cases, however, SAS can select the appropriate engine automatically.
identifying and reserving the z/OS resources required to process the library, which is described in detail in Allocating the Library Data Set.

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. For more information, see Accessing SAS Data Sets without a Libref Using Quoted References and Assigning SAS Libraries Internally .

externally

using a JCL DD statement or a TSO ALLOCATE command. For more information, see Assigning SAS Libraries Externally.

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:

Identifying a logical name (ddname) by which the data set is accessed by the operating system.
Creating the data set and reserving an initial allocation of disk space if it is a new data set on disk.
Identifying, either directly or indirectly, the volumes on which the data set will reside for a new or existing data set.
Establishing a disposition status (also known as a data set enqueue) to prevent other jobs or users on the z/OS system from accessing the data set in a manner inconsistent with your SAS job.
- Specifying a disposition status of OLD, NEW, or MOD requests exclusive access to the library data set. The allocation does not succeed unless no other jobs or users have the library allocated, and z/OS will prevent any other jobs or users from allocating the library until you deallocate the library. In order to update any member of a library, you must request exclusive access to the library data set.
- Specifying a disposition status of SHR requests shared access to the library. The allocation will succeed provided that no other job or users have the library allocated for exclusive access, and z/OS will prevent other jobs or users from allocating the library for exclusive access until you deallocate the library. However, other SHR allocations can exist concurrent with yours.

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.

After 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. For more information, see Assigning Multiple Librefs to a Single SAS Library. 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:

The LIBNAME statement or LIBNAME function can be used to assign a SAS library.
In the following example, the library USER934.MYLIB.SASLIB has been assigned to the libref MYLIB. The z/OS allocation parameter DISP=SHR requests shared access to the library data set. Since no engine was specified, SAS examines the format of the library data set to determine which engine to use.
```
libname mylib 'user934.mylib.saslib' disp=shr;
```
In the DATA step below, the libref MYLIB is used to refer to the library. MYLIB can be used for the remainder of the SAS session until it is cleared by a LIBNAME CLEAR statement.
```
data mylib.member1;
...
run;
```
Except for a few special cases, the LIBNAME statement or function can perform all of the assignment functions that are required for SAS libraries. The LIBNAME statement or function supports the options that are necessary to create a new direct or sequential access bound library, and it also provides a way to specify the engine that is used to create the library. For more information and examples, see LIBNAME Statement: z/OS and LIBNAME Function in SAS Functions and CALL Routines: Reference in the SAS Functions and CALL Routines: Reference.

In most cases, the engine does not need to be specified when assigning existing SAS libraries. SAS also uses a default engine if no engine was specified for a new library. For a description of how SAS determines which engine to use when no engine has been specified, see How SAS Assigns an Engine.
In certain contexts in which the name of a SAS file is specified in libref.member syntax, it is possible to directly specify the full library name and member name, as shown in the following example:
```
data 'user934.mylib.saslib(member1)';
...
run;
```
The statement above has the same effect in most cases as the LIBNAME statement example above. This syntax can be used only if neither the engine name nor LIBNAME options are required to assign the library. For more information, see Accessing SAS Data Sets without a Libref Using Quoted References.

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.

If you use the LIBNAME statement or function, you can allocate your library for only as long as you need it, and then deassign and deallocate it. By contrast, ddnames that are allocated externally remain allocated for the duration of the SAS session or job. The LIBNAME CLEAR statement deassigns an externally allocated libref, but it does not deallocate the file unless FREE=CLOSE is specified on the external allocation and the library is a direct access bound library. Similarly, by conditionally executing a LIBNAME statement or function within macro statements, you can allocate a library data set only if it is required for execution of your particular job.
The LIBNAME statement or function provides an easy way to do dynamic allocation in the batch environment. SAS programs that have LIBNAME statements or functions instead of external allocations can be executed either in the TSO environment or in the batch environment without requiring additional supporting allocation statements in JCL or TSO CLISTs.
The JCL DD statement and the TSO ALLOCATE command are not portable to operating environments other than to another z/OS environment. The LIBNAME statement or function is portable with minor changes to the physical-filename and options parameters.
ddnames that are allocated externally cannot be reassigned later by a LIBNAME statement or a LIBNAME function. You would receive an error message in the SAS log stating that the ddname is currently assigned.
Using a LIBNAME statement or a LIBNAME function enables you to specify an engine. Also, the following SAS engines must be specified in a LIBNAME statement or function because they are not assigned by default: XPORT, BMDP, SPSS, and OSIRIS.
ddnames that are allocated externally are not included in the list that is produced by the LIBNAME LIST statement nor in the SAS Explorer window until after they have been used as librefs in your SAS session. For more information, see Listing Your Current Librefs.

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.

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.

You might not want to allow a SAS job running in batch to start until the libraries that it needs to access are available. If you allocate the libraries using DD statements in JCL, the z/OS job scheduler automatically ensures that the libraries are accessible:
- by granting the job exclusive access to the library if DISP=OLD is specified
- by granting the job shared access to the library if DISP=SHR is specified.
The syntax of the JCL DD statement and the TSO ALLOCATE command is more comprehensive than that of the LIBNAME statement. For example, in order to specify a list of more than 30 volumes, it is necessary to use external allocation.
If a particular SAS program uses an externally assigned SAS library, it is possible to change the library that the program acts upon merely by changing the JCL or TSO CLIST that invokes SAS, as opposed to changing the program. This capability might prove to be convenient in some circumstances.

Note:

Because direct bound libraries are not partitioned data sets (PDS or PDSE), they cannot be concatenated via external allocation. An attempt to concatenate library data sets in this way is ignored with a warning, and only the first library in the concatenation is recognized. However, sequential access bound libraries can be concatenated if they are allocated with DISP=SHR.
SAS will not attempt to deallocate a library data set that was allocated external to SAS. Therefore, externally assigned bound libraries remain allocated until the end of the job step or until a TSO FREE command is issued. However, if FREE=CLOSE is specified on the external allocation for a direct access bound library, the library is deallocated by the system when the last libref assigned to the library is cleared. This exception does not apply to sequential access bound libraries; they would not be freed at deassign time even if FREE=CLOSE was specified.

JCL DD Statement Examples

Allocating an existing SAS library
The following JCL DD statement allocates the cataloged data set LIBRARY.CATALOG.DATA and assigns the ddname BOOKS to it:
```
//BOOKS DD DSN=LIBRARY.CATALOG.DATA,
//         DISP=OLD
```
The following JCL DD statement allocates an existing SAS library, which is stored in a UFS directory:
```
//UFSLIB DD PATH='/corp/dev/test1'
```
Note that UNIX System Services recognizes and distinguishes between uppercase and lowercase letters in pathnames. Also, in contrast to bound libraries, allocating UFS libraries merely provides a convenient way to establish an external logical name (ddname) for a UFS library. It does not place any enqueue that would prevent the library from being accessed by other jobs on the z/OS system.
Allocating a new SAS library
This example allocates a new SAS library on tape:
```
//INTAPE DD DSN=USERID.V9.SEQDATA,
//  UNIT=TAPE,LABEL=(1,SL),

//  DCB=(RECFM=U,BLKSIZE=32760),

//  DISP=(NEW,KEEP),VOL=SER=XXXXXX
```
Notice that DCB attributes are specified. When you allocate a new SAS library externally, you must either specify DCB attributes or accept the default DCB attributes that SAS supplies.
Specifying additional options for a previously allocated SAS library

For more information, see Specifying an Engine for Externally Allocated SAS Libraries.

TSO ALLOCATE Command Examples

Allocating an existing SAS library
The following TSO ALLOCATE command allocates the cataloged data set LIBRARY.CATALOG.DATA and assigns the ddname BOOKS to it:
```
alloc dd(books) da('lib.cat.data') old
```
The following command performs the same allocation, this time using the SAS X statement to submit the TSO ALLOC command.
```
x alloc dd(books) da('lib.cat.data') old;
```
For more information, see X Statement: z/OS.
The following command allocates a directory as a SAS library with the ddname RESULT2:
```
x alloc dd(result2) path('/corp/dev/test2');
```
Note that allocating UFS libraries in this way provides a convenient way to establish an external logical name (ddname) for a UFS library. No enqueue is placed on the library.
Allocating a new SAS library
The following TSO command allocates a new sequential SAS library on disk:
```
alloc fi(intape) da(V9.seqdata) dsorg(ps) recfm(u) new
```
Notice that DCB attributes are specified. When you allocate a new SAS library externally, you must either specify DCB attributes or accept the default DCB attributes that SAS supplies.
Specifying additional options for a previously allocated SAS library

For more information, see Specifying an Engine for Externally Allocated SAS Libraries.

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 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. For more information, 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 which type of library you are accessing. For more information about libraries, see Library Implementation Types for Base and Sequential Engines.

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:

The library data set is on a tape device, or it is a subsystem data set managed by BatchPipes.
The DCB characteristics DSORG=PS and RECFM=U are specified for the data set.

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.

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.

When you issue the LIBNAME command, the SAS Explorer window is displayed. The SAS Explorer window lists all of the librefs that are currently assigned for your session.

The SAS Explorer window displays the full z/OS data set name of the SAS library, and displays the engine that is used to access the library.
The following form of the LIBNAME statement writes to the SAS log the attributes of all the librefs that are currently assigned for your session:

LIBNAME _ALL_ LIST;

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 in Assigning 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:

The library data set is physically closed (if it is not already closed). If FREE=CLOSE was specified on the external allocation for a direct access bound library, the system automatically deallocates the library data set at this point. However, FREE=CLOSE is not honored for a sequential access bound library.
If SAS allocated the library data set (as opposed to using an allocation that had been established external to SAS), SAS releases the allocation. However, SAS does not release allocations that were established externally. These allocations are released at the end of the job step or, in the TSO environment, when a TSO FREE command is issued for the allocation. When an allocation is released, the enqueue on the library is released, making the library available for use by other jobs. Normal disposition processing, such as cataloging or deleting the library data (as specified by the DISP parameter), is also performed at deallocation time.

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

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

To deassign and deallocate a SAS library that was allocated with a LIBNAME statement or LIBNAME function, issue a LIBNAME statement or function in the following forms, using the libref for the library that you want to deallocate:

LIBNAME statement: LIBNAME libref <CLEAR>;

LIBNAME function: LIBNAME (libref, ' ');

This statement deassigns the libref. All libraries assigned during a SAS session are automatically deassigned at the end of the session.
To deassign and deallocate a library that was allocated with a TSO command, first issue a LIBNAME statement or LIBNAME function to deassign the libref, as shown above. Then issue a TSO FREE command to deallocate the data set.
For example, suppose that a SAS library with the libref MYLIB is stored in the z/OS data set MYID.RECENT.DATA. The following two statements would clear the libref and deallocate the library data set:
```
libname mylib clear;
x free da('myid.recent.data');
```
CAUTION:

Do not attempt to release the allocation for a library data set without first deassigning the libref.
You can deassign a SAS library in the SAS Explorer window by selecting the DELETE menu.

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 you allocate 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) that is 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 to extend an existing library (not SMS-managed) via the LIBNAME statement EXTEND option. Using the EXTEND option 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.

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:

A LIBNAME statement should not be used to create a new GDG library, but it can be used to refer to an existing GDG member.
The z/OS GDG facility is somewhat similar to, but is completely unrelated to, the SAS concept of generation data groups. A z/OS GDG is a group of SAS libraries. A SAS GDG is a group of members within a SAS library. The former group is managed by z/OS. The latter group is managed by SAS.