technical: Squeezing Information From a Catalog
Catalogs are essential for anyone accessing z/OS datasets, including z/OS
itself. However accessing information from these catalogs has not necessarily
been straightforward. This article looks at doing exactly this: accesssing catalog
information. Both from interactive sessions, and programs.
Catalogs are special datasets that hold information about traditional z/OS
datasets. From humble beginnings tracking which physical device each dataset
was on, catalogs today hold information like:
- VSAM dataset values.
- DFSMS values such as management class, storage class and data class.
- DFSMShsm information has the dataset been migrated?.
- Where the dataset resides.
- ATL tape library values such as slots used and free.
- ATL tape volume information
Although UNIX Systems Services file and directories don't use the z/OS catalogs,
everyone dealing with all other z/OS datasets use them every day. From creating
dataset lists to opening a dataset, you're accessing the catalog.
This article will cover how to get information from catalogs: from interactive
TSO/ISPF sessions, batch jobs, and programs.
Let's start with the no-brainer: ISPF option 3.4 (DSLIST).
Figure 1: ISPF 3.4 (DSLIST) Output
Menu Options View Utilities Compilers Help
DSLIST - Data Sets Matching DASP1 Row 1 of 5
Command ===> Scroll ===> CSR
Command - Enter "/" to select action Message Volume
************************* End of Data Set list************************
This is the classic utility for listing datasets. Any TSO/E user with datasets
will use 3.4 every day to list and manage their datasets. Although you can specify
a volume serial number when creating the dataset list, no-one ever does, and
so the dataset lists come straight from the z/OS catalogs. However 3.4 doesn't
immediately give you a lot of catalog information; just the dataset name and
volume where it is found. Putting an I next to the dataset will give you more
information, including VSAM-related information.
DSLIST is limited in the dataset lists it can produce it can only be
used to list datasets based on their name. If you want a list of all VSAM indexes
beginning with 'PROD', DSLIST can't help you.
Included free with z/OS, the ISPF based Interactive Storage Management Facility
(ISMF) is a valuable tool for storage administrators to manage DFSMS rules and
classes. However it is also a far more powerful utility for listing and managing
datasets. Tailored dataset lists based on any catalog-related information can
be produced. However you won't find many people who enjoy using the user-unfriendly
panels. Use of ISMF is also restricted by many mainframe sites.
Figure 2: ISMF Output
Panel List Dataset Utilities Scroll Help
DATA SET LIST
Command ===> Scroll ===> CSR
Entries 1-7 of 7
Data Columns 3-5 of 41
Enter Line Operators below:
LINE ALLOC ALLOC % NOT
OPERATOR DATA SET NAME SPACE USED USED
---(1)---- ----------(2)---------- ---(3)--- ---(4)--- -(5)-
DASP1.C.SOURCE 89K 80K 5
DASP1.PROGRAM.LOAD 46K 40K 13
DASP1.REXX.SOURCE 139K 93K 33
DASP1.STANDARD.CNTL 185K 153K 18
-------- ------ --------- BOTTOM OF DATA ------ ------ ----
ISMF is also the weapon of choice for obtaining ATL and tape information from
Both ISMF and ISPF designed for the ISPF user. If you need access to catalog
information from a program or batch job, they're not going to help you.
The Access Method Services LISTCAT command is the command to access all catalog
information. Although it is the bread-and-butter interface for catalogs and
VSAM datasets, many are scared off by the confusing syntax. For example, to
simply list all the catalog information for the dataset DASP1.C.SOURCE, the
Not exactly intuitive. The output from LISTCAT can be just as difficult to digest.
Figure 3: LISTCAT ENTRY Output
LISTCAT ENTRY(DASP1.C.SOURCE) ALL
NONVSAM ------- DASP1.C.SOURCE
STORAGECLASS ---STORCL1 MANAGEMENTCLASS---MGMTCL1
DATACLASS ------DATACL1 LBACKUP ---0000.000.0000
VOLSER------------VOL001 DEVTYPE-----X'3030200E' FSEQN----0
However LISTCAT is very powerful. Not only will it list all catalog information,
it can also produce dataset lists. In fact the often-overlooked LEVEL parameter
will list of datasets based on a dataset name pattern. For example:
Figure 4: LISTCAT LEVEL Output
NONVSAM ------- DASP1.C.SOURCE
NONVSAM ------- DASP1.PROGRAM.LOAD
NONVSAM ------- DASP1.REXX.SOURCE
NONVSAM ------- DASP1.STANDARD.CNTL
The NAME, HISTORY, VOLUME, ALLOCATION and ALL parameters provide at least some
control over how much information is produced.
LISTCAT can be called as a TSO/E command (LISTCAT), or from batch using the
ISPF users can also use LISTCAT in 3.4 or ISMF by entering:
LISTCAT ENT(/) ALL
to the left of any dataset. A better solution would be to create a REXX script
that calls LISTCAT, and puts the output in a dataset to browse. Mark Zelden
has written the XLISTC
REXX to do exactly that.
For users who have no wish to start coding, calling LISTCAT from TSO/E and
batch is the only way to access catalog information from batch and automation
scripts. Because of this, there are a lot of tasks around that call LISTCAT,
and then process the output using something like REXX, SAS or CA-EzyTrieve.
However processing LISTCAT output in this manner is a risk. Any change to
the format of the output may cause problems. This could be something as simple
as a PDS changing to a PDS/E, or an index added to a VSAM Cluster. It could
also come from IBM changing the format of the output; they did exactly this
in z/OS 1.8.
So how else can batch jobs and programs easily access catalog information?.
CAMLIST and LOCATE
CAMLIST and LOCATE are the two basic assembler macros used to access the catalog,
and are documented in the DFSMS Advanced Service manual. CAMLIST is used to
specify what catalog information to get, and LOCATE does the work. For example:
Figure 5: CAMLST/LOCATE Assembler Sample
* --- Get catalog information and put into LOCAREA --
LOCATE #DSET1 Read the Catalog
* entry for #DSET1
(check return codes, and process the output in LOCAREA)
* --- Constants ---------------
#DSET1 CAMLST NAME,#DSETNAM,,LOCAREA
#DSETNAM DC CL44'DASP1.C.SOURCE'
LOCAREA DS 0D
LOCAREAN DS H Number of Volumes
LOCAREAV DS 263C Volume List (up to 20)
This code will insert the volume(s) where the dataset DASP1.C.SOURCE resides
in the 265 byte area LOCAREA. The first halfword is the number of volumes, followed
by 12 byte areas holding:
- The device type (4 bytes)
- The volume serial number (6 bytes)
- The volume sequence number (2 bytes)
CAMLIST and LOCATE can only be used with a fully qualified datasetname, GDG
name or alias to return a volume list. It cannot be used to get any other information
from the catalog.
Similar information is returned by the TSO/E IKJEHCIR service, another option
for programs running under TSO/E. Not only can IKJEHCIR get volume serial information,
it can also get lists of dataset names based on a name pattern. The downside
is that this pattern must be fully qualified (eg. USER1.PDS.): no wildcards
Yet another option for programs running under ISPF is the TSO/E ICQGCL00 services,
which can generate lists of datasetnames from criteria similar to IKJEHCIR.
Catalog Search Interface
It's not all bad news for programmers needing to get access to the catalog.
The DFSMS Catalog Search Interface (CSI) is what almost everyone turns to. It
can be used to create tailored dataset lists with any catalog information you
need from any programming language. IBM documents it in the DFSMSdfp Managing
Callers call the program IGGCSI00, specifying an area to hold the output,
and the selection criteria. This selection criteria can include wildcards (%,
* etc.), and you can specify almost any catalog information to be used to generate
the dataset list. Selection criteria also specifies what information is to be
returned for each list. The CSI is also your only choice for obtaining ATL information
from a program.
Unfortunately, many programmers will be dismayed at the complexity needed
to call this facility. Assembler programmers can see the samples in sys1.samplib,
as can REXX programmers. Mark Zelden has built on the REXX sample with his catsrch.txt
sample. PL/1 programmers can see Herman Vierendeel's sample in Xephon
MVS Update Jan 2000.
C programmers can also see an example in our Resources
Catalog remain critical to everyday z/OS operations, and we all use them every
day. However IBM hasn't made the job of accessing catalog information easy.
ISPF users have basic facilities that can help out. Users with a need to access
information from programs, batch jobs and automation scripts often have relied
on calling LISTCAT and processing the output. However investing the time in
producing callable modules that use the Catalog Search Facility will never be