In VSAM, the high-used RBA (often written HI-U-RBA or high-used RBA) is the highest relative byte address that has been written to in a component. It is the "high-water mark" of data: the byte offset of the last used byte. Together with the high-allocated RBA (HI-A-RBA), which is the total allocated space in bytes, you can see how much of the dataset is in use and how much room is left for growth. LISTCAT reports these values so you can monitor space utilization and plan when to extend or reorganize. This page explains what high-used RBA and high-allocated RBA mean, where to find them, and how to use them to calculate usage and plan for space.
The high-used RBA is the relative byte address (offset from the start of the component) of the last byte that has ever been written. When VSAM writes a record or formats a control interval, it updates this value if the write goes beyond the previous high-water mark. So HI-U-RBA answers: "How far into the dataset have we written?" It is maintained per component (data and index). For the data component, it reflects the end of the last CI that has been used. For the index component of a KSDS, it reflects the end of the index. So high-used RBA is not the number of records; it is a byte offset. For example if HI-U-RBA is 1,000,000, it means that the last written byte is at offset 1,000,000 (the million-and-first byte).
The high-allocated RBA (HI-A-RBA) is the total number of bytes that have been allocated for the component. When you define a cluster with CYLINDERS(10 5), VSAM allocates primary space and may later allocate secondary extents. The sum of all that space, in bytes, is the high-allocated RBA. So HI-A-RBA is the "end of allocated space"—the byte offset just past the last allocated byte. It is always greater than or equal to HI-U-RBA. The difference (HI-A-RBA − HI-U-RBA) is the number of allocated bytes that have not yet been written to. That is the "free" space in the sense of "room to grow" before VSAM needs to allocate more extents (if secondary was specified).
| Term | Description |
|---|---|
| HI-U-RBA (High-Used RBA) | Highest byte offset that has been written in the component. The "end of data" high-water mark. |
| HI-A-RBA (High-Allocated RBA) | Total bytes allocated (all extents). The "end of allocated space." Equal to or greater than HI-U-RBA. |
A simple way to express how full the dataset is is the usage percentage:
Usage % = (HI-U-RBA / HI-A-RBA) × 100
So if HI-U-RBA is 500,000 and HI-A-RBA is 1,000,000, usage is 50%. Half the allocated space has been written to; half is still available. If usage is near 100%, the dataset is nearly full and may soon need secondary allocation (or you need to reorganize or increase allocation). If usage is low (e.g. 20%), you have a lot of allocated space that is not yet used—which might be intentional (room for growth) or might mean the initial allocation was too large.
Note: this usage figure does not account for free space inside control intervals. VSAM reserves FREESPACE(ci ca) inside each CI and in each CA. So the "used" portion (up to HI-U-RBA) includes both actual record data and that reserved free space. So the true "idle" space is more than (HI-A-RBA − HI-U-RBA) when you consider that some of the "used" area is reserved empty. For a rough view of how much room is left for allocation, (HI-A-RBA − HI-U-RBA) is still useful.
IDCAMS LISTCAT reports allocation information for the cluster and for each component. Run LISTCAT against the cluster name (or the component) and look for the allocation/statistics section. The exact field names may appear as HI-U-RBA and HI-A-RBA (or similar, depending on the LISTCAT option and format). LISTCAT ALLOCATION or LISTCAT HISTORY often show these values. You can also use reporting tools or scripts that parse LISTCAT output to monitor usage over time. For KSDS you get separate values for the data component and the index component; both data and index can have high-used and high-allocated RBAs.
Monitoring high-used RBA helps you plan capacity and avoid out-of-space conditions. When HI-U-RBA approaches HI-A-RBA, the dataset will need more space. If you specified secondary allocation (e.g. CYLINDERS(10 5)), VSAM will extend into the next extent when needed, up to the limit of secondary extents. If you did not specify enough secondary (or any), the job may fail when it tries to write past the allocated space. So tracking HI-U-RBA and HI-A-RBA (e.g. via LISTCAT in a regular job or via a monitoring product) lets you see when a dataset is filling up and when to reorganize or increase allocation. After a REPRO or LOAD, HI-U-RBA will reflect the new high-water mark; after a delete of records, HI-U-RBA typically does not decrease—VSAM does not "shrink" the high-water mark when you delete. So the only way to "reset" or lower effective usage after many deletes is usually to REPRO to a new cluster (reorganize).
For a KSDS, the cluster has two components: data and index. Each component has its own HI-U-RBA and HI-A-RBA. The data component holds the records; the index component holds the key index. So when you look at LISTCAT, you may see allocation information for both. The data component is usually much larger than the index. When we talk about "dataset full," we usually mean the data component; but the index also grows as keys are added, so both should be monitored if the dataset is heavily updated.
Imagine a shelf (the dataset). The high-allocated RBA is how long the shelf is. The high-used RBA is how far along the shelf you have put books. So "used" is where the last book ends. If the shelf is 100 cm and the last book ends at 50 cm, you have used 50% of the shelf. The computer remembers where the last book is (high-used) and how long the shelf is (high-allocated) so it knows when to add another shelf (secondary allocation) or when to tidy up (reorganize).
1. What does HI-U-RBA represent?
2. How do you estimate space usage percentage?
3. Where are HI-U-RBA and HI-A-RBA reported?