VSAM — Virtual Storage Access Method Complete Guide
In this tutorial, you'll learn about VSAM. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.
VSAM (Virtual Storage Access Method) is IBM's high-performance file access method for mainframes, providing indexed, sequential, and direct record access with built-in recovery, integrity, and security features.
What You'll Learn
- The four VSAM file organizations and when to use each
- How to define and manage VSAM datasets with IDCAMS
- How to read and write VSAM records using COBOL programs
- Real-world banking scenarios powered by KSDS clusters
Why VSAM Matters
Every time you check your bank balance, a VSAM dataset on a Mainframe likely retrieves your account record in milliseconds. VSAM handles trillions of transactions daily across banking, insurance, and airline systems. It's not just a file system — it's the backbone of online Transaction processing on IBM mainframes.
DodaZIP uses VSAM-inspired indexed access patterns to locate file entries in compressed archives without scanning the entire archive. Durga Antivirus Pro applies VSAM-style record-level locking when scanning concurrently accessed files.
Learning Path
flowchart LR A[Mainframe Basics] --> B[z/OS Guide] B --> C[VSAM
You are here] C --> D[IMS DB] D --> E[DB2 for z/OS]
What Is VSAM?
VSAM is an access method — a way of organizing and retrieving data on disk. Think of it as a specialized filing cabinet designed for high-speed Transaction processing.
Unlike regular files where you read from start to end, VSAM lets you:
- Jump directly to a record using a key (like an index)
- Read records in sorted order without sorting
- Lock individual records so two programs don't corrupt data simultaneously
The Four VSAM File Types
| Type | Full Name | Access Method | Best For |
|---|---|---|---|
| KSDS | Key Sequenced Data Set | Key or sequential | Account master files, customer records |
| ESDS | Entry Sequenced Data Set | Relative byte address | Log files, audit trails |
| RRDS | Relative Record Data Set | Relative record number | Fixed-length lookup tables |
| LDS | Linear Data Set | Byte addressable | High-performance Caching, DB2 logs |
KSDS — Key Sequenced Data Set (Most Common)
KSDS is the workhorse of Mainframe data storage. Each record has a unique key and VSAM maintains an index so you can fetch any record with one or two I/O operations — even if the file has millions of records.
INDEX: KEY → 1001 1002 1003 1004
| | | |
DATA: [Acct 1001] [Acct 1002] [Acct 1003] [Acct 1004]
$1,200 $5,400 $230 $12,800
When a new record is inserted, VSAM places it in key order automatically. No manual sorting needed.
ESDS — Entry Sequenced Data Set
ESDS appends new records to the end, like a log file. You can't access by key — you use the Relative Byte Address (RBA) — but ESDS is perfect for audit trails where you never modify past entries.
RRDS — Relative Record Data Set
RRDS uses slot numbers. Record 1 is in slot 1, record 50 is in slot 50. Excellent for fixed-size tables like currency codes or branch codes.
LDS — Linear Data Set
LDS has no record structure — it's just a block of bytes. DB2 uses LDS for its logs because it needs byte-level control.
Defining a VSAM Dataset with IDCAMS
IDCAMS (Integrated Catalog Access Method Services) is the utility used to define, modify, and delete VSAM datasets. Here's how to create a KSDS:
//DEFVSAM JOB 'DEFINE VSAM',CLASS=A
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER (NAME(ACCT.MASTER) -
VOLUMES(WRK001) -
RECORDS(10000) -
KEYS(6 0) -
INDEXED -
RECORDSIZE(200 200) -
FREESPACE(10 5) )
DATA (NAME(ACCT.MASTER.DATA))
INDEX (NAME(ACCT.MASTER.INDEX))
/*
Expected output:
IDCAMS SYSTEM SERVICES TIME: 14:32:01
DEFINE CLUSTER (NAME(ACCT.MASTER) ...
DATA (NAME(ACCT.MASTER.DATA))
INDEX (NAME(ACCT.MASTER.INDEX))
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
Explanation: KEYS(6 0) means the key is 6 bytes starting at position 0. RECORDSIZE(200 200) means fixed-length 200-byte records. FREESPACE(10 5) reserves 10% free space per control interval and 5% per control area for insert growth.
Loading Data into VSAM
Use the REPRO command to load records from a sequential file:
//LOADVSAM JOB 'LOAD VSAM',CLASS=A
//STEP1 EXEC PGM=IDCAMS
//INDD DD DISP=SHR,DSN=ACCT.INPUT
//OUTDD DD DISP=OLD,DSN=ACCT.MASTER
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
REPRO INFILE(INDD) OUTFILE(OUTDD)
/*
Reading VSAM in COBOL
Here's a COBOL program that reads a customer account from a VSAM KSDS:
IDENTIFICATION DIVISION.
PROGRAM-ID. READACCT.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT ACCT-FILE ASSIGN TO ACCTMAST
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS ACCT-KEY.
DATA DIVISION.
FILE SECTION.
FD ACCT-FILE.
01 ACCT-RECORD.
05 ACCT-KEY PIC X(6).
05 ACCT-BALANCE PIC 9(7)V99.
05 ACCT-NAME PIC X(30).
WORKING-STORAGE SECTION.
01 WS-KEY PIC X(6).
PROCEDURE DIVISION.
DISPLAY 'ENTER ACCOUNT NUMBER: '.
ACCEPT WS-KEY.
MOVE WS-KEY TO ACCT-KEY.
READ ACCT-FILE KEY IS ACCT-KEY
INVALID KEY DISPLAY 'NOT FOUND'.
DISPLAY 'ACCOUNT: ' ACCT-KEY.
DISPLAY 'NAME: ' ACCT-NAME.
DISPLAY 'BALANCE: ' ACCT-BALANCE.
CLOSE ACCT-FILE.
STOP RUN.
Expected output:
ENTER ACCOUNT NUMBER: 1001
ACCOUNT: 1001
NAME: John Smith
BALANCE: 000120000
VSAM and Security
VSAM datasets are protected by RACF or equivalent security products. Access can be controlled at the dataset level with profiles that specify READ, UPDATE, ALTER, or CONTROL authority.
Security best practices:
- Define separate profiles for data and index components
- Use RACF
PE(Permit) commands to grant minimal access - Enable VSAM record-level sharing with proper locking (SHR(1,3))
Common Errors
1. VSAM OPEN failure due to RACF
COSI111I indicates no RACF authorization. Verify the user profile permits access to the dataset.
2. IDC3250I — Dataset not in catalog
You must define the cluster in the master catalog first. Run IDCAMS DEFINE before REPRO.
3. COBOL READ INVALID KEY
The key you supplied doesn't exist in the index. Always handle INVALID KEY with a meaningful error message.
4. VSAM full — SPACE allocation exhausted
Monitor with LISTCAT ENTRIES(ACCT.MASTER) ALL and add secondary allocations.
5. Record size mismatch
If your COBOL program defines a record size different from the IDCAMS definition, you get I/O errors. Always match RECORDSIZE in DEFINE with the FD in COBOL.
6. OPEN with wrong access mode
Opening a KSDS in SEQUENTIAL mode when you need RANDOM access causes unexpected behavior. Use ACCESS MODE IS DYNAMIC for both.
7. Not closing files properly
Unclosed VSAM datasets can cause integrity issues. Always CLOSE files in COBOL and verify with LISTCAT.
Practice Questions
Which VSAM file type would you use for a bank's customer master file? KSDS — it provides keyed access so any customer can be retrieved by account number in one or two I/Os.
What does FREESPACE(10 5) do in a DEFINE CLUSTER? It reserves 10% free space per control interval and 5% per control area so new records can be inserted without reorganizing the file.
How does an ESDS differ from a KSDS? ESDS appends records sequentially with no index. Access is by RBA (Relative Byte Address), not by key. KSDS has an index and supports keyed access.
What is the purpose of IDCAMS REPRO? REPRO copies data into or out of a VSAM dataset, typically used to load a newly defined cluster from a sequential file.
Why use RRDS instead of KSDS for a fixed lookup table? RRDS provides direct access by slot number with less overhead than KSDS indexing, making it faster for fixed-size, known-slot data.
Challenge: Write an IDCAMS job that defines a KSDS cluster for a banking Transaction file with 50-byte records, 8-byte Transaction ID keys, 15% free space, and a secondary allocation of 500 records.
Mini Project: Bank Account Batch Report
Write a COBOL program that reads a VSAM KSDS of 1000 accounts and produces:
- A sorted listing of all accounts with balance > $10,000
- Count of accounts per balance tier (< $1K, $1K-$10K, $10K+)
- Total sum of all balances
IDENTIFICATION DIVISION.
PROGRAM-ID. BATCHRPT.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT ACCT-FILE ASSIGN TO ACCTMAST
ORGANIZATION IS INDEXED
ACCESS MODE IS SEQUENTIAL
RECORD KEY IS ACCT-KEY.
DATA DIVISION.
FILE SECTION.
FD ACCT-FILE.
01 ACCT-RECORD.
05 ACCT-KEY PIC X(6).
05 ACCT-BALANCE PIC 9(7)V99.
05 ACCT-NAME PIC X(30).
WORKING-STORAGE SECTION.
01 WS-TOTAL-BAL PIC 9(9)V99 VALUE 0.
01 WS-COUNT-TIER1 PIC 9(4) VALUE 0.
01 WS-COUNT-TIER2 PIC 9(4) VALUE 0.
01 WS-COUNT-TIER3 PIC 9(4) VALUE 0.
01 WS-EOF PIC X VALUE 'N'.
88 EOF VALUE 'Y'.
PROCEDURE DIVISION.
OPEN INPUT ACCT-FILE.
PERFORM UNTIL EOF
READ ACCT-FILE NEXT
AT END SET EOF TO TRUE
NOT AT END
ADD ACCT-BALANCE TO WS-TOTAL-BAL
EVALUATE TRUE
WHEN ACCT-BALANCE < 1000
ADD 1 TO WS-COUNT-TIER1
WHEN ACCT-BALANCE < 10000
ADD 1 TO WS-COUNT-TIER2
WHEN OTHER
ADD 1 TO WS-COUNT-TIER3
END-EVALUATE
END-READ
END-PERFORM.
CLOSE ACCT-FILE.
DISPLAY 'TOTAL BALANCE: ' WS-TOTAL-BAL.
DISPLAY 'TIER1 (<1K): ' WS-COUNT-TIER1.
DISPLAY 'TIER2 (1K-10K): ' WS-COUNT-TIER2.
DISPLAY 'TIER3 (10K+): ' WS-COUNT-TIER3.
STOP RUN.
Expected output:
TOTAL BALANCE: 45238900.00
TIER1 (<1K): 245
TIER2 (1K-10K): 512
TIER3 (10K+): 243
FAQ
What's Next
| Tutorial | What You'll Learn |
|---|---|
| IMS DB — Hierarchical Database Guide | Explore IBM's hierarchical database for high-volume Transaction processing |
| DB2 for z/OS Guide | Master relational database management on the Mainframe |
| CICS Transaction Processing Guide | Build online Transaction processing applications |
Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. Updated 2026-06-21.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro