z/OS Catalog Components

The Integrated Catalog Facility (ICF) consists of a number of components. These include

  • The Master Catalog
  • Several User catalogs
  • VSAM Volume Datasets

The Master Catalog and User Catalogs are both instances of Basic Catalog Structures or BCS for short.

   EADM Advert

Accelerate DB2 Write with zHyperWrite and "EADM™ by Improving DB2 Logs Volumes Response Time:

Defining a Catalog Structure

Accessing an uncatalogued dataset

You want to access a dataset on volume VOL001. If you know the volume serial number you can simply code it in, either in your JCL code, or on an ISPF panel. The allocation request goes to the VTOC, where it finds the exact cylinder and head location of the dataset. The Volume Table Of Contents (VTOC) also contains physical information about the dataset, such as its record length and blocksize, to allow the fetching program to make sense of the data.

This is fine if you know which volume you want. A typical z/OS shop will have a thousand or so disk volumes available, and several thousand tapes. It will also run DFSMS, an automated data allocation product. When you allocate a new file, DFSMS selects the target volume for you, usually ignoring any preference you might have had. This can make if difficult to find a file later, so what you need is a way to record the location of every file on the system. That is, you need an ICF catalog system to tell you exactly where every file is located.

The VSAM Volume DataSet (VVDS) is an essential component of the ICF catalog structure. It contains physical information about VSAM datasets, and also DFSMS information about non-VSAM datasets. The VVDS can also be considered to be an extension or the Volume table of Contents or VTOC and has a one to one relationship with each volume. Every SMS managed volume and every non-SMS volume that contains VSAM files will contain one VSAM volume Dataset (VVDS).

The diagram below shows the steps required to catalog up a dataset.

Building a Catalog

Define the Master Catalog

The Master Catalog is the starting point for all file allocations. It contains dataset location entries for all the essential system datasets that start SYS1.** and must contain the ones used to IPL (or boot) the operating system. It will also contain other dataset location entries, depending on your installation setup. However, the master catalog should not contain location information for all datasets, system performance would be really dire if it did. It should really only contain what's needed for an IPL and nothing else. It should be RACF protected to ensure that only systems programmers and storage managers can update it. Everybody else should get read only access.
Actually there is nothing special structurally about a master catalog, it is just a BCS. In fact a master catalog in one LPAR can be a user catalog in another LPAR. The master catalog is defined in SYS1.PARMLIB(LOADxx) and the definition will include the VOLSER that the catalog resides on. A simple way to find the name of the master catalog in any LPAR is to just do a LISTCAT against a SYS1.* dataset.

The rest of the location information is held in user catalogs, described on the next page.

So what is a catalog? Physically, its just a VSAM KSDS. Logically, you could think of it as like a telephone directory, except that every entry has to be unique. Each system partition or LPAR must have a master catalog, but it is possible to share a single master catalog between several LPARS.

Define User catalogs

