FREESPACE Parameter

FREESPACE is a DEFINE CLUSTER parameter that reserves a percentage of each control interval (CI) and each control area (CA) for future inserts and record expansion. You code it as FREESPACE(ci-percent ca-percent), where both values are integers from 0 to 100. The first number is the percentage of each CI left free; the second is the percentage of each CA reserved as free CIs (for CI splits). FREESPACE applies only to KSDS and RRDS; for ESDS it is ignored, and for LDS there is no record or free-space structure. This page explains the FREESPACE parameter: where to specify it, default and valid values, how it interacts with DEFINE CLUSTER and ALTER, and how to choose values for your workload.

Syntax and Placement

In IDCAMS DEFINE CLUSTER, FREESPACE is specified as:

1
2
  FREESPACE(ci-percent ca-percent)
  /* or abbreviated: FSPC(ci-percent ca-percent) */

Both ci-percent and ca-percent are numeric values in the range 0–100. They represent percentages. You can specify FREESPACE at the cluster level (in the main parameter list of DEFINE CLUSTER) or inside the DATA(...) subparameters. For a KSDS, the cluster-level FREESPACE applies to the data component. The index component does not use FREESPACE; VSAM manages index structure internally. If you specify FREESPACE in both the cluster and the DATA clause, the DATA value typically takes precedence for the data component. The following table summarizes where FREESPACE can appear and what it affects.

Default Value When Omitted

If you do not specify FREESPACE at all, the default is (0 0). That means no free space is reserved: every control interval is filled with data up to its capacity, and there are no reserved free CIs in each control area. For a file that is loaded once and only read (or only appended, as with ESDS), (0 0) is appropriate and maximizes how much data fits in a given allocation. For a KSDS or RRDS that will receive inserts or updates after the initial load, (0 0) causes VSAM to perform a CI split whenever a new record must go into a CI that is already full, and a CA split when there is no free CI in the CA. Splits cost extra I/O and can degrade performance. So for any cluster that will have random inserts, you should explicitly specify FREESPACE with non-zero values.

Valid Values and Ranges

Both the CI and CA percentages must be in the range 0–100. A value of 0 means no free space at that level. There is no separate "default" keyword; you either omit FREESPACE (giving 0 0) or you supply two numbers. Very high values (e.g. 50 or 100) reserve a lot of space for growth but leave less room for actual data, which can hurt sequential read performance (more CIs to read for the same number of records) and waste DASD. Typical production values are in the range 10–30 for the CI percentage and 5–20 for the CA percentage. The following table gives guidance.

Effect on Data and Index Components

FREESPACE applies only to the data component of a cluster. In a KSDS, the data component holds the actual records in key order; the index component holds the key-to-RBA (or key-to-CI) mapping. The index is maintained by VSAM and has its own internal structure for growth (e.g. index set and sequence set nodes). You do not specify FREESPACE for the index. When you code FREESPACE(20 10) at the cluster level for a KSDS, that 20% and 10% apply to the data component only. The index component is allocated and managed separately; its space allocation is often derived from the cluster allocation or from defaults. So when we talk about FREESPACE, we are always talking about the data component's control intervals and control areas.

FREESPACE by Dataset Type

• KSDS (INDEXED) — FREESPACE is used. Inserts go in key order; free space in each CI and free CIs in each CA absorb new records and reduce CI and CA splits. This is the most common case for specifying FREESPACE.
• RRDS (NUMBERED) — FREESPACE can be used. Fixed-length (or variable) slots are used; additional free space can help when many inserts occur and slots or CIs fill up. Behavior may depend on implementation; see your documentation.
• ESDS (NONINDEXED) — FREESPACE is ignored. Records are appended at the end; there is no in-place insert, so reserving free space in the middle of CIs serves no purpose. You can code FREESPACE on an ESDS without error, but it has no effect.
• LDS (LINEAR) — There is no FREESPACE. LDS has no record structure and no control intervals in the same sense; it is a byte-addressable stream. FREESPACE does not apply.

Example: DEFINE CLUSTER with FREESPACE

The following example defines a KSDS with FREESPACE(25 15). The cluster name is MY.APPL.KEYS.KSDS; the data and index components get default or explicit names. RECORDSIZE, KEYS, and space allocation are also specified.

