COBOL Module 8 – Indexed and relative files (VSAM concepts)
Relative files, VSAM organisations and IDCAMS
Use COBOL relative files with a RELATIVE KEY, compare the VSAM KSDS, ESDS, RRDS and LDS organisations, and read IDCAMS DEFINE, REPRO and PRINT steps.
What you will learn
- Use a relative file with a RELATIVE KEY to write, read, delete and reuse numbered slots
- Describe the VSAM KSDS, ESDS, RRDS and LDS organisations and the COBOL organization that opens each
- Read IDCAMS DEFINE CLUSTER, REPRO and PRINT steps and predict what each command does
- Explain what a relative file holds on disk after a DELETE, and what a RELATIVE KEY that is too small does
Before you start
What you’ll learn · Before you start
What you will learn
- Use a relative file with a RELATIVE KEY to write, read, delete and reuse numbered slots
- Describe the VSAM KSDS, ESDS, RRDS and LDS organisations and the COBOL organization that opens each
- Read IDCAMS DEFINE CLUSTER, REPRO and PRINT steps and predict what each command does
- Explain what a relative file holds on disk after a DELETE, and what a RELATIVE KEY that is too small does
Before you start
On this page
A branch has 50 lockers, numbered 1 to 50, and a locker’s number is all a clerk needs to find who holds it. A relative file stores each record in the slot whose number is its key, so locker 4 is slot 4, with no key field in the record.
This lesson runs a file of lockers with GnuCOBOL, then names the four kinds of VSAM data set that hold files on z/OS and the IDCAMS commands that define, load and print them.
A relative file keeps each record in a numbered slot
lockers.cob declares ORGANIZATION IS RELATIVE and RELATIVE KEY IS LK-SLOT. The RELATIVE KEY: The item named by RELATIVE KEY: a number outside the record that tells a relative-file statement which slot to use. A READ NEXT puts the number of the slot it read there. is a number in WORKING-STORAGE, not a field of the record: a WRITE, READ or DELETE takes its slot from LK-SLOT, and a READ NEXT puts the number of the slot it read there.
IDENTIFICATION DIVISION.
PROGRAM-ID. LOCKERS.
* A relative file of lockers: the locker number is the slot.
* Allocates four lockers, tries a taken one and an empty one,
* releases locker 2 and lists the lockers in use.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT LOCKER-FILE ASSIGN TO "LOCKERS"
ORGANIZATION IS RELATIVE
ACCESS MODE IS DYNAMIC
RELATIVE KEY IS LK-SLOT
FILE STATUS IS LK-STATUS.
DATA DIVISION.
FILE SECTION.
FD LOCKER-FILE.
01 LOCKER-REC.
05 LK-HOLDER PIC X(6).
05 LK-SINCE PIC 9(4).
WORKING-STORAGE SECTION.
01 LK-SLOT PIC 9(3).
01 LK-STATUS PIC XX.
PROCEDURE DIVISION.
OPEN OUTPUT LOCKER-FILE
MOVE 1 TO LK-SLOT
MOVE "AC00011001" TO LOCKER-REC
PERFORM PLACE-LOCKER
MOVE 4 TO LK-SLOT
MOVE "AC00041004" TO LOCKER-REC
PERFORM PLACE-LOCKER
MOVE 7 TO LK-SLOT
MOVE "AC00071007" TO LOCKER-REC
PERFORM PLACE-LOCKER
MOVE 2 TO LK-SLOT
MOVE "AC00021002" TO LOCKER-REC
PERFORM PLACE-LOCKER
MOVE 4 TO LK-SLOT
MOVE "AC00091009" TO LOCKER-REC
PERFORM PLACE-LOCKER
CLOSE LOCKER-FILE
OPEN I-O LOCKER-FILE
MOVE 3 TO LK-SLOT
READ LOCKER-FILE
DISPLAY "READ locker 003 " LK-STATUS " empty"
MOVE 2 TO LK-SLOT
DELETE LOCKER-FILE
DISPLAY "DELETE locker 002 " LK-STATUS " released"
MOVE 0 TO LK-SLOT
READ LOCKER-FILE
DISPLAY "READ locker 000 " LK-STATUS " no slot 0"
MOVE 1 TO LK-SLOT
START LOCKER-FILE KEY IS NOT LESS THAN LK-SLOT
DISPLAY "START >= 001 " LK-STATUS
READ LOCKER-FILE NEXT RECORD
PERFORM UNTIL LK-STATUS NOT = "00"
DISPLAY "READ NEXT " LK-SLOT " " LK-STATUS " "
LK-HOLDER " since " LK-SINCE
READ LOCKER-FILE NEXT RECORD
END-PERFORM
DISPLAY "READ NEXT " LK-STATUS " the end"
CLOSE LOCKER-FILE
STOP RUN.
PLACE-LOCKER.
WRITE LOCKER-REC
INVALID KEY
DISPLAY "WRITE locker " LK-SLOT " " LK-STATUS
" taken: " LK-HOLDER " not placed"
NOT INVALID KEY
DISPLAY "WRITE locker " LK-SLOT " " LK-STATUS
" " LK-HOLDER
END-WRITE.from session import files, run
# Lockers allocated, a taken one and an empty one tried, locker 2 released, and the lockers in use listed.
files("lockers.cob")
run("""
cobc -x lockers.cob
DD_LOCKERS=lockers.dat ./lockers
""")Output
$ cobc -x lockers.cob $ DD_LOCKERS=lockers.dat ./lockers WRITE locker 001 00 AC0001 WRITE locker 004 00 AC0004 WRITE locker 007 00 AC0007 WRITE locker 002 00 AC0002 WRITE locker 004 22 taken: AC0009 not placed READ locker 003 23 empty DELETE locker 002 00 released READ locker 000 23 no slot 0 START >= 001 00 READ NEXT 001 00 AC0001 since 1001 READ NEXT 004 00 AC0004 since 1004 READ NEXT 007 00 AC0007 since 1007 READ NEXT 10 the end
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 lockers_session.py
The WRITEs to slots 1, 4, 7 and 2 returned 00, in that order, and the second WRITE to slot 4 returned 22, because AC0004 already held it. A READ of slot 3 returned 23: the slot is empty. DELETE emptied slot 2, a READ with LK-SLOT 0 returned 23, since slots count from 1, and the browse read slots 1, 4 and 7, skipping the empty ones. Step through the seven slots:
The drawing shows the whole scene; its 8 steps are listed below.
Every step as text
- Locker 1. The program moves 1 to LK-SLOT, the RELATIVE KEY, and runs WRITE. The record AC0001 since 1001 goes into slot 1, with status 00. No field of the record says which slot it is in.
- Lockers 4 and 7. Two more WRITEs put AC0004 in slot 4 and AC0007 in slot 7. Slots 2, 3, 5 and 6 stay empty, because a relative file may leave gaps between the slots it uses.
- Locker 2, below the others. AC0002 goes into slot 2, below slots already in use. In random or dynamic access the order of the WRITEs does not matter.
- A taken slot. A WRITE of AC0009 into slot 4 finds AC0004 there, so it places nothing and returns 22, the invalid key condition for a slot in use.
- An empty slot. A READ of slot 3 finds no record there and returns 23, as a READ of a missing key does in an indexed file.
- Locker 2 released. DELETE with LK-SLOT 2 removes AC0002 and returns 00. Slot 2 is empty again and can take a new holder.
- No slot 0. Slots are numbered from 1. A READ with LK-SLOT 0 found nothing to read and returned 23.
- The lockers in use. START KEY IS NOT LESS THAN 1 and READ NEXT read slots 1, 4 and 7 and skip the empty ones, 2, 3, 5 and 6. The READ NEXT after slot 7 returns 10, and each READ NEXT puts its slot number in LK-SLOT.
A relative file: A file of numbered slots, ORGANIZATION IS RELATIVE, in which each record is stored and found by the number of its slot. On z/OS it is a VSAM relative record data set. uses the same statuses as an indexed file, 22 when the slot is taken and 23 when it is empty or does not exist, but it finds records another way:
| What differs | Indexed file | Relative file |
|---|---|---|
| A record is found by | a key field inside it | the slot number in the RELATIVE KEY |
| A WRITE to a taken key or slot | 22 | 22 |
| A READ of a missing key or empty slot | 23 | 23 |
| READ NEXT reads | records in key order | full slots in number order |
Choose a relative file when the records are numbered from 1 with few gaps, such as lockers or the days of a year. A key such as AC0001, which is not a small number, belongs in an indexed file.
VSAM keeps data in four organisations, and IDCAMS defines them
On z/OS a relative file is one of the four VSAM: Virtual Storage Access Method, the z/OS access method for key-sequenced, entry-sequenced, relative-record and linear data sets. COBOL's indexed and relative files are VSAM data sets on z/OS. More in “Indexed files: keys, access modes and INVALID KEY” organisations, and IBM’s Programming Guide pairs three of them with COBOL’s organizations:
- A KSDS: A key-sequenced data set: a VSAM data set whose records are stored and found by a key field. A COBOL indexed file on z/OS is a KSDS. More in “Indexed files: keys, access modes and INVALID KEY” finds each record by a key field inside it; a COBOL indexed file is one.
- An ESDS: An entry-sequenced data set: a VSAM data set that keeps its records in the order they were written. COBOL opens one as ORGANIZATION IS SEQUENTIAL. keeps records in the order they were written; COBOL opens it as a sequential file.
- A RRDS: A relative record data set: a VSAM data set whose records are found by their relative record numbers. COBOL opens one as ORGANIZATION IS RELATIVE. finds each record by its relative record number: The number of a record's slot in a relative file or a VSAM relative record data set, counted from 1.; COBOL opens it as a relative file.
- A linear data set: A VSAM data set that holds a stream of bytes rather than records, used heavily by Db2 and z/OS system functions. COBOL's file statements do not open one. holds bytes, not records, and COBOL’s file statements do not open it.
The four VSAM organisations differ first in how a program finds a record, so that is the first question to settle for a new file. IDCAMS: Access method services, the z/OS utility that a job step runs as PGM=IDCAMS. Its commands define, load, print and delete VSAM data sets, such as DEFINE CLUSTER, REPRO and PRINT., access method services, is the utility a job step runs to create these data sets, and IBM’s Programming Guide requires every VSAM data set to be defined and catalogued with it before a program uses it. Its DEFINE CLUSTER command creates a data set, REPRO copies records into it, and PRINT lists the records it holds. Answer two questions about some data in the table below to see which organisation fits:
Answer the questions above: the table then marks what fits your case and says why the rest does not.
| Organisation | Finds a record by | Removing a record | COBOL file statements |
|---|---|---|---|
| KSDS The COBOL file: ORGANIZATION IS INDEXED | Good a key field in the record, such as AC-NUMBER | Good DELETE by key | Good READ, WRITE, REWRITE, DELETE and START |
| ESDS The COBOL file: ORGANIZATION IS SEQUENTIAL | Mixed its place only: records are read in the order they were written | Poor IBM: a record cannot be shortened, lengthened or deleted | Mixed sequential READ and WRITE; REWRITE at the same length |
| RRDS The COBOL file: ORGANIZATION IS RELATIVE | Good its relative record number, the slot | Good DELETE empties the slot for a new record | Good READ, WRITE, REWRITE, DELETE and START |
| LDS The COBOL file: no COBOL organization | Poor no records: a byte stream | Poor no records to remove | Poor none: it needs control interval access |
How the answers decide
- “How does the program find the record it needs?” By a key field in the record: rules out ESDS, RRDS and LDS. Only a KSDS finds a record by a field inside it. An RRDS finds a record by its slot number and an ESDS by its place in the file.
- “How does the program find the record it needs?” By a number such as a locker: rules out ESDS and LDS and adds a caveat to KSDS. An RRDS goes straight to slot n. A KSDS can hold the number as its key too, at the cost of an index to keep.
- “How does the program find the record it needs?” Only in the order records were written: rules out LDS and adds a caveat to KSDS and RRDS. An ESDS keeps the order records were written in. A KSDS or an RRDS can be read in order too, but carries a key or slot the data does not need.
- “Must the program remove records?” Yes: rules out ESDS and LDS. IBM says that once a record is in an ESDS it cannot be shortened, lengthened or deleted, and an LDS has no records.
Checkpoint
Check: Slots, the RELATIVE KEY and statuses 22 and 23 · The four VSAM organisations and IDCAMS
Practise: slots and organisations
These questions use the locker run and the four organisations.
Practice that adapts to you
Practise this lesson
4 questions about 5 ideas of this lesson. Each answer is explained at once, and what you get right is kept in this browser.
A relative file on disk: slot bytes, what a DELETE leaves, and a key too small Pro: opens with a Pro, Premium or Ultimate pass
Every slot of a relative file sits at a fixed place in the file, which is what makes slot n quick to find. This part reads the locker file byte by byte, shows what a DELETE leaves behind, and loads eleven lockers through a key of one digit.
In this part:
- The locker file byte by byte, with the numbers worked out
- What a DELETE leaves in the slot, and a release that erases it
- A RELATIVE KEY too small for its slots, on z/OS and in GnuCOBOL 3.2
4 runnable examples (COB, Python) · about 6 minutes
Opening this part with your pass…
This part opens with any MySmartCoPilot pass.
- Pro pass · 1 week₹79$2.99
- 30 days₹179$5.99
- 1 year₹1,699$45
One payment; a pass never renews. The price shown is the total you pay: no fees or charges are added at checkout.
Passes can’t be bought right now, so this part can’t be opened at the moment. The free part above stands on its own. If you have a pass, enter your licence key.
It also opens every other in-depth part in Learn and every Pro tool. Sales are final, except where the law gives you a right to withdraw, for example in the EU and the UK (refund policy).
IDCAMS steps read line by line: DEFINE CLUSTER, REPRO and PRINT Pro: opens with a Pro, Premium or Ultimate pass
An IDCAMS step decides everything VSAM knows about a data set before a COBOL program opens it. This part reads a step that defines, loads and prints the account file of the indexed-files lesson, checks its input the way REPRO needs it, and defines the locker file as an RRDS.
In this part:
- DEFINE CLUSTER for the account file, keyword by keyword
- REPRO needs its input in key order, so check it first
- The locker file as an RRDS, and the organisations COBOL can open
1 diagram · 3 runnable examples (JCL, Python) · about 6 minutes
Opening this part with your pass…Pro part. It opens with the same pass as the part above.
Interview questions
A warm-up with its answer, then three questions about relative files and VSAM loads that went wrong:
-
Fresher to mid · Warm-up
What is a relative file, and where does its RELATIVE KEY live?
A relative file stores each record in a numbered slot, and the slot number is the record's key. The RELATIVE KEY is an item in WORKING-STORAGE, not a field of the record: before a WRITE, READ or DELETE the program moves the slot number into it, and a READ NEXT puts there the number of the slot it read. A WRITE to a slot that holds a record returns 22, a READ or DELETE of an empty slot returns 23, slots count from 1, and READ NEXT skips the empty slots. It suits records numbered from 1 with few gaps, such as lockers, and on z/OS it is a VSAM relative record data set.
-
Mid to senior
Customers' account numbers must not stay in the locker file once a locker is returned. A program releases lockers with DELETE on a relative file that is backed up every night. How do you make sure the number is gone, and how do you prove it?
-
Fresher to mid
A nightly job reloads the locker file with sequential WRITEs and prints each record's RELATIVE KEY, declared PIC 9(2), as the locker number. The branch will grow from 80 to 150 lockers. What can go wrong on z/OS and with GnuCOBOL 3.2, and what do you change?
-
Mid to senior
An IDCAMS step loads a new account KSDS with REPRO from an unsorted extract and ends with error messages, and the next steps find far fewer accounts than the extract held. What went wrong, how do you prepare the input, and how does the job check the load?
Organisations named on this page
The VSAM, IDCAMS and file status rules here are taken from IBM’s Enterprise COBOL, DFSMS and Basic Skills pages, and the locker runs from GnuCOBOL 3.2. Neither IBM nor the GnuCOBOL project has anything to do with MySmartCoPilot.
Flashcards · 6 cards
Recall it, then check
Say the answer to yourself before you look: recalling it is what makes it stick.
-
What is the RELATIVE KEY of a relative file?
A number in WORKING-STORAGE, not a field of the record. WRITE, READ and DELETE take their slot from it, and READ NEXT puts there the number of the slot it read.
-
Which statuses does a relative file give for a taken slot and an empty one?
22 for a WRITE to a slot already in use; 23 for a READ of an empty slot, or of slot 0, since slots count from 1.
-
Which slots does READ NEXT read in a relative file?
Only the full ones, in order of their numbers; empty slots are skipped.
-
When does a relative file suit data better than an indexed one?
When the records are numbered from 1 with few gaps, such as lockers or the days of a year. A key such as AC0001, which is no small number, belongs in an indexed file.
-
Which VSAM organisation holds each kind of COBOL file?
An indexed file is a KSDS, a sequential one an ESDS and a relative one an RRDS. A linear data set holds bytes, which COBOL's file statements do not open.
-
What do IDCAMS's DEFINE CLUSTER, REPRO and PRINT do?
DEFINE CLUSTER creates a VSAM data set, which must exist before a program opens it; REPRO copies records into it; PRINT lists the records it holds.
Key takeaways
- A relative file keeps each record in the slot its RELATIVE KEY names, a number outside the record: a taken slot returns 22, an empty slot or slot 0 returns 23, and READ NEXT skips the empty slots.
- On z/OS, COBOL’s indexed, sequential and relative files are VSAM KSDS, ESDS and RRDS data sets, and a linear data set holds bytes that COBOL’s file statements do not open.
- IDCAMS defines a VSAM data set before any program opens it: DEFINE CLUSTER creates it, REPRO copies records into it, and PRINT lists them.
Terms in this lesson
- control interval
- The unit in which VSAM stores data: records, free space and descriptor fields together, 4K bytes by default and up to 32K. Control intervals are grouped into control areas.
- ESDS
- An entry-sequenced data set: a VSAM data set that keeps its records in the order they were written. COBOL opens one as ORGANIZATION IS SEQUENTIAL.
- IDCAMS
- Access method services, the z/OS utility that a job step runs as PGM=IDCAMS. Its commands define, load, print and delete VSAM data sets, such as DEFINE CLUSTER, REPRO and PRINT.
- linear data set
- A VSAM data set that holds a stream of bytes rather than records, used heavily by Db2 and z/OS system functions. COBOL's file statements do not open one.
- relative file
- A file of numbered slots, ORGANIZATION IS RELATIVE, in which each record is stored and found by the number of its slot. On z/OS it is a VSAM relative record data set.
- RELATIVE KEY
- The item named by RELATIVE KEY: a number outside the record that tells a relative-file statement which slot to use. A READ NEXT puts the number of the slot it read there.
- relative record number
- The number of a record's slot in a relative file or a VSAM relative record data set, counted from 1.
- RRDS
- A relative record data set: a VSAM data set whose records are found by their relative record numbers. COBOL opens one as ORGANIZATION IS RELATIVE.
References
- Enterprise COBOL for z/OS 6.5 Programming Guide: Processing VSAM files (IBM)
- Enterprise COBOL for z/OS 6.5 Programming Guide: Defining VSAM files (IBM)
- Enterprise COBOL for z/OS 6.5 Programming Guide: Specifying sequential organization for VSAM files (IBM)
- Enterprise COBOL for z/OS 6.5 Programming Guide: Specifying relative organization for VSAM files (IBM)
- Enterprise COBOL for z/OS 6.5: File status key values (IBM)
- z/OS Basic Skills: What is VSAM? (IBM)
- z/OS Basic Skills: IDCAMS, use access method services for catalogs (IBM)
- z/OS 3.2 DFSMS Access Method Services Commands: DEFINE CLUSTER optional parameters (IBM)
- z/OS 3.2 DFSMS Access Method Services Commands: PRINT optional parameters (IBM)
- z/OS 3.2 DFSMS Access Method Services Commands: Dynamic allocation (IBM)
- GnuCOBOL 3.2 Programmer's Guide (relative files) (GnuCOBOL project (GNU))
Related tools
Report a problem with this lesson
Kept only in this browser. Your Learn progress