Add Image Catalog Entry (ADDIMGCLGE)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Add Image Catalog Entry (ADDIMGCLGE) command is used to create a virtual image in the image catalog directory (as specified by the Directory (DIR) parameter on the CRTIMGCLG command). If the image is added successfully, the image will be loaded and the image catalog (*IMGCLG) in library QUSRSYS will be updated. Images can be added from the following sources:
- CD or DVD media (by specifying an optical device containing the CD or DVD image to be added). This source is only allowed for optical image catalogs.
- An image file located in a directory. The image file can exist in any directory that is accessible through the Copy Object (CPY) command.
- A new image file by specifying the FROMFILE(*NEW) parameter
If an image catalog entry exists with the same index as specified for the Image catalog index (IMGCLGIDX) parameter, one of the following will occur:
- If REPLACE(*NO) is specified, an error message will be issued and the catalog entry in the image catalog will not be replaced.
- If REPLACE(*YES) is specified, the catalog entry in the image catalog will be replaced.
- If REPLACE(*INSERT) is specified, the catalog entry in the image catalog will be inserted. If a catalog entry already exists at the index specified, the remaining entries will be incremented by one up to the next available index.
If the image does not exist in the target directory, the image is copied and the image catalog is updated with information about this image.
Restrictions:
- The following authorities are required to add an image catalog entry:
- Execute (*EXECUTE) authority to library QUSRSYS.
- Change (*CHANGE) authority to the image catalog.
- Execute (*X) authority to each directory in the image catalog path name.
- If adding an image file from physical media, use (*USE) authority to the physical device is required.
- If adding an image file from an existing image located in a different directory, the authorities required are the same as those required by the Copy Object (CPY) command.
- If adding an image file from an existing image located in the image catalog directory, read (*R) and object management (*OBJMGT) authorities are required.
- Adding from physical CD or DVD media is only supported for optical image catalogs.
- This command does not support dependent image catalogs.
- The following parameters are only valid for tape image catalogs:
- ALCSTG
- VOLNAM
- VOLTYP
- DENSITY
- NEWOWNID
- CODE
If any of the above parameters are specified for an optical image catalog, they will be ignored.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| IMGCLG | Image catalog | Name | Required, Positional 1 |
| FROMDEV | From optical device, or | Name, *VOL | Optional |
| VOL | Volume identifier | Character value | Optional |
| FROMFILE | From image file | Path name, *NEW | Optional |
| TOFILE | To image file | Character value, *GEN, *FROMFILE | Optional |
| IMGCLGIDX | Image catalog index | 1-256, *AVAIL | Optional |
| REPLACE | Replace catalog entry | *NO, *YES, *INSERT | Optional |
| MEDTYPE | Media type | *RAM, *WORM, *ERASE | Optional |
| IMGSIZ | Image size | 48-1000000, *IMGCLGTYPE, *CD650, *DVD2600, *DVD4700 | Optional |
| TEXT | Text 'description' | Character value, *GEN, *BLANK | Optional |
| ALCSTG | Allocate storage size | *MIN, *IMGSIZ | Optional |
| VOLNAM | Tape volume name | Character value, *GEN | Optional |
| VOLTYP | Volume type | *SL, *NL | Optional |
| DENSITY | Tape density | *VRT256K, *VRT240K, *VRT64K, *VRT32K | Optional |
| NEWOWNID | New owner identifier | Character value, *BLANK | Optional |
| CODE | Code | *EBCDIC, *ASCII | Optional |
| Top |
Image catalog (IMGCLG)
Specifies the image catalog that the new entry is to be added to.
This is a required parameter.
- name
- Specify the name of the image catalog.
| Top |
From optical device, or (FROMDEV)
Specifies the CD or DVD device from which the optical image is to be copied. For optical image catalogs, a value must be specified for either the FROMDEV or FROMFILE parameter to identify the optical image file to be copied to the image catalog directory. For tape image catalogs, the FROMDEV parameter is not allowed.
- name
- Specify the name of the optical device from which the optical image file is to be copied.
- *VOL
- Specify the name of the optical volume from which the optical image file is to be copied.
| Top |
Volume identifier (VOL)
Specifies the name of the optical volume identifier to be added to the image catalog. This parameter is only required when FROMDEV(*VOL) is specified. The specified volume cannot be a tape volume. A separate license may be required for this function
- volume-identifier
- Specify the volume identifier of the optical volume to be added.
| Top |
From image file (FROMFILE)
Specifies the image file to be copied. For optical image catalogs, a value must be specified for either the FROMDEV or FROMFILE parameter to identify the optical image file to be copied to the image catalog directory. For tape image catalogs, a value must be specified on the FROMFILE parameter to identify the tape image file to be copied to the image catalog directory.
- *NEW
- A new catalog entry is to be added and an empty image file created.
- name
- Specify the name of the optical or tape image file to be added to the image catalog.
| Top |
To image file (TOFILE)
Specifies the name given to the file that will be copied to the target directory.
- *GEN
- The file name will be generated from the source image.
- *FROMFILE
- The file name will be the same name as source image. If the source image is from optical media, the name given to the file will be the volume ID. If the source image is from another directory, the file will be given the same name as that in the source directory.
- name
- Specify up to 255 characters for the name of the optical or tape image file to be added to the image catalog.
| Top |
Image catalog index (IMGCLGIDX)
Specifies the image catalog index to be assigned to the image being added.
- *AVAIL
- The image catalog index number assigned to the image will be the first index number available.
- 1-256
- Specify the image catalog index number to be used.
| Top |
Replace catalog entry (REPLACE)
Specifies the action to take if a catalog entry with the same index number as specified on the IMGCLGIDX parameter already exists in the image catalog.
- *NO
- The existing catalog entry will not be replaced and an error message will be issued.
- *YES
- The existing image catalog entry will be replaced.
- *INSERT
- The catalog entry specified will be added (or inserted if an existing index number already exists). If the image catalog entry is inserted, the remaining catalog entries will be incremented by one up to the next available index number.
| Top |
Media type (MEDTYPE)
Specifies the type of media to create.
- *RAM
- Random access type media will be created. The supported media format for *RAM media is Universal Disk Format (UDF), which is a subset of the ISO-13346 standard.
- *ERASE
- Erasable type media will be created. The supported media formats for *ERASE media are High Performance Optical File System (HPOFS) and Universal Disk Format (UDF), which is a subset of the ISO-13346 standard.
- *WORM
- Write once read many (WORM) type media will be created. The supported media format for *WORM media is High Performance Optical File System (HPOFS).
| Top |
Image size (IMGSIZ)
Specifies the size of the new image file that is to be created.
For optical image catalogs, this parameter indicates the size of the optical image file that is to be created and the amount of storage to be allocated from the image catalog directory location.
For tape image catalogs, this parameter indicates the maximum size allowed for this tape image file. If ALCSTG(*MIN) is specified, only the amount of storage required to initialize the image file will be allocated. If ALCSTG(*IMGSIZ) is specified, the amount of storage allocated will be the value specified on the IMGSIZ parameter.
- *IMGCLGTYPE
- The size of the image file to be created will be determined by the type of image catalog.
For optical image catalogs, the size of the image file created will be 650 MB. Optical images created with this size can be written to any standard 650 MB media.
For tape image catalogs, the maximum size of the image file created will be set to 1 gigabyte.
- *CD650
- The size of the optical image file will be 650 megabytes. Optical images created with this size can be written to any standard 650 MB optical media.
- *DVD2600
- The size of the optical image file will be 2.6 gigabytes. Optical images created with this size can be written to any 2.6 GB media.
- *DVD4700
- The size of the optical image file will be 4.7 gigabytes. Optical images created with this size can be written to any 4.7 GB media.
- number
- Specify the number of megabytes for the new image file. The valid range is 48-1000000 megabytes.
| Top |
Text 'description' (TEXT)
Specifies the text that briefly describes the image being loaded.
- *GEN
- For optical image catalogs, the text field will be set to the description on the media if it exists, otherwise it will be set to the volume ID of the media. For tape image catalogs, the text will be generated by the system using the current date and time.
- *BLANK
- The text description will be blank.
- character-value
- Specify up to 50 characters of text for this image file.
| Top |
Allocate storage size (ALCSTG)
Specifies for tape image files, whether to allocate the entire amount of storage specified on the Image size (IMGSIZ) parameter.
- *MIN
- Only allocate storage required to initialize the tape image file at the time of the create.
- *IMGSIZ
- Allocate the entire amount of storage specified on the Image size (IMGSIZ) parameter.
| Top |
Tape volume name (VOLNAM)
Specifies the volume name for this virtual tape volume.
- *GEN
- The volume name will be generated by the system.
- character-value
- Specify up to a 6 character volume name used to identify this virtual tape volume. The volume name must contain only alphanumeric characters (A through Z, $, #, @, and 0 through 9), and cannot have a prefix or contain blanks. If the virtual tape volume is being created as a standard labeled tape, the volume name will also be used as the volume identifier in the tape volume label. Each volume name in the catalog must be unique.
| Top |
Volume type (VOLTYP)
Specifies the type of volume for this virtual tape volume.
- *SL
- The type of volume is a standard labeled tape volume.
- *NL
- The type of volume is a non-labeled tape volume.
| Top |
Tape density (DENSITY)
Specifies the density for this virtual tape volume.
- *VRT256K
- The format of the volume is *VRT256K. It is used to write data to a virtual volume using a maximum data block size of 256KB. Volumes written using this format can only be duplicated to tape devices that support a maximum block size of 256KB or greater.
- *VRT240K
- The format of the volume is *VRT240K. It is used to write data to a virtual volume using a maximum data block size of 240KB. Volumes written using this format can only be duplicated to tape devices that support a maximum block size of 240KB or greater.
- *VRT64K
- The format of the volume is *VRT64K. It is used to write data to a virtual volume using a maximum data block size of 64KB. Volumes written using this format can only be duplicated to tape devices that support a maximum block size of 64KB or greater.
- *VRT32K
- The format of the volume is *VRT32K. It is used to write data to a virtual volume using a maximum data block size of 32KB. Volumes written using this format can be duplicated to all supported tape devices.
| Top |
New owner identifier (NEWOWNID)
Specifies the identifier of the tape owner for this virtual tape volume. This parameter is only used for a volume type of *SL.
- *BLANK
- No identifier will be specified.
- name
- Specify no more than 14 characters that identify the owner of the virtual tape volume. If fewer than 14 characters are specified, the field is left-justified and padded on the right with blanks.
| Top |
Code (CODE)
Specifies the character code in which the volume label is written. All data that is not save data written after the label must be in the same code. Codes cannot be intermixed on a tape that is not a save tape. This parameter is only used for a volume type of *SL.
- *EBCDIC
- The volume label is written in EBCDIC and is an IBM standard label; all additional data must also be written in EBCDIC.
- *ASCII
- The volume label is written in ASCII and is an ANSI standard label; all additional data must also be written in ASCII.
| Top |
Examples
Example 1: Adding an Image Catalog Entry from CD/DVD Media
ADDIMGCLGE IMGCLG(MYCLG) FROMDEV(OPT01)
This command adds the optical image in device OPT01 to the image catalog directory and updates catalog MYCLG. The image catalog directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 2: Adding an Image Catalog Entry from a Directory
ADDIMGCLGE IMGCLG(MYCLG) FROMFILE('/MyDir/MyFile.img')
This command adds the image file /MyDir/Myfile.img to the image catalog directory /MyNewDir and updates catalog MYCLG. The image catalog directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 3: Inserting an Image Catalog Entry
ADDIMGCLGE IMGCLG(MYCLG) FROMDEV(OPT01) REPLACE(*INSERT)
This command adds the optical image in device OPT01 to the image catalog directory and, if a catalog entry exists at the specified index, will insert the entry in the catalog and increment the remaining entries up to the next available index. The image catalog directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 4: Adding a New Optical Image Catalog Entry
ADDIMGCLGE IMGCLG(MYCLG) FROMFILE(*NEW) TOFILE(MYFILE)
IMGSIZ(*CD650) MEDTYPE(*RAM)
This command adds new optical image file MYFILE to the image catalog directory with a size of 650 megabytes. The media type for the new volume is *RAM. The image catalog directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 5: Adding a New Tape Image Catalog Entry
ADDIMGCLGE IMGCLG(TAPECLG) FROMFILE(*NEW) TOFILE(TAP001)
IMGSIZ(*IMGCLGTYPE) ALCSTG(*MIN) VOLNAM(MYVOL)
VOLTYP(*SL) DENSITY(*VRT256K) NEWOWNID(MYNAME)
CODE(*EBCDIC)
This command adds new image file TAP001 with a volume name of MYVOL to the target directory with the default maximum allowed size of 1000 megabytes. Only storage required to create and initialize the virtual volume will be allocated at the time of the create. The target directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 6: Adding a New Tape Image Catalog Entry with Allocation.
ADDIMGCLGE IMGCLG(TAPECLG) FROMFILE(*NEW) TOFILE(TAP002)
IMGSIZ(5000) ALCSTG(*IMGSIZ)
This command adds new image file TAP002 to the target directory with a maximum size of 5000 megabytes. All 5000 megabytes of storage will be allocated for this image file when it is created. The target directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.
Example 7: Adding an Image Catalog Entry from the Image Catalog Directory
ADDIMGCLGE IMGCLG(MYCLG) FROMFILE('/MyClgDir/MyFile.img')
TOFILE(*FROMFILE)
This command updates the image catalog MYCLG with information about image file MyFile.img.
| Top |
Error messages
*ESCAPE Messages
- CPFBC28
- Image catalog entry not added to image catalog &1.
- CPFBC45
- Image catalog &1 not found.
- CPF9802
- Not authorized to object &2 in &3.
- CPF9820
- Not authorized to use library &1.
| Top |