VSAM Key Length

In a Key-Sequenced Data Set (KSDS), the primary key is a fixed-length field that identifies each record and determines the order of records. The key length is how many bytes the key occupies—specified as the first value in KEYS(length offset) when you define the cluster. VSAM allows a key length of 1 to 255 bytes. This length is the same for every record, is used by VSAM to compare keys and maintain ascending order, and affects the size and shape of the index component. Choosing the right key length balances uniqueness, storage in the index, and how the key fits in your record layout. This page explains key length in VSAM: the 1–255 range, how it relates to RECORDSIZE and key offset, how it affects the index, and how to choose a key length.

What Is Key Length?

The key length is the number of bytes that make up the primary key in each record. It is the first value in the KEYS parameter: KEYS(length offset). For example KEYS(10 0) means a 10-byte key; KEYS(20 5) means a 20-byte key starting at offset 5. Every record in the KSDS must have a key of exactly this length at the same offset. VSAM uses these bytes to compare records (in collating sequence, usually EBCDIC), to maintain the file in ascending key order, and to build and search the index. The key length is fixed when you define the cluster and cannot be changed with ALTER. If you need a different key length, you must define a new cluster with the new KEYS and migrate the data.

Valid Range: 1 to 255 Bytes

VSAM requires the key length to be between 1 and 255 bytes inclusive. A 1-byte key is valid but allows only 256 distinct values (one per byte value), so it is rarely used except for very small files or type codes. At the other end, 255 bytes is the maximum. Long keys are allowed but they increase the size of the index because each index entry (sequence set or index set) stores key values or key separators. So a 100-byte key uses roughly 100 bytes per index entry, whereas a 10-byte key uses 10 bytes per entry. For a file with many records, a longer key can mean more index control intervals, more index levels, or a larger index component. So in practice, key lengths are often in the 4–20 byte range for numeric or short alphanumeric identifiers, and longer only when the business key is naturally long (e.g. a long code or composite key).

Key Length and Record Length

The key does not have to be the same length as the record, but it must fit inside the record. So: key offset + key length must be less than or equal to the record length. For fixed-length records of 200 bytes with the key at offset 0, the key length can be any value from 1 to 200 (and VSAM allows up to 255, but 200 is the maximum that fits in this record). For variable-length records, the key must fit within the minimum record length (or the maximum, depending on implementation); to be safe, ensure offset + key length does not exceed the minimum record size so that every record can contain a valid key. RECORDSIZE(min max) defines the record lengths; KEYS(length offset) must be consistent with that. For example RECORDSIZE(100 200) with KEYS(50 0) is valid (key fits in the minimum 100-byte record); KEYS(120 0) would be invalid because a 120-byte key cannot fit in a 100-byte minimum record.

How Key Length Affects the Index

The index component of a KSDS stores information used to locate data records. The sequence set contains index records that typically include key values (or high-key values) and pointers to data control intervals. The index set contains separators and pointers to the next level. The amount of key data stored in the index depends on the key length. A 10-byte key uses 10 bytes per relevant index entry; a 100-byte key uses 100 bytes. So for the same number of data records, a longer key produces a larger index: more index CIs, possibly more index levels, and more buffer space for index I/O. That can slightly increase the cost of random access (more index to traverse) and the space used for the index. It does not change how many data records you can store, but it does affect index size and, to some degree, performance. For most applications, key lengths of 8–20 bytes are a good balance; use longer keys only when the natural identifier is long.

Fixed Length for All Records

The key length is the same for every record in the cluster. You cannot have one record with a 10-byte key and another with a 15-byte key. So when you design the key, you must choose a length that accommodates all possible key values. For numeric keys (e.g. customer number), pick a length that holds the largest value (e.g. 8 bytes for a large integer or packed decimal). For alphanumeric keys, pad or truncate to a fixed length (e.g. account code always 12 bytes, padded with spaces). If the natural key varies in length, you either fix the length (with padding) or use a different approach (e.g. a generated fixed-length ID as the key and store the variable-length value in the record).

Choosing a Key Length

Choose the key length based on: (1) Uniqueness—the key must uniquely identify each record, so it must be long enough to hold all distinct values. (2) Record layout—offset + length must not exceed record length. (3) Index size—shorter keys mean a smaller index. (4) Application—match what the program expects (e.g. PIC X(12) in COBOL means 12 bytes). Common choices: 4 or 8 bytes for numeric IDs, 10–12 for account or order numbers, 16–20 for composite keys (e.g. date + time + sequence). Avoid making the key longer than necessary; it wastes index space and can slow index operations.

Defining the Cluster with Key Length

In DEFINE CLUSTER you specify the key length as the first argument of KEYS(length offset). Only KSDS uses KEYS. Example with different key lengths:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
  * 8-byte key at offset 0 (e.g. numeric ID)
  DEFINE CLUSTER ( -
    NAME(USERID.CUST.KSDS) -
    INDEXED -
    RECORDSIZE(100 100) -
    KEYS(8 0) -
    FREESPACE(10 5) -
    CYLINDERS(10 5)) -
  DATA (NAME(USERID.CUST.KSDS.DATA)) -
  INDEX (NAME(USERID.CUST.KSDS.INDEX))
 
  * 20-byte key at offset 0 (e.g. composite or long code)
  DEFINE CLUSTER ( -
    NAME(USERID.ORDER.KSDS) -
    INDEXED -
    RECORDSIZE(500 500) -
    KEYS(20 0) -
    FREESPACE(15 10) -
    CYLINDERS(20 5)) -
  DATA (NAME(USERID.ORDER.KSDS.DATA)) -
  INDEX (NAME(USERID.ORDER.KSDS.INDEX))

In the first example the key is 8 bytes at the start of each 100-byte record. In the second the key is 20 bytes at the start of each 500-byte record. In both cases the key fits within the record and is within the 1–255 byte limit.

Key Length in the Program

Your application must define the key field with the same length as in KEYS. In COBOL, for KEYS(12 0), the key field should be 12 bytes (e.g. PIC X(12) or PIC 9(12)). If the key is numeric, you might use PIC 9(8) for an 8-byte numeric key (depending on how the key is stored). The important point is that the number of bytes the program uses for the key must match the key length in DEFINE CLUSTER. A mismatch can cause incorrect comparisons, failed reads, or corrupt data.

1
2
3
4
5
6
       *> For KEYS(12 0) - 12-byte key at offset 0
       01  CUST-REC.
           05  CUST-KEY    PIC X(12).   *> Must be 12 bytes
           05  CUST-NAME  PIC X(40).
           05  CUST-BAL   PIC S9(7)V99.
           05  FILLER     PIC X(56).

Key Takeaways

• Key length is the first value in KEYS(length offset). It must be between 1 and 255 bytes and is the same for every record.
• Key length cannot be changed after the cluster is defined. Offset + length must not exceed record length.
• Longer keys increase index size (more bytes per index entry). Shorter keys usually mean a smaller, more efficient index.
• The program must define the key field with the same length as in KEYS so that READ by key and REWRITE work correctly.

Explain Like I'm Five

The key is like the label on each drawer: it has to be the same length for every drawer (e.g. always 10 letters). The computer uses that label to find the right drawer and keep them in order. If you make the label too long, the index (the list that helps find drawers) gets bigger. If you make it too short, you might not have enough room to write every different name. So you pick a length that fits your names and doesn’t waste space.

Test Your Knowledge