VSAM NUMBERED Parameter

NUMBERED is the DEFINE CLUSTER keyword that creates a Relative Record Data Set (RRDS). In an RRDS, records (or slots) are identified by relative record number (RRN)—1, 2, 3, and so on—rather than by a key or by byte offset. You read, write, rewrite, or delete by specifying the RRN. NUMBERED is one of four organization types (with INDEXED, NONINDEXED, LINEAR). You use it when you need direct access by position or slot number, when all records are the same length (fixed RRDS), or when you have variable-length records and use variable RRDS (VRRDS). This page explains what NUMBERED does, how RRDS differs from KSDS and ESDS, what you specify (and do not specify—no KEYS), and when to choose NUMBERED.

What NUMBERED Means

When you specify NUMBERED in DEFINE CLUSTER, you are creating an RRDS. The cluster is organized by relative record number. The first record (or slot) is RRN 1, the second is RRN 2, and so on. To read a record you set the RRN (e.g. in COBOL, the RELATIVE KEY) and issue a READ; VSAM goes to that slot or looks up that RRN in the index (for variable RRDS) and returns the record. You can write a record to a specific RRN, rewrite a record in place after reading it, and delete a record (freeing the slot if REUSE is specified). There is no primary key; you do not specify KEYS. The "address" of a record is its RRN, not a key value and not a byte offset (RBA).

NUMBERED vs INDEXED and NONINDEXED

INDEXED (KSDS) uses a primary key; you specify KEYS(length offset) and access by key. NONINDEXED (ESDS) has no key; records are in entry order and you access by RBA or sequential read. NUMBERED (RRDS) uses RRN; you access by slot number. So: use INDEXED when you look up by a key (e.g. customer ID). Use NONINDEXED when you append and read by position (RBA) or sequentially. Use NUMBERED when you address by slot number (RRN)—for example when the logical "index" is 1, 2, 3, … and each slot holds one record (or is empty). RRDS is often used when the application thinks of the file as an array or table of fixed or variable-length rows addressed by row number.

Characteristics of an RRDS

Fixed vs Variable RRDS

With NUMBERED you can define a fixed-length RRDS or a variable-length RRDS (VRRDS). In a fixed RRDS, RECORDSIZE(n n) has the same minimum and maximum; every record is n bytes. The data component is divided into fixed-size slots; each slot holds zero or one record. There is no index component. When you delete a record, the slot is empty; with REUSE you can later write a new record to that same RRN. In a variable RRDS, RECORDSIZE(min max) has min less than max; records can vary in length. VSAM uses an index component to map RRN to the actual record locations. So NUMBERED covers both: the presence of an index and the record size definition determine whether you have fixed or variable RRDS.

What You Specify with NUMBERED

You must specify RECORDSIZE. For fixed RRDS use the same value twice (e.g. RECORDSIZE(80 80)). For variable RRDS use a range (e.g. RECORDSIZE(50 200)). You do not specify KEYS. You specify space allocation (CYLINDERS, TRACKS, or RECORDS). For fixed RRDS you typically specify REUSE if you want deleted slots to be reusable. Optionally you specify VOLUMES, SHAREOPTIONS, and DATA (and for VRRDS, INDEX). FREESPACE can be used for variable RRDS to reserve space for growth.

Syntax and Example

Example: fixed-length RRDS with REUSE.

1
2
3
4
5
6
7
8
  DEFINE CLUSTER ( -
    NAME(USERID.TABLE.RRDS) -
    NUMBERED -
    RECORDSIZE(80 80) -
    REUSE -
    CYLINDERS(2 1) -
    VOLUMES(SYSDA)) -
  DATA (NAME(USERID.TABLE.RRDS.DATA))

NUMBERED makes this an RRDS. RECORDSIZE(80 80) means fixed-length 80-byte records (fixed RRDS). REUSE allows deleted slots to be reused. There is no KEYS and no INDEX clause. Records are addressed by RRN 1, 2, 3, …

When to Use NUMBERED

Use NUMBERED (RRDS) when: (1) You address records by position—slot 1, 2, 3, …—and do not need to look up by a key value. (2) You have fixed-length records and want simple slot-based access (fixed RRDS). (3) You need to delete and reuse slots (use REUSE). (4) Your logic is "record number N" (e.g. configuration row N, cache slot N). Use INDEXED when you need key-based lookup and key order. Use NONINDEXED when you need append-only and RBA or sequential access. RRDS is a good fit for table-like or array-like access by index number.

Key Takeaways

• NUMBERED creates a Relative Record Data Set (RRDS) with access by relative record number (RRN). Do not specify KEYS.
• Fixed RRDS: RECORDSIZE(n n), data component only, fixed slots. Variable RRDS: RECORDSIZE(min max), data + index.
• REUSE allows deleted slots to be reused; a WRITE to that RRN places a new record in the slot.
• Use NUMBERED when you need direct access by slot number (RRN); use INDEXED when you need access by key.
• Organization type is fixed at define time; you cannot change NUMBERED to INDEXED or NONINDEXED with ALTER.

Explain Like I'm Five

NUMBERED is like a row of mailboxes: each box has a number (1, 2, 3, …). You say "put this in box 5" or "give me what's in box 5." You don't look up by name (that would be INDEXED); you look up by the box number. If you empty box 5 (delete), with REUSE you can put something new in box 5 again. So NUMBERED is for "I know the number of the slot I want"; INDEXED is for "I know the key (name or ID) and want to find the record."

Test Your Knowledge