The UPSTREAM Program

Overview

This section describes all the options and functions available in the UPSTREAM main program us and uscmd. It is helpful, but not required, to have looked through the previous chapters to get a feel for using UPSTREAM.

This section explains what UPSTREAM does when it starts, and it explains the menus and functions available when you run UPSTREAM.

There are additional parameters that can be specified on a backup that are specific to each specification. This chapter describes these parameters.

Migration (or Grooming) is the ability to automatically delete files that have been backed up. UPSTREAM has the ability to automatically delete files once the files have been successfully backed up and track them properly. If you are backing up a file system that supports file last access date, UPSTREAM can also automatically detect which files have not been accessed for some specified period of time. This chapter explains how to do this.

There are additional parameters that can be specified for backups and restores. The additional parameters include:

• Compression levels
• Reporting features
• and more

Each backup or restore specification can also have meta-data parameters (workstation/server security options) and other options. This chapter describes these parameters.

There is an alternate restore facility to the one described in previous chapters. This chapter describes that facility.

When UPSTREAM Starts

When UPSTREAM starts it performs many different actions, some of them transparently. These actions include:

• Read and Verify Files
• Check for Failed Backups and Restores
• Start Unattended Operations
• Check for Remote Initiates
• Register your Registration information (see Registration)
• Clear the log (if configured to do so)

This section outlines each of these steps to help you understand them.

Read and Verify Files

The first thing UPSTREAM does is load the communications and file systems drivers. If any of these executables or libraries cannot be found, UPSTREAM displays an error message.

(UNIX only) If you are running the us program, it opens its system file. This file us.res must exist in the default directory. If it does not, you receive a message stating that UPSTREAM could not load its resource file.

us then displays the main screen and reads in the configuration and transfer parameters. Advanced UPSTREAM describe how to set parameters in other ways than using the automated parameter files.

If there are missing or no parameter files, and the remainder of the startup functions are skipped. If the parameter files are found, then they are read in and checked for correctness and completeness.

Check for Failed Backups and Restores

Once the communications services have been started, UPSTREAM checks to see if there is a restartable failed backup or a failed restore. If you are running attended (you checked the Attended box in the backup or restore Options dialog), you are asked if you wish to continue this backup or restore. If you say no, then the backup or restore can be restarted later. If you respond “yes”, then the backup or restore restarts immediately from the first failed file.

If you running unattended and have a failed backup pending, it is automatically restarted (unless you checked the Do not automatically restart failed backups check-box in the Configurator, or started with the option NORESTART Y). Note that setting these options still allows backups to be manually restarted or restarted remotely. Manual restart is the default and preferred method. Doing a manual restart still allows you to use the RESTART options in USTBATCH for restart of a given job at the time of execution.

Start Unattended Operations

If you specified an unattended backup or restore (by not checking the Attended check box in the backup or restore Options dialog), then the backup or restore immediately begins. When the requested function has completed, UPSTREAM terminates.

If the unattended operation that you selected was to wait for Storage Server initiates, UPSTREAM waits for the specified amount of time after the last received request (for RMTPARM.DAT this is 1 minute) and then terminate.

Check for Remote Initiates

UPSTREAM continually checks for remote backup or restore requests after it is started with communications activated and you are at the main display (not in a dialog). Remote requests are also checked for when you begin a new backup or restore.

 Registration

Registration is performed when the first remote check request has returned no remote initiate. It is performed periodically thereafter depending upon how it is configured in the Configurator (daily by default).

Clear the Log

The UPSTREAM log file can be configured to be reduced in size periodically. See Configuration and Settings for a description of doing this.

The UPSTREAM Menus

Once you enter the us program you have many options available via pull down menus. This section describes the functionality available beyond the backup and restore specifications described in prior chapters.

The menus available are:

File menu

Its functions include parameter file and system options.

Action Menu

Besides the backup and restore specification functions, it also allows file transfer, the restart of failed backups, performance bottleneck isolation, toggling of the trace for support purposes, and various other functions.

Remote Menu

Allows you to set up for unattended remote operation, accept or reject remote requests, perform your own remote request and perform various registration operations.

Management Menu

Allows an authorized user to perform certain management functions including viewing/deleting of existing backups, modifying Storage Server configuration entries, viewing the status of the Storage Server, host reporting.

Security Menu

Allows you to modify your active security information and invalidate it.

File Menu

This menu allows you to perform parameter file options as well as several system functions. The parameter file options include:

Open

This option displays a dialog that allows you to use a previously saved backup or restore parameter file. In Windows the standard system open file dialog is displayed. In other operating systems a dialog similar to the following is displayed:

Open Parameter File

Only those files with the .DAT suffix are displayed in the box (though you can enter any file name). When you open a parameter file, the dialog for the function specified in the parameter file is displayed and the fields in the dialog are changed to reflect the new parameters. An accelerator for selecting this option is ALT+O. Note that passwords are not retrieved from parameter files in attended mode for security reasons.

In the Director you can achieve the same results by pulling down the File menu and selecting Open Parameter File. There you can either open a parameter file locally or on the Target system.

Save

This allows you to save parameters that you changed in the backup or restore dialog, but did not save when you exited it. It displays the same save dialog as when you press the OK or button in the backup or restore dialog to allow you to specify the file name to save. An accelerator for selecting this option is ALT+S. In the Director you can accomplish the same result by pressing the Save or Save As button in the various dialogs.

View

This option allows you to view a standard text file without starting another program, and is most often used to viewing the UPSTREAM logs and reports. When you select this option, you see the Open Workstation/Server File dialog.

View File

The default name is upstream.log, but you can view any file in this dialog.

When you select a file, you see it displayed in a list box. There are Top of File and End of File push-buttons to move through the file as well as push buttons to open another file and to close the current file. Note that in many cases, using the scroll bars to scroll through the file does not work as it is paged into memory based on the highlighted item in the list box, so we recommend the use of the cursor keys, control keys (i.e. PgUp, PgDn) or control push buttons.

In the Director, you can view the upstream.log file by pressing the Target button (the icon that looks like a bulls-eye), highlighting the workstation/server whose log you wish to see and pressing the Log button.

File Menu System Options

The system options in the file menu include:

Exit

When you select this option a message box is displayed asking if you wish to exit UPSTREAM at this time. Press OK to exit, or Cancel to remain in UPSTREAM. An accelerator for selecting this option is ALT+X or F3.

Shell

(UNIX only) When you select this option, a message box is displayed asking you to press OK to go to a shell, or Cancel to remain in UPSTREAM. If you press OK to go to a shell, then the screen clears and you see a standard prompt. UPSTREAM is suspended, but the session with the Storage Server remains active.

When you are ready to return to UPSTREAM, enter exit from the command prompt. An accelerator for selecting this option is ALT+D.

About

Selecting this item displays a dialog that provides a simple explanation of UPSTREAM and the current version number. The only option is the OK button.

Action Menu

This menu provides the backup and restore functions described as well as a trace option.

Backup

An accelerator for selecting this option is ALT+B.

List and Restore

An accelerator for selecting this option is ALT+L.

Restart Backup

This option is grayed and unavailable unless there is a failed backup and communications are currently available. If this option is not grayed, you can restart a failed backup (or a backup where certain files were unavailable) by merely selecting this option.

