VSAM Logical Record

In VSAM, the logical record is the unit of data that your application program works with. When you READ a record, you get one logical record into your program buffer. When you WRITE or REWRITE, you send one logical record to VSAM. The logical record is the "record layout" you define in your program—the fields, the key (for KSDS), and the data. VSAM stores many logical records inside control intervals and uses the key, RBA, or RRN to find the right one. Understanding logical records helps you design record layouts, choose fixed vs variable length, and use the right access method. This page explains what a logical record is, how it differs from the physical record (CI), how to define record size in DEFINE CLUSTER and in the program, and how records are identified by key, RBA, and RRN.

What Is a Logical Record?

A logical record is the data that represents one "record" from the application's point of view. For example, one customer, one order, or one transaction. The application programmer designs the logical record: its length (fixed or variable), the position and length of the key (for KSDS), and the layout of the rest of the fields. The program uses this layout in the FILE SECTION (COBOL) or equivalent to read and write data. So the logical record is the "interface" between your program and VSAM: you ask for one logical record by key or position, and VSAM returns one logical record (or you put one logical record and VSAM stores it).

VSAM does not store "logical records" as separate objects on disk. It stores data in control intervals. A CI contains many logical records (plus free space, RDFs, and CIDF). So the logical record is the logical view; the CI is the physical container. When you request logical record 100 by key, VSAM finds the CI that contains that key, reads the CI (if not already in a buffer), and extracts the logical record for your program. You always work in logical records; VSAM handles the mapping to CIs.

Logical Record vs Physical Record

The physical record (or block) in VSAM is the control interval. The CI is the fixed-size unit that VSAM reads or writes in one I/O operation. One CI can hold many logical records (for example 20 fixed-length 80-byte records in a 4096-byte CI, minus space for RDFs and free space). So there is a one-to-many relationship: one physical record (CI) contains many logical records (except in the case of a single spanned record that occupies multiple CIs).

Non-VSAM datasets (e.g. QSAM) often use the term "block" for the physical unit and "record" for the logical unit. In VSAM the terms are "control interval" (physical) and "logical record" (what the program sees). The BLOCK CONTAINS clause in COBOL has no effect on VSAM; VSAM blocking is internal to the CI. You define only the logical record layout and size in your program and in DEFINE CLUSTER (RECORDSIZE).

Fixed-Length and Variable-Length Logical Records

VSAM supports both fixed-length and variable-length logical records for KSDS and ESDS. For RRDS, the classic form uses fixed-length slots (one logical record per slot); variable RRDS (VRRDS) allows variable-length records in slots. Fixed-length means every logical record has the same byte length. Variable-length means records can vary up to a maximum; VSAM stores the length with each record (in the RDF) so it can find the next record.

In DEFINE CLUSTER you specify RECORDSIZE(average maximum). For fixed-length use the same value for both, e.g. RECORDSIZE(80 80) or RECORDSIZE(200 200). For variable-length use different values, e.g. RECORDSIZE(100 500) for records that average 100 bytes but can be up to 500. The maximum must be at least as large as the largest record you will store. For variable-length records, VSAM uses more record descriptor fields (one RDF per record in the variable case), so there is slightly more overhead per record than with fixed-length.

Defining the Logical Record in the Program

In a COBOL program you define the logical record in the FILE SECTION under the FD (file descriptor) for the VSAM file. The 01-level record is the logical record. You specify RECORD CONTAINS n CHARACTERS for fixed-length, or RECORD IS VARYING or RECORD CONTAINS n TO m for variable-length. The key (for KSDS) is typically a subfield at a fixed offset; you define it in the record layout. Example for a fixed-length KSDS record:

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 logical record is 120 bytes; the key is the first 10 bytes (CUST-KEY). The program reads CUST-REC, updates fields, and writes or rewrites CUST-REC. VSAM uses CUST-KEY for key-based access. BLOCK CONTAINS is omitted because it has no effect on VSAM.

How Logical Records Are Identified

Depending on the dataset type, you identify a logical record by key, by relative byte address (RBA), or by relative record number (RRN). The access mode (random vs sequential) and the identifier determine how VSAM finds the record.

In a KSDS you typically use the key for random access: move the key to the key field in your record, issue READ, and VSAM returns the logical record with that key. You can also read sequentially in key order. In an ESDS you do not have a key; you read by RBA (if you saved the RBA from a prior read or from a key in an alternate index) or sequentially from the start. In an RRDS you use the RRN to read or write a specific slot (1-based). So the logical record is always the same concept—one record layout—but the way you address it depends on the VSAM type.

RECORDSIZE in DEFINE CLUSTER

When you define a cluster, RECORDSIZE(average maximum) tells VSAM the size of the logical records. For fixed-length, use RECORDSIZE(n n). For variable-length, use RECORDSIZE(avg max). The CI size (CISZ) must be large enough to hold at least one maximum-length record (unless you use spanned records). VSAM uses the record size to format CIs and to compute how many records fit in a CI (for space estimation when you use RECORDS(n m) allocation). If your program writes a record larger than the maximum, the request fails. So the logical record size in the program must match (or be within) the RECORDSIZE you used at define time.

Spanned Records

A spanned record is a logical record that is larger than one control interval. VSAM can store it across multiple CIs (within the same control area). Spanned records are used when the logical record size exceeds the CI size—for example very long text or large structures. You define the cluster with the SPANNED attribute and RECORDSIZE with a maximum larger than CISZ. There is only one logical record per spanned record; it just occupies more than one CI. Most applications use non-spanned records (logical record fits in one CI).

Key Takeaways

• The logical record is the unit of data the application program reads or writes: one record layout (key + data fields).
• VSAM stores many logical records inside control intervals. The CI is the physical unit of I/O; the logical record is the program's view.
• RECORDSIZE(average maximum) in DEFINE CLUSTER defines the logical record size. Use the same value twice for fixed-length; use different values for variable-length.
• Logical records are identified by key (KSDS), RBA (ESDS/KSDS), or RRN (RRDS), depending on dataset type and access mode.
• The program's record layout (e.g. COBOL 01-level) must match the RECORDSIZE and key definition used when the cluster was defined.

Explain Like I'm Five

The logical record is one "card" in your filing system. When you ask for "the card for customer 123," the computer finds the drawer (control interval) that has that card, brings the whole drawer to the desk, and then hands you just that one card (the logical record). You only see your one card; the computer worries about where the drawer is and how many other cards are in it. The key (or the card's position) is how you ask for the right card.

Test Your Knowledge