VSAM KEYS Parameter

The KEYS parameter in DEFINE CLUSTER specifies the primary key for a Key-Sequenced Data Set (KSDS). It is written as KEYS(length offset): the first value is the key length in bytes (1 to 255), and the second is the byte offset from the start of each record where the key begins. KEYS is required only when defining an INDEXED cluster; for ESDS, RRDS, and LDS you do not specify KEYS. Once the cluster is created, key length and offset cannot be changed. This page explains the KEYS parameter syntax, when it is required, how it interacts with RECORDSIZE and INDEXED, valid values and constraints, and how to use it correctly in DEFINE CLUSTER and in your program's record layout.

Where KEYS Appears

KEYS is a parameter on the DEFINE CLUSTER command. It is specified in the cluster-level parameter list, usually together with RECORDSIZE, FREESPACE, and space allocation. Because KEYS defines the primary key, it applies only to clusters that have a key—that is, INDEXED (KSDS) clusters. For NONINDEXED (ESDS), NUMBERED (RRDS), and LINEAR (LDS) clusters, there is no primary key, so KEYS is neither required nor allowed in the usual syntax. If you omit KEYS when defining an INDEXED cluster, IDCAMS will reject the DEFINE or prompt for the key definition.

Syntax: KEYS(length offset)

The syntax is KEYS(length offset). Both values are unsigned integers. No spaces are required inside the parentheses, but KEYS(12 0) and KEYS(12 0) are both valid. The first value is the key length; the second is the key offset. Some documentation writes this as KEYS(length offset) or KEYS(length, offset); the comma may or may not be required depending on your IDCAMS version—check your documentation. The important point is that the first number is always the length in bytes and the second is always the zero-based offset.

Key Length (First Operand)

The key length must be between 1 and 255 bytes. Every record in the KSDS has a key of exactly this length at the same offset. VSAM uses the key length to know how many bytes to read from each record when comparing keys (for ordering and search) and when building or updating the index. The index component stores key values or key separators in the sequence set and index set; longer keys therefore use more space per index entry and can make the index larger. For most applications, key lengths in the range of 4 to 20 bytes are common (e.g. customer ID, order number, account number). You cannot change the key length after the cluster is defined.

Key Offset (Second Operand)

The key offset is the zero-based byte position of the first byte of the key within the logical record. Offset 0 means the key starts at the first byte of the record; offset 10 means the key starts at the 11th byte. The key must fit entirely within the record: offset + length must be less than or equal to the record length. For fixed-length records, that means offset + length ≤ the fixed record length. For variable-length records, the key is typically required to fit within the minimum record length so that VSAM can always find the key regardless of actual record size. If you specify an offset or length that would make the key extend past the end of the record, the DEFINE may fail or behavior may be undefined. The key offset cannot be changed after the cluster is defined.

When KEYS Is Required

KEYS is required only for INDEXED clusters (KSDS). The KSDS organization depends on a primary key: records are stored in ascending key order, and the index component maps key values to control intervals in the data component. Without KEYS, IDCAMS would not know which bytes in each record form the key, so it could not build or maintain the index. For all other organization types, KEYS is not used.

Relationship to RECORDSIZE

RECORDSIZE defines the minimum and maximum record length (or fixed length) for the cluster. The key defined by KEYS must fit within that record. For fixed-length records, RECORDSIZE(n n) means every record is n bytes; therefore offset + length must be ≤ n. For variable-length records, RECORDSIZE(min max) means records can be between min and max bytes; the key must fit within the minimum length (offset + length ≤ min) so that even the shortest record still contains the full key. If you specify KEYS(20 100) but the minimum record length is 80, the key would extend from byte 100 to 120, which is past the end of a 80-byte record—that is invalid. Always choose RECORDSIZE and KEYS so that the key lies entirely within the record.

Examples

Example 1: 10-byte key at the start of a 200-byte fixed-length record. The key is the first 10 bytes (offset 0). Offset + length = 0 + 10 = 10 ≤ 200, so the key fits.

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

Example 2: 12-byte key starting at byte 20. The first 20 bytes might be a fixed header (e.g. record type, timestamp); the key is bytes 20–31. For a 500-byte record, offset + length = 20 + 12 = 32 ≤ 500, so the key fits.

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

Example 3: Variable-length records with minimum length 100. The key must fit in 100 bytes. KEYS(16 0) means a 16-byte key at the start; 0 + 16 = 16 ≤ 100, so it is valid.

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

Matching the Program's Record Layout

Your application program must use a record layout that matches the KEYS definition. The key field in the program must start at the same byte offset and have the same length as specified in KEYS. For example, if you defined KEYS(12 0), the first 12 bytes of your COBOL 01-level record should be the key. If you defined KEYS(8 20), bytes 21–28 (0-based: 20–27) in the record must be the key in your layout. If the program puts the key in a different position or length, VSAM will compare or update the wrong bytes and the file will not behave correctly—ordering may be wrong, key-based reads may fail or return the wrong record, and inserts may corrupt the index.

Common Mistakes

• Specifying KEYS for a non-KSDS cluster (ESDS, RRDS, LDS). KEYS is only for INDEXED. Omit KEYS for other organization types.
• Using a key length or offset that makes the key extend past the record. Always ensure offset + length ≤ record length (or ≤ minimum record length for variable-length).
• Swapping length and offset. The first value is always length, the second is offset. KEYS(0 12) would mean length 0 and offset 12, which is invalid (length must be 1–255).
• Defining the key in the program at a different offset or length than in DEFINE CLUSTER. The program and the cluster definition must agree.
• Assuming KEYS can be changed with ALTER. It cannot. To change the key, define a new cluster with the new KEYS and migrate the data.

Key Takeaways

• KEYS(length offset) in DEFINE CLUSTER defines the primary key for a KSDS: length in bytes (1–255) and zero-based offset within the record.
• KEYS is required only for INDEXED (KSDS) clusters. Do not specify KEYS for ESDS, RRDS, or LDS.
• The key must fit in the record: offset + length ≤ record length (or minimum record length for variable-length). RECORDSIZE and KEYS must be consistent.
• Key length and offset are fixed at define time and cannot be changed with ALTER. To change the key, define a new cluster and copy the data.
• The program's record layout must have the key at the same offset and length as KEYS so that key-based access works correctly.

Explain Like I'm Five

Imagine a row of lockers, and each locker has a label (the key) in the same spot on every door. When you create the row, you tell the builder: "The label is 10 letters long and it starts right at the beginning of the door." That's KEYS(10 0). The builder then puts every label in that same place so that when someone says "find the locker labeled SMITH," they can look at that one spot on each door. If you said the label was 10 letters but actually wrote 12, or put it in a different place, the builder would look at the wrong part of the door. So KEYS tells the system exactly where and how long the "label" (key) is on every record.

Test Your Knowledge