IBM Tivoli Storage Manager, Version 7.1

DEFINE VOLUME (Define a volume in a storage pool)

Use this command to assign a random or sequential access volume to a storage pool.

When you define a random-access (DISK) storage-pool volume or a sequential access storage pool volume that is associated with a FILE device class, you can have the server create the volume before it is assigned. Alternatively, you can use space triggers to create preassigned volumes when predetermined space-utilization thresholds are exceeded. For details about space triggers, see DEFINE SPACETRIGGER (Define the space trigger). For volumes associated with device classes other than DISK or device types other than FILE, you can use the DEFINE VOLUME command to assign an already-created volume to a storage pool.

Sun Solaris operating systems Remember: Raw partitions generally provide the best performance, however an IBM® Tivoli® Storage Manager server running on Solaris 10 does not support ZFS raw partitions.

AIX operating systems Linux operating systems When you use a FILE device class for storage that is managed by a z/OS® media server, it is not necessary to format or define volumes. If you define a volume for such a FILE device class by using the DEFINE VOLUME command, the z/OS media server does not allocate space for the volume until the volume is opened for its first use.

Attention: Volumes for the z/OS media server that are created using the DEFINE VOLUME command remain physically full or allocated after Tivoli Storage Manager empties the volume, for example, after expiration or reclamation. For FILE volumes, the DASD space is not relinquished to the system when the volume is emptied. If a storage pool requires an empty or filling volume, the FILE volume can be used. In contrast, tape volumes that are logically empty are the same as physically empty. FILE and tape volumes remain defined in Tivoli Storage Manager. In contrast, SCRATCH volumes, including the physical storage allocated for SCRATCH FILE volumes, are returned to the system when emptied.

To create space in sequential access storage pools, you can define volumes or allow the server to request scratch volumes as needed, as specified by the MAXSCRATCH parameter for the storage pool. For storage pools associated with the FILE device class, the server can create private volumes as needed using storage-pool space triggers. For DISK storage pools, the scratch mechanism is not available. However, you can create space by creating volumes and then defining them to the server. Alternatively, you can have the server create volumes that use storage-pool space triggers.

Tivoli Storage Manager does not validate the existence of a volume name when defining a volume in a storage pool that is associated with a library. The defined volume has "0" EST capacity until data is written to the volume.

Attention: The size of a storage pool volume cannot be changed after it is defined to the Tivoli Storage Manager server. AIX operating systems HP-UX operating systems Sun Solaris operating systems Windows operating systems
  • AIX operating systems If you change the size of Tivoli Storage Manager volumes by extending raw logical volumes through SMIT or otherwise altering the file sizes of the volumes with operating system commands or utilities, the server might not initialize correctly and data can be lost.
  • HP-UX operating systems If you change the size of Tivoli Storage Manager volumes by extending raw logical volumes or otherwise altering the file sizes of the volumes with operating system commands or utilities, the server might not initialize correctly and data can be lost.
  • Sun Solaris operating systems Windows operating systems If you change the size of Tivoli Storage Manager volumes by altering the file sizes of the volumes with operating system commands or utilities, the server might not initialize correctly and data can be lost.

You cannot use this command to define volumes in storage pools with the parameter setting RECLAMATIONTYPE=SNAPLOCK. Volumes in this type of storage pool are allocated by using the MAXSCRATCH parameter on the storage pool definition.

You cannot define volumes in a storage pool that is defined with the CENTERA device class.

Physical files that are allocated with DEFINE VOLUME command are not removed from a file space if you issue the DELETE VOLUME command.

Privilege class

To issue this command, you must have system privilege, unrestricted storage privilege, or restricted storage privilege for the storage pool to which the volume is assigned.

Syntax

Read syntax diagramSkip visual syntax diagram
>>-DEFine Volume--pool_name--volume_name------------------------>

   .-ACCess--=--READWrite-------.   
>--+----------------------------+------------------------------->
   '-ACCess--=--+-READWrite---+-'   
                +-READOnly----+     
                +-UNAVailable-+     
                |         (1) |     
                '-OFfsite-----'     

