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.
| 1 | Qualified media definition name | Input | Char(20) |
| 2 | Input data | Input | Char(*) |
| 3 | Length of data | Input | Binary(4) |
| 4 | Format name | Input | Char(8) |
| 5 | Public authority | Input | Char(10) |
| 6 | Text description | Input | Char(50) |
| 7 | Replace | Input | Char(1) |
| 8 | Error code | I/O | Char(*) |
The Create Media Definition (OPM, QSRCRTMD; ILE, QsrCreateMediaDefinition)
API creates 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.
The media definition to be created. 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 value 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 this special value 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. |
The variable that is to hold all the information defining the use of multiple tape files for a save or restore operation. See Input Data Format for the format of the input data.
The length of the data in the input data parameter. The length of data
parameter may be specified up to the size of the input data variable specified
in the user program. If the length of data parameter specified is larger than
the allocated size of the input data variable specified in the user program,
the results are not predictable. The minimum length is 72 bytes
for format TAPE0100 and 92 bytes for format TAPE0200.
The name of the format for input data. The valid values are:
| TAPE0100 | Tape devices and media |
| TAPE0200 |
Tape devices and media (extended) |
The authority you give to users who do not have specific private or group authority to the media definition. Once the media definition has been created, its public authority stays the same when it is moved to another library or restored from backup media.
If the replace parameter is used and an existing media definition is replaced, this parameter is ignored. All authorities are transferred from the replaced media definition to the new one. The valid values for this parameter are:
| *ALL | The user can perform all authorized operations on the media definition. |
| Authorization list name | The media definition is secured by the specified authorization list, and its public authority is set to *AUTL. The specified authorization list must exist on the system when this API is issued. If the list does not exist, the create process fails, and an error message is returned to the application. |
| *CHANGE | The user has read, add, update, and delete authority for the media definition and can read the object description. |
| *EXCLUDE | The user cannot access the media definition in any way. |
| *LIBCRTAUT | The public authority for the media definition is taken from the CRTAUT value for the target library when the object is created. If the CRTAUT value for the library changes later, that change does not affect media definitions already created. If the CRTAUT value contains an authorization list name and that authorization list secures an object, do not delete the list. If you do, the next time you call this API with the *LIBCRTAUT parameter, it will fail. |
| *USE | The user can read the object description and contents, but cannot change the media definition. |
A brief description of the media definition.
Whether you want to replace an existing media definition. The valid values are:
| 0 | Do not replace an existing media definition of the same name and library. |
| 1 | Replace an existing media definition of the same name and library. The replaced media definition is moved to the QRPLOBJ library, which is cleared at system IPL. For details about authorities, ownership, and renaming, see the discussion of the REPLACE parameter in Control Language (CL) |
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
The input 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 Input Data.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Reserved |
| 4 | 4 | BINARY(4) | Reserved |
| 8 | 8 | BINARY(4) | Maximum parallel device resources |
| 12 | C | BINARY(4) | Minimum parallel device resources |
| 16 | 10 | BINARY(4) | Offset to first device definition |
| 20 | 14 | BINARY(4) | Number of device definitions |
| CHAR(*) | Device definitions | ||
Format TAPE0200| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | All fixed fields from format TAPE0100 | |
| 24 | 18 | BINARY(4) | Length of header |
| 28 | 1C | BINARY(4) | Device allocation |
| 32 | 20 | BINARY(4) | Save format |
| CHAR(*) | Device definitions | ||
Device allocation. When to allocate the tape
devices. This field is ignored for save operations that specify a target release
earlier than V5R4M0. The default value is 0. The possible values are:
| 0 | All tape devices are allocated at the beginning of the operation. |
| 1 | One tape device is allocated at the beginning of a save operation. Additional devices are allocated when data is ready to be written, at which time the number of devices specified for the Minimum parallel device resources field is required. |
| 2 | The number of devices specified for the Minimum parallel device resources field is allocated at the beginning of a save operation. Additional devices are allocated when data is ready to be written. |
Device definitions. A description of the devices to be used. See Device Definition Format for the format of a device definition.
Length of header. The length of
the fixed portion of the header information.
The value must be 36.
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 input data to the first device definition for the media definition. This value must be a multiple of 4.
Reserved. The value must be hexadecimal zeros.
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:
| -2 | If one library is saved, it is saved in parallel format. If more than one library is saved, all libraries are saved in serial format. |
| -1 | All data is saved in serial format. |
| 0 | All data is saved in parallel format. |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to next device definition |
| 4 | 4 | CHAR(10) | Device name |
| 14 | E | CHAR(2) | Reserved |
| 16 | 10 | BINARY(4) | Offset to first media file definition |
| 20 | 14 | BINARY(4) | Number of media file definitions |
| CHAR(*) | Media file definitions | ||
Format TAPE0200| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | All fixed fields from format TAPE0100 | |
| 24 | 18 | BINARY(4) | Length of device definition |
| CHAR(*) | Media file definitions | ||
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.
The value must be 28.
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. The possible values are 1 through 32.
Offset to first media file definition. The offset from the beginning of the input data to the first media file definition for the device. This value must be a multiple of 4.
Offset to next device definition. The offset from the beginning of the input data to the next device definition for the media definition. This value must be a multiple of 4.
Reserved. The value must be hexadecimal zeros.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to next media file definition |
| 4 | 4 | BINARY(4) | Sequence number |
| 8 | 8 | BINARY(4) | Offset to volume identifier array |
| 12 | C | BINARY(4) | Number of volume identifiers |
| 16 | 10 | BINARY(4) | Length of volume identifier |
| 20 | 14 | BINARY(4) | Starting volume array element |
| CHAR(*) | Volume identifier array | ||
Format TAPE0200| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | All fixed fields from format TAPE0100 | |
| 24 | 18 | BINARY(4) | Length of media file definition |
| CHAR(*) | Volume identifier array | ||
Length of media file definition. The length of
the fixed portion of the media file definition.
The value must be 28.
Length of volume identifier. The number of bytes in each volume identifier. The possible values are 0 through 6. If 0 is specified, the number of volume identifiers specified must be 0.
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 input data to the next media file definition for the device. This value must be a multiple of 4.
Offset to volume identifier array. The offset from the beginning of the input data to the first volume identifier for the tape file. This value must be a multiple of 4.
Sequence number. The tape file sequence number for the media file.
The possible values are:
| 0 | A save operation begins after the last sequence number on the starting volume. A restore operation searches the starting volume for a media file containing any of the objects to restore. |
| 1-16777215 | The sequence number of the tape file. |
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 specified. If the number of volume identifiers is 0, this value must be 0. If the number of volume identifiers is greater than 0, this value must be greater than 0.
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:
| Volume identifier | The identifier of a volume. |
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF386F E | Value in input data parameter not valid. |
| CPF3C17 E | Error occurred with input data parameter. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C29 E | Object name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
| CPF9999 E | Function check. &1 unmonitored by &2 at statement &5, instruction &3. |
| Top | Backup and Recovery APIs | APIs by category |