Retrieve Media Definition (QSRRTVMD, QsrRetrieveMediaDefinition) API

The Retrieve Media Definition (OPM, QSRRTVMD; ILE, QsrRetrieveMediaDefinition) API retrieves a media definition specified by the user. A media definition defines the devices, media, and data format to be used in parallel by a save or restore operation. For more information about using a media definition, see Save to multiple devices in the Backup and recovery topic.

Authorities and Locks

Media Definition Authority

*USE

Library Authority

*EXECUTE

Media Definition Lock

*SHRNUP

Required Parameter Group

Qualified media definition name

INPUT; CHAR(20)

The media definition to be retrieved. The first 10 characters contain the media definition name. The second 10 characters contain the name of the library in which the media definition is located.

You can use the following special values for the library name. It should be noted, however, that the library name that is actually used is not passed back to the user. Care should be taken when using these special values to avoid unexpected results.

*CURLIB	The job's current library is used to locate the media definition. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the media definition.

Receiver variable

OUTPUT; CHAR(*)

The variable that is to hold all the information defining the use of multiple tape files for a save or restore operation. See Format of Receiver Variable for the format of the information.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The name of the format for the receiver variable. The valid values are:

MDFN0100	Format name that was used to create the media definition
TAPE0100	Tape devices and media
TAPE0200	Tape devices and media (extended)

Media definitions created with format TAPE0100 can be retrieved with format TAPE0200. The additional options in format TAPE0200 will be set to their default values.

Media definitions created with format TAPE0200 can be retrieved with format TAPE0100. The additional options in format TAPE0200 will be lost.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Receiver Variable

For format MDFN0100, the retrieved data consists of the following structure. For detailed descriptions of the fields, see Field Descriptions for Receiver Variable.

Format MDFN0100

For other formats, the retrieved data consists of a header and a set of device definitions and media file definitions. The following defines the format for the header. For detailed descriptions of the fields, see Field Descriptions for Receiver Variable.

Format TAPE0100

Format TAPE0200

Field Descriptions for Receiver Variable

Bytes available. The number of bytes available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned. If this is less than the bytes available, the information returned is not complete.

Device allocation. When to allocate the tape devices. The default value is 0. The possible values are:

Device definitions. A description of the devices to be used. See Device Definition Format for the format of a device definition.

Format name. The name of the format that was used to create the media definition.

Length of header. The length of the fixed portion of the header information.

Maximum parallel device resources. The maximum number of device resources to use in parallel. The possible values are 0 through 32. If 0 is specified, the value assumed is the total number of media file definitions specified in all of the device definitions.

Minimum parallel device resources. The minimum number of device resources to use in parallel. A save or restore operation will end if fewer resources are available. A restore operation will also end if any of the devices specified have no resources available. The possible values are 0 through 32. If 0 is specified, the value assumed is the number of device definitions specified.

Number of device definitions. The number of device definitions for the media definition. The possible values are 1 through 32.

Offset to first device definition. The offset from the beginning of the receiver variable to the first device definition for the media definition.

Save format. Whether to save data in serial format or parallel format. This field is ignored for restore operations. The default value is -2. The possible values are:

Device Definition Format

Format TAPE0100

Format TAPE0200

Field Descriptions for Device Definition

Device name. The name of a tape device description or tape media library device description.

Length of device definition. The length of the fixed portion of the device definition.

Media file definitions. A description of the media files to be used on this device. See Media File Definition Format for the format of a media file definition.

Number of media file definitions. The number of media file definitions for the device.

Offset to first media file definition. The offset from the beginning of the receiver variable to the first media file definition for the device.

Offset to next device definition. The offset from the beginning of the receiver variable to the next device definition for the media definition.

Reserved. An ignored field.

Media File Definition Format

Format TAPE0100

Format TAPE0200

Field Descriptions for Media File Definition

Length of media file definition. The length of the fixed portion of the media file definition.

Length of volume identifier. The number of bytes in each volume identifier.

Number of volume identifiers. The number of volume identifiers used for the tape file. The possible values are 0 through 75. If 0 is specified, the volume currently placed in the device is used. If 0 is specified for a tape media library device, volume identifiers must be supplied by using the Tape Management exit program during the save or restore operation.

Offset to next media file definition. The offset from the beginning of the receiver variable to the next media file definition for the device.

Offset to volume identifier array. The offset from the beginning of the receiver variable to the first volume identifier for the media file.

Sequence number. The tape file sequence number for a tape media file.

The possible values are:

Starting volume array element. The element in the volume identifier array containing the volume on which the save or restore operation should begin. The possible values are 0 through the number of volume identifiers.

Volume identifier array. An array of volume identifiers. The save or restore operation will use the volumes in the order specified, beginning with the starting volume array element. If additional volumes are needed after the last array element is used, the save or restore operation will call the Tape Management exit program or prompt the user to provide each additional volume. The possible value for a volume identifier is:

Error Messages