VSAM Spanned Records

Sometimes a logical record is larger than the control interval size you want to use for the dataset. In VSAM you do not have to break the record into pieces in your program: you can define the dataset with spanned records. The SPANNED parameter lets a single logical record extend across (span) more than one control interval. VSAM stores the record in segments—one or more full CIs—and reassembles it when you read. Spanned records can reduce DASD usage when you have a mix of short and long records or when the average record is large compared to the CI. This page explains what spanned records are, when to use them, the rules (KSDS/ESDS only, key in first CI, no locate mode, 255 CI limit), and how to define a cluster with SPANNED.

What Are Spanned Records?

A spanned record is one logical record that is stored in more than one control interval. Normally, each logical record fits entirely inside one CI; if the record is longer than the CI, without SPANNED you would have to either make the CI very large (wasting space for shorter records) or split the record yourself. With SPANNED, you define the cluster with RECORDSIZE such that the maximum record length can exceed the CI size, and you specify SPANNED. VSAM then stores a long record in consecutive CIs within the same control area. When you read the record, VSAM reads all the segments and returns one logical record to your program. So from the program's point of view it is still one record; on disk it occupies multiple CIs.

Spanned records can improve space use. For example, if your CI size is 4096 bytes and you have some records of 2000 bytes and some of 10000 bytes, without spanning you might need a 10240-byte CI to hold the longest record, and the shorter records would leave unused space in each CI. With a smaller CI (e.g. 4096) and SPANNED, the 2000-byte records fit in one CI, and the 10000-byte record spans three CIs. The total space can be less because you are not forcing every CI to be as large as the longest record.

When to Use Spanned Records

Use spanned records when:

• Your maximum record length is larger than the control interval size you want (e.g. for better sequential performance with smaller CIs, or to match other files).
• Record lengths vary a lot and you want to avoid wasting space—smaller CIs with spanning can use DASD more efficiently than one huge CI per record.
• You are defining a KSDS or ESDS and need to support very long records (e.g. document text, large XML, or variable blocks) without making the CI oversized for the majority of records.

Do not use spanned records for RRDS or LDS (they are not supported). If almost all records fit in one CI and only a few are long, the overhead of spanning (extra I/O to read multiple segments) may not be worth it; you might instead use a larger CISZ or keep long data in a separate file.

Rules for Spanned Records

IBM documents several rules you must follow when using spanned records. Violating them can lead to define failures, incorrect behavior, or runtime errors.

Defining a Cluster with Spanned Records

To allow spanned records, specify SPANNED when you define the cluster. You can do this in the DEFINE CLUSTER command or in the data class used by the cluster. RECORDSIZE must have a maximum large enough for your longest record; that maximum can exceed the CI size. Example:

1
2
3
4
5
6
7
8
9
10
11
  DEFINE CLUSTER ( -
    NAME(USERID.DOCS.KSDS) -
    INDEXED -
    RECORDSIZE(2000 12000) -
    KEYS(20 0) -
    SPANNED -
    CISZ(4096) -
    FREESPACE(10 5) -
    CYLINDERS(10 5)) -
  DATA (NAME(USERID.DOCS.KSDS.DATA)) -
  INDEX (NAME(USERID.DOCS.KSDS.INDEX))

Here RECORDSIZE(2000 12000) allows records up to 12000 bytes; CISZ(4096) sets the control interval to 4KB. A 12000-byte record would span three 4KB CIs. SPANNED tells VSAM that records may cross CI boundaries. For a KSDS, the key (20 bytes at offset 0) must fit in the first CI—it does, since 20 is less than 4096. VSAM decides at write time whether a given record is stored in one CI (nonspanned) or multiple CIs (spanned) based on its length and the CI size.

Key in the First CI (KSDS)

For key-sequenced data sets, the entire primary key of a spanned record must reside in the first control interval (the first segment). VSAM uses the key to build the index; the index points to the first CI of the record. When you read by key, VSAM finds that first CI and then reads as many more CIs as needed to return the full record. So the key offset and key length (KEYS(length offset)) must be such that the key fits entirely in the first CI. In practice this is almost always the case, because key length is usually small (e.g. 10–50 bytes) and the first CI is at least 512 bytes or more.

Locate Mode Not Allowed

Locate mode (OPTCD=LOC on the Request Parameter List, or the equivalent in your programming interface) is not valid for datasets that contain spanned records. In locate mode, VSAM gives the program a pointer to data in the buffer rather than copying the record. For spanned records, the data is in multiple segments; the access method cannot expose a single contiguous pointer for the whole record. If you use locate mode with a spanned dataset, VSAM returns a nonzero return code. Use move mode so that VSAM assembles the full record and moves it into your buffer.

Unused Space in the Last Segment

The control interval that contains the last segment of a spanned record may have unused space at the end (because the record does not fill the whole CI). That space can be used only to extend the same spanned record (e.g. with a REWRITE that lengthens the record). It cannot hold another record or part of another record. So the last CI of a spanned record is dedicated to the tail of that record only.

Compressed Data Sets and Spanned Records

For compressed datasets with spanned records, the record prefix length is 5 bytes. The key offset plus key length (the relative key position) must be less than or equal to the CI size minus 15. This ensures the key fits in the first CI after accounting for the compression prefix. If you use compression and SPANNED, check your KEYS and CISZ against this rule.

Key Takeaways

• Spanned records let one logical record extend across multiple control intervals. Specify SPANNED when defining the cluster (or in the data class).
• Spanned records are supported only for KSDS and ESDS. RRDS and LDS do not support them.
• For KSDS, the entire key must be in the first CI of the spanned record. Locate mode (OPTCD=LOC) cannot be used with spanned records.
• A single record can span at most 255 data control intervals and must stay within one control area.
• Spanned records can reduce DASD usage when record lengths vary and the maximum is larger than the desired CI size.

Explain Like I'm Five

Imagine one long drawing that doesn't fit on a single page. You tape several pages together and draw across them. That's a spanned record: one picture (one record) that uses more than one "page" (control interval). The computer knows to read all the pages and give you the whole picture. For a KSDS, the "label" (key) has to be on the first page so the computer can find the picture in the index.

Test Your Knowledge