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.
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.
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.
The server 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.
- 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.
- If you change the size of 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.
- If you change the size of 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.
- You cannot use raw logical volumes for storage pool volumes.
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
>>-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-'
- This value is valid only for volumes that are assigned to copy storage pools.
- This parameter is valid only for DISK or FILE volumes.
- 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.
Remember: Volume names cannot contain embedded blanks or equal signs.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 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. 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. 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. If a name contains embedded blanks, equal signs, or other special characters, enclose the list in quotation marks.
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.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./usr/storage/sbkup01.dsm
If you are using an AIX® logical volume, enter the path name as:
where xxx is the logical volume name./dev/rxxx
"c:\program files\tivoli\tsm\server\data3.dsm"
A regular file name with a fully qualified path name:/opt/tivoli/tsm/server/bin/sbkup01.dsm
A symbolic link to a character special file is entered in the format:
where /... is zero or more directories and fn is the file name. For example:/dev/.../rdsk/.../fn
/dev/rdsk/c1t3d0s6
A regular file name with a fully qualified path name:/storage/sbkup01.dsm
A character mode special file is entered in the format:
where vg is the volume group name and xxx is the logical volume name. For example:/dev/vg/rxxx
/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. 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).
/data/fpool01.dsm
"f:\data storage\fpool01.dsm"
/opt/tivoli/tsm/server/bin/fpool01.dsm
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 the server to generate volume names, consider using SCRATCH volumes.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
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 or active-data 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 or active-data 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. The volume name is /var/storage/bf.dsm. The volume name is j:\storage\bf.dsm. Let the volume be created as a background process.define volume backuppool
/var/storage/bf.dsm formatsize=100
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 that is named FILEPOOL is assigned to a device class with a device type of FILE. Define a volume that is named filepool_vol01 to this storage pool.Define a volume that is named fp_vol01.dsm to this storage pool.define volume filepool /usr/storage/filepool_vol01
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 10 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 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
Command | Description |
---|---|
DEFINE STGPOOL | Defines a storage pool as a named collection of server storage media. |
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. |