Mainframes 360
The one stop destination for System Z professionals

Monday, June 29, 2009

DD Statement for Reading Datasets

Q. What is the DD Statement used for?
Hook-up an electrical appliance, a grinder-mixer, a microwave oven, a Television to any plug-point, and it’ll work. If you wanna feed Inputs to your COBOL Programs, or store the data results they produce, you’ve gotta use the Inlets and Outlets – that the COBOL Program offers. Every inlet or outlet point is referred to by a short symbolic name like INFILE, OUTFILE, SYSUT1, SYSUT2 and so on. You need to hook up or plug-in real physical Mainframe Files like SYSADM.INPUT.FILE and SYSADM.OUTPUT.FILE into the INFILE and OUTFILE points, to run the Program and process the Data.   COBOL Programs refer to files by a short symbolic-name. At the time of running the Program, when you type a job, you code a DD Statement to attach, or hook-up an actual physical Mainframe File to these mere symbolic names. Get things straight, if a COBOL Program accesses 5 files, to run the Program, the job's got to have 5 DD Statements. Each DD Statement falls into one of these categories: 1. Reading a Dataset
2. Sending output to the Spool(Output queue)
3. Writing Output to a Dataset
In this article, I’ll show you what you need to know, to code DD Statements for reading Datasets.
Q. What is the simplest DD Statement for reading?
You can code the simplest and the most common DD Statement for reading from a Mainframe File like this :


The DD-name that you code on the DD-Statement, should match the symbolic-name, that the program expects. The DD-name should start with an Alphabet, and can be upto eight characters long. It may contain @,#,$ or numbers as well. The ready-made IBM Software IEBGENER expects to read Input records from SYSUT1 File. Hence, I have coded the DD-name SYSUT1 on the DD Statement.

assigns an Mainframe file-name value – SYSADM.DEMO.INPUT to the mere symbolic file-name SYSUT1, that the IEBGENER Program refers to. The DSN or DSNAME parameter specifies the actual Mainframe File-name Value. DSN stands for "Dataset-name". Putting it altogether, when you look at the //SYSUT1 DD Card, you can tell IEBGENER software would read the data from SYSADM.DEMO.INPUT Mainframe File.

The only additional thing, you need to code on a DD Statement is DISP. DISP Keyword stands for "Disposition". DISP can take several inputs, but when you’re reading data from a Mainframe-File, you can code either DISP=SHR, or DISP=OLD.
Q. What DISP=SHR means?
When you code DISP=SHR, you are telling the OS that you need Shared Access on the file. You do not want to lock or reserve the dataset exclusively for you use. You are okay and do not care if someone-else is already reading from the Dataset, which is of-course acceptable.

DISP=SHR is the most preferred way, of coding the DISPosition, when you want read from the Datasets. At a time, upto 127 jobs can read from the dataset.
Q. What DISP=OLD means?
DISP=OLD is opposite to coding a DISP=SHR. If you code DISP=OLD, on a DD-Statement for reading a dataset, it means you are locking the file exclusively for your use. When you read a Dataset, with a DISP=OLD, it reserves the Dataset exclusively only for you. Any other job cannot access the data-set at the same time, and will keep on waiting for your job to complete. With DISP=OLD, only 1 job can read the dataset at a time.

For reading datasets, coding a DISP=OLD on a dataset to lock it exclusively for your job, is a very selfish strategy. Here’s why, coding a DISP=OLD to read from a Dataset is a bad idea :
- DISP=OLD denies access to data-set to any other jobs, so long as your job is reading from it.
- DISP=OLD can delay your job, if there are any other jobs currently reading the dataset, and your job needs exclusive-access to it.

Look at the below Job(JCL). I have coded DISP=OLD on the //SYSUT1 DD Card. //SYSUT1 File points to the SYSADM.DEMO.INPUT Dataset. This implies, when the IEBGENER Program runs, it’ll try to acquire exclusive access to the file and lock the SYADM.DEMO.INPUT file. 


Now, I am gonna keep the SYSADM.DEMO.INPUT Mainframe file open in TSO-Edit Mode for reading in the ISPF Editor.


Here’s the contents of the SYSADM.DEMO.INPUT file, when I open the dataset in Edit-mode in ISPF Editor.


Look what happens, when I try to hit SUBMIT on the Job, that tries to read the data from SYSADM.DEMO.INPUT in DISP=OLD(Exclusive) access mode, with the file open in TSO-Edit Mode. Recall, that only one job can have Exclusive access to a dataset at a time.


So, the Log-report of the SYSADMB job in the Spool shows the following messages.


As you can see OLD requires exclusive-access to the Dataset SYSADM.DEMO.INPUT. In this case, the dataset I am trying to read is already opened in TSO-Edit mode. The system-messages indicate that the job is waiting on the dataset to become free and available for exclusive-access. SHR doesn’t suffer from this problem. Always use DISP=SHR for reading from Datasets!
Q. What's the problem if I omit the DISP Parameter, when reading a Dataset?
The first sub-parameter of DISP could  be OLD, SHR, NEW or MOD. Essentially, the last two -  NEW and MOD are applied, when you want to create New Datasets. If you don't code DISP at all, it defaults to NEW. Because of the error messages MVS uses, this can be quite a confusing problem.

I have coded a Job, that runs the free IBM Software-Program IEBGENER. IEBGENER copies the contents of //SYSUT1 File to //SYSUT2 File. I have
attached(Hooked-up) the physical Mainframe file SYSADM.DEMO.INPUT to the //SYSUT1 Symbolic-name. The Mainframe-File SYSADM.DEMO.OUTPUT is assigned to the //SYSUT2 DD Card. So, IEBGENER tries to read the data from the SYSADM.DEMO.INPUT Dataset, and copy it to SYSADM.DEMO.OUTPUT File.

I have not coded the DISP Parameter, on the //SYSUT1 DD Statement for reading the Dataset.


When I Submit this job, to run the IEBGENER Software, the MVS OS complains about my JCL, and kicks it out(rejects it). Here's a snapshot of the JESMSGLG Listing.


To find out, what's wrong with the JCL, I’d see the JESYSMSG Listing. Here is a picture of the messages printed in the JESYSMSG Listing. Upon omitting the DISP, MVS defaults to DISP=NEW on the //SYSUT1 DD Statement. However, the error-message printed in the Log-Report, IEF344I says "SPACE was not specified for allocation of dataset SYSADM.DEMO.INPUT", which a really weird looking message. This does not hint at my failure to code the DISP Parameter on the //SYSUT1 DD Statement.


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.