The option has a list box that shows all restartable backups.

Select Restartable Backup

Proceed

If selected, the backup restarts just after the last file that was entirely received at the Storage Server.

Kill All

Removes all information for all restartable backups. Do this to cleanup if you know that you will not restart any backups. If you wish to remove just a single backup, there is a menu option for that.

View

Allows you to view the parameters that were used for this backup.

Cancel

Exits this screen without performing any functions.

In the Director you can restart a backup or restore in the Target dialog (press the icon that looks like a Bulls-eye), highlight the system that has a backup you wish to restart and press the Re-startables button. This displays the Restart menu.

Restartable(s)

Kill

Removes all information about this restartable backup or restore. If it was a backup, what was backed up remains on the Storage Server, but it can no longer be restarted. If it was a restore all data restores remains on the Client and the restore can no longer be restarted.

Load

Reads all the parameters about this backup or restore into your copy of the Director, brings you to the backup or restore tab and sets it up as if you had specified the backup or restore. Can be a powerful way to see all the settings used.

Restart

Restarts the backup or just after the last file fully received at the Storage Server. Restarts the restore just after the last successfully received file at the Client at the checkpoint, which is every 15 seconds by default.

Restart Last Backup

Ignores the backup or restore highlighted and restarts the last restartable backup run from this Client.

Restart Last Restore

Ignres the backup or restore highlighted and restarts the last restartable restore run from this Client.

Close

Closes this dialog without performing any additional functions.

Kill Restartable Backup

This option is grayed and unavailable unless there is a failed backup pending and communications are currently available. If this option is not grayed, you can specify that a backup never be restarted by selecting this option. You have to confirm that you really do not ever want to restart the backup and then UPSTREAM deletes its restart information for that backup.

Restart Restore

This option is grayed and unavailable unless there is a failed restore pending and communications are currently available. If this option is not grayed, you can restart a failed restore by merely selecting this option in the same way as you can restart a failed backup (see the Client description above).

Kill Restartable Restore

This option is grayed and unavailable unless there is a failed restore pending and communications are currently available. If this option is not grayed, you can specify that a restore never be restarted by selecting this option. You need to confirm that you really do not ever want to restart the restore and then UPSTREAM deletes its restart information for that restore.

File Transfer

(UPSTREAM z⁄OS only) This option allows you to exchange files with the Storage Server. See File Transfer for a complete description.

File Migration

A facility designed to migrate (identify, and remove) files off the workstation/server. See File Migration for a description of the facility.

Trace

Select this option only on the request of BMC Support .

Performance

This option displays a performance test dialog that allows you to isolate performance bottlenecks. See Performance for a complete description of this option and other suggestions on how to improve performance. An accelerator for selecting this option is ALT+P.

Set Environment

Allows a method of setting lesser used UPSTREAM parameters that are usually set through environment variables. See Advanced UPSTREAM for a complete description.

Set Priority

(Windows only) See Advanced UPSTREAM for a complete description.

Run a Job

See Advanced UPSTREAM for a complete description. An accelerator is ALT+J.

Restore Without Plugins (Windows only) or Restore and Inquiry (old)

See Long, Mangled File Name Support for UPSTREAM z⁄OS. An accelerator is ALT+R.

Disable Line Chars

If your terminal emulator is displaying the borders in a bad way, you may find the screens easier to view by selecting this option that uses ASCII characters only for the borders rather than PC extended line characters.

Remote Menu

The remote menu supports functions related to remote initiation of backups and restores.

Unattended Remote Functions

This option allows you to specify unattended operations where the control of these operations is remote. This is primarily used to have the Client wait a given amount of time for a remote system to request a function. See Start Unattended Operations for more information.

Accept Remote Functions

This is a single flag that indicates whether UPSTREAM accepts and processes remote requests. Remote functions are accepted if there is a check mark next to the option; they are disabled if there is no check mark. You toggle this flag by selecting the option on the menu (with the mouse or by pressing the ENTER key when the option is highlighted). Even if remote functions are disabled, UPSTREAM continues to look for them, but sends an error message to the remote indicating that they are disabled.

Request Remote Function

This option allows you to request that a remote function be performed on another Client. These requests can be directed via the Storage Server program or directly. See Advanced UPSTREAM for more information.

Listen for Remote Functions

This is a single flag that indicates whether UPSTREAM periodically checks for remote functions. Since we recommend a daemon or service for checking for remote functions this should be turned off for any attended operations, and is by default.

Registered Names

Allows an authorized user to modify the Storage Server registered name table as well a specify automatic updates. See Management and Reporting for more information.

Resend Target Name

If you have configured to use a target (registered) name, you can resend it at any time by selecting this option.

Notification Targets

See UPSTREAM Notification for more information on e-mail and SNMP notification. Note that only the Client can configure SNMP notification; both the Client and the

Management Menu

The management menu allows authorized users to perform certain management tasks.

Profile Management

Allows an authorized user to view backups for all profiles or a selected subset of profiles and delete full backups. See Management and Reporting for more information.

Profile Configuration

(UPSTREAM z⁄OS only) Allows an authorized user to view, add, modify, or delete Storage Server profile configuration entries. Options such as allowing a given type of backup, Storage Server file names generic and global profiles and more can be set here. See Management and Reporting for more information. In the Reservoir you must use the Director to perform profile configuration.

Status of all UPSTREAM

Allows an authorized user to view detailed status about the current functions being performed by the Storage Server and perform some functions to it. See Management and Reporting for more information.

Host Reporting

Allows a workstation/server user access to the facilities and data of the Storage Server reporting facility. Most Host Reporting here is only for the UPSTREAM z⁄OS; to get similar Host Reports for the Reservoir you must use the Director. See Management and Reporting for more information.

FDRSOS Local Backup Admin

(UPSTREAM z⁄OS only) Administration of EMC disks shared between the UPSTREAM Storage Server and the workstation/server. See UPSTREAM SOS - SAN Express Passthru for more information.

Security Menu

The security menu allows a user to modify or invalidate the existing Storage Server security logon information.

Host Security Login

Select this option to display the Storage Server security entry dialog.

Logout (Reset Security)

Invalidates your login. We recommend that you select this option if you are leaving your workstation/server and are not terminating UPSTREAM.

Physical Menu

The physical menu allows physical disk backups and FDRSOS/physical disk restores.

Physical disk backup

Select this option to specify complete disk backups at the physical level. See Chapter 12 “Physical Disk” for more information.

FDRSOS/Physical disk restore

Select this option to specify complete disk restores of physical disk or FDRSOS backups. See Chapter 12 “Physical Disk” for more information.

Backup Specs

A specification used in a backup, specified in the Director by pressing the Add as Include or Add as Exclude buttons.

Include

These are specifications where the file(s) that are specified are included in the backup.

Exclude

These are specifications where the file(s) are specified in another file spec and you wish to exclude these from the backup. Exclude specs follow the rules specified for an Exclude File.

To specify the type of file specification and to modify the associated parameters, add or update a file spec on the backup dialog, highlight the file spec you wish to modify In the Director, highlight the spec you wish to modify and the modifying fields are displayed in the Backup Specifications window, to the right of the file specs:

Backup Specifications

General Tab Options

The options in the General tab are:

Sub-directories

Check this option if you wish the files that match the backup specification to be included in the backup in all subdirectories beneath the given one. Thus, if you wish to backup all the files on the F: drive, use a file specification of F:\*.* and check the Backup Subdirectories check box. The default is checked.

Preserve last access date

Backup operation effectively keeps (by resetting) the last access date. The default is checked.

Files Open For Update

How to deal with files that are open for update (when possible).

Default by Operating System

This is the recommended value as it is the most portable. Linux OS on IBMZ ignores this parameter and backs up all open files.

Include - Backup

Backup when possible these files.

No - Don't backup

When detectable, skip these files. This is the default for AIX. Most Windows, NetWare and other non-UNIX/Linux file systems do not allow them to be backed up.

Incremental

Whether only files that were changed since the last backup are included. Usually this option is grayed and unavailable as this is set by the Type above.

No Directory Entries Sent

Only available for incremental backups, we recommend you only check this option when you know that directory entries do not change (security or ownership).

Fail Backup On Error

Checking this option causes any file access error to fail a backup. Recommended only for database backups where any failure would result in an unusable backup.

Hardlink Support

Hardlinks are multiple file entries to a single set of storage. Used extensively in most environments; it is recommended that you use the default of Default by Operating System that makes your backups portable to the few operating systems that do not use hard links extensively.

Write Physical Disk Timestamp

If checked, UPSTREAM creates a zero length file at the root of the file spec’s file system that can be used at restore time for a Files Back To Physical Disk restore. The default is not checked. If you wish, the file can be written at the file path you specify rather that the root of file spec’s file system.

Write SOS Timestamp

If checked, UPSTREAM creates a zero length file at the root of the file spec that can be used at restore time for a Files Back to FDRSOS restore. The default is not checked. If you wish the file can be written at the File path you specify rather than the root of the file spec. This can not be used with Windows Snapshots (WinSS).

Segmented File

Check this option if you wish to have a large file broken into pieces that allow it to be backed up incrementally as the system detects segments that change. If you check this option, you must enter the options below it.

Segmented File Size (Gbytes)

If non-zero, enables file segmentation, in which a large file is broken down into multiple smaller files so that only the changed segments of the file are backed up when the file changes rather than the complete file. Specify in 1024 MB gigabytes. 0 is the default that disables the feature.

Segment Size (Mbytes)

If segmentation is enabled above, the size of each segment (except the last one). The default is 1 megabyte (1024 KB).

The Delete Tab

The Delete tab is only enabled for non-merge backups; if you wish to do file deletion, we recommend that you use UPSTREAM's Migration facility instead.

Delete files

If checked, indicates that this file spec is a deletion file spec and all files that are successfully backed up are to be deleted. Not checked by default.

Delete empty directories

If checked, UPSTREAM attempts to delete any directory that it emptied. The default is not checked.

The Date Limits Tab

The Date Limits tab allows you to limit the files included in a backup based on their dates (modification, access or creation).

Last access

Backup only those files which show a last access date which is earlier than the number of Days specified. The default is not checked.

Date cutoff

Used if Last access is not used. Include files only if date criteria specified below is matched:

Creation Date

Compare against the date the file was created.

Modification Date

Compare against the date the file was last modified.

Once you specify the date type to be used you must specify one of the date option radio buttons below it:

Compare to Specified Date

If you select this option you must specify the exact date to compare the date type above against. Because it is exact, it is rarely used as most people prefer relative dates (below).

Compare to Backup Date (+/-) some Days

Enter the number of days before the current date. If you then specify Minus, then files whose dates are BEFORE the calculated date are used; if you specify Plus, then files whose dates are AFTER the calculated date are used.

Windows Tab

Windows Options are only enabled when backing up a Windows machine.

Add Permissions

On NTFS volumes, when access to a file or directory is denied, attempt to add the administrative user to the ACL list. The default is not checked.

Reset Archive Bit

Check this box if you wish the included files to have the archive bit reset after they have been backed up. The archive bit is set by the operating system when a file has been changed and is used specifically for backups. Use this option for all backups if you wish to perform incremental backups; do not use this option if you wish to perform differential backups except on the full. The default is checked.

Hidden Files

Check this box if you wish hidden and system files to be included in the backup. The default is checked.

Mountpoints

A feature of Windows 2000 and above, mount points allow you to associate an entry in the file system (a directory) with another location on disk. Check this if you wish to backup the mount point and all the files beneath it. The default is not checked.

Registry and Event Logs

Check to include the system registry and event logs, part of the Windows system state. Checked by default.

NTFS File Extended Attributes

Important for a complete system backup, checked by default.

NTFS Directory Extended Attributes

Important for a complete system backup, checked by default.

NTFS File and Directory ACLs (Security)

Important for a complete system backup, checked by default.

Reparse Point Options

Reparse points options.

Skip Files With Reparse Points

This would cause no entry for files with reparse points.

Open Files Without Using Reparse Points

This causes the backup of the reparse point itself without activating the underlying function. This is checked by default.

Open Files Using Reparse Points

This opens the file as if it was a regular file. If you check this option, you can also check the option below it, Recall offline files to disk, as offline files are managed by reparse points.

UNC Machine Name Alias

Allows you to specify an Alias Name that replaces the server name in transmission to the UPSTREAM Storage Server. The default is not checked. It's used when you move the data from one server to another and use a different name and want to avoid a first-time full.

Lotus Notes R5/6 tab (works with IBM/Lotus Notes up to R8). See IBM Notes and Domino for more details.

UNIX Options Tab

UNIX Options tab allows you to specify UNIX specific options.

Include NFS Mounts

Check to have UPSTREAM traverse into NFS mounts. Otherwise UPSTREAM only backs up local file systems. The default is not checked.

Single File System

Check to have UPSTREAM limit its backup to the file system of the file spec. Otherwise, UPSTREAM backs up all local file systems that match the file spec and subdirectories flags. The default is not checked.

Loop Back File System

Backs up the “lofs” file system type when encountered if checked.

Include Linux ACLs

Check to have extended attributes which include ACLs and Novell NSS information included with each file in the backup. The default is checked.

No UID GID Names

If you check this box, UPSTREAM only includes the UID and GID numbers. If you do not check this box (the default), UPSTREAM attempts to resolve the numbers to names store the names, and use them on restore to allow the numbers to be different on the target system.

File Migration

Migration is defined as the action of backing up a file and then automatically deleting it (this is also known as Grooming). UPSTREAM has the capability to do this and more.

Migration backups can be done in several ways:

• Using the File Migration facility. This is the recommended method.
• As part of a full merge backup. This has the added advantage of having the migrated files easily viewed and recovered through standard inquiry and restore facilities and the Storage Server assures that these files are continuously moved forward until the given retention period has expired.
• As part of a separate merge backup, using a separate backup profile. This has the advantage of having the migrated files stored separately from the standard backup (thus saving space), but loses the advantages of easy inquiry and restore.
• As a non-merge backup using a separate profile. This method loses the advantage of real Storage Server migration control and it is discussed with file deletion in the section Backup Specs  above.