User catalogs contain location information for the majority of your data. User catalogs are defined using IDCAMS with a syntax that looks like

  DEFINE USERCATALOG( -
    catalog name and other cluster parms -
    ICFCATALOG -
  DATA -
    data parms -
  INDEX -
    index parms -
  CATALOG(master.catalog.name)

Each User catalog is connected to the Master catalog using the IDCAMS 'import .. connect' command. User catalogs can be shared between LPARs, but if the LPARs have unique Master catalogs, then every User catalog must be connected to every Master catalog.

How many User catalogs are required? You basically need enough to spread the performance load, and also to spread the risk of catalog failure. More about this in the next section, about aliases.

If you want to delete a User catalog, use the IDCAMS command

  DELETE USERCATALOG ( -
    name -
  RECOVER -
  USERCATALOG

This physically deletes the catalog. but the RECOVER parameter keeps the aliases that pointed to that catalog intact in the Master catalog.

Define Aliases

The Master catalog contains a list of aliases which point to the correct User catalog. You do this with the IDCAMS command 'define alias {name} relate catalog {name}'. This is the point where you need to sit down and work out your catalog structure and naming standards. The 'alias' is the high level qualifier, or the bit of the dataset name before the first dot. (It is possible to set catalogs up with multi-level aliases, but I'm keeping this simple. I like it that way, its easier to fix when it breaks}.

If you want to define a new AXP alias you have two things to worry about. First, will your AXP alias be used heavily? If so, you don't want to put it into a User Catalog which is already busy. Second, a User catalog is a single point of failure. If AXP forms part of an application, then its best to keep it in a different catalog from other, independent applications. If the catalog fails, then you limit the impact to one application system. So in other words, you need enough user catalogs to separate out applications, and to keep busy aliases separate. However be sensible. If you have five hundred applications it would probably not be a good idea to have five hundred catalogs as you need to monitor and maintain them all. In this case, group applications together into sets that make sense in business and recovery terms and give each group its own catalog.

If you need to list out all the defined aliases that are defined in the master catalog use the IDCAMS command

LISTCAT ALIAS CAT(master.catalog.name)

If you want to delete an alias use the DELETE ALIAS command. If you want to delete all the aliases that are defined to one user catalog, the easiest way is to use the EXPORT .. DISCONNECT command, followed by IMPORT .. CONNECT. DISCONNECT will delete all the aliases, but CONNECT does not re-define them. Before you do that, I'd suggest saving the output from a LISTCAT ALAIS command as above, just in case you need to put them back again.

Catalog the dataset

Finally, you add a dataset entry to the user catalog, which points to VOL001. That's a long winded way of saying that you catalog the dataset. This is normally done for you automatically when you allocate the file. Uncatalogued datasets can be defined using the IDCAMS DEFINE ... RECATALOG command.

For each dataset, the catalog entry contains the volume location, DFSMS data and the dataset type. The physical information about the dataset is held in the VTOC and the VVDS. Every volume (unless it is non-SMS and contains no VSAM files) has a VVDS, which is always called SYS1.VVDS.Vvolser, so the relationships between volume and VVDS is 1:1.
The information held for a VSAM record includes The Catalog Sphere or base cluster record, the True Name, which is the actual name of a VSAM component and is used to access components directly, and the Path Record, which contains the paths to alternate indexes.

A volume can contain several catalogs, and typically, a volume will contain datasets which are catalogued in several catalogs, so the relationship between volume and catalog is n:n. There are no proscribed naming standards for catalogs, but a good one is catalog.** Since the introduction of hypervolumes it has been standard practice to allocate each catalog on its own, dedicated volume. This may not be necessary since PAV aliases were introduced, but it still seems to be a intuitively sensible thing to do.

Catalog Management and CAS

Catalog management is handled by the Catalog Address Space (CAS), and communicates with the users address spaces using cross memory services. CAS contains the info needed to handle catalog requests like control block info for open catalogs, aliases and VOLSERs. Data is loaded into CAS at IPL time. Catalogs are opened in CAS the first time they are accessed, and are usually kept open until the system is IPLd. There are several commands available to check and manage CAS. Here are a few, but use these with caution, because if CAS abends, then your system will probably come down with it

  • F CATALOG,REPORT - info about CAS
  • F CATALOG,OPEN - info about open catalogs
  • F CATALOG,CLOSE(catname) - refresh a catalog's control blocks in CAS
  • F CATALOG,UNALLOCATE(catname) - unallocate and refresh the control blocks
  • F CATALOG,VCLOSE(volser) - refresh the control blocks for a VVDS
  • F CATALOG,RESTART - use this one as a last resort if you are having severe catalog problems. CAS will be abended and then restarted in a new address space. If the restart fails then the only recovery option is to IPL.

ICF Catalogs with RLS

The VSAM RLS (Record Level Sharing) page describes how RLS provides multisystem sharing at a record level across a sysplex using the coupling facility (CF). VSAM RLS uses a CF-based Lock Manager and CF Cache Manager in the implementation of Record Level Sharing. DFSMS V2.1 introduced RLS usage for ICF catalogs, with the intention of improving catalog performance and availability. RLS provides locking at a record level, rather than having to serialize on the the whole shared catalog when updating. It also places the catalogs self describing VVR in the Coupling Facility to reduce I/O. Master catalogs cannot use RLS.
For catalogs in RLS mode the catalog records are placed in RLS local buffer pools or CF cache structures. The STORAGECLASS cacheset defines which cache structure to use. The DATACLAS controls buffer pool (64 bit) and caching options through the RLSOVETHEBAR and RLSCFCACHE settings. Other tuning parameters like STRNO, BUFND, BUFNI on DEFINE USERCATALOG command, these settings will be ignored in an RLS environment. RLS will obtain buffers dynamically as they may be needed using System Managed Buffering.

ICF catalogs can have 4 possible RLS states

  1. Eligible means that the catalog has been defined with, or altered to have the LOG attribute. This is the first stage for getting the catalog access into RLS mode, but at this stage a catalog OPEN will still be non-RLS.
  2. RLS quiesced means that the RLS quiesced indicator is set to YES, and the catalog can only be opened in non-RLS mode.
  3. RLS enabled means that the RLS enable indicator is set to YES and the catalog will be opened in RLS mode.
  4. RLS mode means that the catalog is currently open in RLS mode or was last closed in RLS mode.

Some new parameters are available on the IDCAMS DEFINE statement of catalog RLS processing. These are

  • LOG(NONE) Catalog is eligible for access in RLS mode. In the first implementation, only unrecoverable catalogs are supported, hence LOG(NONE)
  • SUSPEND Requests will be suspended until a RESUME has been issued.
  • RESUME Request for the catalog will be executed immediately. Command will release a SUSPEND state.
  • RLSQUIESCE The catalog will be accessed in non-RLS mode following the define.
  • RLSENABLE The catalog will be accessed in RLS mode after the allocation.
  • RECONNECT Request the new catalog to use existing ALIAS information.

If the catalog is in LOCKED or SUSPENDED mode, an authorized user with READ access to the RACF STGADMIN profile can still access and repair a locked catalog. At the same time, other operations against the catalog will be failed or queued.

Typical allocation JCL for a catalog enabled for RLS looks like this. LOG(NONE) is used to prepare for RLS, and RLSENABLE will enable OPEN in RLS mode.

DEFINE USERCATALOG -
(NAME(Catalog.name) ICFCATALOG -
VOLUME(volser) TRK(50 50) -
LOG(NONE) RECONNECT RLSENABLE -
FREESPACE(20 20) -
NOIMBED NOREPLICATE) -
DATA (CISZ(32768))

Symbolic Aliases

Extended catalog aliases are used to refer to a dataset by another name. This could typically be useful if you need to rename files, but do not want to have to alter all the applications and JCL that refer to that file. So for example if you rename a file called SWX.CX04.CLIST, currently catalogued in CATALOG.USER4 to HMARC.USER.CLIST, then you can still access that file as SWX.CX04.CLIST by defining an extended alias like this

Define alias -
  (name(SWX.CX04.CLIST) -
  relate(HMARC.USER.CLIST)) -
  catalog(CATALOG.USER4)

However extended aliases do not work for VSAM files.

From DFSMS/MVS 1.5 you can extend this idea further with symbolic aliases. Suppose you have a file name that is different depending on which LPAR you are running on, for example SWX.COBOL.release.LOAD. If you have lots of LPARS, it would be a real pain to have to work out which LPAR you are on, then adjust your filename to suit. It would be much better if you can just call your file SWX.COBOL.LOAD and let the system work it out the correct release level for you. That is exactly what symbolic aliases does.

System symbols are defined in SYS1.PARMLIB member IEASYMxx, with a list of symbols for each LPAR defined like this

LPARNAME(SYSA)
SYSNAME(SA00)
SYMDEF(&COLEVEL='V312')
SYMDEF(&SITE='DC01')
SYMDEF ... more symbols

You must define a set of symbols for every LPAR and unfortunately you need an IPL on every system for them to take effect, so this is not something that you will change very often. Once the symbols are defined and active you can define an extended catalog alias using the symbolic relate parameter like this

DEFINE ALIAS -
  (NAME(SWX.COBOL.LOAD) -
  SYMBOLICRELATE(SWX.COBOL.&COLEVEL..LOAD)) -
  CATALOG(CATALOG.USER4)

Note the double period at the end of the symbol variable. The first period defines the end of the variable and the second period is included in the resolved DSN. The catalog name will be the correct catalog for the alias at your site, of course.

You can check to see if aliases are defined, and what they relate to with the listcat command

LISTC CATALOG('CATALOG.USER4) ALIAS

will list all the extended aliases that are defined in catalog.user4

You can check individual datasets with the standard listcat

LISTCAT ENT(MGUTILS.TEMP.RUNDECKS) ALL

result

ALIAS --------- MGUTILS.TEMP.RUNDECKS
    HISTORY
      RELEASE----------------2
     ASSOCIATIONS
      NONVSAM--MIGRO.BATCH.JCL

If you run a listcat against a real dataset that has aliases pointing to it, you will see something like this

NONVSAM ------- MIGRO.BATCH.JCL
    IN-CAT --- UCAT.APPLS
    HISTORY
      DATASET-OWNER-----(NULL) CREATION--------2006.093
      RELEASE----------------2 EXPIRATION------0000.000
      ACCOUNT-INFO-----------------------------------(NULL)
      DSNTYPE----------LIBRARY
    SMSDATA
      STORAGECLASS ---SCFWSTST MANAGEMENTCLASS--M7M30B2
      DATACLASS --------(NULL) LBACKUP ---2008.234.0608
    VOLUMES
      VOLSER------------DX312D DEVTYPE------X'3010200F' ---------0
    ASSOCIATIONS
      ALIAS----MGUTILS.TEMP.RUNDECKS
      ALIAS----GUS0250.TEMP.RUNDECKS

A listcat of an alias that contains symbolic references will look like this

ALIAS --------- SYSTEM.GDPS.GEOPARM
    IN-CAT --- UCAT.APPL
    HISTORY
    ASSOCIATIONS
      SYMBOLIC-SYSX.GDPS.&SYSPLEX..GEOPARM
      RESOLVED-SYSX.GDPS.PBOR1.GEOPARM

back to top