BUFFERSPACE Parameter

BUFFERSPACE is a DEFINE CLUSTER (or DEFINE DATA) parameter that specifies the amount of space, in bytes, to reserve for I/O buffers when the VSAM cluster is opened. The value you give helps VSAM determine the size of the data component's and index component's control intervals (CIs). It is stored in the catalog and used at open time to allocate buffer space. BUFFERSPACE is not the same as the runtime parameters BUFND and BUFNI (number of data and index buffers), which you specify in JCL AMP or in the ACB; BUFFERSPACE is a define-time hint for minimum buffer space and for CI sizing. This page explains the BUFFERSPACE parameter: syntax, default behavior, where to specify it, and when it is ignored (e.g. for RLS and DFSMStvs).

Syntax and Abbreviations

In DEFINE CLUSTER (or in the DATA subparameters, or when defining/altering a catalog), you specify:

1
2
  BUFFERSPACE(size)
  /* Abbreviations: BUFSP(size) or BUFSPC(size) */

size is the amount of space in bytes. You can specify it in decimal (e.g. 16384), hexadecimal (e.g. X'4000'), or binary (e.g. B'...') form. The value should not be less than the space needed to hold two data component control intervals and, for a key-sequenced (KSDS) cluster, one index component control interval. If you specify a smaller value, VSAM still obtains at least that minimum when the dataset is opened. The actual number of buffers allocated at open time is limited by storage available in your region and by other dataset attributes. The following table summarizes the main aspects of BUFFERSPACE.

Default When Omitted

If you do not specify BUFFERSPACE at all, VSAM uses a default: enough space to contain two data component control intervals and, if the cluster is key-sequenced (KSDS), one index component control interval. So the default is derived from the CI sizes. For an ESDS or RRDS there is no index component, so the default is effectively space for two data CIs. For a KSDS, the default ensures that at open time there is at least room for two data CIs and one index CI in the buffer space. This minimum allows basic sequential and keyed access. For better performance, you can specify a larger BUFFERSPACE so that more buffers can be allocated (subject to region and system limits). If you specify BUFFERSPACE(0), some implementations of Access Method Services calculate a value based on the data and index CI sizes—effectively a calculated default.

Effect on Control Interval Size

The BUFFERSPACE value helps VSAM determine the size of the data and index component control intervals. So BUFFERSPACE is not only a buffer allocation hint; it can influence how large each CI is. When you define a cluster, VSAM may use the BUFFERSPACE you specify (along with RECORDSIZE, block size constraints, and other factors) to choose or validate the CI size. IBM recommends that when you alter a cluster, the BUFFERSPACE you give be equal to or greater than the amount specified in the original definition if you want to avoid reducing effective buffer space. If you reduce BUFFERSPACE below what was originally defined, VSAM may still obtain the minimum (two data CIs + one index CI for KSDS) at open, but the cataloged value is reduced.

Where BUFFERSPACE Can Be Specified

You can specify BUFFERSPACE only for:

• A catalog — When defining or altering a catalog entry, with the CATALOG parameter specified. This applies to the catalog's own buffer space.
• The data component of a cluster — In DEFINE CLUSTER, at the cluster level (which applies to the data component), or inside the DATA(...) subparameters. You cannot specify BUFFERSPACE for the index component alone; the value you give for the data component helps VSAM determine both data and index CI sizes.
• The data component of an alternate index — When defining an alternate index, BUFFERSPACE can be specified for its data component.

You cannot specify BUFFERSPACE for the index component in the INDEX(...) clause in the sense of a separate index-only value; the cluster-level or DATA-level BUFFERSPACE influences both data and index CI sizing.

When BUFFERSPACE Is Ignored

The BUFFERSPACE parameter is ignored when the dataset is opened for VSAM Record Level Sharing (RLS) or for DFSMStvs (transactional VSAM). In RLS mode, multiple address spaces share the same VSAM data; buffer and cache management are handled by the RLS server and the coupling facility, not by the local BUFFERSPACE from the catalog. In DFSMStvs mode, similar considerations apply. So for clusters that are always opened under RLS or DFSMStvs, coding BUFFERSPACE in DEFINE CLUSTER has no effect on runtime buffer allocation. It may still be stored in the catalog and can affect CI size at define time, but at open time the RLS/DFSMStvs path does not use it for buffer allocation.