The Reservoir only has the capability to do simple migrations. Merge forward migrations with file-level retention are only supported by UPSTREAM z⁄OS.

File Migration

If you wish you can integrate your migrated and non-migrated data (see the following section), however, you are encouraged to separate migrated files from your normal production backups by using a File Migration Only backup profile.

A File Migration backup profile is a backup profile that is reserved for migrated files only. They cannot be used for regular merge backups and features such as duplicate file checking are specifically disabled. There is an option in Profile Configuration for setting a profile as File Migration Profile Only. The Usage Notes denote recommendations for File Migration Profile Only backups.

In the Director, press the Migration tab:

File Migration

File Migration Options

Full merge migration

Similar to a full merge backup, this creates a backup of all newly migrated files, plus it copies any unexpired files from previous full migrations and any files that were migrated with Simple Migration since the last Full Merge Migration. The Simple Migration backups are uncataloged (if on disk, they are also scratched).

Specified as MERGE 1. This is usually directed to tape.

Simple Migration

Similar to a non-merge backup, this creates a backup of only the newly migrated files. This is usually directed to disk for faster backup and restore. You should not allow DASD management systems to migrate these backups.

Specified as MERGE 0.

Migration End Set

Identical to a Full Merge Migration, except that it marks the profile so that the next Full Merge Migration does not copy forward any migrated files from this (or previous) full migration backups. As the name “end set” implies, this ends a set of migration backups so that the next migration creates the beginning of a new self-contained set for this profile. See Note 3 in Usage Notes. This is usually directed to tape.

Specified as MERGE 3.

Usage Notes

1. Migrated files are not deleted from the workstation/server until all are backed up. For Full Merge Migration, the deletion does not occur until the merge from previous backups is complete. If the migration fails while the workstation/server is sending files to z⁄OS and the migration is marked restartable, you may restart the migration. However, if the migration fails while it is merging migrated files from previous backups, the backup is discarded and must be started over. If the merge fails because some expected previous backup is not available (e.g., no longer cataloged or not on the expected disk), you must manually delete the unavailable backup from UPSTREAM’s records (see Section “Profile Management”) or recover a vaulted copy of the missing backup before redoing the migration.
2. We recommend that you do Simple Migrations frequently (e.g., daily or weekly) to disk. This allows for fast restores if the data is needed. Full Merge Migrations should be done on an infrequent schedule (perhaps monthly). The data set names used for the Simple Migrations on disk (DASDPREF) and for the Full Merge Migrations on tape (TAPEPREF) should be different. You may want to make the tape backups a GDG, with a limit of at least 3 or 4 generations so that backup copies of the migrated files are retained (but see “File Retention vs. Backup Retention” in Section); the disk backups do not need to be a GDG, but you must insure that they are retained until the next Full Merge Migration (not deleted by a DASD management system).
3. “Migration End set” can be used when the amount of unexpired migrated data in the current full migration backup has become so large that merge processing time or the number of tapes required has become too large. The Full Merge Migration backup it creates is the last one in this “set” of migration backups; subsequent migrations contain only the files that are migrated after this point. But this means that this migration end set must be retained until all the migrated files on it reach their individual expirations; see “File Retention vs. Backup Retention” in Section. The Migration End set is probably not required unless:
   1. 
      
      • A large amount of data has been migrated under this profile with a long retention.
      • The maximum file retention used under this profile exceeds 1 year.
      • You do manual migration (not based on date of last usage) of a set of files and need to keep them for an extended period (longer than the usual migration retention).
4. Since these migration backups are the only copies of the migrated data sets, we strongly recommend that you create backup copies using the USTVAULT utility (see the UPSTREAM Storage Server User Guide).

File Retention vs. Backup Retention

As mentioned earlier, migrated files are given a retention period as part of the file spec used to select them. This retention used to calculate an expiration date associated with each migrated file. When a Full Merge Migration is done, previously migrated files are always copied forward to the new full backup unless they are past their expiration date, so expired files are automatically discarded. If you do not use the Migration End Set option, this means that the latest full migration contains all unexpired files that have ever been migrated under this profile (we recommend that you retain several previous full migration backups for safety). You can view the expiration dates by checking the Display expiration dates check-box in the Restore parameters dialog from List and Restore.

However, if you do use the Migration End Set option (see Note 3 in “Usage Notes” in Section), the migrated data sets on the backup created by that option are not copied forward to subsequent migration backups. You must insure that this end set backup is retained until every migrated file on it has reached its individual expiration date.

The easiest way to do this is to use the configuration option to include an exclamation mark (!) in the backup data set prefix in the profile (see DSN Prefix in the description for Profile Configuration); “Migration End set” replaces that with an “E”, while it is replaced with a “F” for Full Merge Migration or “N” for Simple Migration. This allows you to create one GDG for the normal Full Merge Migrations (keeping 3 or more generations) and a separate GDG for the Migration End Set backups, allowing them to be kept much longer. Depending on how often you intend to do a Migration End set, you must define this GDG with sufficient generations so that the backups are retained until the migrated files with the highest retentions reach their expiration dates. For example, if you do Migration End set once a quarter, and the highest retention is 365 days (1 year), the end set GDG should have at least 5 generations (5 quarters).

If you are doing migrations as part of MERGE BACKUPs, note that if you do a “First Time Full” backup, this does not copy any previously migrated files from previous full backups, so the previous full merge backup need to be retained until all the migrated files expire. There is no convenient mechanism for automating this, so you may need to manually change the retention of that previous full backup in your tape management system. This is one reason why separate migration is now the recommendation.

Last Access Date

Some file systems store and maintain much more information than is stored in the DOS FAT file system. Novell, all UNIX file systems, and NTFS maintain a Last Access Date that is the last date that the given file was opened for any reason.

UPSTREAM can optionally respect this date on backups. When performing a backup of a file system that supports Last Access Date, UPSTREAM can save the directory information before opening the file and replace it after closing the file. As you would expect, this is essential for Migration.

UNIX maintains in its file system, a file’s last access date. Since by its nature, a backup has to access a file, UPSTREAM can optionally (on by default) save the directory information before opening the file and replacing it after closing the file. As you would expect, this information is used for Migration and is thus required if you will be using last access date for migration.

Migration as Part of Backups

Separate migration profiles as described above is the recommended way of doing migration. In this mode, migration file specs are included with the backup file specs and the migrated files are included in the backups. For MERGE BACKUPs, the migrated files are copied forward to each successive full backup until they reach their expiration date.

