Table of Contents
This chapter provides a general description of the catalog including its structure, searching order and the master catalog, and describes how to manage catalogs and use associated tools.
In OpenFrame, the integrated catalog module and related tools are provided to manage meta information about data sets. A catalog plays the role of a central information counter for a data set.
VSAM data sets must be registered in a catalog before being used. Non-VSAM data sets may be used without being registered to the catalog. To use a non-VSAM data set that are not registered in a catalog, you must specify all information about the data set or the volume on which the data set resides.
A catalog contains meta information about other data sets. By cataloging a data set, you can access the data set with its name even when you do not know the exact location of the data set. This allows you to use data sets without knowing system storage settings.
The catalog is composed of two types of data sets in mainframe systems: BCS data sets and VVDS data sets. In OpenFrame, a BCS data set comprises a catalog table, and a VVDS data set is combined with VTOC to form a VTOC table. A catalog table includes information about basic attributes, volume, user permissions, and relationships with other entries.
When you use a cataloged data set or create a data set to be registered in a catalog, multiple catalogs are searched in order to find an appropriate catalog.
A catalog search order is decided by the catalog alias, name, or alias search level. An alias search level is a system setting that determines how many high-level qualifiers for data set names are to be examined.
Most catalog searches are based on the catalog alias. An appropriate alias is identical to the high-level qualifier of a data set name, and if all catalogs have such aliases, the system easily finds a catalog that is needed to process your request.
Alternatively, you can specify catalogs by using JOBCAT or STEPCAT in JCL, or the access method services CATALOG parameter.
The following is the order of search conditions used to find or define a data set.
If the system catalog is specified, the catalog is searched.
When the IDCAMS utility CATALOG parameter is given, the corresponding catalog is searched.
If it is a GDS data set, the catalog with a defined GDG BASE is searched.
The catalog designated by STEPCAT or JOBCAT in JCL is searched.
If a high-level qualifier of a specific catalog is an alias, the catalog is searched.
Lastly, the master catalog is searched.
When you are using a system catalog with the AMP parameter set to AMORG, the system catalog is not searched.
A master catalog is similar to a user catalog in terms of structure. The difference between the two is how it is being used and what data sets are being cataloged. The OpenFrame system can only use one master catalog at a time.
The master catalog has all the user catalogs registered to a system and all the alias entries pointing to user catalogs. General data sets used by an application as well as user catalogs can be registered to a system.
Entries being registered to a master catalog are as follows:
A system catalog has been used before integrated catalogs. It can be used in OpenFrame by specifying a user catalog as the system catalog. The OpenFrame system can only use one system catalog at a time as for the master catalog.
When using the system catalog, non-VSAM, GDG, GDS, and non-VSAM alias entries are registered in the system catalog and VSAM entries are registered in a master or user catalog.
To find a data set, the data set is first searched in the system catalog. However, if AMORG is specified in the AMP parameter of an FD statement in JCL, the data set is not searched in the system catalog. When a new non-VSAM data set or GDG is defined or deleted using a data set management tool, such as dscreate, dsdelete, gdgcreate, and gdgdelete, it is defined in or deleted from the system catalog even if a particular catalog name is specified.
For more information about configuration for using the system catalog, refer to OpenFrame Configuration Guide.
The entry types registered in the OpenFrame integrated catalog and descriptions of each catalog entry are described as follows:
| Catalog Entry | Description |
|---|---|
Non-VSAM data set catalog entry. If a non-VSAM data set is registered in a catalog, its volume information can be found in the catalog. Using the volume information, the data set information can be obtained from VTOC. | |
GDG catalog entry. It includes GDG attributes, such as GDG LIMIT, and names of associated data sets. | |
GDS catalog entry. The data being stored, in general, is identical to a non-VSAM data set entry. It stores the GDG name as a related entry. | |
VSAM cluster catalog entry. It is registered into the catalog to manage the VSAM data and index components with a single name. It stores data and index components' names as related entries. | |
VSAM data component catalog entry. This is the object that stores the actual record data of VSAM data set. | |
VSAM index component catalog entry. As an entry for the binary tree object, it allows for a faster search of the VSAM data set's primary key. | |
Alternate index catalog entry. The information being managed in the catalog is basically identical to that of the VSAM cluster, but the entry type is different. It stores the data component's name, index component's name, and the base cluster's name as related entries. | |
Alternate index path catalog entry. It defines the access path to a base cluster using the alternate index. It stores the alternate index name and base cluster name as related entries. | |
Catalog entry about user catalogs. User catalogs must also be cataloged in the master catalog, and the information stored is basically identical to the VSAM cluster. | |
Catalog entry about an alias. User catalogs can have multiple alias entries, and the aliases are used to determine the catalog search order. |
Information managed by the OpenFrame integrated catalog can be categorized into the information groups defined in the following table. Information from the Allocation Group and Statistics Group is managed in OpenFrame system tables.
| Information Group | Description |
|---|---|
Stores entry name, entry type, created data, expiry data and owner ID. | |
Stores storage class, management class, and data class. | |
Stores security setting and passwords. (Not supported in OpenFrame) | |
Stores volume serial and device type. | |
Stores average record size, maximum record size, key position, key length, VSAM type, VSAM attribute, AIX attribute and share option. | |
GDG limit, GDG attribute, and last modified date. | |
Stores type (PDS, GDS, or general) of the non-VSAM data set. | |
Stores information such as related entry count, entry name, and entry type. |
A new user catalog can be defined with the DEFINE USERCATALOG command of access method services. When using the DEFINE USERCATALOG command, the ICFCATALOG parameter must be specified.
The following example shows how a user catalog is created with the name SYS1.ICFCAT.TEST in the volume named SYS305. (The IDCAMS utility used in the example can be replaced with JSCVSUT or KQCAMS depending on the product.)
//DEFCAT EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DEFINE USERCATALOG -
( NAME(SYS1.ICFCAT.TEST) -
MEGABYTES(15 15) -
VOLUME(SYS305) -
ICFCATALOG -
FREESPACE(10 10) -
STRNO(3) ) -
DATA( CISZ(4096) -
BUFND(4) ) -
INDEX( BUFNI(4) )
/*
To use the catalog, the system must decide which specific data set is to be registered in which catalog, and the easiest way to achieve this is by defining an alias in the catalog.
There are cases when the user cannot access the data set due to an incorrect alias definition. Hence, you must carefully consider the effect a new alias may have on the existing data set.
After using the DEFINE USERCATALOG command of the access method services to define a user catalog, the DEFINE ALIAS command can be used to define an alias in the catalog. The catalog alias, like the user catalog, must be defined in the master catalog.
The following example defines two aliases, USER0001 and PROJECTA, in a user catalog named SYS1.ICFCAT.TEST. (The IDCAMS utility used in the example can be replaced with JSCVSUT or KQCAMS depending on the product.)
//ALIAS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DEFINE ALIAS -
( NAME(USER0001) -
RELATE(SYS1.ICFCAT.TEST) )
DEFINE ALIAS -
( NAME(PROJECTA) -
RELATE(SYS1.ICFCAT.TEST) )
/*
Using the LISTCAT command of the access method services, you can output the catalog record list and verify the catalog data set information. However, the LISCAT I/O statistical information about the user catalog is not accurate.
The following example shows how to check all aliases related to a specific user catalog by using LISTCAT. The alias is displayed in the Associations Group section. (The IDCAMS utility used in the example can be replaced with JSCVSUT or KQCAMS depending on the product.)
//LSTALIAS EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=A //SYSIN DD * LISTCAT ALL ENTRIES(SYS1.ICFCAT.TEST) /*
The DELETE command of the access method services can be used to delete user catalogs, cataloged data sets, and all other catalog entries.
Generally, there must be no registered entry in the user catalog that needs to be deleted. If there is, an option can be used to delete a user catalog that contains catalog entries.
If a user catalog is empty, the DELETE USERCATALOG command can be used to delete the user catalogs. This command removes data sets registered in the user catalog and user catalog entries registered in the master catalog.
If a user catalog is not empty, the DELETE USERCATALOG command can be used with the FORCE option. The FORCE option deletes aliases linked to a user catalog, which in turn deletes all data sets and catalog entries registered in the user catalog.
Related tools include IDCAMS(JSCVSUT/KQCAMS) and volmgr.
| Program/Utility | Description |
|---|---|
IDCAMS(JSCVSUT/KQCAMS) | Utility that manages mainframe data set and catalog information (for both VSAM and Non-VSAM data sets). For more information, refer to OpenFrame Utility Reference Guide. |
Tool that creates a space for managing volumes during the initial setup of an OpenFrame product. |
The volmgr tool creates, updates, deletes and queries volumes and devices during the initial setup or operation of an OpenFrame product.
Starting from OpenFrame 7.1, VOLUME, DEVICE and ESOTERIC are managed by volmgr, and ESOTERIC is now called a device group. Furthermore, a tape volume can be created by using a specific option.
When installing OpenFrame for the first time, ofruisvr requires a volume creation before startup. To create, update and delete volumes without operating ofruisvr during installation, use the -i option. After the initial installation, you must execute commands without the -i option.
To create a volume in OpenFrame, a tablespace with the same name as the volume must be defined in the database. However, a tape volume can be created without a tablespace.
The following example shows how to execute volmgr:
Usage: volmgr <command> <type> [options]
Parameters
| Parameter | Description |
|---|---|
command |
|
type |
|
Options
The following are different options specified for each command:
DEFINE
When creating a volume
| Option | Description |
|---|---|
[-v volser] | Volume name. |
[-p path] | Volume directory path. |
[-dn device_number] | Device number. |
[-s spool] | Used for a spool volume. |
[-t tape] | Used to create a physical tape volume. |
[-lv logical_volume] | Used to specify a logical tape volume to connect when creating a physical tape volume. |
[-i init] | Used at the initial setup. |
When creating a device
| Option | Description |
|---|---|
[-dn device_number] | Device number. |
[-dt device_type] | Device type.
|
[-ms max_space] | Maximum space. |
When creating a device group
| Option | Description |
|---|---|
[-dn device_number] | Device number. |
[-dg device_group] | Device group. |
DELETE
When deleting a volume
| Option | Description |
|---|---|
[-v volser] | Name of the volume to be deleted. |
[-f force] | Force deletes a volume in use. |
[-t tape] | Used to delete a physical tape volume. |
[-i init] | Used at the initial setup. |
When deleting a device
| Option | Description |
|---|---|
[-dn device_number] | Number of the device to be deleted. |
[-f force] | Force deletes a device in use. |
When deleting a device group
| Option | Description |
|---|---|
[-dg device_group] | Device group to be deleted. |
[-dn device_number] | Number of the device to be deleted. |
UPDATE
When updating a volume
| Option | Description |
|---|---|
[-v volser] | Volume name. |
[-p path] | Volume directory path. |
[-dn device_number] | Device number. |
[-pv physical volume] | Used to update a physical tape volume connected with a logical tape volume. |
[-i init] | Used at the initial setup. |
When updating a device
| Option | Description |
|---|---|
[-dn device_number] | Device number. |
[-dt device_type] | Device type. |
[-ms max_space] | Maximum space. |
LIST
When searching for a volume
| Option | Description |
|---|---|
[-v volser] | Volume name. |
[-l] | Detailed information. |
[-d] | Uses raw type. |
[-t] | Used to retrieve the list of defined physical tape volumes. |
When searching for a device
| Option | Description |
|---|---|
[-dn device_number] | Device number to search for. |
When searching for a device group
| Option | Description |
|---|---|
[-dg device_group] | Device group. Cannot be used along with the -dn option. |
[-dn device_number] | Device number. Cannot be used along with the -dg option. |
The following creates a DEFVOL volume belonging to a device whose number is 0001 from a device group named SYSDA.
$ volmgr define device -dn 0001 -dt 3380 -ms 2048 $ volmgr define group -dn 0001 -dg SYSDA $ volmgr define volume -v DEFVOL -dn 0001 volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42 *** Volume Manager *** COMPLETED SUCCESSFULLY!
You can verify that the volume has been successfully created as follows:
$ volmgr list volume -v DEFVOL
volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42
*** Volume Manager ***
---------------------------------------------------------------------------------------------------------------------
Volume Total Usage Free Tablespace Volume Path
---------------------------------------------------------------------------------------------------------------------
DEFVOL | VSAM 100(MB) 13.75(%) 88320(KB) DEFVOL ------
| NONVSAM 179(GB) 76.51(%) 43145(MB) ------ /home/tmax/oframe_7_1/volume_DEFVOL
---------------------------------------------------------------------------------------------------------------------
* Total 1 volume entries printed.
COMPLETED SUCCESSFULLY!
The following defines a tape device and logical and physical tape volumes. It creates a physical tape volume and then connects it with a logical tape volume by using the UPDATE command.
$ volmgr define device -dn 0010 -dt 3480 -ms 2048 $ volmgr define group -dn 0010 -dg STAPE $ volmgr define volume -v STAPE1 -dn 0010 $ volmgr define volume -v ST0001 -lv STAPE1 -t $ volmgr update volume -v STAPE1 -pv ST0001 -t
The following deletes the DEFVOL volume and 0001 device.
$ volmgr delete volume -v DEFVOL $ volmgr delete device -dn 0001
The following deletes the SYSDA device group.
$ volmgr delete group -dg SYSDA
The following deletes the 0001 device in the SYSDA device group.
$ volmgr delete group -dg SYSDA -dn 0001
The following updates the DEFVOL volume and the 0002 device.
$ volmgr update volume -v DEFVOL -dn 0003 $ volmgr update device -dn 0002 -dt 3380 -ms 2048
The following connects the STAPE1 tape volume with the ST0002 physical tape volume.
$ volmgr update volume -v STAPE1 -pv ST0002
The following queries a volume list.
$ volmgr list volume
The result is as follows:
$ volmgr list volume
volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42
*** Volume Manager ***
--------------------------------------------------------------------------------------------------------------------
Volume Total Usage Free Tablespace Volume Path
--------------------------------------------------------------------------------------------------------------------
DEFVOL | VSAM 100(MB) 13.75(%) 88320(KB) DEFVOL ------
| NONVSAM 179(GB) 76.51(%) 43145(MB) ------ /home/tmax/oframe_7_1/volume_DEFVOL
--------------------------------------------------------------------------------------------------------------------
* Total 1 volume entries printed.
COMPLETED SUCCESSFULLY!
The following queries a physical tape volume list.
$ volmgr list volume -t
The result is as follows. The * mark followed by a volume name means that the physical tape volume is connected with a logical tape volume.
$ volmgr list volume -t volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42 *** Volume Manager *** ------------------------------------------------------------------------------------ Volume Linked Volume Volume Path ------------------------------------------------------------------------------------ NVOL00 | STAPE1 /home/arena/oframe_71_fix3/volume_NVOL00 ------------------------------------------------------------------------------------ *ST0001 | STAPE1 /home/arena/oframe_71_fix3/volume_ST0001 ------------------------------------------------------------------------------------ *ST0002 | STAPE3 /home/arena/oframe_71_fix3/volume_ST0002 ------------------------------------------------------------------------------------ ST0003 | STAPE3 /home/arena/oframe_71_fix3/volume_ST0003 ------------------------------------------------------------------------------------ * Total 4 volume entries printed.
The following queries device information.
$ volmgr list device
The result is as follows:
volmgr list device volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42 *** Volume Manager *** ------------------------------------------------------------------------------------------- Device Number | Device Type Volume Space Limit ------------------------------------------------------------------------------------------- 0001 | 3380 3000 4096 ------------------------------------------------------------------------------------------- 0002 | 3380 DEFVOL 2048 ------------------------------------------------------------------------------------------- 0005 | 3380 4000 4096 -------------------------------------------------------------------------------------------
The following queries device group information.
$ volmgr list group
The result is as follows:
volmgr list device
volmgr version 7.1.0(10) tmax@tgumdev:oframe_7_1_src/base(#1) 2019-10-21 10:16:42
*** Volume Manager ***
-------------------------------------------------------------------------------------------
Device Group | Device Number Device Type Volume Space Limit
-------------------------------------------------------------------------------------------
SYSBB | 0005 3380 3000 4096
-------------------------------------------------------------------------------------------
SYSDA | 0001 3380 DEFVOL 2048
| -----------------------------------------------------------------------
| 0002 3380 4000 4096
-------------------------------------------------------------------------------------------