Mainframes 360
The one stop destination for System Z professionals

Thursday, February 25, 2010

IDCAMS – LISTCAT Command

Q. What is a Catalog? What is meant by cataloging or un-cataloging a file?

Data on computers is stored in Files. The files are generally scattered everywhere haphazardly in Computer Memory. Well, let's say you want to see, or read the file in which you stored your Birthday photographs. The file containing the birthday photographs could be placed anywhere in the Computer Memory. How do you know, the location of your file(where is it) in this vast galaxy of Computer Memory space? It’s like finding a needle in a haystack.

The MVS Operating System keeps a diary/register, which contains name of each file, and its location in the computer memory. This diary/register is like your map around the Mainframe's memory land. You want to find a file, just see the MVS operating system’s diary, and it will tell you the location of your file.

This diary or map, which you consult to find a file on a Mainframe computer, is called Catalog. The Catalog contains entries for each file, a file-name and a pointer to the physical memory location, where the file is present.

Not all the files present on a Mainframe may have an entry in the Catalog. If a given file’s entry is not present in the Catalog, you will have to find the file manually, by explicitly specifying the UNIT and VOLUME parameters on the DD Statements. Adding an entry for a file i.e. File name and its location to Catalog, is called cataloging a file. Deleting the entry of a file, from the Catalog is called uncataloging the file.

Actually, the Catalog itself is a VSAM File. So, you can use the ready-made IBM Supplied program IDCAMS to read the contents of the Catalog.

Q. What is the LISTCAT command in IDCAMS?

LISTCAT command stands for List Catalog. It is the control-instruction or order to IDCAMS, to display the contents of the Catalog.

LISTCAT command of IDCAMS is a very powerful tool. You can use LISTCAT command to ask a Yes/No Question. Is there a file by the name of AGY0157.DEMO.FILE on the system? If such a file exists, the answer returned is yes. If the file does not exist the answer returned is no.

The LISTCAT command has the following syntax :

LISTCAT ENTRIES(your.file.name) ALL

I have written a JCL, to test if a given file is available on the system. Take a look at it –

Image144[1] 

In the above JCL, I have asked a question, is there a file called AGY0157.DEMO.FILE available? If yes, then IDCAMS will leave behind a Condition Code = 0. If the file does not exist, then IDCAMS will sign off with a return Code > 0.

Image145[1]

Since, I do have a file called AGY0157.DEMO.FILE, IDCAMS will print a description about the file to the log. The Log shows various details – like the catalog in which the file's entry is present, when the file was created, the file’s location(On which volume the file resides?) etc.

Image146[1]

Upon scrolling down to the bottom of the log, you would find that, IDCAMS has left a trail – the condition code is set to 0.

Image147[1]

Q. Wait a minute, you are asking me to use LISTCAT command, just to know if the file’s availability. In TSO/ISPF, I would just navigate to Dataset List Menu 3.4, and perform a simple search to check availability. What’s the difference?

That’s a good question, why use LISTCAT Command, when you can just use Dataset List Menu 3.4. Let me set things straight. The Dataset List Menu 3.4 is an ISPF Screen, where you type the name of the file, and press <ENTER>, you get the list of files, and details(description) about them.

Image148[1]

Actually, Dataset List Menu 3.4 is just a GUI Front-end or screen. It presents a nice, friendly user-interface for checking the availability of a file. In background, there is a ready-made template JCL. The file-name you typed on the 3.4 screen is substituted in this template JCL. This template JCL, uses LISTCAT command to find infomation from the catalog. This template JCL is ready-made, you don’t have to write it. When you press <ENTER>, this template Job is submitted to the MVS Operating System. After the job completes, the results of this job, are populated on the ISPF Screen.

Using the TSO/ISPF Menu 3.4, is equivalent to submitting a job in background which uses LISTCAT command to query the Catalog, and check the availability of the file.

In fact, just to let you guys know, behind every ISPF Menu screen, there is a  corresponding skeleton or template JCL that runs in the background. ISPF Screen is just a presentation layer, a front-end.

Q. Well that sounds good in theory. Is the LISTCAT command used in real production environment, in projects?  

In most projects/sites, there is a complex relationship amongst systems. As an example, suppose there are two Jobs(systems) 1 and 2. Suppose, the JOB 1 produces an Output file. This Output file is fed as Input to JOB 2. In other words, the Job1 is the feeder system of Job 2. Generally in projects, they would express this fact as, Job 2 has a dependency on Job 1.

Suppose Job 2 has been scheduled to run at 12 o'clock. Remember, that Job 2 expects to pick up a file, which Job 1 will produce as Output. If this file is not available by 12 o'clock, when the Job 2 is about to start, the Job 2 will fail(abnormally end) or abend. 

Many-a-times, Job 1 gets delayed, and does not make it within the cut-off time -  12 o'clock. In this unfortunate situation, Job 2 abends(fails). How could you prevent this incident?

You could add a condition to the Job 2, to first check if the file is available. Provided the file is available, the Job 2 should process it. If the file is not yet available, the Job 2 should bypass it, avoid processing it. Take a look at the JCL, I have written below -

Image149[1]

Here, I have used LISTCAT command to check the availability of the file AGY0157.DEMO.FILE. If the file exists, the step //CHECK01 leaves behind a condition code=0. If the file is not available, I set the
MAX Condition Code = 4. The next step //PROCESS will execute if, the condition code of //CHECK01 is 0. If the condition code of //CHECK01 is 4, meaning the file is not available, the next step //PROCESS is bypassed. The job will however not fail or abend.

To many people who are thrown to work at a mainframe computer on their first job, they feel lost. Mainframe people seem to speak a completely different language and that doesn't make life easy. What's more, the books and manuals are incredibly hard to comprehend.

"What on earth is a Mainframe?" is an absolute beginner's guide to mainframe computers. We'll introduce you to the hardware and peripherals. We'll talk about the operating system, the software installed on a mainframe. We'll also talk about the different people who work on a mainframe. In a nutshell, we'll de-mystify the mainframe.

Readers based in India, can buy the e-book for Rs. 50 only or the print book. International readers based in the US and other countries can click here to purchase the e-book.