Most VSAM introductions lead beginners straight to CYLINDERS(primary secondary) or TRACKS(primary secondary) because those units map cleanly to mainframe disk geometry and to the way capacity planners speak. BLOCKS(primary secondary) is the less flashy cousin: it requests the same logical idea—initial space plus per-extension growth—but counts physical blocks on the device rather than whole tracks or cylinders. That choice sounds abstract until you remember that every track is divided into blocks, and the block size for a given device type and recording format determines how many bytes each block holds. Once you know the bytes per block, BLOCKS becomes just another way to express megabytes of space with integers that might already appear on storage worksheets from vendors or from migration tools that originated on non-z platforms. This page explains what BLOCKS does in DEFINE CLUSTER, how it compares to the other space parameters, why teams still encounter it in production JCL, and what beginners should double-check so they do not confuse block counts with cylinder counts and accidentally define a cluster that is orders of magnitude smaller or larger than intended.
The pattern matches the other allocation keywords: a primary quantity and an optional secondary quantity separated by a space inside the parentheses. You code BLOCKS at the cluster level or inside DATA and INDEX subparameters the same way you would code CYLINDERS, depending on whether you want one umbrella allocation or split control for a KSDS data and index pair. IBM documents the exact grammar and any restrictions alongside CYLINDERS in the Access Method Services reference; releases occasionally refine edge cases for SMS-managed data or for certain device types. If your site standard says "always CYLINDERS," you might never author BLOCKS yourself, but you will still read it in inherited procedures, so recognition matters as much as authorship.
1234567891011DEFINE CLUSTER ( - NAME(USERID.BATCH.KSDS) - INDEXED - RECORDSIZE(100 100) - KEYS(5 0)) - DATA (NAME(USERID.BATCH.KSDS.DATA) - BLOCKS(5000 1000) - VOLUMES(SYSDA)) - INDEX (NAME(USERID.BATCH.KSDS.INDEX) - BLOCKS(50 10) - VOLUMES(SYSDA))
The numbers in the example are illustrative only. Before you run anything on a real LPAR, convert them to megabytes using your device block size, compare against volume free space, and walk through the same sizing exercise you would use for CYLINDERS.
| Keyword | Why beginners see it | How BLOCKS relates |
|---|---|---|
| CYLINDERS(p s) | Easy to reason about on 3390-class disks; common in examples. | Convertible to blocks via geometry if you need to compare. |
| TRACKS(p s) | Finer than cylinders; good for smaller clusters. | Tracks themselves contain multiple blocks. |
| RECORDS(p s) | Starts from expected row counts; system converts using record and CI assumptions. | Indirect relationship to physical blocks. |
| BLOCKS(p s) | Counts physical blocks; must know device block size to map to MB. | Use when policy or tooling standardizes on blocks. |
The fundamental invariant across all four forms is that VSAM ultimately receives a set of extents on volumes; the keyword only changes how you describe the size of each extent request to IDCAMS. BLOCKS adds the requirement that you think in device-block multiples, which is powerful when your accounting system already tracks block counts from a vendor audit, but weaker when you are sketching capacity on a whiteboard with coworkers who think in cylinders.
Suppose a teaching device uses 4 KB blocks for quick mental math. Primary BLOCKS(1024) then suggests four megabytes before secondary extensions, because 1024 times 4096 bytes is four megabytes. Change the device or recording format and the same 1024 blocks might represent a different byte count. That dependence is not a flaw; it is the definition of block-oriented allocation. When migrating clusters between device families, never copy BLOCKS literals blindly—recompute from byte targets. CYLINDERS has the same physical truth underneath, but cylinder vocabulary stays more stable in human conversation across 3390 generations.
Secondary allocation with BLOCKS behaves conceptually like secondary with CYLINDERS: when the allocated space is exhausted and the cluster must grow, the system requests another chunk whose size is governed by the secondary number, subject to extent limits, volume fragmentation, and SMS rules. A tiny secondary in blocks might generate many extensions; a huge secondary might overshoot free space on a nearly full pack. The same operational discipline you learned on the Secondary allocation tutorial page applies here—only the unit of the ruler changed.
When SMS constructs or constrains datasets, ACS routines may assign volumes or data classes that influence how space is satisfied even though your DEFINE names BLOCKS explicitly. Always read the LISTCAT output after define to confirm extents and high-level allocation match expectations. Beginners sometimes assume the keyword alone tells the whole story; modern z/OS coupling between IDCAMS, SMS, and the catalog means verification is part of the workflow, not an optional extra.
Imagine measuring a playground in fence panels instead of measuring it in whole yards. BLOCKS counts fence panels. CYLINDERS counts whole yardsticks laid end to end. You can describe the same playground both ways, but you must know how wide one fence panel is before fence counts mean anything to your friends.
1. BLOCKS(800 200) allocates space in what unit?
2. Which statement best describes BLOCKS vs CYLINDERS?
3. Does choosing BLOCKS remove the need for secondary allocation when the file grows?