VSAM free space tuning

Free space tuning is the art of leaving intentional emptiness where VSAM needs it: inside control intervals for growing records and between records as they pack during load, and as whole empty control intervals sprinkled through each control area so CI splits can borrow a new CI without allocating a brand-new CA. Get the first number wrong and CI splits spike even though plenty of tracks remain allocated at the cluster level. Get the second number wrong and CA splits punish insert bursts even when individual CIs still had a few bytes left. This page complements the conceptual FREESPACE article by focusing on tuning methodology: how to read LISTCAT split counters, how to pair percentages with CI and CA sizing, and how to schedule reorganizations when historical packing no longer matches future growth.

Read the two numbers separately

Beginners sometimes memorize FREESPACE(20 10) without knowing which digit is which. Internalize: CI percent equals intra-interval slack; CA percent equals spare empty intervals inside each CA. Write that on your cheat sheet next to the bookcase analogy from CA split training: spare shelves versus spare boxes.

Example combinations

Tuning loop

1. Capture baseline CI and CA split counts after a representative month.
2. Increase the relevant percentage in test, reload sample data, rerun the insert workload.
3. Compare split deltas and sequential scan elapsed time; reject changes that help splits but crush reporting.

When to reorganize instead of nudging percentages

If the file is already physically packed from years of updates, higher FREESPACE on DEFINE only helps the next build. A REPRO to a fresh cluster applies the new percentages across all CIs and CAs uniformly. Operations teams sometimes schedule quarterly reorganize windows for volatile files even when splits look tolerable, simply to restore predictable geometry before holiday peaks.

DEFINE fragment

The following JCL fragment is illustrative; your standards may wrap lines differently and include SMS clauses.

1
2
3
  DEFINE CLUSTER (NAME(ORDERS.KSDS) -
    KEYS(12 0) RECORDSIZE(200 800) -
    FREESPACE(25 12) CISZ(18432) ... )

Pitfalls

• Copying FREESPACE from a static file onto a volatile file without analysis.
• Ignoring CA percent on insert-heavy ascending keys.
• Expecting ALTER to instantly create slack inside every existing CI without reorganize.

Coordinating with capacity and finance

Slack space is real disk cost. Finance sees allocated tracks; performance engineers see avoided latency. Bring both views into the change record: show projected extra tracks from higher FREESPACE against projected CPU and elapsed savings from fewer splits using SMF estimates. Sometimes a compromise pair like (15 8) beats the theoretical ideal (30 15) because the business cannot fund idle tracks that quarter. When you cannot fund slack, you must fund more frequent reorganize windows instead—another line item, but an honest trade. Document who owns that trade so pager rotations do not argue philosophy at 3 a.m. during month-end.

Seasonal workloads

Retail and tax workloads swing between quiet and stormy seasons. A FREESPACE pair tuned for average weeks may fail during Black Friday inserts. Some shops maintain two cluster definitions or use automation to REPRO into a higher-slack clone before peak, then compact afterward. Even if you never automate that far, mark the calendar to watch LISTCAT splits during known peaks and adjust next year proactively instead of reactively.

Automation guardrails

When REXX or Python on z/OS automates LISTCAT parsing, validate that you read the correct cluster entry versus component entries and that you handle scientific notation in exported numbers carefully. A script that emails the wrong field can hide a genuine space crisis or cry wolf weekly. Version-control automation alongside DEFINE templates so every change to FREESPACE defaults is traceable. Good automation reinforces tuning discipline instead of replacing human judgment with brittle alerts nobody trusts after three false alarms.

Practical exercises

1. Graph monthly CI splits for one production file; correlate with business events.
2. Build a table comparing scan seconds for dense versus slackened clones in test.
3. Explain to a peer why CA percent matters even when total DASD free is huge.

Explain like I'm five

The first FREESPACE number leaves air inside each shoebox so new toys still fit when you add stickers. The second number leaves a few empty shoeboxes on each shelf so when one box splits in half, you already have an empty box on the same shelf instead of buying a whole new shelf in a hurry.

Test your knowledge