Optional parameters of the Java hbackup command

This topic describes the optional parameters of the Java™ hbackup command.

-X
Specifies that subdirectories should be examined for files in need of backup. However, if a subdirectory is the mount point for a different file system, then that subdirectory should not be entered. (Equivalent to RECURSE(NOCROSSMOUNTS) on the BACKDS Storage Administrator command.) Default processing is not to examine subdirectories. This option cannot be specified along with the -R option.
-R
Specifies that subdirectories should be examined for files in need of backup. All subdirectories are entered until no more are found. (Equivalent to RECURSE(CROSSMOUNTS) on the BACKDS Storage Administrator command.) Default processing is not to examine subdirectories. This option cannot be specified along with the -X option.
-C STD|PREF|REQ
Specifies what form of zFS File Snapshot processing to use for the z/OS® UNIX files. Options are:
STD
Do not use zFS File Snapshot to process the UNIX files. Serialization is held on the z/OS UNIX file during the backup.
PREF
Use the zFS File Snapshot processing if possible. When the zFS File Snapshot is initiated, serialization on the file is released, and other processes can write to the file without changing the contents that are being backed up. When the backup is complete, the zFS File Snapshot resources are released.
REQ
zFS File Snapshot processing must be used. If the feature is unavailable, the backup is failed.
-e
Specifies exclude criteria <exclude_list> for file names and directories to be excluded from backup processing. Comma separated exclude criteria patterns can be any of the following:
  • Patterns to match files in the exclude list can contain any valid file name characters and might contain the wildcard characters: question mark (?) and asterisk (*). Directory names cannot be specified in a file name pattern.
  • An asterisk (*) can be used to match any number of characters within a file name. An asterisk may be used at any position in the pattern.
  • A question mark (?) can be used to represent any single character in the file name. Multiple question mark characters are allowed.
  • A backslash character (\) must be used to escape any question mark, asterisk, open curly brace, open square bracket, and backslash characters to indicate it is not a special character. (for example \?, \*, \{, \[, or \\). Other CCSIDs might have a different character for hex value x’5C’ (CCSID 037 backslash) that need to be specified. For example, CCSID 1141 x’5C’ would be the umlaut O (Ö).
  • If the requested file name pattern does not include any wildcard characters, then that exact name is used to compare with files that are found in the subdirectories processed.
  • Directory names that are specified in the exclude list must end in a forward slash character. If the directory name begins with a forward slash character, then it is considered as an absolute path. If the directory name does not begin with a forward slash character, it is considered as a relative path that begins at the directory that is requested on the command. Wildcard characters cannot be used in directory names.
  • The comma (,) character cannot be used in file name patterns or directory names.
  • The syntax /.../ can be used to indicate any number of directories matched. (Equivalent to /**/ in glob format.)
  • A combination of directory names and file name pattern.
  • Trailing white space in a criteria is trimmed off.
-E
Specifies a file name, exclude_filename, that contains the exclude criteria to be used during processing. The exclude criteria must be specified one per line. A line starting with a blank character is considered a comment and is ignored. Valid criteria must conform to the types of patterns described in -e description. The user must have read permission to the file.
-f
Force a new backup. Send all supported, matching files to DFSMShsm for backup.
-h
Write out this explanation of options.
-I

UNIX files that are in use at the time of backup will have their backup retried up to a specified maximum number of times, delaying a specified number of minutes in between each retry. On retry, an attempt to obtain exclusive serialization to the UNIX file will be made. If on retry exclusive serialization is obtained then a normal backup of the UNIX file will be made. If exclusive serialization cannot be obtained, then additional retries of the backup will be made until the maximum number of retries has been made. If after the maximum number of retries exclusive serialization cannot be obtained, the backup request will either fail or a backup of the file will be taken anyway, depending on if the command specified serialization was required or preferred.

The -I option has suboptions retry, delay, and serialization that enable the user to specify the maximum number of retries, the time to delay in between retries, and whether exclusive serialization is required or preferred. The -I option and its associated suboptions has the following syntax.

-I retry=nn,delay=min,serialization=PREF|REQ
retry
Specifies the maximum number of retries. DFSMShsm will retry a maximum of nn times to back up a UNIX file after the first attempt fails because of the UNIX file is in use. For nn, specify a value 0 to 99. The default value is 0.
delay
Specifies the number of minutes to delay in between retries. DFSMShsm delays for min minutes before retrying a backup attempt which failed because the UNIX file is in use. For min, specify a value from 0 to 999. The default value is 15.
serialization
Specifies whether exclusive serialization of the UNIX file is required or preferred to make the backup. The default is serialization is required. The following are the possible values for the serialization suboption:
PREF
Serialization is preferred. If the UNIX file is still in use after the max number of retries for the backup have been made, the UNIX file will be backed up anyway. A message indicating a fuzzy backup was made will be issued. If the UNIX file is not in use at that time, a normal backup will be made. If retry=0 is in effect and exclusive serialization could not be obtained on the first attempt then a fuzzy backup will be made.
REQ
Serialization is required. If the UNIX file is still in use after the max number of retries for the backup have been made, the backup request will fail.

The -I suboptions can be specified in any order and any omitted suboption will have their default values used. However, at least one suboption must be specified.

Start of changeAll supported UNIX file types can be backed up with the -I option, however only Regular Files will be checked to be in use. Symbolic links, FIFOs, and directories will not be checked to be in use and will not have their backup retried. End of change

zFS File Snapshot is not supported for in use UNIX files. If serialization=PREF and -C PREF or -C REQ are specified on the command and the UNIX file is in use at the time of backup, the backup request will still fail.

-o
Storage Administrator mode. Any files that are sent to DFSMShsm for backup are processed as if they are sent by using a BACKDS Storage Administrator command. If using this option, you should also switch to UID(0) by using the su UNIX command first so that all files are accessible to the program.
-p
Specifies the maximum number of outstanding requests that are sent to the DFSMShsm host at any one time. Default value is 100.
-r
Specifies the number of days to keep this backup past when it would normally be expired or rolled off. (RETAINDAYS) Default: None
-t
Specifies the target of the backup. It can be either DASD, tape, or not specified in where DFSMShsm chooses the backup target. Default: None
-test
Requests only the matched file names are displayed, but not sent to the DFSMShsm host for backup.
Start of change
-i
Specifies the host ID of the DFSMShsm host that the backup request will be directed to. Host ID must be 1 character A-Z, 0-9, @, #, or $.

The host ID must correlate to a DFSMShsm host that is active on the system from which the java hbackup command was issued. If the DFSMShsm host on the system with the specified host ID is inactive or does not exist, message ARC0055A will be issued to the operator console and processing will not continue until the message is responded to. If a filemode host is active on the system, then the backup request will be directed to the filemode host that has the specified host ID. Using this option will not direct backup requests to DFSMShsm hosts on other systems within the PLEX.

This option, on its own, does not provide functionality to divide and distribute UNIX file backups to multiple DFSMShsm hosts on a system. The user must decide how to divide and distribute UNIX file backups and which specific DFSMShsm hosts to direct those backup requests to.

End of change
-version
Display the current version of the hbackup program.
-v{val}
Issue verbose messages during processing. An optional value might be specified for a level of verbosity. For example, -vDTL . If -v is specified without a value, it defaults to -vSTAT.
val might be:
  • STAT - Display statistics.
  • DTL - Display detailed information about file selection.
  • TIMES - Display timestamps on messages.
  • ALL - Display all message types.
Note: The hbackup program examines the following types of files:
  • Regular files.
  • Empty directories.
  • Symbolic links.
  • FIFO files
UNIX hard links are always sent to DFSMShsm because only the DFSMShsm host knows whether the backup version in the DFSMShsm inventory is the most recent for that file name.