Management, Fault finding and fixing

This page describes how to use raw IDCAMS to investigate and fix catalog problems. It is usually easier to use a maintenance product for this. The shortcuts below will take you to specific points on the page.

Working out Catalog space requirements

How do you work out how much space to allocate to a catalog, if you know how many records you will be adding? Someone asked me this recently and it was not easy to find an answer, so I thought it worthwhile to add the detail here

There is no simple answer to this question, as catalogs use variable length records and the amount of space used will depend on your average record size. It will also depend of the amount of freespace that you specify when you allocate the catalog. If your catalog will hold a large proportion of GDG files or DB2 databases, then they will have long file names and so will use more disk space. Ron Ferguson, who knows his way around a catalog, estimates that the average record size of a catalog entry is 106 bytes, so I'm using that figure as a starting point. You may want to check with your own catalogs to get the best size for your site.
Assuming that you allocate your catalog with a 4096 CI size and 20-20 freespace, then a 4K CI with 20% free space will hold (4096/106)*0.8 = 30 records.
At 10 blocks to a track, that is 300 records.
Assuming your CA size is 15 tracks, and your freespace is 20,20 then on initial load you will get (300*15)*0.8 = 3,600 records per cylinder.
100,000 records will then need just over 27 cylinders, which is not very much!

However, like I said, it's not an exact science. I'd add in 50 cylinders at least, just to be on the safe side.

Back to top

Listing catalog information

The ICF catalog structure is complex, so if you have a problem, the first thing to work out is exactly which component is broken. Typically you'll be passed a problem ticket from someone who cannot access his data. Start by querying the catalog status for an affected file, by using the listcat command. The easiest way is to pick up a file list from ISPF option 3.4, then type the following line command against a file.


Here's a tip which you probably know already. You'll find yourself using the listcat command all the time. Shortcut it by sticking the following clist into a command library in your logon procedure. Type TSO LISTA to find an appropriate library. Add the clist as member name LC.


Now when you want to list the catalog entry for a dataset, all you need to do is type LC against it.
The LISTCAT output tells you; which catalog the dataset entry is in, which volume the catalog thinks the dataset is on, and SMS class information. You get a lot more detail for VSAM datasets.

Back to top

Checking the physical condition of a Catalog

If you are getting a lot of problems in the same catalog, then it is possible you have a physical error on the catalog dataset (it is just a VSAM KSDS). Physical errors often cause the catalog backups to fail too. If you use
against a catalog, it will tell you which master catalog it is in, which volume it is on, and a list of all the aliases which point to it. To see the full VSAM information, you need to use
listcat ent(/) catalog(/) all

To check the physical status of the catalog, run the following IDCAMS statements in batch

) -

  and hopefully you see the output


If the examine reports problems, then you might have to recover the catalog, as described on the next page. However, before you start to recover, try an IDCAMS verify first, as it might just be that the file was not closed properly.
The syntax is


If you have a catalog maintenance product onsite, it will have functions to allow you to fix physical catalog errors. The maintenance product section has more details.

Back to top

Checking the logical Catalog condition

The following IDCAMS command will check that the dataset entries in a catalog are complete. For example, it will check that VSAM truenames are associated with a cluster record.


  and you should see

followed by a list of all the entries

It is a good idea to schedule regular DIAGNOSE commands for all ICF catalogs through your scheduling package. This means you will get an early warning of any problems that result in non-zero return codes, which lets you fix the problem before things get worse.

If your diagnose runs clean, but you still get catalog errors, try refreshing the catalog buffers using the console command


The following command will check out the logical structure of a VVDS

    INFILE(DD1) -

All the previous two commands do is check out that a single catalog entity is correct. What you need, is to ensure all the catalog components are consistent.


This will check that the entries in a catalog are consistent with those in one VVDS. It does not check out the entries in all the other VVDS datasets. To find out which VVDSs are referenced by a catalog, use the command

listcat level(sys1.vvds) catalog(CATALOG.ICFUSER.VOL001)

Two errors are possible. If the VVDS contains datasets, but there are no catalog entries for them, create them by using


If the Catalog contains entries, but they are not in the VVDS and don't physically exist, use


The next command will validate a VVDS against a catalog

    INFILE(DD1) -

If you end up with a missing VSAM Volume Record (VVR) for one component of a VSAM file, then do a delete / noscratch at the cluster level first to clean things up. That leaves all the components uncatalogued. Then do a define without the recatalog parameter, specifying the correct volumes and allocated space for the file you are fixing. So in the IDCAMS statement below, change the dataset name, volumes and space as appropriate.


IBM removed support for VSAM parameters IMBED and REPLICATE some time ago. They must be removed from all catalogs before you install z/OS 1.8 or they will cause abends.

The number of processing strings is quite critical to catalog performance as they control the number of possible parallel read requests. The default value is 2, but this is too low. Consider changing your strings 5 or 7, depending on how busy it is. You will also need the correct number of data and index buffers. 5 data buffers and 7 index buffers are about right for 5 strings. If you define more buffers than this you are probably just wasting storage.

Catalog tuning was automated in z/OS R1V7, so CAS will now adjust strings and buffers on a regular basis based on current performance. You can disable that automation with the command


z/OS uses hardware reserves by default to ensure catalog integrity in a shared environment. If all your LPARs are in the same GRSplex then consider changing the reserve on the SYSIGGV2 resource to an ENQ. Problems have been reported with converting hardware reserves to dataset enqueues with CA-MIM. Consider using GRS in a STAR configuration instead.

Extended Catalog Sharing (ECS) can improve performance between LPARs as this puts the VVDS serialisation information into the coupling facility. This means that no IO is required for serialisation which apparently reduces IO by 50%. This was problematical at first but seems to be stable now.

A better solution is to use Record Level Sharing (RLS) on your user catalogs as this uses locking at a logical record level to serialise catalog updates. RLS is not supported for master catalogs, so they should use ECS

There are two commands you can use to see how your catalogs are performing at present. These are


In general, there is no point in performing catalog reorgs to remove CA and CI splits as they will soon re-appear once the reorg finishes. However, catalogs are just VSAM files and so limited to 123 extents, so if you see a catalog with a high number of extents, then a reorg is necessary. If you have a catalog management product then you should be able to reorg the catalog while it is open. Otherwise the reorg is a disruptive process and will need downtime scheduling. It is best to use CA reclaim with catalogs to minimise reorg requirements.
If you have a very active high-level qualifier that creates a lot if insets in a catalog, consider moving that qualifier to a dedicated ICF catalog.

back to top

Managing VSAM files

Lascon updTES

I retired 2 years ago, and so I'm out of touch with the latest in the data storage world. The Lascon site has not been updated since July 2021, and probably will not get updated very much again. The site hosting is paid up until early 2023 when it will almost certainly disappear.
Lascon Storage was conceived in 2000, and technology has changed massively over those 22 years. It's been fun, but I guess it's time to call it a day. Thanks to all my readers in that time. I hope you managed to find something useful in there.
All the best