>--+------------------------------------------------+----------->
   |                           .-Wait--=--No------. |   
   '-Formatsize--=--megabytes--+------------------+-'   
                               '-Wait--=--+-No--+-'     
                                          '-Yes-'       

   .-Numberofvolumes--=--1----------.   
>--+--------------------------------+--------------------------->
   |                 (2)            |   
   '-Numberofvolumes------=--number-'   

>--+---------------------------+-------------------------------><
   |          (3)              |   
   '-LOcation------=--location-'   

Notes:
  1. This value is valid only for volumes that are assigned to copy storage pools.
  2. This parameter is valid only for DISK or FILE volumes.
  3. This parameter is valid only for sequential access volumes.

Parameters

pool_name (Required)
Specifies the name of the storage pool to which the volume is assigned.
volume_name (Required)
Specifies the name of the storage pool volume to be defined. If you specify a number greater than 1 for the NUMBEROFVOLUMES parameter, the volume name is used as a prefix to generate multiple volume names. The volume name that you specify depends on the type of device that the storage pool uses.

Each volume that is used by a server for any purpose must have a unique name. This requirement applies to all volumes, whether the volumes are used for storage pools, or used for operations such as database backup or export. The requirement also applies to volumes that reside in different libraries but that are used by the same server.

AIX operating systems HP-UX operating systems Linux operating systems Sun Solaris operating systems Remember: Volume names cannot contain embedded blanks or equal signs.
Windows operating systems Remember: Volume names cannot contain embedded blanks or equal signs, except for DISK or FILE volumes.
See the following tables for volume name requirements:
Table 1. Volume name requirements for DISK
Volume Name Requirements Example
AIX operating systems Linux operating systems Windows operating systems The name of the file to contain the volume data, with either the fully qualified path name or a path name relative to the current working directory. Sun Solaris operating systems A regular file name, or if you are using a raw partition (non-ZFS), a symbolic link to the character special file. A regular file name can be either a fully qualified path name or a path name relative to the current working directory. HP-UX operating systems A regular file name, or if you are using a raw logical volume, a character special file. A regular file name can be either a fully qualified path name or a path name relative to the current working directory.

Windows operating systems If a name contains embedded blanks, equal signs, or other special characters, enclose the list in quotation marks.

Sun Solaris operating systems Attention: The server cannot always detect if data exists on a raw partition. Existing data can be destroyed if you define a volume to that partition.
HP-UX operating systems Attention: The server cannot always detect if data exists on a raw logical volume. Existing data can be destroyed if you define a volume to that logical volume.
AIX operating systems Linux operating systems
/usr/storage/sbkup01.dsm
AIX operating systems If you are using an AIX® logical volume, enter the path name as:
/dev/rxxx
where xxx is the logical volume name.
Windows operating systems
"c:\program files\tivoli\tsm\server\data3.dsm"
Sun Solaris operating systems A regular file name with a fully qualified path name:
/opt/tivoli/tsm/server/bin/sbkup01.dsm
Sun Solaris operating systems A symbolic link to a character special file is entered in the format:
/dev/.../rdsk/.../fn
where /... is zero or more directories and fn is the file name. For example:
/dev/rdsk/c1t3d0s6
HP-UX operating systems A regular file name with a fully qualified path name:
/storage/sbkup01.dsm
HP-UX operating systems A character mode special file is entered in the format:
/dev/vg/rxxx
where vg is the volume group name and xxx is the logical volume name. For example:
/dev/groupa/rdsa
Table 2. Volume name requirements for FILE
Volume Name Requirements Example
The name of the file to contain the volume data, with either the fully qualified path name or the path name relative to a directory identified in the DIRECTORY parameter for the device class.

Windows operating systems If a name contains embedded blanks, equal signs, or other special characters, enclose the list in quotation marks.

Place FILE volumes in one of the directories that are specified with the DIRECTORY parameter of the DEFINE DEVCLASS command. Otherwise, storage agents might not have access to the volumes. For details, see DEFINE PATH (Define a path).