For example, if you are regularly performing merge backups on /users/* and wish to migrate files in the /users/bob directory that have not been accessed in more than 180 days create the following file specs when you are running a full merge.

When this backup is run, all the files in the /users directory are backed up and the files in the /users/bob directory that are older than 180 days are deleted. These files are stored on the Storage Server and merged forward onto subsequent full backups until the retention period (180 days) has expired.

Migration Inquiries and Restores

Version inquiries display all backup file specs except Migration file specs. To display Migration file specs you need to:

• In the Director, pull down the Options menu and select Version View. In that dialog, press the Yes radio button in the Show Migrated Files frame.
• In the client, check the Display Migrated Files check-box in the restore dialog.

Next to the Display Migrated Files check-box are two check-boxes:

Only

If checked, then only migrated files are displayed; standard (non-migrated) files are not displayed. This can be useful in determining specific migrated files to restore.

Display Expiration Dates

If checked, the file list includes the expiration date for migrated files. Note that this date is the last date that files are merged forward; they remain on the Storage Server until the disk or tape file expires.

There are two ways to restore migrated files:

1. Specifically add or update a migrated file in the Inquire Files list box (using the mouse or keyboard).
2. Specify wild-cards in the Specification field and check the Restore migrated files check-box in the Options dialog.

Overall Backup/Restore Parameters

You can specify significant overall parameters (not file spec related) for either backups or restores by pressing the Options button in the Backup Specifications or Restore Options windows. In the Director, the fields are broken up into multiple small screens, each of which is accessed via tabs:

Backup Options - Miscellaneous

Compression Frame

The compression radio buttons allow you to specify the type of compression used during the backup. These fields are grayed for restores. Each level or compression has advantages and disadvantages. The default is fast compression.

No Compression

If you press this radio button, then the data is not compressed. Select no compression for the highest performance in local Token-Ring environments with medium to slow clients where reducing data storage is less important than throughput.

Fast Compression

If you press this radio button, then a high performance compression method is used. This method if not particularly effective with many types of files in reducing the amount of data transferred. Select this option for high performance in most high speed communications environments. This is the default in most environments.

High Compression

If you press one of the high compression buttons, then the maximum compression is used. These methods are effective on all types of files. However, they significantly impact the performance of the backup and require additional memory. High compression is recommended in low speed environments (56K bps or less), in high speed environments where z⁄OS storage is at a premium and for small backups. The three levels of high compression run at about the same speed, but take increasing amounts of memory and are slightly more effective (1-3% per level).

The additional memory requirements are:

• High Compression 1: 26K
• High Compression 2: 46K
• High Compression 3: 91K

zLib

zLib is a standard compression technique that has higher overhead in time and system resources than the options above, but can deliver the most effectively compressed data. Note that If you select this option, you will also need to specify a zLib Level. 0 is no compression, 1 is a small amount of compression, 6 is the default, and 9 is the most effective but has the highest overhead. We recommend using 6 in most environments. Contact BMC Support if you are having questions about the best level to select.

Minimum Size File to Compress

Since there is overhead in any compression method and since very small files tend to compress poorly, a minimum file size must be reached to cause the file to be compressed.

Default: 65536.

Jobs Tab

The jobs tab allows you to specify jobs to be run before, after and in the event of failure of an UPSTREAM process.

Preprocess

This is the name of a program, batch file, or script file that runs immediately before the UPSTREAM function. While only displayed for backups and restores, this field is active for all other unattended UPSTREAM functions (file transfers, host reporting, etc.). If the pre-process job fails (cannot be run or returns a non-zero return code), the UPSTREAM function is not performed. If the pre- or post-process job fails, and you are running CONV=WAIT, Storage Server jobs, the entire function returns a non-zero return code on the Storage Server.

Postprocess

This is the name of a program, batch file, or script file that is run immediately after the UPSTREAM function. While only displayed for backups and restores, this field is active for all other unattended UPSTREAM functions (file transfers, host reporting, etc.). If the post-process job fails and you are running CONV=WAIT, Storage Server jobs, the entire function returns a non-zero return code.

Process Failed

This is the name of a program, batch file or script file that is run immediately after the UPSTREAM function if it fails. While only displayed for backups and restores, this field is active for all other unattended UPSTREAM functions (file transfers, host reporting, etc.).

Process Failed jobs can be useful in that they can run jobs that notify support personnel in the event of a backup or other UPSTREAM job failure. For example, you can create a Process Failed job to run a LAN SEND command to notify users that a workstation/server backup failed. Note though that if UPSTREAM or the operating system crashes, there is no notification.

Wait for Job - Issue Wait Complete Message Tim (in milliseconds)

Almost all users will leave this at 0 to avoid having to worry about jobs timing out.

Kill job when time expires - issue message

Most users will specify a 0 timeout so will not need to worry about messages logged.

Send job output (stdout, stderr) to UPSTREAM log

Most users will check this as output is almost always interesting in problem determination.

Miscellaneous Tab

The check-boxes are:

Log Non-Fatal Messages

If you check this box, UPSTREAM messages that do not terminate a backup are displayed and written to the log. These messages include detail on why a file was skipped, failure to obtain non-file data, and the like. It is recommended that this button be checked during testing and the initial phases of production and be unchecked when the log or reports are regularly checked for backup or restore completeness. The default is unchecked.

Only errors causing skipped files sent to host

If Log Non-Fatal Messages above is checked you can reduce the amount of logging by checking this check-box. Thus, only those messages that result in skipped files are logged; messages that do not result in a file being skipped (inability to access non-file data, resetting the archive bit, etc.), are not logged. The default is not checked.

No UID/GID Error Messages

(Director only) (UNIX only) If you check this box, then 8000 and 8001 error messages warning about missing UID or GID names are suppressed.

Attended

If you check Attended it is assumed that this is an attended backup or restore. Do not check this box if you are building a parameter file for unattended backups or restores; it is ignored in all other cases. The default is checked.

Hold Open all Directory(s)

(UNIX only) If checked, a scan of all user directories is made and each user's directory is held open so that it is included in the backup. This was added specifically for UPSTREAM⁄ USS so that user's home directories would be included in a full system backup and is only recommended in that environment. The default is not checked.

Skip build backup file

When UPSTREAM begins a backup, it usually pre-scans the data to be backed up before it begins the backup. This provides an estimate on the amount of data that is backed up and minimizes the amount of time that the tape is mounted. You can disable the pre-backup scan of the data so that UPSTREAM begins sending data almost immediately. In some cases, particularly when you are performing a merge full backup of a large number of small files, this can result in some performance advantage. Some UNIX backups which contain a large number of small files may show a particular benefit. However, the disadvantages are many. For example, without an estimate of the backup size, Storage Server disk data sets including UPSTREAM/ SOS pseudo-data sets cannot be properly pre-estimated. If you check this option, you must also specify a DASDOVERRIDE to avoid backup failures. Even if you check this box, UPSTREAM still creates a backup file as it needs it for restart, merge backups and file deletions. So you still need to reserve adequate space for it in the work-path. The default is not checked. It may not actually change the behavior of a backup for some plugins (e.g. WinSS.).

Send client log details to repository

If you check this box, UPSTREAM sends all message lines (except for the additional text for each message) to the Storage Server whenever it reports an error; otherwise UPSTREAM only sends the first line of the message. The default is not checked.

Sort backup

Enabling this option is not recommended at this time as it slows down the backups slightly and consumes memory. The default is not checked.

Use Incremental Database Facility

With this option, the client maintains in the workpath a database of files backed up. In UNIX this is particularly useful as, without an archive bit, there is no better way to detect when a file is new or has changed. Since it knows all files, it also reflects deleted files on incremental backups.

Check this box to use the local incremental database rather than the UNIX modify file or the PC archive bit for the detection of changed files. Highly recommended in UNIX, required for segmented files and generally not recommended for PC or plug-in backups. The default is not checked.

Hold Tape

If checked, for tape backups keeps the tape mounted for a minute or so after a backup completes in case another backup requests the same tape. Recommended for database backups like Oracle where the same tape is repeatedly written on. The default is not checked.

Fail Backup If File(s) Are Skipped

Checking this box causes a backup to immediately fail if a file fails for any reason. Automatically set for database backups, highly recommended for single file backups. The default is not checked.

Use Windows Style Wildcard File Compare

If checked PC backups use file compares with a more sophisticated algorithm than was used with previous versions - the wild-carding scheme in use by Windows today. UNIX backups are unaffected by this option. The default is not checked.

Send UPSTREAM Client Log Details to Repository

If checked, all lines of Client messages are sent to the repository rather than just the first line. The default is not checked.

SAN Backup/Restore

(Reservoir only) Causes the backup or restore to be written directly to tape bypassing the LAN - the SAN Express Direct. Unchecked by default.

Solo

(Reservoir only) Causes this job to wait for all other jobs to complete. The job only runs when it is the only job in the system. This option is only used in ustbatch jobs.

Set archive bit on restore

If checked, the archive bits are set for files when they are restored. The default is not checked.

Use I/O Optimizer

(Linux only) This feature enables reading file data in parallel to improve backup performance. Depending on the current networking and I/O characteristics UPSTREAM may consume over 1GB of additional memory. Optimization parameters (number of read threads and buffers) can be tuned with the help from BMC.

Skip plug-in processing and restore to a regular file

This is most commonly used with WinSS backups when you wish to restore a component file to a local disk or for SQL Server or Exchange backups to be processed externally to UPSTREAM. Use with caution and with the assistance of technical support.

Truncate Long File Names on Backup (Restore Full Name)

If the file name is longer than the Storage Server can handle (255 for z⁄OS, 1023 for Reservoir), the default behavior is to skip the file. there is a technique (discussed in Long, Mangled File Name Support for UPSTREAM z⁄OS) that discusses the truncation technique that allows the full name to be used for the restore. The default is not checked.

Maximum file name size

The maximum number of characters in the file name. This field is ignored in all 3.7.2 client versions and above as the longest possible number is used. Since the maximum for z⁄OS Storage Server is 255 the name is truncated using a method where the name is stored in the data as described in Long, Mangled File Name Support for UPSTREAM z⁄OS). For Reservoir to a 3.7.2 client or above, the default of 1023 is used and this value is ignored.

Duplicate Checking

If you check this box then placeholder records are send instead of the file data for files with last modification dates greater than the value specified. See Chapter 16 “Duplicate Files” for more information. The default is not checked.

DASD Override

See Sequential Disk Size Allocation for a complete description. But this value allows you to specify an increase, a decrease or a definite number for the size of the backup and can be critical, particularly for z⁄OS Storage Server.

Exclude File

Enter an exclude list file, formatted as described in Exclude File below.

Record Size

No longer controlled through this option.

Packing Size

This is the Storage Server communications record packing (blocking) size. The records transmitted to the Storage Server over communications are an even multiple of the record size, less than or equal to the specified packing size. 0 disables record packing. Records are stored on the Storage Server using the record size; this is a communications tuning parameter. For example, a 6000 byte record size and a record packing size of 32700 results in communications of 30000 byte records (excluding the affects of compression). For some environments, you may be able to increase performance by decreasing this value (or disabling record packing entirely). The default is 32700 but the value can go up to 65400 with z⁄OS Storage Server or Reservoir v3.7 or above and we have seen higher speeds and lower CPU utilization with higher values.

Maximum Time

The maximum number of minutes the job is allowed to run before it is killed by the Client for running too long. 0 disables this feature and is the default.

Switch to tape size (MB)

Allows you to specify that a backup run to disk and have it automatically switch to tape instead if the estimate is larger than the specified size (in megabytes). Be aware that UPSTREAM uses the tape data set name rather than the disk data set name specified in the profile, which may cause GDG issues.

Checkpoint time

For restores, this is an interval (in seconds), when a checkpoint is taken. If the restore is restarted, it restarts on checkpoints. The checkpoint interval is also used for physical disk backups as the restart point.

Max log days (UPSTREAM local) or Log Clear (Director)

If non-zero, the UPSTREAM log file is automatically cleared after a backup completes. Specify the number of days worth of log information to preserve (similar to the uslogclr program). The default is 0. It is recommended that you use the log maintenance facility in the Configurator rather than this value as it consistently cleans the log.

TCP Timeout

The number of seconds of inactivity before a send or receive times out. 0, which is the default, disables the timeout. A non-zero TCPTIMEOUT may cause performance degradation unless you have specified a TCP/IP Send and Receive buffer size (in the UPSTREAM Advanced Configurator) of at least 65535. Certain UPSTREAM functions, such as registration timeout automatically regardless of the TCPTIMEOUT value.

Vault Number

(Reservoir only) The active vault group to access. 0 indicates standard backups and is the default. Numbers starting at 1 reference the vault group. This is specified in the Version View in the UPSTREAM ZDIRECTOR.

The following section describes the exclude list option mentioned above. Reporting, describes reporting options.

Exclude File

UPSTREAM supports an exclude list file that allows you to specify any number of files to be excluded from a backup or restore.

Note that once a file, directory or volume has been excluded, it can’t later be included back in. Excludes take precedence over includes.

The wild-carding discussed here is used for exclude file specs as well.

The exclude list is a text file, each line indicating the file(s) to be excluded:

Where:

“<File name>”

The fully qualified file name, surrounded by quotes, of file(s) to exclude from the backup or restore. Wild-cards can be used in the file name. Non-UNIX systems may use the generic “#” drive letter indicating any drive. For exclude specifications, wild-cards can be included in the middle of paths. For example, to exclude all the mp3 files in the users directory and in each “music” subdirectory, specify the exclude list entry below.
“/users/*/music/*.mp3” Y
A single star can be used as a wildcard to indicate all files on both UNIX and Windows. Use “?” to indicate single characters or to exclude a given number of characters. For example, “???” excludes entries with 3 characters.

<subdirectory flag>

Y

Indicates that all files and directories in subdirectories beneath the one selected are excluded.

N

Indicates to only exclude these files in the specified subdirectory. However, if the file name itself is a directory, then that directory is completely excluded and UPSTREAM does not traverse it. This is the most efficient way to exclude full directories.

<comments>

Any text, to the end of the line, that helps you remember the entry. Note that comments can’t be used in file specifications (only valid in an EXCLUDELISTNAME file)

Specify the exclude list file name in the Options button, Miscellaneous tab of the backup or restore dialog. You can also specify it from the command line, environment or the Storage Server with the UPSTREAM parameter EXCLUDELISTNAME.

Even ignoring wild-cards in the middle of an exclude spec, there are lots of cases where it can get confusing. Below are some examples:

• (UNIX) /users/bob N
  (Windows) C:\Users\Bob N

Assuming that ‘bob” is a directory, in this example UPSTREAM looks at the directory “bob” and exclude all files starting with the directory bob and below. This is a very special case as it excludes it in such a way that it does not traverse it. This is the recommended method to exclude the contents of a single directory including all files below it and should be used to get the best performance whenever possible.

However, if “bob” is a file, it is excluded from the “users” directory and not below.

If “bob” is a directory and you specify “Y” for subdirectories, then the files in “bob” and all files below are skipped but it is traversed and thus you lose the performance advantage.

• (UNIX) /users/bob/* Y
  (Windows) C:\Users\Bob\* Y

The difference between this and the example above is effectively nothing. Again assuming that “bob” is a directory, “bob”, its contents and the contents of all subdirectories are excluded. However, in this case the directory is traversed so the first method (the one without subdirectories) is the recommended method.

• (UNIX) /users/bob/* N
  (Windows) C:\Users\Bob\* N

The contents of the directory “bob” is excluded. Nothing below that level is excluded.

•  (UNIX) /*.mp3 Y
  (Windows) #:\*.mp3 Y

Any files with the extension “mp3” are excluded, anywhere on the system. For example: Music.mp3 would be excluded. But in UNIX, Music.MP3 is not, as UNIX is case sensitive for directories. Note the ‘#’ in Windows to include the file on all drives.

• (UNIX) /*.mp3 N
  (Windows) #:\*.mp3 N

Any files with the extension “mp3” will be excluded, but only in the highest level directory, and not below. For example: /Music.mp3 would be excluded, but /users/Music.mp3 would not be excluded, Note the ‘#’ in Windows to include the file in the highest level on all drives.

• (UNIX) /users/*/music/*.mp3 Y
  (Windows) #:\users\*\Music\*.mp3 Y

Any files with the “mp3” extension are excluded from the Music subdirectory directly below the user’s main directory and in all directories below that. The asterisk wild-card in the middle means that any *.mp3 files in a Music subdirectory below the user’s directory are excluded. Thus, /users/bob/music/dir/Music.mp3 and /users/bob/d1/Music.mp3 would both be excluded.

Some additional notes about exclude specs:

• (UNIX) You can not specify a location pointed to by a symbolic link in an exclude specification. UPSTREAM resolves the location of the symbolic link to the actual data location. So you must only use real data locations, not linked locations.
• Restore excludes work slightly differently than backup excludes. For example, in a backup exclude, to exclude the directory ./d1, specify the directory just like that; in a restore, exclude the directory with wild-cards, like ./d1/*.

If you do not specify a drive or directory for a file, the “#” (universal) drive and subdirectories flag is assumed. The “!” can be used as a wildcard for UNC or system state file excludes.

(non-UNIX) A sample EXCLUDE.LST file is provided (see below) that works with many environments. We recommend deleting lines inappropriate to your environment.

Reporting

When you press the Reporting tab, you see the following dialog:

Reporting

A similar dialog is available in the Director when you press the Options button and the Reporting tab.

Files Backed Up/Restored

If checked, file names included in a backup or restore is written to the report file.

Files Skipped

If checked, files skipped during the backup are written to the report file as well as written to the local and Storage Server logs. Note that skipped files are written to the local and Storage Server logs only if Log non fatal messages is checked.

Files Excluded (Restore Only)

If checked, files that were excluded during a restore are reported. This is particularly useful for Windows where a wide number of files may be automatically excluded by UPSTREAM (based on Windows requirements). Excluded files are also written to the UPSTREAM log. You can suppress this logging with the environment variable USDONTLOGEXCLUDEDFILES.

Files Deleted/Migrated

If checked, all files deleted during a backup (with file deletion or migration options) are written to the report file.

Version Inquiries

If checked, the results of version inquiries (all version and file specs within the versions) are written to the report file. Check the Summary ONLY for a more compact description of each version.

File Inquiries

If checked, the results of each file inquiry (in directory format) is written to the report file.

Parameters (backup and restore)

If checked, the specified parameters are written to the report file at the beginning of a backup or restore.

Files Requested During Merge Phase 3

In a full merge backup, those files that are requested from the Storage Server as seen in the backup scan but not found in prior backups and now need to be transmitted as the final phase of the merge.

Files Backed Up During Merge Phase 3

In a full merge backup, those files which are backed up in phase 3 of the merge (found in the scan but not sent in phase 1 or found in prior backups, phase 2).

Segmented Files

Lists the files that were segmented and the individual segments backed up and restored. Allows you to report only on files segmented and see the affect of segmentation on your overall backup.

Report File

The file name where the report information is written. We recommend that it be fully qualified. The file name is required for reporting. The default is upstream.rpt

Report clear - preserve days

The UPSTREAM report files grow infinitely unless you take steps to occasionally shrink it. This parameter allows you to shrink the report after a backup in the same way as the “uslogclr” program. Enter the number of days worth of report entries to preserve. The default of 0 keeps UPSTREAM from shrinking the report.

The report file is simply a text file on the Client that contains the date and time of each event followed by the specific information for that event. Report files can be displayed with the viewing facility, your favorite text editor, printed, and, like upstream.log, maintained by uslogclr (see Errors) or the configurator or by the facility adding to the report.

A simple backup report entry might look like:

A simple inquire files entry might look like:

Report options are written to parameter files. Thus, if you wish you can change reporting options with each backup or restore, or control them from the Storage Server.

Restart Tab

The Restart Backup/Restore frame lists radio buttons that allow you to select the situations in which a failed backup or restore is restarted.

Never

If you press this radio button, and a backups or restores failed for any reason, it is not restarted.

On any error

If you press this radio button, and a backup fails for any reason or a file is skipped for any reason the backup restarts at the point of failure (if the backup did not complete) and skipped files are retried. This field is grayed for restores.

Not completed

If you press this radio button, and a backup or restore does not complete, the backup or restore restarts at the point of failure. Failed files during a backup are also retried. If the backup or restore runs to completion (regardless of whether files were skipped), then it is not restarted.

The other options have to do with remotely request USTBATCH options to a z⁄OS Storage Server and are described below.

UPSTREAM Notification

UPSTREAM has the capability of sending e-mail if an operation succeeds or fails, along with log and other useful information. By configuring your backups and restores to send notifications of specific events, you can add another valuable management tool to your data management tasks.

If you are using the Dispatcher scheduling facility, you can setup mail notification in the Dispatcher configuration facility in the Director. See “Step 5: Set/Edit Schedule Dates” in Section for a description of how to setup mail notification in the UPSTREAM Dispatcher.

Notification Target Files

Notification is accomplished by defining the destination users in a notification target file. When you specify the action (backup, restore, etc.), you then specify the notification target file name along with the status (success or failure) and attachments (log or report).

A notification target file can be specified for any action that UPSTREAM can perform so that notifications for events associated with that action may be sent to the targets defined To modify notification targets in the Director, enter the Target Name list, highlight the system you wish to modify notification target files for, and press the Setup Mailings button.

Mail Notification File Management

The upper frame (Notification Target File Name) displays the name of the currently active notification target file name along with a number of buttons relating to the file. The New button is used to create a new notification target file and the Open button is used to open an already existing notification target file. The Save button is used to save the notification target information to the file specified in the Notification Target File Name field. And the Save As button is used to save the notification target information to a different notification target file.

Notification Events

Once a notification target file has been created with one or more notification targets, it can be specified for any action that UPSTREAM can perform. The name of the notification target file to use is specified with the NOTIFYTARGETS parameter.

Before UPSTREAM can use a notification target file, the events for which notifications are sent must be specified. The NOTIFYEVENTS parameter is used to specify which events trigger notification messages to be sent to the various notification targets specified in the notification target file.

The NOTIFYTARGETS and NOTIFYEVENTS parameters are set from the Options button, Mail Notification tab. The key for this function to work correctly is that you must select a target before you press the Options button. Then, the configuration drop down contains the list of files available on that target and the mail options apply to the users specified in that file when selected.

In the Director, you specify notification by pressing the Options button, and the Mail Notification tab. The dialog is much more useful if you select a target before entering it, as it then allows you to select the notification file from a pull-down of files which currently exist on the target system.

Restore Options - Mail Notification

The fields on this dialog are:

Target File Name

The name of a notification target file (created in the Notification Targets dialog). Press the Browse button to help you find an already configured notification target file.

“Send Notification When” Frame

The Send Notification When options include:

Action Fails

Check this check box to be notified of any failed action. The default is checked.

If you check “Action Fails” the following two check-boxes are enabled:

Attach Log

If you check this box the relevant portion of the UPSTREAM log is attached to the notification message for a failed action. Only e-mail notification targets can receive attachments and only if they are configured to receive them.

Attach Report

Check this check box to have the relevant portion of the UPSTREAM report attached to the notification message for a failed action. Only e-mail notification targets can receive attachments and only if they are configured to receive them.

Along with the following edit field:

Attach File

If you wish, any user defined text file can be transmitted as an attachment with this notification. Specify the fully qualified file name here.

Action Succeeds

Check this check box to be notified of any successful action. If you check this box, there are similar check-boxes for Attach Log and Attach Report along with Attach File as for the Action Fails option (above).

Error message issued

Check this check box to have UPSTREAM error messages trigger a notification.

Warning message issued

Check this check box to have UPSTREAM warning messages trigger a notification.

Information message issued

Check this check box to have UPSTREAM informational messages trigger a notification.

Remote Initiated Notification

When you specify a z⁄OS or other remote initiated request, you can also request notification using the following two non-repeating UPSTREAM parameters. These parameters go with the other Client non-repeating parameters such as ACTION.

NOTIFYEVENTS=

If a NOTIFYTARGETS parameter is specified, the conditions in which a notification occurs. This is a bit map, where you add the notification values. This option is not required.

1

Notify if the action failed

2

Notify if the action succeeded

4

Notify for any errors

8

Notify for any warnings

16

Notify for any informational messages

256

Attach the log if the action failed and value 1 is specified.

512

Attach the report if the action failed, value 1 is specified and reporting is enabled.

1024

Attach the log if the action succeeded and value 2 is specified.

2048

Attach the report if the action succeeded, value 2 is specified and reporting is enabled.

Default: 769.

NOTIFYFAILUREATTACHMENT=

The file name to send if a file should be attached on operation failure. You must also specify a NOTIFYTARGETS file. This option is not required.

Default: None.

NOTIFYSUCCESSATTACHMENT=

The file name to send if a file should be attached on operation success. You must also specify a NOTIFYTARGETS file. This option is not required.

Default: None.

NOTIFYTARGETS=

The name of the notification targets file name if you wish to enable notification. This option is not required.

Default: None.

For example, if you wish to backup a complete Windows system with the backup profile SERVER, and notify the users specified in the notification file upstream.not when the backup failed, your batch job might look like:

E-mail Messages

If you enable e-mail messages for successful or failed actions, UPSTREAM generates e-mail text and attach the log and report if you request it. The following is a sample message from a failed backup:

Date: Mon, 02 Dec 2002 17:26:18 -0400
From: <user@company.com>
To: <user@company.com>
Subject: Backup failed
X-RCPT-TO: user@company.com
This message was automatically generated by the FDR/UPSTREAM Client application produced by BMC Software, Inc. Please do not reply to this message as your reply will most likely be discarded.The application issued message #2053:2053D Backup failedAdditional information:Error in receive started
Variable: BACKUPPROFILE = “PROFILE"
Variable: VERSIONDATE = “”
Variable: MACHINENAME = “MACHINE"
Variable: USERNAME = “user”
Attached file: \opt\fdrupstream\ACTION.1296.log

Content-type: text/plain; charset="iso-8859-1" name="ACTION.1296.log"
Content-disposition: attachment; filename="ACTION.1296.log"

If you enable notification messages for error, warning, and informational messages, you get a notification for each message logged (which may result in lots of notifications). For example, if you had enabled informational message notification, the message indicating a backup had started would result in the following notification:

From: <user@company.com >
To: <user@company.com>
Subject: FDR/UPSTREAM Informational Message
X-RCPT-TO: user@company.com
This message was automatically generated by the FDR/UPSTREAM Client application produced by BMC Software, Inc. Please do not reply to this message as your reply will most likely be discarded.The application issued message #2050:Msg #PC2050I Backup started (First-time full)Additional information:Profile: PROFILE, UPSTREAM v3.6.5 (S390 Linux)

Long, Mangled File Name Support for UPSTREAM z⁄OS

To support all files in a file system, even those longer than the maximum supported file name size of 255 bytes when backing up to z⁄OS Storage Server, the Client has been modified to shrink the file name down to fit.

This requires that the file name be mangled. What is done is:

• If the subdirectory part of the file name is less than 255 bytes, but the file name is longer, then the file name only is mangled.
• If the subdirectory part (+ 13 bytes) exceeds 255 bytes, then the subdirectory is mangled and the file name part is mangled independently.

The mangling of the component is done by taking the checksum of the whole name, representing it in 8 byte hex, and surrounding it by “<“ and “>” characters, which are illegal in most operating systems as they are used for file redirection. The leading “<“ is followed by the letter “t” to indicate that it is a truncation specification.

This facility is activated automatically when going to z⁄OS Storage Server. This feature is deactivated when going to Reservoir as it supports file name lengths up to the maximum supported by the client (1023 bytes).

If you wish to inactivate it: to skip files longer than the maximum supported by z⁄OS Storage Server (255 bytes) set the environment variable USNOLONGTRUNCNAMES to any value (in your job, in usenv.dat or a parameter file).

When activated, the file name is stored as the first part of the data. So, if you restore the file back to its original location, the file gets its original name. Similarly, if you redirect part of the path at a level above the truncation, then the names are correctly restored.

Thus is the example above, if /longname/* is restored to /long2/, then all the file names are correctly restored.

If file level reporting is enabled for backup or restore, then the original name and the truncated name are both reported. Thus we strongly recommend that if you need to know the original file names at a later time, that you enable file level reporting.

Two other environment variables can affect long file name support:

USTRUNCNOLONGNAMETREE

If set to any value, UPSTREAM does not maintain a list of truncated names and is not be able to detect any duplicates within a backup. However, there is a memory savings; so if you need to save memory, enabling this option can save a bit if there are a lot of truncated files.

USTRUNCUSEOLDCHECKSUM

Starting in v3.6.3 the checksum algorithm was changed. For compatibility with old versions (that would allow matching of files on a full merge backup) setting this to any value enables the function. However, the possibility of duplicate truncated names is higher due to the use of a poorer algorithm (a simple checksum rather than a complex digest).