Create Image Catalog (CRTIMGCLG)

The Create Image Catalog (CRTIMGCLG) command is used to create an image catalog object (*IMGCLG) in library QUSRSYS and associate the image catalog with a target directory.

This command also creates an image catalog object QIMGCLG of type stream file (*STMF) in the directory specified on the Directory (DIR) parameter. This catalog object is used when IMPORT(*YES) is specified on the Create Image Catalog (CRTIMGCLG) or Change Image Catalog (CHGIMGCLG) commands to recover your image catalog from the image catalog directory.

An image catalog can be associated with a virtual optical or virtual tape device. It contains information about images that have been added to the image catalog using the Add Image Catalog Entry (ADDIMGCLGE) command. The image catalog contains the following information:

Directory name

The directory where the image files will reside.

Device name

The device name of the virtual device associated with the image catalog.

Catalog Status

The current status of the image catalog and its association with a virtual device.

Catalog Auxiliary Storage Pool (ASP) Threshold

The percentage of the auxiliary storage pool (ASP) that a virtual volume will be allowed to use during creation and additional space allocation.

The image catalog contains the following information for each entry:

Image file name

The name of the image file.

Volume identifier or name

The formatted name of the optical or tape volume that image file represents.

Index number

The order of this image within the image catalog.

Image file status

The status of the image within the virtual device.

Text

A short description of the image.

Restrictions:

• The following authorities are required to create an image catalog:
  1. Read (*READ) and Add (*ADD) authority to library QUSRSYS.
  2. Execute (*X) authority to each directory in the image catalog path name.
• If the REFIMGCLG parameter is specified, the following additional authorities are required:
  1. Use (*USE) authority to the reference image catalog.
  2. Execute (*EXECUTE) authority to library QUSRSYS.
• If the Add virtual volumes (ADDVRTVOL) parameter is specified, the following additional authorities are required:
  1. Execute (*EXECUTE) authority to library QUSRSYS.
  2. Change (*CHANGE) authority to the image catalog.
• If IMPORT(*YES) is specified, read (*R) and object management (*OBJMGT)authorities are required to the image catalog object in the directory as specified on the Directory (DIR) parameter.
• A directory can only be associated with a single image catalog.
• If DIR(*REFIMGCLG) is specified, the catalog defined by the REFIMGCLG parameter must not be in ready status.
• The following file-systems are supported for the image catalog directory:
  1. "root" (/)
  2. QOpenSys
  3. Mounted user-defined file system (UDFS)
  4. QOPT when the volume is initialized as a container.
• The root directory of a UDFS is not supported for the image catalog directory.

Parameters

Image catalog (IMGCLG)

Specifies the image catalog to be created.

This is a required parameter.

name

Specify the name of the image catalog.

Directory (DIR)

Specifies the directory to be associated with this image catalog.

This is a required parameter.

path-name

Specify the path name of the directory for the image catalog. If symbolic links exist in the path name, the links will be resolved and the absolute path will be used.

*REFIMGCLG

Specify the name of another image catalog as a reference for the new image catalog.

Note: The requirements for catalogs created using the *REFIMGCLG parameter are complex with respect to the limitations and supported uses. For details see the Storage solutions category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Image catalog type (TYPE)

Specifies the type of image catalog to create.

*OPT

This is an optical image catalog. Only optical image catalog entries are allowed in this type of catalog.

*TAP

This is a tape image catalog. Only tape image catalog entries are allowed in this type of catalog.

Create directory (CRTDIR)

Specifies whether the directory (DIR parameter) should be created if it doesn't exist.

*YES

The directory will be created if it does not exist. The created directory will have the following default authorities:

                Data            Object Authorities
User         Authority     Exist  Mgt  Alter  Ref
*PUBLIC        *EXCLUDE
Owner          *RWX          X     X     X     X

For all other attributes, the defaults as provided on the CRTDIR command are chosen.

*NO

The directory will not be created.

Import image catalog (IMPORT)

Specifies whether to import the catalog and entry information from the image catalog directory.

*NO

Create the image catalog with no information from the image catalog directory.

*YES

Create the catalog by importing the data from image catalog object QIMGCLG located in the directory specified on the Directory (DIR) parameter.

Note: The values of the Image catalog (IMGCLG), Directory (DIR), and Text description (TEXT) parameters specified on the Create Image Catalog (CRTIMGCLG) command are used for the image catalog. All other values are imported from image catalog object QIMGCLG.

Catalog ASP threshold (CLGASPTHLD)

Specifies the percentage of the auxiliary storage pool (ASP) that a virtual volume will be allowed to use during creation and additional space allocation. This value is enforced when new volumes are added, allocated, or when files are expanding during write operations. For image catalogs residing in QOPT file system, the ASP threshold value is ignored and set to *MAX.

*CALC

The maximum storage threshold is calculated. The ASP space to be used by an image catalog virtual volume is the greater of either 95% or 5GB of space remaining in the ASP. The tape operation will stop with an end of media error when the maximum storage threshold for the virtual volume is reached. Adding of a virtual volume will also check for this limit when ALCSTG(*IMGSIZ) is specified.

*MAX

The maximum storage available in the location of the image catalog directory will be used by virtual volumes.

1-99

Specify the percent of image catalog directory ASP space to be used by virtual volumes.

Add virtual volumes (ADDVRTVOL)

Specifies the number of virtual volumes to automatically add to the image catalog or to add volumes based on the existing files in the image catalog directory. The following attributes will be used in the creation of these new virtual volumes:

1. PREFIX
2. ALCSTG
3. VOLNAM
4. VOLTYP
5. DENSITY
6. NEWOWNID
7. CODE

