Purpose

Use the GETVOLUME subcommand to request a scratch volume and assign it to an owner defined to DFSMSrmm. The default owner is the owner who issues the command.

You can request volumes from specific pools by specifying a pool ID. If you use an asterisk to specify a pool ID, DFSMSrmm assigns you a volume from the system default scratch pool.

When DFSMSrmm assigns a volume, it sets the volume status to USER, which means that the volume can be overwritten by any data set. DFSMSrmm prevents you from reading any existing data on a scratch volume that is obtained using the GETVOLUME subcommand.

Parameters

ACCESS(NONE|READ|UPDATE)

Specifies user access to a volume. Specify a value to define the access level for users defined as users who can access this volume. You can specify one of these:

NONE

Users do not have access to the volume

READ

Users have only read access to the volume

UPDATE

Users have write access to the volume

The default is NONE.

DESCRIPTION(text)

Specifies descriptive text about the volume. Descriptive text is one to thirty characters enclosed in single quotation marks if it contains any special characters or blanks.

EXPDT(expiration_date)

Specifies date the volume should be considered for release.

Supply the year and day in one of two forms. We recommend that you use the yyyy/ddd format rather than the yyddd format for dates.

• yyyy/ddd, where yyyy is the four-digit number for the year. The maximum allowable value for yyyy is 9799. ddd is the three-digit number for the day of the year, such as 2012/001. The slash is required.
• yyddd, where yy is the last two-digit number for the year and ddd is the three-digit number for the day of the year, such as 12001. When you use the yyddd format, DFSMSrmm determines the century by using a date window:
  • DFSMSrmm uses the current century if the difference between the current year and the specified year is not greater than 50.
  • DFSMSrmm uses the previous or next century if the difference between the current year and the specified year is greater than 50.

EXPDT is mutually exclusive with RETPD.

LOCATION(SHELF|library_name|LOCDEF_location_name)

Specifies a library from which the volume should be chosen. Specify one of these:

SHELF

To indicate that the volume should come from a non-system-managed library. This is the default.

library_name

To indicate that the volume should come from a specific system-managed library. A library name is one-to-eight alphanumeric characters, $, #, or @, starting with a non-numeric character, and previously defined in the TCDB as a system-managed library. You can specify a distributed library name only if the library is an IBM® Virtualization Engine.

LOCDEF_location_name

A LOCDEF_location_name is one-to-eight alphanumeric or national characters. It is the installation defined storage location name defined on LOCDEF in the current parmlib.

MEDIANAME(medianame)

Specifies the volume's media name. The media name allows you to specify the type or shape of media. Media names are defined by your location and one to eight characters.

Use the LISTCONTROL subcommand to display media names for your installation. See LISTCONTROL: Displaying parmlib options and control information for more information.

OWNER(owner)

Specifies the owner ID of the volume's owner. An owner ID consists of one-to-eight alphanumeric characters, $, #, or @. The first character cannot be a number. We suggest that you use a RACF® user ID or RACF group name.

OWNERACCESS(ALTER|READ|UPDATE)

Specifies the type of access the owner has to the volume.

When the RACF TAPEVOL class is active, and TPRACF(P) or TPRACF(A) is in effect, DFSMSrmm uses the OWNERACCESS information to build the RACF TAPEVOL access list. OWNERACCESS can be used together with OWNER to define the initial RACF TAPEVOL volume profile access, specifying the type of access the volume owner has to a volume.

The OWNERACCESS value can be one of these:

ALTER

The volume owner is allowed to read from the tape volume, to write add and delete data sets to the volume, and to create or destroy tape volume labels through OPEN or end-of-volume operations. For discrete tape volume profiles, the volume owner is allowed to change the profile, including the access list.

ALTER is the default value.

READ

The volume owner has only read access.

UPDATE

The volume owner is allowed to read from the tape volume, and to write additional data sets to the volume.

For more information, refer to the topic Maintaining the User Access List in z/OS DFSMSrmm Implementation and Customization Guide.

POOL(pool_ID)

Specifies a pool ID for a group of shelf locations in the removable media library from which DFSMSrmm assigns the volume. The value is one-to-five alphanumeric, national, or special characters followed by an asterisk. Enclose it in single quotation marks if it contains any special characters. If you do not specify a pool ID, DFSMSrmm assigns a volume from the default scratch pool.

Pool IDs are defined by your installation. You can view information about pools by using the LISTCONTROL subcommand with the VLPOOL operand. See LISTCONTROL: Displaying parmlib options and control information for more information.

RELEASEACTION(SCRATCH,REPLACE,RETURN,INIT,ERASE, NOTIFY)

Specifies the actions to be taken when the volume is eligible for release. RELEASEACTION can be specified as a list of keywords separated by commas.

You can specify one of these:

SCRATCH

To request that DFSMSrmm return the volume to scratch status.

REPLACE

To request that the volume be replaced with a new volume and returned to scratch status.

RETURN

To request that the volume be returned to its owner.

SCRATCH, REPLACE and RETURN are mutually exclusive. The default is SCRATCH.

You can specify any or all of these, separated by commas:

INIT

To request that DFSMSrmm initialize the volume.

ERASE

To request that DFSMSrmm erase the volume.

NOTIFY

To request that DFSMSrmm automatically notify the owner when the volume is released.

For example, you can specify multiple actions as follows: RELEASEACTION(SCRATCH,INIT,NOTIFY)

RETPD(retention_period)

Specifies the number of days DFSMSrmm retains the volume before considering it for release. The value is a decimal number from 0 to 93000. The retention period is added to today's date to compute the EXPDT.

SECLEVEL(security_class)

Specifies the volume's security class. This value is one to eight characters and defined by your installation.

Use the LISTCONTROL subcommand with the SECCLS operand to display the security classes defined for your location. See LISTCONTROL: Displaying parmlib options and control information for more information.

USE(IRMM,MVS,VM)

Specifies the operating systems where the volume can be used. You can select one or more of: IRMM, MVS™, and VM. When you change the systems where a volume can be used, include all the systems you need and to indicate multiple operating systems are valid, enter the values with a comma as a separator. The default is MVS.

USERS(user_ID,user_ID...)

Specifies the user IDs and group names of users that are allowed to access the volume as defined by the ACCESS keyword. You can specify a maximum of twelve user IDs separated by blanks or commas.

Return codes

See DFSMSrmm return codes and reason codes for DFSMSrmm reason codes.

0

Subcommand completed normally.

4

Warning. Subcommand completed but some operands could have been ignored or modified. DFSMSrmm sets a reason code.

8

User not authorized.

12

Subcommand ended with an error. DFSMSrmm sets a reason code.

16

Error. The DFSMSrmm subsystem is not active.

20

Error. The data is incomplete or incorrect and the TSO user has set NOPROMPT.

24

The TSO subcommand is not APF authorized.

28

The user pressed the attention key.