VOLUMES Parameter

VOLUMES is a DEFINE CLUSTER parameter that specifies the DASD volume serial(s) (volser) where the VSAM cluster will be allocated. When you define a cluster, the system must know on which physical volume(s) to allocate the data and index components. You code VOLUMES(volser) or VOLUMES(volser1 volser2 ...) to list one or more volumes. For SMS-managed datasets, you often omit VOLUMES and let the Storage Management Subsystem choose the volume(s) from the storage class. For non-SMS VSAM, specifying at least one volume is typical. The catalog stores the volume and extent information so that when a job allocates the cluster by name (DSN=), the system finds the volumes from the catalog and does not require a VOLUME parameter in JCL. This page explains the VOLUMES parameter: syntax, when to specify it, SMS vs non-SMS behavior, and how to add or remove volumes with ALTER.

Syntax and Meaning

In DEFINE CLUSTER (or in DATA(...) or INDEX(...) for component-level placement in some implementations), you specify:

1
2
  VOLUMES(volser [ volser ... ])
  /* Abbreviation: VOL(volser ...) */

Each volser is a 1- to 6-character volume serial that uniquely identifies a DASD volume to the system. You can specify one volume or a list of volumes. The system allocates primary space (and when the cluster extends, secondary space) on these volumes. The order of volsers can matter for where the initial allocation goes and where extensions are taken; see your installation's conventions. The following table summarizes the main aspects of VOLUMES.

Why Specify VOLUMES?

For non-SMS (traditional) VSAM, the system needs to know which DASD volume(s) to use. Without a volume, allocation can fail or use installation-defined defaults. By specifying VOLUMES(SYSVOL) or VOLUMES(VOL1 VOL2), you control where the cluster lives. That can be important for performance (e.g. placing a file on a fast volume), for capacity planning (spreading large files across volumes), or for compliance (e.g. certain data on certain volumes). For SMS-managed datasets, the storage class and other SMS policies determine volume selection; you typically do not code VOLUMES so that SMS can choose from its pool of managed volumes. Some sites allow specifying volumes even with SMS for overrides; check your SMS and security rules.

SMS vs Non-SMS

If your cluster is managed by the Storage Management Subsystem (SMS), the data class and storage class (and optionally management class) drive where the dataset is placed. In that case you usually omit VOLUMES. SMS selects volume(s) from the storage pool that match the storage class. If you do specify VOLUMES for an SMS-managed cluster, behavior depends on your SMS configuration: some installations allow it to request specific volsers (subject to SMS policy), others may ignore it or use it only as a hint. For non-SMS VSAM, VOLUMES is the way you tell the system which volume(s) to use; without it, the job may rely on default volume or UNIT specifications, which can vary by site.

Catalog and Allocation by Name

Once the cluster is defined, the catalog stores the volume serial(s) and extent information for the data and index components. When a job runs with DSN=cluster-name (and no VOLUME on the DD), the system looks up the cluster in the catalog and gets the volume and extent information from there. So the application JCL does not need to specify the volume; the catalog supplies it. That is one of the benefits of cataloged VSAM: you allocate by name, and the system finds the dataset. Only when the cluster is in a user catalog that is not in the job's catalog search order do you need JOBCAT or STEPCAT to point to that catalog; you still do not code VOLUME in the DD for the dataset itself.

When to Use VOLUMES

Example: DEFINE CLUSTER with VOLUMES

The following example defines a KSDS on a specific volume. The cluster and its data and index components will be allocated on SYSVOL.

1
2
3
4
5
6
7
8
9
  DEFINE CLUSTER ( -
    NAME(MY.APPL.VSAM.KSDS) -
    INDEXED -
    RECORDSIZE(80 80) -
    KEYS(10 0) -
    VOLUMES(SYSVOL) -
    CYLINDERS(20 5)) -
  DATA (NAME(MY.APPL.VSAM.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.VSAM.KSDS.INDEX))

If you have two volumes and want to allow the cluster to use both (e.g. for primary on one and extension on another), you might code VOLUMES(VOL1 VOL2). The exact behavior of multi-volume allocation (which volume gets primary, which gets secondary) can depend on the access method and the installation; see your documentation.

ADDVOLUMES and REMOVEVOLUMES (ALTER)

After a cluster is defined, you can add volumes with IDCAMS ALTER so that the cluster can extend onto more DASD when it runs out of space on the current volumes. The syntax is:

1
  ALTER cluster-name ADDVOLUMES(volser [ volser ... ])

The new volumes become candidate volumes for allocation. The system does not allocate space on them until the cluster actually extends (e.g. when secondary space is needed). The cluster should be closed when you run ALTER ADDVOLUMES on many systems; otherwise the change may be deferred or rejected. REMOVEVOLUMES(volser ...) removes volumes from the cluster. Those volumes must not contain any allocated extents for this cluster (or the data must have been moved). Use REMOVEVOLUMES with care to avoid losing access to data.

IMPORT and VOLUMES

When you restore a VSAM cluster with IDCAMS IMPORT (from an EXPORT backup), you can specify VOLUMES(volser ...) to place the restored cluster on specific volumes. That is useful when restoring to a different system or when you want the restored file on a particular volume for performance or policy reasons. If you omit VOLUMES on IMPORT, the system (or SMS) chooses the volume(s) for the restored cluster.

Key Takeaways

• VOLUMES(volser ...) specifies the DASD volume serial(s) where the VSAM cluster is allocated at define time.
• For non-SMS VSAM, specify at least one volume. For SMS-managed clusters, VOLUMES is usually omitted so SMS can choose the volume(s).
• The catalog stores volume and extent information so jobs can allocate by DSN without coding VOLUME in JCL.
• Use ALTER ADDVOLUMES to add candidate volumes for extension; use REMOVEVOLUMES to remove volumes (ensure no data is on them).
• Volser is 1–6 characters and uniquely identifies a DASD volume to the system.

Explain Like I'm Five

VOLUMES is like writing the address on a box (the cluster). You are telling the computer: "Put my file on this disk (or these disks)." The computer remembers that address in the catalog. Later when someone asks for the file by name, the computer looks in the catalog and finds which disk it is on. If you don't give an address (omit VOLUMES) and the file is "SMS-managed," the computer's storage manager picks a disk for you. If it's not SMS-managed, the computer might not know where to put the file unless you give at least one volume.

Test Your Knowledge