This parameter is valid for tape and optical image catalogs. For optical image catalogs, volumes are added, fully allocated and are not initialized. For tape image catalogs, volumes are added and initialized. For additional information, refer to the Add Image Catalog Entry (ADDIMGCLGE) command. The *DIR parmameter finds files within the image catalog directory and adds them to the specified image catalog.

Addimg volumes from existing image files can be controlled by the IMGTYPE parameter. The IMGTYPE options are:

1. *ALL
2. *ISO
3. *BIN

All options are valid for optical image catalogs. Tape image catalog only support the *ALL and *BIN options. For additional information, refer to the Fill Image Catalog (QVOIFIMG) API.

*NONE

No virtual volumes will be added.

*DIR

Specify to add virtual volumes from image files in the image catalog directory.

1-256

Specify the number of virtual volumes to add to the image catalog.

Image file type (IMGTYPE)

Specifies the type of image files to add to the image catalog.

*ALL

Specifies that all files found in the image catalog directory will be added to the image catalog.

*ISO

Specifies that files that have an extension of .iso will get added to the specified image catalog. A value of *ISO will only work with an optical image catalog. If a value of *ISO is specified along with a tape image catalog, the catalog will not be changed.

*BIN

Specifies that files that have an extension of .bin will get added to the specified image catalog.

For tape image catalogs, only valid tape image files will be added to the catalog.

For optical image catalogs, tape image files will not be added to the catalog.

Reference image catalog (REFIMGCLG)

Specifies the name of the image catalog as a reference for the new image catalog. The new dependent image catalog will contain the image catalog entries that exist in the reference image catalog at the time the dependent image catalog is created. Any additional changes to the reference image catalog will not be reflected in the dependent image catalog.

This parameter is valid only when DIR(*REFIMGCLG) is specified.

name

Specify the name of the reference image catalog.

File and volume name prefix (PREFIX)

Specifies the 3 characters used to generate volume names and file names for the ADDVRTVOL parameter.

*GEN

The 3 character volume name and image file name prefix will be generated by the system.

character-value

Specify up to a 3 character prefix to be used to generate volume and image file names.

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

Image size (IMGSIZ)

Specifies the size of the new image files that are 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 from the specified directory location to be allocated.

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.

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.

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.

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.

Text 'description' (TEXT)

Specifies the text that briefly describes the image catalog being created.

*BLANK

The text description will be blank.

character-value

Specify up to 50 characters of text for this image catalog.

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*EXCLUDE

The user cannot access the object.

*LIBCRTAUT

The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will not affect any existing objects.

*CHANGE

The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL

The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.

*USE

The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.

name

Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Examples

Example 1: Creating an Optical Image Catalog

CRTIMGCLG   IMGCLG(MYCLG)  DIR('/MyDir')

This command creates optical image catalog MYCLG in library QUSRSYS and associates directory /Mydir with it.

Example 2: Creating an Image Catalog Using a Reference Image Catalog

CRTIMGCLG   IMGCLG(MYCLG)  DIR(*REFIMGCLG) REFIMGCLG(MYCLG2)

This command creates optical image catalog MYCLG, based on image catalog MYCLG2 in library QUSRSYS and associates the directory specified in image catalog MYCLG2 with it.

Example 3: Creating a Tape Image Catalog

CRTIMGCLG   IMGCLG(TAPECLG)  DIR('/TapeDir') TYPE(*TAP)

This command creates tape image catalog TAPECLG in library QUSRSYS and associates directory /TapeDir with it.

Example 4: Creating a Tape Image Catalog with Additional Volumes

CRTIMGCLG   IMGCLG(TAPECLG)  DIR('/TapeDir') TYPE(*TAP)
            ADDVRTVOL(12)  IMGSIZ(1500)

This command creates tape image catalog TAPECLG in library QUSRSYS and associates directory /TapeDir with it. It adds 12 tape volumes with default volume values and a maximum size of 1500 MB. The default volume values are as follows:

• PREFIX(*GEN)
• ALCSTG(*MIN)
• VOLTYP(*SL)
• DENSITY(*VRT256K)
• NEWOWNID(*BLANK)
• CODE(*EBCDIC)

Example 5: Creating an Image Catalog Imported From the Image Catalog Directory

CRTIMGCLG   IMGCLG(MYCLG)  DIR('/MyDir') IMPORT(*YES)

This command creates image catalog MYCLG in library QUSRSYS and associates directory /MyDir with it. It updates the catalog and entry information from the catalog directory.

Example 6: Creating a Optical Image Catalog with Additional Volumes

CRTIMGCLG   IMGCLG(MYCLG)  DIR('/MyDir') TYPE(*OPT)
            ADDVRTVOL(4) PREFIX(ABC) MEDTYPE(*RAM) IMGSIZ(*DVD4700)

This command creates optical image catalog MYCLG in library QUSRSYS and associates directory /MyDir with it. It adds 4 optical volumes with a prefix of ABC, media type of *RAM, and a size of *DVD4700.

Example 7: Creating a Optical Image Catalog and Add Image Files

CRTIMGCLG   IMGCLG(MYCLG)  DIR('/MyDir') TYPE(*OPT)
            ADDVRTVOL(*DIR) IMGTYPE(*ALL)

This command creates optical image catalog MYCLG in library QUSRSYS and associates directory /MyDir with it. All image files other than tape image files found in the associated directory are added to the catalog.

Error messages

*ESCAPE Messages

CPFBC02

Image catalog &1 was not created in library &2.

CPFBC12

Image catalog &1 created. &2 of &3 volumes not added.

CPFBC45

Image catalog &1 not found.

CPF9802

Not authorized to object &2 in &3.

CPF9820

Not authorized to use library &1.