Retrieve Image Catalog Details (QVOIRCLD) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified image catalog name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Image Catalog Details (QVOIRCLD) API retrieves the contents of an image catalog. The QVOIRCLD API places the information in the receiver variable.
Authorities and Locks
- Image Catalog Authority
- *USE
- Image Catalog Library Authority
- *EXECUTE
- Image Catalog Lock
- *SHRRD
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that is to receive the catalog information. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the 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 format of image catalog entries to list. You can use one of the following format names:
RCLD0100 Header information only. RCLD0200 Header information and entry list for optical image catalogs. RCLD0300 Header information and entry list for tape image catalogs.
- Qualified image catalog name
- INPUT; CHAR(20)
The image catalog about which to list information, and the library in which it is located. The first 10 characters contain the object name, and the second 10 characters contain the library name.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format RCLD0100
For detailed descriptions of the fields in this table, see Field Descriptions.| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(1) | Image catalog type |
| 9 | 9 | CHAR(1) | Image catalog status |
| 10 | A | CHAR(1) | Reference image catalog indicator |
| 11 | B | CHAR(1) | Dependent image catalog indicator |
| 12 | C | CHAR(50) | Image catalog text |
| 62 | 3E | CHAR(10) | Virtual device name |
| 72 | 48 | BINARY(4) | Offset to image catalog directory |
| 76 | 4C | BINARY(4) | Number of image catalog directories |
| 80 | 50 | BINARY(4) | Length of image catalog directory |
| 84 | 54 | BINARY(4) | CCSID of image catalog directory |
| 88 | 58 | BINARY(4) | Offset to first image catalog entry |
| 92 | 5C | BINARY(4) | Number of image catalog entries returned |
| 96 | 60 | BINARY(4) | Length of image catalog entry |
| 100 | 64 | BINARY(4) | Number of image catalog entries |
| 104 | 68 | CHAR(10) | Reference image catalog name |
| 114 | 72 | CHAR(10) | Reference image catalog library name |
| 124 | 7C | CHAR(6) | Next tape volume |
 130 |
