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:

1. 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 type image catalogs.
2. An image file located in a directory. The image file can exist in any directory that is accessible through the Copy Object (CPY) command.
3. 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:

1. If REPLACE(*NO) is specified, an error message will be issued and the catalog entry in the image catalog will not be replaced.
2. If REPLACE(*YES) is specified, the catalog entry in the image catalog will be replaced.
3. 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:

• This command is shipped with public *EXCLUDE authority.
• The following authorities are required to add an image catalog entry:
  1. Execute (*EXECUTE) authority to library QUSRSYS.
  2. *CHANGE authority to the image catalog.
  3. Execute (*X) authority to each directory in the image catalog path name.
  4. If adding an image file from physical media, the following additional authorities are required:
     1. *USE authority to the physical device is required.
  5. 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.
• Adding from physical CD or DVD media is only supported for optical type image catalogs.
• This command does not support dependent image catalogs.
• The following parameters are only valid for tape type image catalogs:
  1. ALCSTG
  2. VOLTYP
  3. DENSITY
  4. NEWOWNID
  5. CODE

  If any of the above parameters are specified for an optical type image catalog, they will be ignored.

Parameters

Keyword	Description	Choices	Notes
IMGCLG	Image catalog	Name	Required, Positional 1
FROMDEV	From optical device, or	Name	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
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.

From optical device, or (FROMDEV)

Specifies the CD or DVD device from which the optical image is to be copied. For optical type 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 type 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.

From image file (FROMFILE)

Specifies the image file to be copied. For optical type 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 type 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

Specifies that 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.

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. This value is not allowed if *NEW is specified on the FROMFILE parameter.

*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.

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.

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

Specify that the existing catalog entry will not be replaced and an error message will be issued.

*YES

Specify that the existing image catalog entry will be replaced.

*INSERT

Specify that 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.

Image size (IMGSIZ)

Specifies the size of the new image file that is to be created.

For optical type image catalogs, this parameter indicates the size of the optical image file that is to be created and the amount of system storage to be allocated.

For tape type 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

Specifies that 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 type image catalogs, the maximum size of the image file created will be set to 1 gigabyte.

*CD650

Specifies 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

Specifies 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

Specifies 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. For optical image files, the valid range is 48-16000 megabytes. For tape image files, the valid range is 48-1000000 megabytes.

Text 'description' (TEXT)

Specifies the text that briefly describes the image being loaded.

*GEN

For optical type 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 type 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.

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

Specify to only allocate storage required to initialize the tape image file at the time of the create.

*IMGSIZ

Specify to allocate the entire amount of storage specified on the Image size (IMGSIZ) parameter.

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.

Volume type (VOLTYP)

Specifies the type of volume for this virtual tape volume.

*SL

Specify the type of volume is a standard labeled tape volume.

*NL

Specify the type of volume is a non-labeled tape volume.

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.

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.

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.

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 Type Image Catalog Entry

ADDIMGCLGE   IMGCLG(MYCLG)  FROMFILE(*NEW)  TOFILE(MYFILE)
             IMGSIZ(*CD650)

This command adds new optical image file MYFILE to the image catalog directory with a size of 650 megabytes. The image catalog directory is the directory specified for the Directory (DIR) parameter of the CRTIMGCLG command.

Example 5: Adding a New Tape Type 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 Type 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.

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.