1
2
3
4
5
6
7
8
9
10
  DEFINE CLUSTER ( -
    NAME(MY.APPL.KEYS.KSDS) -
    INDEXED -
    RECORDSIZE(80 80) -
    KEYS(12 0) -
    FREESPACE(25 15) -
    CISZ(4096) -
    CYLINDERS(10 5)) -
  DATA (NAME(MY.APPL.KEYS.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.KEYS.KSDS.INDEX))

Here, 25% of each control interval in the data component is left free for new or expanded records, and 15% of each control area is reserved as free CIs. When you load the cluster (e.g. with REPRO or with an application program), VSAM fills only about 75% of each CI with data. As you insert records later, that free space is used first; when it is exhausted in a given CI, the next insert that belongs in that CI triggers a CI split. The 15% free CIs in each CA give room for those splits within the same CA, reducing the need for more expensive CA splits.

ALTER and Changing FREESPACE

You can change FREESPACE after the cluster exists by using the IDCAMS ALTER command. The syntax is:

1
  ALTER cluster-name FREESPACE(ci-percent ca-percent)

The important limitation: ALTER only affects new space that is allocated from that point on. Existing control intervals and control areas were already formatted with the previous FREESPACE (or 0 0). Their free space does not change. So if you defined with (0 0) and later ALTER to (20 10), only new CIs and CAs allocated (e.g. when the file extends into secondary space) will get 20% and 10% free space. To get uniform free space throughout the entire file, you must define a new cluster with the desired FREESPACE and REPRO (copy) the data from the old cluster to the new one, then retire or replace the old cluster.

Choosing CI and CA Percentages

The CI percentage controls how much of each control interval is left empty. Higher values mean more room for inserts in each CI, so fewer CI splits, but more CIs are needed to hold the same amount of data (more I/Os on sequential reads). The CA percentage controls how many CIs in each control area are left free for receiving records during CI splits. If the CA percentage is too low, CI splits will often find no free CI in the same CA and will force a CA split, which is more expensive. A common rule of thumb is to set the CA percentage to about half of the CI percentage (e.g. 20 10 or 25 15), but you can raise the CA percentage if you expect very heavy insert activity. For files that are loaded once and rarely updated, (0 0) or (10 5) may be enough. For transaction files that grow daily with random key order, (25 15) or (30 20) can reduce reorganizations and split overhead.

Step-by-Step: Adding FREESPACE to a New KSDS

1. Decide how much insert activity you expect after the initial load. If the file is read-only or append-only, use (0 0) or omit FREESPACE. If there will be random inserts, choose a CI percent (e.g. 20–25) and a CA percent (e.g. 10–15).
2. In your DEFINE CLUSTER command, add FREESPACE(ci-percent ca-percent) in the main parameter list (or inside DATA(...)).
3. Allocate space (CYLINDERS, TRACKS, or RECORDS) and other parameters (RECORDSIZE, KEYS, etc.) as usual. Run IDCAMS to create the cluster.
4. Load the cluster with REPRO or with your application. VSAM will leave the specified percentage of each CI and CA free.
5. Monitor the file over time. If you see high split activity or need to reorganize often, consider a higher FREESPACE when you next redefine (e.g. after REPRO to a new cluster).

Key Takeaways

• FREESPACE(ci-percent ca-percent) is a DEFINE CLUSTER parameter that reserves free space in each CI and each CA for the data component.
• Default when omitted is (0 0). For KSDS or RRDS with inserts, specify explicit values (e.g. 20 10 or 25 15) to reduce CI and CA splits.
• Valid values are 0–100 for both numbers. Typical production range is 10–30 (CI) and 5–20 (CA).
• FREESPACE applies only to the data component; it is ignored for ESDS and does not apply to LDS.
• ALTER can change FREESPACE for new allocations only; to refresh free space throughout, REPRO to a new cluster defined with the desired FREESPACE.

Explain Like I'm Five

FREESPACE is like telling the computer: "When you put my records in a box (control interval), don't fill the box all the way. Leave a little empty space (the CI percent). And when you have a bunch of boxes in a cabinet (control area), leave some boxes empty (the CA percent)." Later when you add new records, they go into that empty space first. If you never leave any space (0 0), every time you add something new the computer has to move a lot of stuff around (a split). So FREESPACE is the "leave room for later" instruction when you create the file.

Test Your Knowledge