VSAM Free Space

Free space in VSAM is the unused portion of each control interval (and each control area) that is reserved for future inserts and for record expansion. When you define a KSDS or RRDS, you specify FREESPACE(ci-percent ca-percent). The first number reserves that percentage of each CI for new or expanded records; the second reserves that percentage of each CA as free CIs so that when a CI fills and must split, there is room within the same CA. Without enough free space, inserts and updates trigger frequent CI and CA splits, which cost extra I/O and can hurt performance. This page explains what free space is, how FREESPACE works, which dataset types use it, and how to choose and tune it.

What Is Free Space?

Free space is the area inside each control interval that VSAM does not fill with logical records when the file is loaded or when records are first written. In a KSDS, when you load records in key order, VSAM places them in CIs but leaves a portion of each CI empty—the free space. Later, when you insert a new record, VSAM puts it in the correct CI in key order, using that free space. If the free space is sufficient, the insert does not require a CI split. Similarly, the CA percentage in FREESPACE reserves some CIs in each control area that are left empty (or largely empty). When a CI split is needed, VSAM moves some records from the full CI to another CI in the same CA—but only if there is a free CI available. The CA free space provides that free CI. So free space is the "room to grow" that reduces how often splits happen.

Free space is specified only at define time (or via ALTER for new allocations). Once a CI or CA is formatted, the amount of free space in it is fixed. So if you load a file with FREESPACE(20 10), every CI is 20% empty and every CA has 10% of its CIs available for splits. As you insert and update, that free space is consumed. When it is gone, the next insert that would go in that CI forces a CI split (or a CA split if there are no free CIs left in the CA). You cannot add more free space to already-formatted CIs and CAs without reorganizing (e.g. REPRO to a new cluster with the same or higher FREESPACE).

FREESPACE(ci-percent ca-percent)

In DEFINE CLUSTER you specify FREESPACE(ci-percent ca-percent). Both values are percentages (0–100). A value of 0 means no free space is reserved. Typical values are in the range 10–30 for the CI percentage and 5–20 for the CA percentage, depending on how much the file will grow after initial load.

• CI percentage — The proportion of each control interval that is left free. For example FREESPACE(20 10) leaves 20% of each CI empty. So in a 4096-byte CI, 20% is about 819 bytes. That space is used when you insert new records or when an existing record is updated and gets longer (if variable-length). Once that 20% is used up in a given CI, the next insert that belongs in that CI causes a CI split.
• CA percentage — The proportion of each control area that is reserved as free CIs (or equivalent). So 10% of each CA means roughly 10% of the CIs in that CA are left available for receiving records during CI splits. When a CI splits, VSAM moves about half the records from the full CI to a free CI in the same CA. If there is no free CI, VSAM must do a CA split instead (allocate a new CA and move half the CIs), which is much more expensive.

So the two numbers work together: the CI percentage gives room inside each CI for inserts; the CA percentage gives room (free CIs) in each CA for CI splits. Both help avoid the more expensive CA splits.

Which Dataset Types Use Free Space?

For ESDS you do not specify FREESPACE in the same way because records are only added at the end. For LDS there are no records, so there is no free space. When defining a KSDS or RRDS, always consider FREESPACE based on expected insert and update activity after the initial load.

Choosing FREESPACE Values

If the file is loaded once and rarely updated, you can use FREESPACE(0 0) to use all space for data. If the file will receive many inserts over time (e.g. a transaction file that grows daily), use higher values so that CI and CA splits are delayed. Too low and you get many splits and possible performance degradation; too high and you waste space and may hurt sequential read performance (more CIs to scan for the same amount of data). A common starting point is FREESPACE(20 10) or FREESPACE(25 15). For files that are mostly read and rarely updated, 10 5 or even 0 0 may be enough. For heavily updated files, 25 20 or higher can reduce reorganizations. After the file has been in use for a while, LISTCAT and tools that report "high-used RBA" vs "high-allocated RBA" can show how much space is still free; if free space is nearly exhausted, plan a REPRO to a new cluster with fresh free space.

Free Space and Splits

When you insert a record into a KSDS, VSAM finds the CI that should contain it (by key order). If that CI has free space, the record is placed there and no split occurs. If the CI is full (free space used up), VSAM performs a CI split: it takes some records from that CI and moves them to a free CI in the same CA, then inserts the new record in the correct CI. If there is no free CI in the CA, VSAM performs a CA split: it allocates a new CA, moves about half the CIs from the full CA to the new one, and updates the index. CI splits cost several I/Os; CA splits cost many more. Adequate FREESPACE keeps most inserts from causing splits and keeps CA splits rare.

Defining with FREESPACE

Example DEFINE CLUSTER with free space:

1
2
3
4
5
6
7
8
9
10
11
  DEFINE CLUSTER ( -
    NAME(USERID.TRANS.KSDS) -
    INDEXED -
    RECORDSIZE(100 200) -
    KEYS(15 0) -
    FREESPACE(25 15) -
    CISZ(4096) -
    CYLINDERS(20 5)) -
  DATA (NAME(USERID.TRANS.KSDS.DATA)) -
  INDEX (NAME(USERID.TRANS.KSDS.INDEX))
 

Here FREESPACE(25 15) reserves 25% of each CI and 15% of each CA. As the file is loaded and later updated, that space is used for inserts and expansions. When the file eventually runs low on free space, you can run a job that REPROs the cluster to a new cluster (with the same or new FREESPACE) to regain free space across the file.

Altering FREESPACE

You can use IDCAMS ALTER to change FREESPACE. The change applies to new control areas that are allocated after the ALTER (e.g. when the file extends into secondary space). Existing CIs and CAs keep their original free space. So ALTER does not "refill" free space in already-used areas. To get uniform free space throughout, define a new cluster with the desired FREESPACE and REPRO the data from the old cluster to the new one, then swap or replace the old with the new.

Key Takeaways

• Free space is the unused portion of each CI (and reserved free CIs in each CA) reserved for inserts and to reduce splits.
• FREESPACE(ci-percent ca-percent) is specified at DEFINE CLUSTER. CI percent = free space inside each CI; CA percent = free CIs in each CA for CI splits.
• KSDS and RRDS use free space; ESDS and LDS do not (in the same way).
• Too little free space leads to frequent CI and CA splits; too much wastes space. Typical range is 10–30% CI and 5–20% CA.
• ALTER can change FREESPACE for new allocations only; to refresh free space throughout, REPRO to a new cluster.

Explain Like I'm Five

Free space is like leaving empty slots in a drawer (CI) and empty drawers in a cabinet (CA). When you add new cards (records), you put them in the empty slots. When a drawer gets full, you move some cards to an empty drawer in the same cabinet (CI split). If there are no empty drawers in the cabinet, you have to bring in a whole new cabinet (CA split), which is a lot more work. Leaving enough empty slots and empty drawers from the start means you do not have to do the big job as often.

Test Your Knowledge