VSAM KSDS Structure

A Key-Sequenced Data Set (KSDS) is the most common VSAM type when you need key-based access. Its structure has two parts: the data component, which holds the actual records in ascending key order, and the index component, which holds the index (sequence set and index set) that maps key values to control intervals in the data. Together they form one cluster. Programs open the cluster and read or write by primary key; VSAM uses the index to find the right CI and keeps records sorted automatically. Understanding KSDS structure helps you design key layout, choose CI size and FREESPACE, and reason about performance. This page explains the two components, how records are organized, and how sequential, random, and dynamic access work.

Two Components: Data and Index

Every KSDS cluster has two components. The data component is where the logical records live. Each record has a primary key (a contiguous set of bytes at a fixed offset and length you specify with KEYS). VSAM stores records in ascending collating sequence by that key. So the data component is not "just a pile of records"—it is a sorted structure. Records are packed into control intervals; within each CI they are in key order. When you insert a record, VSAM finds the correct CI for that key (using the index), puts the record in key order within the CI (using free space), and if there is no room, performs a CI split (or CA split). So the data component is always logically ordered by key.

The index component is what makes key-based lookup fast. It does not hold the actual application data; it holds key values and pointers. The lowest level of the index is the sequence set: one entry per control interval in the data component. Each entry has the highest key in that CI and a pointer to that CI. So when you ask for a record with key "X", VSAM looks at the sequence set, finds the entry whose key range includes X, and follows the pointer to the data CI. That one CI is then read and the record with key X is returned (or "not found" if it is not there). If the sequence set is large, VSAM adds one or more levels above it—the index set—with separator keys and pointers, so that finding the right sequence set entry takes only a few steps. So the index component is a B-tree style structure that points into the data component.

Records in Key Order

A KSDS keeps records in ascending key order at all times. When you load the file (e.g. with REPRO or with a program writing in key order), VSAM places records in CIs in key sequence. When you insert a new record, VSAM finds the CI that should hold it (by key), uses free space in that CI to insert the record in the correct position, and if there is no free space, splits the CI (and possibly the CA). So you never have to sort the file yourself—VSAM maintains the order. Sequential read (READ NEXT after a START, or simply sequential) returns records in key order. That is why KSDS is called "key-sequenced": the physical and logical order are the same, and both are by key.

Access Modes

KSDS supports three ways to access data. In sequential access you read records one after another in key order (forward or backward). VSAM uses the sequence set to walk through the data CIs in order. In random (direct) access you supply the full primary key and issue a READ; VSAM uses the index set and sequence set to find the data CI that contains that key, reads that CI, and returns the record. In dynamic access you mix both—for example, read a record by key, then do a series of READ NEXT to process a range. The same open file supports all three; you choose the access mode when you open or when you issue the request, depending on the interface.

Defining a KSDS

You define a KSDS with DEFINE CLUSTER and the INDEXED organization. You must specify the primary key with KEYS(length offset) and the record size with RECORDSIZE. Example:

1
2
3
4
5
6
7
8
9
  DEFINE CLUSTER ( -
    NAME(USERID.CUSTOMER.KSDS) -
    INDEXED -
    RECORDSIZE(120 120) -
    KEYS(12 0) -
    FREESPACE(20 10) -
    CYLINDERS(10 5)) -
  DATA (NAME(USERID.CUSTOMER.KSDS.DATA)) -
  INDEX (NAME(USERID.CUSTOMER.KSDS.INDEX))

INDEXED means KSDS. KEYS(12 0) means the key is 12 bytes long and starts at offset 0 (first 12 bytes of each record). The data and index components get the names in the DATA and INDEX clauses. VSAM creates both components and builds the index as you load or insert records.

Key Takeaways

• KSDS has two components: data (records in key order) and index (sequence set + index set mapping keys to data CIs).
• Records are stored in ascending key order; VSAM maintains order on insert via free space and splits.
• Access can be sequential (in key order), random (by key), or dynamic (mix of both).
• The primary key must be unique. KEY length and offset are set at define time with KEYS(length offset).

Explain Like I'm Five

Think of a KSDS as a dictionary: the data is the list of words in alphabetical order (key order). The index is the thumb tabs that tell you "this page has words from A to C." When you want the word "apple," you look at the tabs (index), find the right page (data CI), then find "apple" on that page. The book always keeps words in order; when you add a new word, the book makes room in the right place (and sometimes splits a page).

Test Your Knowledge