AIX operating systems HP-UX operating systems Linux operating systems
/data/fpool01.dsm
Windows operating systems
"f:\data storage\fpool01.dsm"
Sun Solaris operating systems
/opt/tivoli/tsm/server/bin/fpool01.dsm
AIX operating systems Linux operating systems
Table 3. z/OS media server: Volume name requirements for FILE
Volume Name Requirements Example

For FILE volumes used with the z/OS media server server, specify a data set name. The data set name can consist of one or more qualifiers that are delimited by a period. The qualifiers can contain up to 8 characters. The maximum length of the data set name is 44 characters. The first letter of each qualifier must be alphabetic or national (@#$), followed by alphabetic, national, hyphen, or numeric characters.

To allocate the associated VSAM Linear Dataset when the volume is tendered on the z/OS system, the High Level Qualifier (HLQ) is typically filtered by specific ACS routines within the SMS policy constraints on the system where the z/OS media server is running.

The behavior of the HLQ is similar to the behavior of the PREFIX name on a scratch request. The HLQ is typically used by DFSMS to affect allocation attributes, such as Extended Addressability for data sets that are expected to extend when space that is already allocated to the file volume is used up.

If the data set does not exist, the server creates it when the volume is used for a specific Tivoli Storage Manager storage operation. The data set is not created when the volume is defined. Data loss can result when defining volumes because the z/OS media server reuses the volume or VSAM LDS if it exists at the time of allocation time.
Important: To allow Tivoli Storage Manager to generate volume names, consider using SCRATCH volumes.
AIX operating systems Linux operating systems
SERVER1.BFS.POOL3.VOLA
Table 4. Volume name requirements for tape
Volume Name Requirements Example

Use 1 - 32 alphanumeric characters.

The volume name cannot contain any embedded blanks or equal signs.

DSMT01
AIX operating systems Linux operating systems
Table 5. z/OS media server: Volume name requirements for tape
Volume Name Requirements Example

For tape cartridges, specify a tape volume name with 1 - 6 alphanumeric characters. The server converts tape volume names to uppercase.

The volume name cannot contain any embedded blanks or equal signs.

Each volume that is used by a server for any purpose must have a unique name. This requirement applies to all volumes, whether the volumes are used for storage pools, or used for operations such as database backup or export. The requirement also applies to volumes that reside in different z/OS media libraries but that are used by the same server.

DSMT01
Table 6. Volume name requirements for REMOVABLEFILE
Volume Name Requirements Example
1–6 alphanumeric characters

The server converts volume names to uppercase.

DSM01
ACCess
Specifies how client nodes and server processes (such as migration) can access files in the storage pool volume. This parameter is optional. The default value is READWRITE. Possible values are:
READWrite
Specifies that client nodes and server processes can read from and write to files stored on the volume.
READOnly
Specifies that client nodes and server processes can only read files that are stored on the volume.
UNAVailable
Specifies that client nodes or server processes cannot access files that are stored on the volume.

If you define a random access volume as UNAVAILABLE, you cannot vary the volume online.

If you define a sequential access volume as UNAVAILABLE, the server does not attempt to access the volume.

OFfsite
Specifies that the volume is at an offsite location from which it cannot be mounted. You can specify this value only for volumes in copy storage pools.
Use this value to help you track volumes at offsite locations. The server treats volumes that are designated as offsite differently:
  • The server does not generate mount requests for volumes designated offsite.
  • The server reclaims or moves data from offsite volumes by retrieving files from other storage pools.
  • The server does not automatically delete empty, offsite scratch volumes from a copy storage pool.
LOcation
Specifies the location of the volume. This parameter is optional. It can be specified only for volumes in sequential access storage pools. The location information can be a maximum length of 255 characters. Enclose the location in quotation marks if it contains any blank characters.
Formatsize
Specifies the size of the random access volume or FILE volume that is created and formatted in one step. The value is specified in megabytes. The maximum size is 8 000 000 MB (8 terabytes). This parameter is required if any of the following conditions are true:
  • A single FILE or DISK volume is specified, which is to be created and formatted in one step.
  • The value for the NUMBEROFVOLUMES parameter is greater than 1, and DISK volumes are being created.
  • The value of the NUMBEROFVOLUMES parameter is greater than 1, and the value of the FORMATSIZE parameter is less than or equal to the MAXCAPACITY parameter of the DEFINE DEVCLASS command.

If you are allocating volumes on a z/OS media server, this parameter is not valid.

For a FILE volume, you must specify a value less than or equal to the value of the MAXCAPACITY parameter of the device class associated with the storage pool.

You cannot use this parameter for multiple, predefined volumes. Unless you specify WAIT=YES is specified, the operation is completed as a background process.

Numberofvolumes
Specifies the number of volumes that are created and formatted in one step. This parameter applies only to storage pools with DISK or FILE device classes. This parameter is optional. The default is 1. If you specify a value greater than 1, you must also specify a value for the FORMATSIZE parameter. Specify a number from 1 to 256.

If you are allocating volumes on a z/OS media server, the only value that this parameter supports is the default value of 1.

If the value for the NUMBEROFVOLUMES parameter is greater than 1, the volume name you specified will have a numeric suffix appended to create each name, for example, tivolivol001 and tivolivol002. Be sure to chose a volume name so that a valid file name for the target file system is created when the suffix is appended.

Important: You must ensure that storage agents can access newly created FILE volumes. For more information, see DEFINE PATH (Define a path).
Wait
Specifies whether volume creation and formatting operation is completed in the foreground or background. This parameter is optional. It is ignored unless you also specify the FORMATSIZE parameter.
No
Specifies that a volume creation and formatting operation is completed in the background. The NO value is the default when you also specify a format size.
Yes
Specifies that a volume creation and formatting operation is completed in the foreground.
Remember: You cannot specify WAIT=YES from the server console.

Example: Use a background process to define a new 100 MB volume for a disk storage pool

Create a volume of 100 MB in the disk storage pool named BACKUPPOOL. AIX operating systems HP-UX operating systems Linux operating systems Sun Solaris operating systems The volume name is /var/storage/bf.dsm. Windows operating systems The volume name is j:\storage\bf.dsm. Let the volume be created as a background process.

AIX operating systems HP-UX operating systems Linux operating systems Sun Solaris operating systems
define volume backuppool 
/var/storage/bf.dsm formatsize=100
Windows operating systems
define volume backuppool j:\storage\bf.dsm formatsize=100

Example: Define a volume to a disk storage pool with read and write access

A storage pool named POOL1 is assigned to a tape device class. Define a volume named TAPE01 to this storage pool, with READWRITE access.
define volume pool1 tape01 access=readwrite

Example: Define a volume to a file storage pool

A storage pool named FILEPOOL is assigned to a device class with a device type of FILE. AIX operating systems HP-UX operating systems Linux operating systems Sun Solaris operating systems Define a volume named filepool_vol01 to this storage pool.Windows operating systems Define a volume named fp_vol01.dsm to this storage pool. AIX operating systems HP-UX operating systems Linux operating systems Sun Solaris operating systems
define volume filepool /usr/storage/filepool_vol01
Windows operating systems
define volume filepool j:\storage\fp_vol01.dsm

Example: Example: Use a background process to define 10 volumes for a file storage pool with a device class 5 GB maximum capacity

Define ten volumes in a sequential storage pool that uses a FILE device class. The storage pool is named FILEPOOL. The value of the MAXCAPACITY parameter for the device class that is associated with this storage pool is 5 GB. Creation must occur in the background.
define volume filepool filevol numberofvolumes=10 formatsize=5000

The Tivoli Storage Manager server creates volume names filevol001 through filevol010.

Volumes are created in the directory or directories that are specified with the DIRECTORY parameter of the device class that is associated with storage pool filepool. If you specified multiple directories for the device class, individual volumes can be created in any of the directories in the list.

Related commands

Table 7. Commands related to DEFINE VOLUME
Command Description
DEFINE STGPOOL Defines a storage pool as a named collection of server storage media.
DELETE VOLUME Deletes a volume from a storage pool.
QUERY VOLUME Displays information about storage pool volumes.
UPDATE DEVCLASS Changes the attributes of a device class.
UPDATE LIBVOLUME Changes the status of a storage volume.
UPDATE VOLUME Updates the attributes of storage pool volumes.


Feedback