VSAM Primary Allocation

Primary allocation is the amount of space that is allocated when you first create a VSAM cluster with DEFINE CLUSTER. It is the first value in the space parameter: CYLINDERS(primary secondary), TRACKS(primary secondary), or RECORDS(primary secondary). That initial space is used for the data component (and for a KSDS, the index component) from the moment the cluster exists. When the dataset grows and uses up that space, the system allocates more space in chunks called extensions, using the secondary value. Choosing the right primary affects how many extents you get, whether you hit extent limits, and how efficiently the cluster uses DASD. This page explains what primary allocation is, how it differs from secondary, where you specify it, and how to size it.

What Primary Allocation Is

When IDCAMS processes a DEFINE CLUSTER with a space parameter such as CYLINDERS(20 10), it allocates space on the volume(s) you specified (or that SMS chooses). The first number—20—is the primary allocation. So at define time you get 20 cylinders (or the equivalent in tracks or record count, depending on which parameter you use). That space is formatted into control areas (CAs) and control intervals (CIs) and is ready to receive data. No data exists yet, but the extent is reserved. When you load the cluster (e.g. with REPRO or with a program that writes records), the data fills that primary space first. When the primary space is full and the program or REPRO tries to write more, VSAM requests an extension of secondary size (here 10 cylinders). So primary is "how much you get at creation"; secondary is "how much you get each time you need more."

Primary vs Secondary

It is important to understand the difference. Primary is a one-time allocation at define time. Secondary is used repeatedly: each time the dataset needs more space, one extension of secondary size is allocated (subject to extent limits and volume space). So if you specify CYLINDERS(10 5), you start with 10 cylinders. When those are full, you get 5 more (first extension). When those are full, you get 5 more (second extension), and so on. The total space used is primary plus (number of extensions × secondary). If you set primary too small, you will have many extensions and thus many extents. On many systems there is a limit on the number of extents per volume (e.g. 16); hitting that limit can cause allocation failures. So sizing primary (and secondary) is about balancing initial need, growth, and extent count.

Where You Specify Primary

Primary (and secondary) are specified in the same space parameter you use in DEFINE CLUSTER. You can specify at the cluster level or in the DATA and INDEX subparameters. For example: CYLINDERS(30 15) at the cluster level means the whole cluster gets 30 cylinders primary and 15 secondary (the system may split this between data and index for a KSDS). Or you can specify DATA(NAME(...) CYLINDERS(100 50)) and INDEX(NAME(...) CYLINDERS(2 1)) so the data component gets 100 cylinders primary and 50 secondary, and the index gets 2 primary and 1 secondary. The first number in each case is the primary allocation for that level.

Units: CYLINDERS, TRACKS, RECORDS

The primary value is in the same units as the parameter. CYLINDERS(primary secondary) means primary and secondary are in cylinders. TRACKS(primary secondary) means they are in tracks. RECORDS(primary secondary) means they are in estimated record count—the system converts to tracks or cylinders using RECORDSIZE and control interval size. So "primary allocation" is always the first value in whichever space parameter you use. A larger primary in cylinders gives more initial space than a larger primary in tracks (one cylinder is many tracks). Choose the unit that matches how you think about size: cylinders for large datasets, tracks for smaller, records when you know the record count.

How to Size Primary

Size primary so that the cluster has enough space for the initial load and for near-term growth. If you are loading 100,000 records of 200 bytes each, estimate the space (accounting for control interval and control area overhead, and FREESPACE). Convert to cylinders or tracks and use that as primary (with some margin). If primary is too small, the dataset will extend during the first load or soon after; you will get multiple extents quickly. If primary is too large, you waste DASD until the data grows into it. For a KSDS, remember that the index component needs much less space than the data component; if you specify at the cluster level, the system divides space between them, but specifying DATA and INDEX separately gives you control. Many sites use a rule of thumb such as "primary = expected initial size + 20%" or size based on historical growth.

Example

Data component for a KSDS: initial load about 50 cylinders, growth about 10 cylinders per month. Use primary 60 (enough for initial load plus a few months) and secondary 15 (so each extension is meaningful but not huge). Index is small; primary 2 and secondary 1 is often enough.

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

Here the data component has primary 60 cylinders and secondary 15. The index has primary 2 and secondary 1. At define time, 60 cylinders are allocated for data and 2 for the index. When the data component fills 60 cylinders, it will extend by 15 cylinders at a time.

Extent Limits and Primary

On many systems, a single volume can hold only a limited number of extents per dataset (e.g. 16). The first extent is the primary allocation. Each extension adds one more extent (up to the limit). So if primary is 10 cylinders and secondary is 2, and you need 50 cylinders total, you will have 1 (primary) + 20 (extensions) = 21 extents—which may exceed the limit. A larger primary (e.g. 40) and secondary (e.g. 5) would give 1 + 2 = 3 extents for the same 50 cylinders. So increasing primary (and secondary) reduces the number of extents and helps avoid hitting the extent limit.

Key Takeaways

• Primary allocation is the first value in CYLINDERS(primary secondary), TRACKS(primary secondary), or RECORDS(primary secondary). It is the space allocated at DEFINE CLUSTER time.
• Secondary is the amount added per extension when the dataset runs out of space. Primary is one-time; secondary is used repeatedly.
• Size primary to cover initial load and near-term growth. Too small a primary leads to many extensions and extents; too large wastes space.
• You can specify primary (and secondary) at cluster level or in DATA and INDEX separately. For KSDS, separate DATA and INDEX allocation is common.
• Extent limits (e.g. 16 per volume) make it important to use a primary (and secondary) large enough to limit the number of extents.

Explain Like I'm Five

Primary is like the first box you get when you start a collection. You ask for "20 boxes to start"—that's primary. When you fill those 20 boxes, you ask for "5 more boxes"—that's secondary, and you can ask for 5 more again and again. So primary is how much you get right away; secondary is how much you get each time you need more. If you ask for too few boxes at the start (primary too small), you have to keep asking for more (many extensions). If you ask for way too many at the start (primary too big), you have empty boxes for a long time (wasted space).

Test Your Knowledge