VSAM Secondary Allocation

Secondary allocation is the second number you specify in the VSAM space parameters CYLINDERS(primary secondary), TRACKS(primary secondary), or RECORDS(primary secondary). If you think of primary allocation as the size of the parking lot you pave on day one, secondary allocation is the size of each additional strip you add when the lot fills up. Every time the dataset needs more room and the already allocated space is exhausted, the access method and catalog cooperate to obtain another chunk of space equal to the secondary quantity, in the same units you chose at define time. That chunk becomes a new extent. The choice of secondary therefore controls how often your dataset extends, how many extents it accumulates over its life, and how large each growth step is. Getting secondary right is a core skill for anyone who defines production KSDS, ESDS, or RRDS clusters, because it sits directly between operational stability (not running out of space during the overnight batch window) and storage economics (not reserving half an empty volume after a single extension).

Where Secondary Appears in DEFINE CLUSTER

IDCAMS does not use a separate keyword named SECONDARY. Instead, the pair syntax encodes both values at once. For cylinders, you write CYLINDERS(20 5): twenty cylinders primary, five cylinders secondary per extension. The same pattern applies to TRACKS and RECORDS. You can specify space at the cluster level or, for a KSDS, independently on DATA and INDEX. It is common for the data component to carry almost all of the primary and secondary attention, while the index uses small values because index growth is usually modest compared to data growth. If you specify only a primary value and omit secondary, behavior depends on your environment defaults and whether extensions are allowed at all; in many practical definitions you always supply both numbers explicitly so that growth is predictable. When SMS manages the dataset, data and management classes can influence allocation, but the DEFINE you submit still expresses your intent in primary/secondary terms at the VSAM cluster definition layer.

What Happens at Runtime

After define, the cluster occupies the primary extent. As records are written or updated in ways that consume space (including CI splits that use reserved free space and then need new CIs), the high-used relative byte address moves toward the end of the allocated range. When a request needs space beyond the current allocation, VSAM does not silently fail if secondary was specified and limits allow: it drives an extent request for the secondary quantity. If that succeeds, the new space is formatted as additional VSAM control areas in line with your CI and CA sizing. If it fails, the application receives an error related to space rather than a generic I/O error, and you will need to investigate volume free space, extent counts, or SMS constraints. Operators and storage administrators often correlate those failures with LISTCAT ENTries showing many extents already present, which is a clue that secondary was too small relative to growth or that primary was under-sized from the beginning.

Extents and Why They Matter

Each primary allocation is typically one extent at define time, and each successful secondary request adds at least one more extent. Many systems enforce a maximum number of extents per dataset per volume. When you approach that limit, even a successful business day can end with an allocation failure because the dataset cannot grow further without reorganizing onto fewer, larger extents or adding volumes. Secondary that is too small relative to total growth causes the extent count to climb quickly: imagine primary of five cylinders and secondary of one cylinder while the file eventually needs two hundred cylinders. You would experience roughly one hundred ninety-five extension events after the primary is filled, which is a lot of catalog churn and fragmentation risk. Conversely, secondary that is fifty cylinders each time grows in large jumps; you might reach the final size in only a handful of extents, but you might also allocate tens of cylinders that sit empty for months. The tuning exercise is to match the granularity of growth to the real workload.

Sizing Secondary Alongside Primary

Primary should cover the initial population plus near-term headroom so that you are not extending during the first large load. Secondary should reflect how you expect the file to grow after that: monthly inserts, seasonal peaks, or rare one-off bulk adds. A useful mental model is to estimate the number of extensions you can tolerate over the life of the dataset on a single volume, then solve for secondary roughly as (expected final size minus primary) divided by that extension budget, respecting rounding to whole cylinders or tracks. In practice, teams also copy patterns from similar files that already have SMF history or RMF data showing growth slopes. Remember that FREESPACE reserves empty space inside CIs and CAs, which consumes allocated space without holding user records; a cluster with aggressive FREESPACE percentages fills allocated space faster in terms of high-used RBA versus logical record volume, which indirectly presses secondary sooner.

Example Definitions

The following example separates DATA and INDEX space. The data component uses forty cylinders primary and ten secondary, so each growth step adds a meaningful amount of space without being as large as the entire initial file. The index uses one cylinder primary and one secondary, reflecting rare index extent growth for many workloads.

1
2
3
4
5
6
7
8
9
10
11
12
  DEFINE CLUSTER ( -
    NAME(USERID.ORDERS.KSDS) -
    INDEXED -
    RECORDSIZE(250 250) -
    KEYS(10 0) -
    FREESPACE(15 10)) -
  DATA (NAME(USERID.ORDERS.KSDS.DATA) -
    CYLINDERS(40 10) -
    VOLUMES(SYSDA)) -
  INDEX (NAME(USERID.ORDERS.KSDS.INDEX) -
    CYLINDERS(1 1) -
    VOLUMES(SYSDA))

Relationship to CI and CA Splits

Secondary allocation is about macro-level disk space. CI and CA splits are about reorganizing records inside already allocated VSAM structures. When free space inside the cluster is exhausted at the CA level and splits cannot proceed without new space, growth still ultimately depends on having unused bytes in the allocation or obtaining more via extension. Poor FREESPACE choices can cause split activity to spike even when gross allocated space looks ample, because free bytes might not be in the right places. Good secondary sizing does not remove the need for sensible CI size, CA size, and FREESPACE; it ensures that when the dataset truly needs another slice of the volume, the slice is neither a sliver nor a monolith that does not fit.

Monitoring and Operations

After implementation, operators should know where to look when a job fails with space-related VSAM errors. LISTCAT on the cluster shows allocation history at a high level. Comparing extent counts over weeks tells you whether secondary is too small. If you routinely see single-digit free cylinders on the hosting volume after extensions, coordinate with storage administration for volume balance or a planned REPRO to a new cluster with revised primary/secondary. Documentation at the run book level should record the rationale for the chosen numbers so that future ALTER or redefine decisions do not guess blindly.

Explain Like I'm Five

Imagine you have one notebook that is completely full. Instead of buying one hundred new notebooks at once, you buy five more notebooks each time you run out. Those "five at a time" purchases are like secondary allocation. If you only bought one page at a time, you would spend all day at the store—that is secondary too small. If you bought a whole truck of notebooks each time, your desk would be buried—that is secondary too big.

Test Your Knowledge