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.

ISPF Sessions

Let's start with the no-brainer: ISPF option 3.4 (DSLIST).

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
----------------------------------------------------------------------
       DASP1                                                  *ALIAS
       DASP1.C.SOURCE                                         VOL001
       DASP1.PROGRAM.LOAD                                     VOL001
       DASP1.REXX.SOURCE                                      VOL001
       DASP1.STANDARD.CNTL                                    VOL001
************************* 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.

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 the catalog.

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.

LISTCAT

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 command is:
LISTCAT ENTRY(DASP1.C.SOURCE) ALL
Not exactly intuitive. The output from LISTCAT can be just as difficult to digest.

LISTCAT ENTRY(DASP1.C.SOURCE) ALL 

 NONVSAM ------- DASP1.C.SOURCE 
    HISTORY 
      DATASET-OWNER-----(NULL)   CREATION--------2009.244 
      RELEASE----------------2   EXPIRATION------2009.244 
      DSNTYPE----------LIBRARY 
    SMSDATA 
      STORAGECLASS ---STORCL1    MANAGEMENTCLASS---MGMTCL1 
      DATACLASS ------DATACL1    LBACKUP ---0000.000.0000 
    VOLUMES 
      VOLSER------------VOL001   DEVTYPE-----X'3030200E'   FSEQN----0
    ASSOCIATIONS--------(NULL)

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:

LISTCAT LEVEL(DASP1) 

 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 IDCAMS program:

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:

* --- 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 allowed.

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 Catalogs manual.

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

Conclusion

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 time wasted.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.