BUFFERSPACE vs BUFND and BUFNI

Do not confuse BUFFERSPACE with BUFND and BUFNI. BUFFERSPACE is a define-time parameter: you set it in DEFINE CLUSTER (or ALTER) and it is stored in the catalog. It specifies a size in bytes (total buffer space) and helps VSAM determine CI sizes. BUFND and BUFNI are runtime parameters: you specify them when opening the file, typically in the JCL DD statement (AMP=(BUFND=...,BUFNI=...)) or in the program's ACB. BUFND is the number of data buffers (each holding one data CI); BUFNI is the number of index buffers (each holding one index CI). So BUFFERSPACE is "how much buffer space in bytes" at define time; BUFND and BUFNI are "how many buffers" at open time. For runtime tuning of buffer counts, use BUFND and BUFNI; for define-time minimum buffer space and CI sizing, use BUFFERSPACE.

Example: DEFINE CLUSTER with BUFFERSPACE

The following example defines a KSDS with an explicit BUFFERSPACE. The value 24576 bytes might be chosen to allow at least two 4KB data CIs (8192 bytes) and one index CI, plus headroom (or to influence CI size). Exact values depend on your CISZ and workload.

1
2
3
4
5
6
7
8
9
10
  DEFINE CLUSTER ( -
    NAME(MY.APPL.BUF.KSDS) -
    INDEXED -
    RECORDSIZE(100 200) -
    KEYS(12 0) -
    BUFFERSPACE(24576) -
    CISZ(4096) -
    CYLINDERS(10 5)) -
  DATA (NAME(MY.APPL.BUF.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.BUF.KSDS.INDEX))

Here BUFFERSPACE(24576) is stored in the catalog. When the cluster is opened (in non-RLS, non-DFSMStvs mode), VSAM uses this value as a minimum for buffer allocation and it has already been used at define time to help determine or validate the data and index CI sizes.

ALTER and BUFFERSPACE

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

1
  ALTER cluster-name BUFFERSPACE(size)

The new value is stored in the catalog and used the next time the cluster is opened. IBM recommends that when altering, the size be equal to or greater than the amount in the original definition. Increasing BUFFERSPACE can allow more buffers to be allocated at open (subject to region limits); decreasing it may result in VSAM still obtaining the minimum required space at open, but the cataloged hint is reduced.

Limitations

The actual number of buffers allocated when the dataset is opened is limited by: (1) the storage available in your region (address space), (2) other parameters and attributes of the dataset (e.g. CI size, BUFND/BUFNI if specified at open), and (3) system limits. So specifying a very large BUFFERSPACE does not guarantee that much memory will be allocated; the system allocates what it can up to the limit. For performance tuning of how many buffers are used at runtime, use the AMP parameter (BUFND, BUFNI) on the DD statement or the equivalent in the ACB.

Key Takeaways

• BUFFERSPACE(size) specifies the amount of buffer space in bytes at define time and helps VSAM determine data and index CI sizes.
• Default when omitted: space for two data CIs and one index CI (KSDS). For ESDS/RRDS, two data CIs.
• Specify only for the data component of a cluster (or alternate index) or for a catalog (with CATALOG). Minimum: two data CIs + one index CI for KSDS.
• BUFFERSPACE is ignored when the dataset is opened for RLS or DFSMStvs.
• For runtime buffer count tuning, use BUFND and BUFNI (e.g. in JCL AMP); BUFFERSPACE is a define-time size hint.

Explain Like I'm Five

BUFFERSPACE is like telling the computer when you create the file: "Leave at least this much room in memory for reading and writing my data." The computer uses that number to decide how big each "chunk" (control interval) of your file can be. When you open the file later, it tries to reserve that much space for buffers. If you open the file in a special shared way (RLS or DFSMStvs), the computer ignores this number and uses its own shared buffers instead.

Test Your Knowledge