Filelist

You can use the filelist option with the following commands:

• archive
• backup group
• backup group
• delete archive
• delete backup
• expire
• incremental
• query archive
• query backup
• restore
• retrieve
• selective

The Tivoli® Storage Manager client opens the file you specify with this option and processes the list of files within according to the specific command. Except for the restore and retrieve commands, when you use the filelist option, Tivoli Storage Manager ignores all other file specifications on the command line.

The files (entries) listed in the filelist must adhere to the following rules:

• Each entry must be a fully-qualified or a relative path to a file or directory. Note that if you include a directory in a filelist entry, the directory is backed up, but the contents of the directory are not.
• Each path must be specified on a single line. A line can contain only one path.
• Paths must not contain control characters, such as 0x18 (CTRL-X), 0x19 (CTRL-Y) and 0x0A (newline).
• By default, paths must not contain wildcard characters. Do not include asterisk (*) or question marks (?) in a path. This restriction can be overridden if you enable the option named wildcardsareliteral. For more information about that option, see Wildcardsareliteral.
• The filelist can be an MBCS file or a Unicode file with all Unicode entries. For Mac OS X, the filelist can be encoded in the current operating system language or UTF-16.
• If it is set, the client option called quotessareliteral allows quotation marks in a file specification to be interpreted literally, as quotation marks and not as delimiters. For more information about that option, see Quotesareliteral. If quotesareliteral and wildcardsareliteral are not set, quotation mark and wildcard processing works as described in the following list:
  • If a path or file name contains a space, enclose the entire path in quotation marks (") or single quotation marks ('). For example "C:\My Documents\spreadsheet.xls" or 'C:\My documents\spreadsheet.xls'.

  • If a path contains one or more single quotation marks ('), enclose the entire entry in quotation marks ("). If a path contains one or more quotation marks, enclose the entire path in single quotation marks. File list processing does not support paths that include a mix of quotation marks and single quotation marks.

    The following examples illustrate the correct and incorrect use of quotation marks and single quotation marks in paths.

    This path example contains a single quotation mark, so the path must be enclosed in quotation marks:

    "/home/gatzby/mydir/gatzby's_report.out"

    This path example contains quotation marks, so it must be enclosed in single quotation marks:

    '/home/gatzby/mydir/"top10".out'

    This path example contains a space character, so it must be enclosed in either quotation marks or single quotation marks:

    "/home/gatzby/mydir/top 10.out"

    or

    '/home/gatzby/mydir/top 10.out'

    This path example is not supported for filelist processing because it contains unmatched delimiters (" and ’):

    /home/gatzby/mydir/andy's_"top 10" report.out

    These paths are not supported for filelist processing because they contain wildcard characters:

    /home/gatzby*
    /home/*/20??.txt

• Any Tivoli Storage Manager filelist entry that does not comply with these rules is ignored.

The following are examples of valid paths in a filelist:

   /home/dir/file1
   /usr/tivoli/file2
   /usr/avi/dir1
   /fs1/dir2/file3
   "/fs2/Ha Ha Ha/file.txt"
   "/fs3/file.txt"

   c:\myfiles\directory\file1
   c:\tivoli\mydir\yourfile.doc
   ..\notes\avi\dir1
   ..\fs1\dir2\file3
   "d:\fs2\Ha Ha Ha\file.txt"
   "d:\fs3\file.txt"

To override standard processing of quotation marks and wildcard characters, see Quotesareliteral and Wildcardsareliteral.

You can use the filelist option during an open file support operation. In this case, Tivoli Storage Manager processes the entries in the filelist from the virtual volume instead of the real volume.

If an entry in the filelist indicates a directory, only that directory is processed and not the files within the directory.

If the file name (the filelistspec) you specify with the filelist option does not exist, the command fails. Tivoli Storage Manager skips any entries in the filelist that are not valid files or directories. Tivoli Storage Manager logs errors and processing continues to the next entry.

Use file specifications with the restore and retrieve commands to denote the destination for the restored filelist entries. For example, in the following restore command, the file specification /user/record/ represents the restore destination for all entries in the filelist.

restore -filelist=/home/dir/file3 /usr/record/

However, in the following selective command, the file specification /usr/record/ is ignored.

selective -filelist=/home/dir/file3 /usr/record/

Use file specifications with the restore and retrieve commands to denote the destination for the restored filelist entries. For example, in the following restore command, d:\dir\ represents the restore destination for all entries in the filelist.

restore -filelist=c:\filelist.txt d:\dir\

However, in the following selective command, the file specification d:\dir\ is ignored.

selective -filelist=c:\filelist.txt d:\dir\

If you specify a directory in a filelist for the delete archive or delete backup command, the directory is not deleted. filelists that you use with the delete archive or delete backup command should not include directories.

The entries in the list are processed in the order they appear in the filelist. For optimal processing performance, pre-sort the filelist by file space name and path.

For example, your filelist includes the entries /home/dir/file1 and /home/dir. If the /dir directory does not exist on the server, the /home/dir directory is sent to the server a second time.

For example, your filelist includes the entries c:\dir0\myfile and c:\dir0. If the \dir0 directory does not exist on the server, the c:\dir0 directory is sent to the server a second time.

Supported Clients

This option is valid for all clients. The Tivoli Storage Manager client API does not support this option.

Parameters

filelistspec

Specifies the location and name of the file that contains the list of files to process with the command.

Note: When you specify the filelist option on the command line, the subdir option is ignored.