82 | CHAR(1) | Image catalog mode |
| 131 | 83 | CHAR(*) | Reserved |
| CHAR(*) | Image catalog directory | ||
Format RCLD0200
For detailed descriptions of the fields in this table, see Field Descriptions.| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format RCLD0100 | |
| These fields repeat, in the order listed, for the number of image catalog entries returned. | BINARY(4) | Image catalog entry index | |
| CHAR(1) | Image catalog entry status | ||
| CHAR(100) | Image catalog entry text | ||
| CHAR(1) | Write protect status | ||
| CHAR(32) | Volume name | ||
| CHAR(1) | Access information | ||
| CHAR(1) |
Media type |
||
| BINARY(4) | Image size | ||
| BINARY(4) | Length of image file name | ||
| CHAR(512) | Image file name | ||
Format RCLD0300
For detailed descriptions of the fields in this table, see Field Descriptions.| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format RCLD0100 | |
| These fields repeat, in the order listed, for the number of image catalog entries returned. | BINARY(4) | Image catalog entry index | |
| CHAR(1) | Image catalog entry status | ||
| CHAR(100) | Image catalog entry text | ||
| CHAR(1) | Write protect status | ||
| CHAR(6) | Volume name | ||
| BINARY(4) UNSIGNED | Maximum volume size | ||
| BINARY(8) UNSIGNED | Current number of bytes available | ||
| BINARY(8) UNSIGNED | Current number of bytes used by volume | ||
| BINARY(4) UNSIGNED | Percent used (units in tenths) | ||
| BINARY(4) UNSIGNED | First file sequence number in the virtual volume | ||
| BINARY(4) UNSIGNED | Last file sequence number in the virtual volume | ||
| CHAR(1) | Next volume indicator | ||
| CHAR(10) | Density | ||
| CHAR(1) | Type of volume | ||
| BINARY(4) | Length of image file name | ||
| CHAR(512) | Image file name | ||
| BINARY(4) UNSIGNED | Allocated volume size | ||
Field Descriptions
Access information. The type of access allowed to this image catalog entry. The possible values are:
| 0 | Read only. |
| 1 | Read/Write. |
Allocated volume size. The current allocated size of this virtual volume in megabytes.
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
CCSID of image catalog directory. The CCSID of the image catalog directory returned.
Current number of bytes available. The current number of bytes available by this virtual volume.
Current number of bytes used by volume. The current number of bytes being used by this virtual volume.
Density. The density associated with this image catalog entry.
Dependent image catalog indicator. An indicator of whether this image catalog is a dependent image catalog. The possible values are:
| 0 | This catalog is not a dependent catalog. |
| 1 | This catalog is a dependent catalog. |
First file sequence number in the virtual volume. The sequence number associated with the first file in this virtual volume. The possible values are:
| 0 | Unknown. |
| 1-n | The sequence number associated with the first file in this virtual volume. |
Image catalog directory. The Integrated File System (IFS) directory associated with the image catalog.
Image catalog entry index. The index number of this image catalog entry. An image catalog entry index is a number between 1 and 256.
Image catalog entry status. The status of this image catalog entry. The possible values are:
| 0 | Unloaded. |
| 1 | Loaded. |
| 2 | Mounted. |
| 3 | Error. |
| 4 |
Available. |
Image catalog entry text. The text associated with this image catalog entry. This text will be returned in UTF-16, coded character set identifier (CCSID) 1200.
Image catalog mode. The current mode for a loaded optical image catalog. The possible values are:
| 0 | Not ready or tape type image catalog. |
| 1 | Normal. |
| 2 | Library. |
Image catalog status. The current status of the image catalog. The status indicates whether the image catalog is loaded into a virtual optical device or not. The possible values are:
| 0 | Not ready. |
| 1 | Ready. |
Image catalog text. The text description associated with the image catalog.
Image catalog type. The type of this image catalog. The possible values are:
| 0 | This catalog is an optical catalog. |
| 1 | This catalog is a tape catalog. |
Image file name. The Integrated File System name of this image catalog entry. The image catalog entry name returned will be represented in UTF-16.
Image size. The size of the optical image file in MB. The possible values are:
| 0 | The size is not available (for example, the entry is not mounted, or the image file is not available). |
| n | The size of the optical image file in MB. |
Last file sequence number in the virtual volume. The sequence number associated with the last file in this image. The possible values are:
| 0 | Unknown. |
| 1-n | The sequence number associated with the last file in this virtual volume. |
Length of image catalog directory. The length, in bytes, of the image catalog directory that is associated with the image catalog.
Length of image catalog entry. The length of each image catalog entry in the image catalog.
Length of image file name. The length, in bytes, of the image file name.
Maximum volume size. The maximum size allowed for this virtual volume in megabytes.
Media type. The media type of this image catalog entry. The possible values are:
| 0 | *RAM. |
| 1 | *WORM. |
| 2 | *ERASE. |
| 3 | *ROM. |
| 4 | *UNKNOWN. |
5 |
*RMS.
|
Next tape volume. Because no volume is currently mounted, this volume will be the one used by VOL(*MOUNTED). The following special value may be returned:
| *NONE | The catalog is an optical catalog, or there is a mounted entry, or no volume is available to be used. |
Next volume indicator. Indicates if the volume is the one that will be used by VOL(*MOUNTED) because no volume is currently mounted. The possible values are:
| 0 | This volume is not the next tape volume. |
| 1 | This volume is the next tape volume. |
Number of image catalog directories. The number of image catalog directories associated with this image catalog.
Number of image catalog entries. The number of image catalog entries in the image catalog.
Number of image catalog entries returned. The number of image catalog entries returned. When format RCLD0100 is specified, this field will be zero.
Offset to first image catalog entry. The offset to the first image catalog entry. When format RCLD0100 is specified, this field will be zero.
Offset to image catalog directory. The offset to the image catalog directory name.
Percent used (units in tenths). The percentage of this virtual volume that has been used.
Reference image catalog indicator. An indicator of whether a dependent image catalog was created, with this catalog as the reference image catalog. The possible values are:
| 0 | This catalog is not a reference catalog. |
| 1 | This catalog is a reference catalog. |
Reference image catalog library name. The library containing the image catalog that was named as the reference catalog when this catalog was created. If this image catalog is not a dependent image catalog, this field will be blank.
Reference image catalog name. The image catalog named as the reference catalog when this catalog was created. If this image catalog is not a dependent image catalog, this field will be blank.
Reserved. Space included for alignment.
Type of volume. The type associated with this image catalog entry. The possible values are:
| 0 | This is a nonlabeled virtual volume. |
| 1 | This is a standard labeled virtual volume. |
| 2 | The type of this virtual volume is unknown. |
Virtual device name. The name of the virtual device that this image catalog is associated with. A blank virtual device name indicates that the catalog is not associated with a virtual device.
Volume name. The volume name of this virtual volume.
Write protect status. An indicator of whether this image file is write protected or not. The possible values are:
| 0 | Not write protected. |
| 1 | Write protected. |
| 2 | Unknown. |
Error Messages
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9810 E | Library &1 not found. |
| CPFBC45 E | Image catalog &1 not found. |
| CPFBC4B E | Image catalog &1 in use. |
API introduced: V5R4
[ Back to top | Object APIs | APIs by category ]