RELEASE Procedure: z/OS

Releases unused space at the end of a disk data set.
z/OS specifics: All

Syntax

PROC RELEASE DDNAME=file-specification <options> ;

Details

Overview of PROC RELEASE

PROC RELEASE can be used with most sequential or partitioned data sets, not just with a SAS library that contains SAS data sets. However, PROC RELEASE is not supported for, and cannot be used to release unused space from, the following types of data sets:
  • the SAS WORK library
  • extended partitioned data sets (PDSEs)
  • ISAM or VSAM data sets
  • multivolume SAS libraries
  • multivolume data sets.
If you delete some members from a SAS library (using the DATASETS procedure, for example), you can use the RELEASE procedure to release the unused space at the end of the last member. You cannot use PROC RELEASE to release embedded space. That is, you can release only space that follows the “Highest Used Block,” as indicated by the CONTENTS or DATASETS procedure.
In order to use PROC RELEASE on a SAS library, the library must be closed. If the library is open, SAS generates an error message. If you have assigned a libref to the library and have used some members of that library in your SAS session, the library is opened. To close it, issue a LIBNAME statement of the following form for each libref currently assigned to the library:
LIBNAME libref CLEAR;
Then issue a new LIBNAME statement for the library and immediately run PROC RELEASE. As an alternative to issuing a second LIBNAME statement, you can simply specify the library's name (enclosed in quotation marks) as the value of the DDNAME= option in the PROC RELEASE statement.
In the control language, you can release unused space by using specifications such as SPACE=(,,RLSE) in the DD statement (in batch mode), or you can use the RELEASE operand of the TSO ALLOCATE command. However, releasing unused space with PROC RELEASE offers several advantages over methods provided by the operating environment. For example, with PROC RELEASE, the user, not the operating environment, controls when unused space is released. This advantage is especially applicable to TSO users.
Another advantage of PROC RELEASE is that you can use PROC RELEASE options to specify exactly how many tracks you want to keep or release. There is no danger of erasing all or part of a data set because PROC RELEASE frees only unused space. PROC RELEASE returns unused space to the pool of available space on the disk volume. Once released, the space is still available for allocation to the data set, provided a secondary space allocation is given for the data set in the control language or SAS statement, and provided all free space on the volume is not subsequently allocated to other data sets.

PROC RELEASE Statement

PROC RELEASE DDNAME=file-specification <options> ;
DDNAME=file-specification
specifies the ddname or the data set name of the data set whose unused space is to be released. A name that is not enclosed in quotation marks is treated as a ddname, and a quoted name is treated as a data set name. For data sets that were allocated by SAS, the ddname that is associated with the data set is usually the same as the fileref or libref that is specified in the first assignment of the data set. If a data set name is specified, PROC RELEASE dynamically allocates it.
options
specify how much unused space to keep or release, and specify the unit boundary on which the data set should end.
For extended format sequential data sets and data sets residing in Extended Addressing Space on Extended Address Volumes, PROC RELEASE can be used only to release all unused space. Therefore, for such data sets, no options can be specified on the PROC RELEASE invocation.
TOTAL=number | TRACKS=number
specifies the total number of tracks that the data set should contain after unused space is released, that is, after PROC RELEASE has executed. For example, the following statement releases all but ten tracks for the data set that is referenced by the fileref SURVEY:
proc release ddname=survey total=10;
The procedure calculates the amount of space to release as follows:
amount of space allocated − (value of TOTAL= option) = amount of unused space released
If the value that you specify is smaller than the amount of used space in the data set, then SAS releases only the unused space at the end of the data set.
UNUSED=number
specifies the number of tracks of unused space that the data set should contain after PROC RELEASE has executed. The procedure calculates the amount of unused space to release as follows:
amount of space allocated − (used space + value of UNUSED= option) =
amount of unused space released
If the value that you specify is greater than the amount of unused space at the end of the data set, then no space is released at the end of the data set.
RELEASE=number
specifies how many tracks of unused space to release. If the value that you specify is greater than the amount of unused space at the end of the data set, then SAS releases all the unused space at the end of the data set.
EXTENTS | EXTENT | EX
tells SAS to release only the space that is allocated to completely unused secondary extents. After the procedure releases unused space from the data set, the size of the data set is the sum of the primary extent plus all used secondary extents.
If you do not specify one of these options in the PROC RELEASE statement, then all unused space at the end of the data set is released.
Use the following option to specify the unit boundary on which the data set should end:
BOUNDARY=type | TYPE=type
specifies whether the data set ends on a track boundary or on a cylinder boundary.
After the total amount of space to be retained is calculated, this amount is rounded up to the next unit boundary. Any remaining space is then released. Remember that the total amount of space includes the space that is actually used and can also include unused space that was requested with other options. BOUNDARY=type then increases the amount of unused space that is retained in the data set by the portion of the unit that is needed in order to reach (or round up to) the next boundary. TYPE can be one of the following:
DATASET | DSCB
specifies that the data set ends on the next track or cylinder boundary depending on how space was originally allocated. If allocated in tracks, the total amount of space to be retained is calculated, and remaining unused tracks are released. If allocated in cylinders, the space to be retained is rounded up to the next cylinder boundary, and remaining unused space is released. This value is the default boundary type.
CYLINDERS | CYLINDER | CYLS | CYL
specifies that space to be retained is rounded to the next cylinder boundary before remaining unused space is released. This specification is effective only if the data set is currently allocated in multiples of cylinders.
TRACKS | TRACK | TRKS | TRK
specifies that unused tracks are to be released. Because the minimum unit of space that can be released is a track, the space to be retained is not rounded up.
ALLOC | DD | JCL
specifies that space to be retained is rounded to the next unit boundary (tracks or cylinders) depending on the allocation unit that was specified in the JCL statement, TSO ALLOCATE command, FILENAME or LIBNAME statement, or FILENAME or LIBNAME function that allocated the data set. For example, the following, in combination with BOUNDARY=DD, is equivalent to specifying BOUNDARY=CYL:
//DD2 DD DISP=OLD,DSN=MY.DATA,
//       SPACE=(CYL,2)

Usage Notes

If the messages in the SAS log indicate that no space was released from the data set, check to see whether the data set is allocated to another job or to another user. When PROC RELEASE is invoked, the operating environment's disk space management function (DADSM) must be able to obtain exclusive control of the data set. If it cannot, then no indication that DADSM does not have control is passed to SAS software, no space is released from the data set, and no error message is issued by SAS software.
Beginning with SAS 9.2, the RELEASE procedure supports large sequential data sets, which might occupy more than 64K tracks on any of its volumes.

Output

PROC RELEASE writes the following information to the SAS log:
  • how many tracks were allocated to the data set before and after the procedure was executed
  • how many tracks were used
  • how many extents were used.
However, for extended format sequential data sets, PROC RELEASE only reports the number of tracks used after space was released.

Example: Example

The following example releases the unused secondary extents for a physical file that is referenced by the fileref THISFILE:
filename thisfile 'my.pgm.lib';
proc release ddname=thisfile extents;
run;

See Also

IBM's MVS JCL Reference