VSAM Key Definition

For a Key-Sequenced Data Set (KSDS), the primary key is the field that identifies each record and determines the order in which records are stored. You define the key when you create the cluster with DEFINE CLUSTER, using the KEYS(length offset) parameter. The key length is how many bytes the key is (1 to 255); the key offset is where in the record those bytes start (0 for the first byte, or a higher number if the key is not at the beginning). The key must be unique—no two records can have the same primary key—and it cannot be changed after the cluster is defined. Understanding key definition helps you design record layouts and write correct COBOL or other programs that read and write by key. This page explains KEYS(length offset), key length and offset, uniqueness, and how the key fits in the record and in the program.

KEYS(length offset)

In DEFINE CLUSTER for a KSDS you specify KEYS(length offset). Both values are in bytes. The first value (length) is how long the primary key is. It must be between 1 and 255. Every record in the file has a key of this length at the same position. The second value (offset) is the byte position of the first byte of the key relative to the start of the record. Offset 0 means the key is the first bytes of the record; offset 10 means the key starts at the 11th byte (byte 10 in 0-based terms). So KEYS(10 0) means a 10-byte key at the start of the record; KEYS(8 20) means an 8-byte key starting at byte 20. The key must fit entirely within the record: offset + length must be less than or equal to the record length (minimum record length for variable-length, or the fixed record length).

Key Length

The key length is fixed for the life of the cluster. VSAM uses it to compare keys (byte by byte, in collating sequence) and to maintain records in ascending key order. A longer key uses more space in the index (sequence set and index set entries store key values or separators), so very long keys can make the index larger. A shorter key is cheaper in the index but must still uniquely identify each record. Common key lengths are 4–20 bytes for IDs (e.g. customer number, account number). The maximum is 255 bytes. You cannot change the key length after the cluster is defined; if you need a different length you must define a new cluster with the new KEYS and migrate the data.

Key Offset

The key offset tells VSAM where in each record the key bytes are. Many designs put the key at offset 0—the first bytes of the record—so that the key is easy to define in the program (e.g. the first field in the COBOL 01). You can put the key elsewhere: for example if the first 20 bytes are a header and the key is the next 10 bytes, you would use KEYS(10 20). The offset must be such that the key fits in the record. For variable-length records the key must fit within the minimum record length (or the maximum, depending on how your system interprets it; safe to keep offset + length within the minimum record size). For fixed-length records, offset + length must be less than or equal to the record length.

Unique Keys

The primary key in a KSDS must be unique. No two records can have the same key value. When you insert a record, VSAM checks that the key does not already exist; if it does, the insert fails. When you update a record, you cannot change the key (changing the key would effectively be a delete plus insert; some interfaces may support that as a single operation, but the key value must remain unique). So when you design the key, choose a field that is guaranteed unique per record—customer ID, order number, account number, etc. Do not use a field that can repeat (e.g. last name) as the primary key unless you extend it (e.g. last name + first name + ID) to make it unique.

Key in the Program

In your application program the record layout must match the DEFINE CLUSTER: the key must be at the same offset and have the same length. In COBOL you define the 01-level record and ensure the key subfield is at the correct position. Example for KEYS(12 0):

1
2
3
4
5
       01  CUST-REC.
           05  CUST-KEY    PIC X(12).   *> Key: 12 bytes at offset 0
           05  CUST-NAME  PIC X(40).
           05  CUST-BAL   PIC S9(7)V99.
           05  FILLER     PIC X(56).

The total record length here is 120 bytes; the key is the first 12. When you do a random READ, you move the key value to CUST-KEY and issue READ; VSAM finds the record with that key and returns the full record. The key in the record (CUST-KEY) must match the KEYS(12 0) used when the cluster was defined.

Defining the Cluster with KEYS

Only KSDS uses KEYS. For ESDS, RRDS, and LDS you do not specify KEYS (ESDS has no key; RRDS uses RRN; LDS has no record structure). Example DEFINE CLUSTER for a KSDS with a 10-byte key at offset 0:

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

INDEXED makes it a KSDS. KEYS(10 0) defines a 10-byte key at the start of each record. RECORDSIZE(200 200) means fixed-length 200-byte records, so the key fits (10 < 200). The program must use a record layout with the key as the first 10 bytes.

Key Takeaways

• KEYS(length offset) in DEFINE CLUSTER sets the primary key for a KSDS: length in bytes (1–255) and offset from the start of the record.
• The key must fit within the record (offset + length ≤ record length). Key length and offset cannot be changed after the cluster is defined.
• The primary key must be unique. No two records can have the same key. Inserts with duplicate keys fail.
• The program's record layout must have the key at the same offset and length as KEYS so that READ by key and REWRITE work correctly.

Explain Like I'm Five

The key is like the name on a folder. Everyone's folder has a name in the same place (same offset) and the same length (e.g. 10 letters). No two folders can have the same name (unique). When you say "give me the folder for Smith," the computer looks at the names (keys) and finds the right folder. You have to tell the computer when you create the file: "the name is 10 letters and it's at the very start of each folder"—that's KEYS(10 0).

Test Your Knowledge