dsmmigrate

The dsmmigrate command selects specific files from the local file system and migrates them to a Tivoli® Storage Manager server.

Tip: On large file systems, selective migration can take a long time. Migration can be quicker if you premigrate files before you migrate them. The quickest way to create free space requires two steps:
  1. Prepare for migration by premigrating files.
  2. When you need to create free space quickly, use the stubmigrated option to migrate only premigrated files.

If the file exists in a file system with a different server stanza than the last processed file, a new session starts for each migrated file. This action can happen as a result of links from one file system to another.

Note:
  1. You are prompted either to wait for the medium to mount or to skip the file when the following two conditions are met:
    • The tapeprompt option is set to YES in the dsm.opt file.
    • The destination for the migrated file is a storage pool that consists of removable media (such as tape)
  2. The Tivoli Storage Manager for Space Management client does not migrate contents of symbolic links. Symbolic links are not followed during recursive selective migration.

The first file migrates even if the file size exceeds the quota that you specified for the file system. When migration occurs, the ddf command displays zero migrated and premigrated bytes for the file system. If the total number of bytes exceeds the quota after the file migrates, the next file is not migrated.

Syntax

Read syntax diagramSkip visual syntax diagram
                            .------------------------------.   
                            V                              |   
>>-DSMMIGRATE--+---------+----+-filespec-----------------+-+---><
               '-options-'    '- -FIlelist--=--file_path-'     

Parameters

options
–Detail
Displays the size and file name for each file that you migrate.
–ERRORLOGName=file_path
Specifies the path and file name of the error log file to be used by this command. Output from only this command is logged to the specified file. Other commands and daemons write output to the error log file specified by the errorlogname option in options file dsm.sys or dsm.opt, or as specified by the DSM_LOG environment variable. If any part of the path you specify does not exist, the Tivoli Storage Manager for Space Management client creates it.
–Help
Displays syntax and options for the command. Do not specify other options when you specify the help option.
–Logname=file_path
Specifies the path and file name of the log file to be used by this command. The kinds of events that are logged to the file are specified with the hsmlogeventflags option. Error events are not logged to the file.
–Premigrate
A copy of the file is sent to Tivoli Storage Manager storage, and the file remains on the local file system. The file state changes to premigrated. You cannot use the premigrate option and the stubpremigrated option at the same time.
–PREViewsize=n
Specifies the preview size of the stub file. Valid values are 0 - 1,073,741,824, and must not be greater than the stub size.

When the attributes are set and the preview size is defined, a recall operation begins only when an application reads the stub file beyond the preview section of the stub file. If an operation reads only the preview section of the stub file, the file is not recalled.

–REAdstartsrecall=No|Yes
Specifies whether a recall operation starts when an application reads the stub file.

This option applies only if streaming recall mode is set.

If the previewsize option is set for the stub file, a recall operation starts only when an application reads beyond the preview section of the stub file.

The default value is No.

Regardless of the value of the readstartsrecall option, the file is recalled when either of the following conditions are true:
  • The recall daemon determines that the stub file does not contain all of the data that is required by a read operation.
  • An operation modifies the file.
–Recursive
Migrates files in any subdirectory of the specified directory that matches the file specification. If you do not use this option, only those files from the directories that you specify are migrated.

The Tivoli Storage Manager for Space Management client does not migrate contents of symbolic links. Symbolic links are not followed during recursive selective migration.

–SErver=server_name

Specify the target server for the task. This option is valid only in a multiple-server environment. If the file system is managed by multiple servers and you do not specify server, the task is attempted with the default migration server.

If a file is coupled with a Tivoli Storage Manager server, you must specify that server. If a file is not coupled with a Tivoli Storage Manager server, you can specify any Tivoli Storage Manager server that was added to the multiple-server environment.

–STUBSize=n
Specifies the size of stub files that remain on the file systems when files are migrated to storage.

For Tivoli Storage Manager for Space Management clients on AIX® GPFS™ and Linux x86_64 GPFS file systems, you can specify 0 or a multiple of the file system block size. The default value is 0.

For Tivoli Storage Manager for Space Management clients on AIX Enhanced Journaled Files Systems (JFS2), you can specify a multiple of the file system fragment size. The default value is the file system fragment size.

For all file system types, the maximum value for a stub file size is 1 GB.

–STUBPremigrated
Only files that are in premigrated state are migrated. The migration process yields free space on the file system quickly. File copies exist in Tivoli Storage Manager storage. The migration process only replaces the local files with stub files.
filespec
The path and file name of the files that you want to migrate. This parameter is required. You can use wildcard characters to specify a group of files or all files in a directory. You can enter more than one file specification in one command. If you enter more than one file specification, separate each specification with one or more blank spaces.
–FIlelist=file_path
Specifies the path of a file that contains a list of files to be processed by this command.
The entries in the list file must adhere to the following rules:
  • Each entry is a fully qualified path to a file or a relative path to a file.
  • No entry is a directory object.
  • Each entry is on a separate line.
The Tivoli Storage Manager for Space Management client ignores any entry that does not adhere to these rules.
The following rules apply to a file list for the Tivoli Storage Manager for Space Management client. These rules differ from the rules for backup-archive client file lists.
  • An entry can contain unprintable characters, but cannot contain a carriage return.
  • Wildcard characters are allowed.
  • A file path that contains blank spaces must be enclosed in quotation marks.
  • An entry that begins with a quotation mark and ends with a quotation mark is tolerated. The Tivoli Storage Manager for Space Management client assumes that the quotation marks are not needed and omits them when the Tivoli Storage Manager for Space Management client processes the entry. If beginning and ending quotation marks are required to identify the file, add double quotation marks before the beginning and after the end of the entry.
The following example shows a list of files within a list file:
  /home/dir/file1
  "/fs1/dir2/file3"
  "/fs2/my files/file4"
  ../tivoli/'file1'
  "'fs3'/dir3/'file.txt'"
  fs4/dir/a"file".txt
  '/fs4/dir/file.txt'
  /fs5/dir/file*with?wildcards.txt

If the list file name that you specify with the filelist option does not exist, the command fails.

Examples

Task Command
Migrate all files in a directory that is named /migfs2/test/dir1 and in all of its subdirectories. Display the information. dsmmigrate -Recursive -Detail /migfs2/test/dir1
Migrate a file that is named tf04 from the current directory and display the information. Log the results in the file /tmp/miglog. dsmmigrate -Detail -L=/tmp/miglog tf04
Migrate all files in a file list that is named /tmp/filelist. Log the results in the file /tmp/miglog. Set the stub size to 4096 bytes and the preview size to 2048 bytes.
Restriction: When a file is recalled, the preview size affects recall processing only if streaming recall mode is set and readstartsrecall=yes. You can set streaming recall mode with the minstreamfilesize option on the dsmmigfs command or with the recallmode option on the dsmattr command.
 dsmmigrate -logname=/tmp/miglog -filelist=/tmp/filelist -stubsize=4096 -previewsize=2048 -readstartsrecall=yes
Use a shell application to build a list of files that are owned by user ibm, and then migrate the files. find /hsmfilesystem -user ibm -print > /tmp/filelist dsmmigrate -filelist=/tmp/filelist
Premigrate the file /migfs2/test/file1, but do not replace the local file with a stub. dsmmigrate -p /migfs2/test/file1
Migrate all premigrated files in directory /migfs2/test/dir1/ and in all of the subdirectories dsmmigrate -R -ST /migfs2/test/dir1