The RECORDS parameter in DEFINE CLUSTER specifies space allocation in terms of estimated record count instead of tracks or cylinders. You give RECORDS(primary secondary): primary is the number of records the initial allocation must hold, and secondary is the number of records each extension must hold. The system converts these counts to tracks or cylinders using the cluster’s RECORDSIZE, control interval size (CISZ), and device geometry. So you think in “how many records” and VSAM figures out how much DASD to allocate. This page explains RECORDS(primary secondary), how the conversion works, when to use RECORDS instead of CYLINDERS or TRACKS, and practical considerations such as variable-length records and extension limits.
RECORDS(primary [secondary]) tells the system to allocate the minimum space required to hold “primary” logical records (and “secondary” records per extension). VSAM uses the cluster’s record size (RECORDSIZE), key length for KSDS, and control interval size to determine how many records fit in each CI, then how many CIs fit on a track or cylinder. It then allocates enough tracks or cylinders to hold at least that many records. So RECORDS is a convenience: you specify record count and the system does the physical calculation. If you omit secondary, behavior is implementation-dependent (e.g. no extension or a default). You must specify RECORDSIZE (or equivalent) for the cluster when using RECORDS so the conversion can be done.
You specify RECORDS(primary [secondary]) at the cluster level or in the DATA and INDEX subparameters, just like CYLINDERS or TRACKS. At the cluster level, the value applies to the whole cluster. For a KSDS you can specify RECORDS in DATA and INDEX separately—for example RECORDS(100000 20000) for the data component and RECORDS(1000 500) for the index, so the index gets space for 1,000 index entries initially. The maximum record count is often 16,777,215; check your IDCAMS documentation.
To convert record count to space, VSAM needs: (1) Record size — from RECORDSIZE(min max) or RECORDSIZE(length) for fixed-length. (2) Control interval size — from CISZ or the default (e.g. 4 KB or 8 KB). (3) Key length and offset for KSDS — so it can compute index space. From this it computes: records per CI (depending on record length and CI size), CIs per track (from device geometry), and tracks (or cylinders) needed for the given number of records. The result is the minimum allocation that can hold that many records. So RECORDS(10000) with 80-byte fixed records and 4 KB CIs might allocate a few tracks; with 4 KB records it would allocate more. Variable-length records use the maximum record length (or an average) for the calculation; the actual space may vary.
RECORDS specifies “space for N records”; CYLINDERS and TRACKS specify physical units. The following table summarizes.
| Parameter | What you specify | When to use |
|---|---|---|
| RECORDS | Number of logical records | When you know or estimate record count; system converts to tracks/cylinders. |
| CYLINDERS | Physical cylinders | When you want to specify space in cylinders (e.g. large datasets). |
| TRACKS | Physical tracks | When you want to specify space in tracks (e.g. small datasets). |
RECORDS is useful when you have an estimate of record count (e.g. from a load program or file layout) and want the system to choose the right amount of space. CYLINDERS or TRACKS is useful when you prefer to think in physical units or when the record count is unknown or variable.
Primary should be at least the number of records you plan to load initially (or a reasonable estimate). If you underestimate, the dataset will extend often (using secondary), and you may hit extension limits (e.g. 123 secondary allocations on some systems) or get many small extents. Secondary should be large enough to reduce the number of extensions; a common approach is to set it to a fraction of primary (e.g. 20% of primary) or to your expected growth per run.
123456789DEFINE CLUSTER ( - NAME(MY.FILE.KSDS) - INDEXED - RECORDSIZE(100 200) - KEYS(10 0) - RECORDS(50000 10000)) - DATA (NAME(MY.FILE.KSDS.DATA)) - INDEX (NAME(MY.FILE.KSDS.INDEX))
This allocates space for 50,000 records initially and 10,000 records per extension. The system uses RECORDSIZE(100 200) and the default (or specified) control interval size to compute how many tracks or cylinders are needed. RECORDSIZE must be specified so the conversion can be performed.
12345678DEFINE CLUSTER ( - NAME(MY.APPL.KSDS) - INDEXED - RECORDSIZE(80 80) - KEYS(8 0)) - DATA (NAME(MY.APPL.KSDS.DATA) RECORDS(200000 40000)) - INDEX (NAME(MY.APPL.KSDS.INDEX) RECORDS(5000 1000))
The data component gets space for 200,000 records primary and 40,000 per extension. The index component gets space for 5,000 index records primary and 1,000 per extension. The system converts each to tracks/cylinders based on record and CI sizes.
For variable-length records (RECORDSIZE(min max) with min < max), the conversion typically uses the maximum record length or an average to estimate space. So the actual number of records that fit may be higher if records are shorter. For spanned records (records that cross CIs), the calculation is more complex; the system still produces an allocation that can hold approximately the requested number of records. If in doubt, allocate a bit more (e.g. higher primary or secondary) or use CYLINDERS/TRACKS for fine control.
Imagine you are building shelves for boxes. RECORDS is like saying "I have 10,000 boxes; build enough shelves to hold 10,000 boxes." You don’t say how many rows or sections (tracks or cylinders)—the builder (VSAM) figures that out from the size of each box (RECORDSIZE) and the size of each shelf (control interval). CYLINDERS is like saying "give me 10 sections of shelves" and TRACKS is like "give me 50 rows." RECORDS is handy when you know how many boxes you have.
1. What does RECORDS(50000 10000) mean?
2. What does VSAM use to convert RECORDS to space?
3. When is RECORDS allocation useful?