RECORDSIZE Parameter

RECORDSIZE is a DEFINE CLUSTER parameter that specifies the minimum (average) and maximum record length in bytes for the VSAM cluster. You code it as RECORDSIZE(average maximum) or RECORDSIZE(min max). For fixed-length records you use the same value for both (e.g. RECORDSIZE(80 80)). For variable-length records you specify the shortest and longest possible record (e.g. RECORDSIZE(50 200)). VSAM uses these values to determine how records are stored in control intervals, how much space to reserve, and to validate record length on write. RECORDSIZE applies to KSDS, ESDS, and RRDS; it does not apply to LDS, which has no record structure. This page explains the RECORDSIZE parameter: syntax, fixed vs variable length, effect on CI and space, and how it differs by dataset type.

Syntax and Abbreviations

In DEFINE CLUSTER (or in the DATA subparameters), you specify:

1
2
  RECORDSIZE(average maximum)
  /* Abbreviation: RECSZ(average maximum) */

Both average and maximum are numeric values in bytes. The first value is often called the "average" or "minimum" length; the second is the "maximum" length. For fixed-length records, the two must be equal: every record is exactly that many bytes. For variable-length records, each record can be any length from the first value up to the second value. VSAM uses the average (or minimum) and maximum to compute how many records can fit in a control interval and to allocate space. The following table summarizes the main aspects.

Fixed-Length vs Variable-Length

When you specify RECORDSIZE(80 80), you are defining fixed-length records of 80 bytes. Every record in the cluster must be exactly 80 bytes when written. The program (or REPRO) must supply 80-byte records. VSAM can pack fixed-length records efficiently into control intervals because it does not need to store a length for each record in the same way as variable-length (though internal control structures may still be used). When you specify RECORDSIZE(50 200), records can be any length from 50 to 200 bytes. Each record has a record descriptor field (RDF) that stores its length so VSAM knows where one record ends and the next begins. Variable-length records use more overhead per record and can leave more unused space in a CI when records are shorter than the maximum. Choose fixed length when all records are the same size; choose variable when record length varies (e.g. different-sized customer or transaction records).

Effect on Control Intervals and Space

VSAM uses RECORDSIZE (along with control interval size and free space) to determine how many records fit in each control interval. Larger maximum record length means fewer records per CI (and possibly more CIs for the same number of records). Smaller fixed length means more records per CI and often better sequential read density. When you allocate space with RECORDS(primary secondary), VSAM uses the record size to compute how many control intervals and control areas are needed. So RECORDSIZE directly affects storage efficiency and I/O: getting it right at define time avoids wasting space or having to redefine and copy the cluster later.

RECORDSIZE by Dataset Type

Key and Record Length

For a KSDS, the key is part of the record. You specify KEYS(length offset). The key must lie entirely within the record. So the key offset plus key length must not exceed the record length. For example, with RECORDSIZE(100 100) and KEYS(10 0), the key is bytes 0–9 and the record is 100 bytes, so the key fits. With RECORDSIZE(80 80) and KEYS(15 70), the key would extend from byte 70 to 84, but the record is only 80 bytes—that is invalid. So when you choose RECORDSIZE for a KSDS, ensure the maximum record length is at least key offset + key length, and that your application never writes records shorter than that (for variable-length).

Example: DEFINE CLUSTER with RECORDSIZE

Fixed-length KSDS with 80-byte records:

1
2
3
4
5
6
7
8
9
  DEFINE CLUSTER ( -
    NAME(MY.APPL.FIXED.KSDS) -
    INDEXED -
    RECORDSIZE(80 80) -
    KEYS(10 0) -
    FREESPACE(20 10) -
    CYLINDERS(5 2)) -
  DATA (NAME(MY.APPL.FIXED.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.FIXED.KSDS.INDEX))

Variable-length ESDS with records between 100 and 500 bytes:

1
2
3
4
5
6
  DEFINE CLUSTER ( -
    NAME(MY.APPL.VAR.ESDS) -
    NONINDEXED -
    RECORDSIZE(100 500) -
    CYLINDERS(10 5)) -
  DATA (NAME(MY.APPL.VAR.ESDS.DATA))

In the first example, every record is exactly 80 bytes and the key is the first 10 bytes. In the second, there is no key (ESDS) and records can vary from 100 to 500 bytes.

ALTER and RECORDSIZE

Some implementations of IDCAMS allow you to change RECORDSIZE with ALTER. When you do, the new value is stored in the catalog. It may affect how much space is reserved for new records or how VSAM validates writes; it does not reformat existing records. So increasing the maximum with ALTER might allow longer records to be written from that point on, but existing records are unchanged. If you need to change record length in a way that affects all data (e.g. switch from 80 to 100 bytes fixed), you usually define a new cluster with the new RECORDSIZE and copy the data (e.g. with a program or REPRO with a reformat step). Check your IDCAMS documentation for whether ALTER RECORDSIZE is supported and how it behaves.

Key Takeaways

• RECORDSIZE(average maximum) specifies minimum and maximum record length in bytes. Use the same value twice for fixed-length.
• Fixed-length: RECORDSIZE(n n). Variable-length: RECORDSIZE(min max) with min < max.
• RECORDSIZE affects how many records fit in a CI and how space is allocated. It applies to KSDS, ESDS, and RRDS; not to LDS.
• For KSDS, key offset + key length must not exceed record length.
• RECORDSIZE is set at define time; ALTER may allow changing it in some implementations, but existing records are not reformatted.

Explain Like I'm Five

RECORDSIZE is like telling the computer: "Each of my records is this big (or between this and this big)." If you say (80 80), every record is exactly 80 bytes—like every card in a stack being the same size. If you say (50 200), each record can be as short as 50 or as long as 200 bytes—like cards of different sizes. The computer uses this to pack records into boxes (control intervals) and to know how much space the file needs.

Test Your Knowledge