VSAM Record

In VSAM, the term "record" means the unit of data your application program reads or writes: one customer, one order, one transaction. A record has a defined structure—for a KSDS that includes the key and the data fields; for an ESDS or RRDS it is the data (and for RRDS, a fixed-length slot). VSAM stores many records inside control intervals and uses keys, RBAs, or RRNs to find them. Understanding what a record is in VSAM, how it differs from the control interval, and how record type (fixed, variable, spanned) and size are defined will help you design files and write correct COBOL or other programs. This page explains the record concept, record structure by dataset type, RECORDSIZE and SPANNED, and how records are stored and operated on.

What Is a Record in VSAM?

A record in VSAM is the logical unit of data that your program treats as one item. When you issue a READ, you get one record into your buffer. When you WRITE or REWRITE, you send one record to VSAM. So "record" in everyday VSAM usage means the same thing as "logical record": the single unit of information (with a defined layout and size) that the application works with. VSAM does not move one record at a time to or from disk; it moves control intervals (physical blocks) that contain many records. The access method figures out which CI holds the record you want, reads that CI (if needed), and then gives your program just that one record. So from the program's point of view, everything is in records; from VSAM's point of view, everything is in CIs that hold many records.

The record layout is what you define in your program—for example in COBOL, the 01-level under the FD for the VSAM file. That layout must match what you told VSAM when the cluster was defined: record size (RECORDSIZE), and for KSDS the key position and length (KEYS). If the program writes a record larger than the maximum you defined, the request fails. So the "record" is the agreed unit of data between your program and VSAM, with a defined size and (for KSDS) key.

Record vs Control Interval

It is important to keep "record" and "control interval" distinct. The record is what the program sees: one logical unit. The control interval (CI) is the fixed-size block that VSAM uses for I/O. One CI holds many records (except when one record is spanned across several CIs). So there is a one-to-many relationship: one CI contains multiple records. When you ask for record number 50 by key, VSAM does not read 50 separate records from disk; it finds the CI that contains that key, reads that whole CI (one I/O), and then returns the one record to your program. So the record is the unit of work for the application; the CI is the unit of transfer for VSAM.

Record Structure by Dataset Type

What a "record" looks like depends on the VSAM dataset type. In a KSDS the record includes the primary key (at a fixed offset) and the rest of the data. In an ESDS there is no key—the record is just the data, and order is the order in which records were written. In an RRDS the record is one fixed-length slot; the slot may hold a record or be empty. In an LDS there are no VSAM records at all—just a byte stream that the application interprets.

Fixed-Length, Variable-Length, and Spanned Records

VSAM supports three ways to store records: fixed-length, variable-length, and spanned. Fixed-length means every record has the same size (e.g. 80 bytes or 200 bytes). Variable-length means each record can be shorter or longer up to a maximum; VSAM stores the length with each record so it can find the next one. Spanned means a single record can extend across more than one control interval—used when the maximum record size is larger than the CI size. You choose the type when you define the cluster.

For fixed-length you specify RECORDSIZE(n n)—the same value for average and maximum. For variable-length you specify RECORDSIZE(average maximum), e.g. RECORDSIZE(100 500). The maximum must be at least as large as the largest record you will store. For spanned records you also specify SPANNED when defining the cluster; the maximum record length can then exceed the CI size, and VSAM will store the record across as many CIs as needed (up to 255 CIs per record). Spanned records are allowed only for KSDS and ESDS. Locate mode (OPTCD=LOC) cannot be used with spanned records.

RECORDSIZE in DEFINE CLUSTER

When you define a cluster, RECORDSIZE(average maximum) tells VSAM the size of the logical records. The values are in bytes. For fixed-length use the same number twice, for example RECORDSIZE(120 120). For variable-length use two different numbers: the first is the average length (used for space estimation), the second is the maximum. Example for variable-length records that can be up to 300 bytes:

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

