BRMS Retrieve Media Information (Q1ARTVMED) API
| Required Parameter Group: | |||
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Control value information | Input | Char(33) |
| 5 | Error code | I/O | Char(*) |
| Default Public Authority: *USE | |||
| Threadsafe: No | |||
The BRMS retrieve media information API lets you retrieve BRMS media information for a specific volume or select an active or expired volume in a media class and/or location.
Required Parameter Group
- Receiver variable
- OUTPUT; Char(*)
The receiver variable that is to receive the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length of the receiver variable correctly. As a result, the API returns only the data the area can hold.
- Length of receiver variable
- INPUT; Binary(4)
The length of the receiver variable. This length must be at least 6 bytes.
- Format name
- INPUT; Char(8)
MEDV0100 is the only format name available.
- Control value information
- INPUT; Char(*)
Information needed by the API to select a media volume is supplied in this structure. For more information, see Format of Control Value Information.
- Error code
- INPUT/OUTPUT; Char(*)
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
Format of the Generated Information
The following table shows the format of the MEDV0100. The MEDV0100 format includes the information about the requested media volume. For a description of each field, see Field Descriptions for the Generated Information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Char(6) | Volume serial |
| 6 | 06 | Char(4) | Secure volume |
| 10 | 0A | Char(10) | Media group type |
| 20 | 14 | Char(13) | Media group identification |
| 33 | 21 | Char(10) | Media class |
| 43 | 2B | Char(10) | Location |
| 53 | 35 | Char(7) | Move date |
| 60 | 3C | Char(10) | Move policy |
| 70 | 46 | Char(7) | Expiration date |
| 77 | 4D | Char(1) | Volume expired indicator |
| 78 | 4E | Char(7) | Creation date |
| 85 | 55 | Char(4) | Volume sequence |
| 89 | 59 | Char(6) | Beginning volume |
| 95 | 5F | Char(50) | Volume description |
| 145 | 91 | Char(8) | Registered system |
| 153 | 99 | Char(8) | System using volume |
| 161 | A1 | Char(10) | Job name |
| 171 | AB | Char(6) | Job number |
| 177 | B1 | Char(10) | User |
| 187 | BB | Char(10) | Next location |
| 197 | C5 | Char(7) | Next move date |
| 204 | CC | Char(10) | Container ID |
| 214 | D6 | Char(6) | Slot number |
| 220 | DC | Char(10) | Previous location |
| 230 | E6 | Char(1) | Move verification pending |
Field Descriptions for the Generated Information
- Beginning volume
- The first volume of a multi-volume set.
- Container ID
- The container ID of the container in which the volume is stored, if you are using containers.
- Creation date
- The date expressed in cyymmdd (century, year, month, day) format that the most current data was written on the media.
- Expiration date
- The date expressed in cyymmdd (century, year, month, day) format that the media expires and can be used as scratch media.
- Job name
- The name of the job that created the media.
- Job number
- The number of the job that created the media.
- Location
- The location where the media is currently stored.
- Media group type
- A grouping factor assigned by BRMS to handle *GRPnnn moves.
- Media group identification
- A sub-grouping to bundle like volumes in the same group.
- Media class
- The media class assigned to the volume.
- Move date
- The date expressed in cyymmdd (century, year, month, day) format that the media is scheduled to move.
- Move verification pending
- Indicates whether BRMS marked
the volume for movement and based on the move policy specified below,
whether the move must be verified before it can actually occur. The
values are:
- 0
- Verification of moves is not in effect and the volume has been moved when this exit point is reached. The current location is the location to which the volume was moved.
- 1
- The volume has not moved yet, verification of moves is in effect and the location shows the current location of the volume. The next location shows where BRMS intends to move the volume.
- Move policy
- The name of the move policy associated with the volume.
- Next location
- The next location to which the media will move.
- Next move date
- The date expressed in cyymmdd (century, year, month, day) format on which the media is scheduled to move next.
- Previous location
- The location the media moved from to arrive at its current location.
- Registered system
- The system whose License Manager was used to register the media.
- Secure volume
- Whether the media requires special authority for read access.
- Slot number
- The slot number assigned to the media.
- System using volume
- The system name of the system that last wrote data on the tape.
- User
- The identification of the user who is assigned to the volume.
- Volume expired indicator
- Indicates whether or not the volume is expired. The values are:
- Y
- The volume is expired.
- N
- The volume is active.
- Volume serial
- The volume serial of the media.
- Volume sequence
- The sequence number of the volume in a media set.
- Volume description
- A text description of the volume.
Format of Control Value Information
The following table shows the format of the control value information. For a description of each field, see Field Descriptions for Control Value Information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Char(6) | Volume serial |
| 6 | 06 | Char(10) | Media class |
| 16 | 10 | Char(10) | Location |
| 26 | 1A | Char(7) | Expiration date |
Field Descriptions for Control Value Information
- Volume serial
- The volume serial ID for the media volume to be retrieved. The
values are:
- volume-serial
- A six character media volume serial.
- *EXP
- Specify to request that an expired volume be located.
- *ACT
- Specify to request that an active volume with space available for write operations be located.
- Media class
- A media class name that will be used to locate the media volume.
This field must be specified if special values *EXP or *ACT are
specified for theVolume serial field. The possible values are:
- *ANY
- Specifies the retrieved volume can be assigned to any media class.
- media-class
- Specifies the retrieved volume must be assigned to this media class.
- Location
- A location name that will be used to locate the media volume.
This field must be specified if special values *EXP or *ACT are
specified for theVolume serial field. The possible values are:
- *ANY
- Specifies the retrieved volume can be assigned to any location.
- location-name
- Specifies the retrieved volume must be assigned to this location.
- Expiration date
- The expiration date expressed in cyymmdd (century, year, month,
day) format that will be used to locate an active media volume.
- *ANY
- Specifies any active volume can be retrieved that meets the media class and location control values.
- expiration-date
- Specifies the expiration date used to retrieve active volumes. If an active volume with the specified date cannot be retrieved, then the first available active volume that meets the media class and location control values is retrieved.
- blank
- Specifies that a date is not necessary to locate the media volume. This value should not be specified whenever the Volume serial is specified with the special value *ACT.
Error Messages
- BRM1147 E Volume not found.
- BRM1480 E No media of class &1; available.
- BRM1868 E File &1 not opened successfully.
- CPF24B4 E Severe error while addressing parameter list.
- CPF3CF1 E Error code parameter not valid.
- CPF3C19 E Error occurred with receiver variable specified.
- CPF3C1E E Required parameter omitted.
- CPF3C21 E Format name &1; is not valid.
- CPF3C24 E Length of receiver variable is not valid.
- CPF3C3B E Value for parameter &2 for API &1 not valid.
- CPF3C4B E Value not valid for field &1.