The CI size (CISZ) must be large enough to hold at least one maximum-length record unless you use spanned records. If your maximum is 300 and you do not use SPANNED, the control interval must be at least 300 bytes plus space for RDFs and CIDF. In practice CIs are usually 4KB or 8KB so that many records fit in one CI and I/O is efficient.

How Records Are Stored in a CI

Inside a control interval, records are packed from the beginning. Each record is preceded (or described) by a record descriptor field (RDF) that stores the record length—essential for variable-length records so VSAM knows where one record ends and the next begins. After the records there is free space (for KSDS and RRDS), then the RDFs and the control interval descriptor field (CIDF) at the end. So the layout is: [record][record][record]… [free space] [RDFs][CIDF]. You do not define this layout; VSAM manages it. Your program only sees whole records; VSAM handles packing and unpacking.

Record Operations by Dataset Type

The operations you can perform on a record depend on the dataset type. In a KSDS you can read a record by key (random) or in key sequence (sequential), insert a new record (VSAM places it in key order using free space), update a record in place (REWRITE), and delete a record (VSAM marks it and can reclaim space). In an ESDS you can read by RBA or sequentially, and update in place, but you cannot physically delete a record—you can only overwrite it or use a logical-delete pattern (e.g. a flag byte). In an RRDS you read or write by relative record number (RRN); you can insert into an empty slot, delete (free the slot), and replace (overwrite the slot). So the idea of "record" is the same—one unit—but the operations and how you identify the record (key, RBA, RRN) differ by type.

Spanned Records in More Detail

A spanned record is one logical record that is larger than the control interval. VSAM stores it in segments across multiple CIs (all within the same control area). For a KSDS, the entire key must be in the first CI (first segment). Spanned records can reduce wasted space when you have a few very long records: without spanning you might need a huge CI to hold the longest record, or you would have to split the record yourself. With SPANNED, VSAM handles putting one record across CIs. Remember: only KSDS and ESDS support spanned records; locate mode is not allowed; and a single record cannot span more than 255 data CIs.

Defining the Record in Your Program

In a COBOL program you define the record in the FILE SECTION under the FD for the VSAM file. The 01-level is the record. For fixed-length you use RECORD CONTAINS n CHARACTERS. For variable-length you use RECORD IS VARYING or RECORD CONTAINS n TO m. The key (for KSDS) is a subfield at the offset and length you specified in KEYS. Example:

1
2
3
4
5
6
7
8
       FILE SECTION.
       FD  CUSTFILE.
           RECORD CONTAINS 120 CHARACTERS.
       01  CUST-REC.
           05  CUST-KEY    PIC X(10).
           05  CUST-NAME  PIC X(40).
           05  CUST-BAL   PIC S9(7)V99.
           05  FILLER     PIC X(60).

Here the record is 120 bytes; the key is the first 10 bytes. This must match the RECORDSIZE and KEYS you used when the cluster was defined. The program reads and writes CUST-REC; VSAM uses CUST-KEY for key-based access.

Key Takeaways

• In VSAM, a "record" is the logical unit of data the program reads or writes—one customer, one transaction—with a defined layout and size.
• Records are stored inside control intervals; one CI holds many records. The program works in records; VSAM moves CIs and extracts or stores records.
• RECORDSIZE(average maximum) in DEFINE CLUSTER defines record size. Same value twice = fixed-length; different values = variable-length. SPANNED allows one record across multiple CIs (KSDS and ESDS only).
• Record structure and operations depend on dataset type: KSDS (key + data), ESDS (data, RBA), RRDS (fixed-length slot, RRN), LDS (no record structure).
• The program's record layout (e.g. COBOL 01-level) must match RECORDSIZE and KEYS from the cluster definition.

Explain Like I'm Five

Imagine a record as one card in a filing box. The box is like a control interval—it holds many cards. When you want one card (one record), the computer finds the right box, brings the whole box to the table, and then hands you just that one card. The card can be a fixed size (every card the same) or different sizes (variable), and sometimes one card is so big it needs to be split across two boxes (spanned). The computer knows how to find your card by its label (key), its position in the box (RBA), or its slot number (RRN).

Test Your Knowledge