2.2 Backup and Restore Options

The backup and restore options are used to specify the data sets to either backup or restore. Both processes use the Open Mode Options which are discussed in the next section. Other unique options are discussed within each relevant section entitled Restore Options and Backup Options.

2.2.1 Open Mode Options

Open mode options are defined by NWSMTSWriteDataSet and contain a mixture of restore modes and writing modes such as: update the data set, overwrite the data set, and do not restore the trustee information. These modes allow a finer control (than scan control options) in defining data sets since the open mode options are applied to individual data sets as each data set is opened, read, or written to. For example, the engine can back up all data sets or lock data sets before they are opened.

There are two basic groups of open modes:

  • Numeric open modes are represented by values numbered 0-15. Because these modes are sequential, the engine can specify only one numeric open mode.

  • Bitmap open modes are represented by bit positions. More than one of these modes can be ORed together.

Both modes are contained in a 32-bit integer where bits 0-3 contain the numeric open modes, and bits 4-31 contain the bitmap open modes.

Figure 2-1 Two basic groups of Open Modes

Illustrates the two basic groups of open modes in a 32 bit integer: bits 0-3 contain the numeric open modes and bits 4-31 contain the bitmap open modes

All numeric open modes and bits 4-7 of the bitmap open modes are classified as predefined TSA open modes. Each TSA must either support the options or indicate which options are not supported.

Bits 8-31 contain open modes specific to a particular TSA and are classified as TSA-specific open modes. These open modes are required by NWSMTSWriteDataSet.

If a numeric open mode is chosen and set to Yes, its corresponding value is set into the numeric mode field of the open mode bit map. The engine must ensure that only one numeric option is chosen. If a bitmap mode is chosen, its corresponding bit is set into the bit map.

Open Mode Option Lists

The open mode option lists display the TSA-specific and generic open options to the user for selection and are optional. The engine can internally set the values for the open modes without any user intervention (see Section 9.2, Target Services Generic Open Mode Values).

The open mode options list has four parts:

  • The open mode generic strings

  • The open mode TSA-specific strings

  • The open mode string index number

  • The open mode number

2.2.2 Restore Options

The restore options specify the data sets to restore. Options include excluding data streams, file trustees, directory space restrictions, etc.

Figure 2-2 Restore Options

The Restore Options

There are basically two restore option types:

Names Option Lists

The names option list is a list of data sets that were defined by the user to be restored (such as restore all *.exe and *.txt files) and their optional associated path. The data set names can contain wild cards (in the terminal path node-parent or child only), fully qualified paths, or terminal names.

After the data sets are specified, the engine puts the list into an NWSM_SELECTION_LIST structure. The engine must set the selection type for all entries in this structure to No Selection Type or zero.

Unsupported Options

Since TSAs might not support all TSA options, the engine can call NWSMTSGetUnsupportedOptions to find out which generic TSA option string it should not build and display to the user.

2.2.3 Backup Options

The backup options specify the data sets to backup.

There are three backup option lists:

The order of the strings returned by these functions corresponds to the bit position of a bit map.

The engine builds the strings for generic TSA options, and the TSA builds all strings for predefined and SMS-defined options. The engine uses the information from the NWSM_SCAN_CONTROL structure and the generic open mode options to build the strings for its part of the options list.

All of the options do not have to be used by the engine. The engine can pick and choose which options it wants to display to user.

Scan Control Options

Scan Control Options specify the attributes and characteristics of all data sets to scan for and are applied to every data set in the session. For example, you can specify to scan for all DOS data sets accessed within the last 10 days.

The scan control options are based upon the information required by the NWSM_SCAN_CONTROL structure and are returned by NWSMTSGetTargetScanTypeString.

Scan Control Options Lists

The scan control option lists contains at least two different lists. The number of lists is dependent upon how the engine presents the options to itself or the user. The engine can set the values in both of the following lists without any user intervention:

  • Date and Time Option Lists

  • Scan Type Option Lists

The date and time options list is optional. The engine builds the strings for the date and time fields and all other fields of the NWSM_SCAN_CONTROL structure except the scan type field. The fields that have no date values should be considered as having a zero value. The engine uses these strings as prompts to get the user's input.

The scan type options list displays the TSA-specific and predefined scan options to the user for selection and is also optional. However, unlike other lists, the engine must check for valid combinations of scan types. The TSA will also check for valid combinations, but this checking is not done until all options are specified and the backup has begun.

The scan type options list has three parts:

  • The scan type strings are built by the TSA.

  • The scan type string index number specifies which scan type string to retrieve.

  • The scan type value which indicates the type of the scan to perform.

Selection Options

Selection options allow the selection of an option and name the data sets to backup. For example, a user can select the exclude directories option and specify the sub-directory to be excluded. These options are returned by NWSMTSGetTargetSelectionTypeStr.

Selection options are used with path information to specify the name of the data sets to apply the selection type to. Call NWSMPutFirstName and NWSMPutNextName to build the selection list.

There are basically two selection option types:

Selection Types

There are two kinds of selection types: the SMS-defined selection types and the selection types particular to a TSA.

SMS-defined TSA selection types are common to most TSAs, but each TSA does not have to support them. However, every TSA must acknowledge whether it supports a SMS-defined selection type.

Both selection types are represented in the 32-bit selection type bit map. Each selection type is represented by two bits within the bit map. Bit 0 represents a TSA-specific defined action, while bits 1-31 represent the data sets to apply the action against. For example, the TSA defines bit 0 as an include/exclude action. When this bit is not set, a data set is excluded from the session.

Figure 2-3 Selection Type

Illustrates graphically that combining bit zero and bit two produces a selection type pair: Exclude Directories (bit 0=0, bit 2=1) and Include Directories (bit 0=1, bit 2=1)

The following table lists the SMS-defined bits 1 through 4.

Table 2-1 SMS-defined Bits

Bit

Description

1

TSA defined resource: These resources are always TSA-specific resources.

2

Parents (e.g., Directories or folders)

3

Children (Files)

4

Children by full name (a fully qualified path)

A separate bit map must be used to represent each selection type.

Selection Options List

The selection options list displays the TSA-specific and SMS-defined selection options to the user for selection and is optional.

The selection options list has four parts:

  • The selection option strings

  • The selection option string index number

  • The selection option bit mask

  • The path

The TSA builds the selection option strings. The selection option index number is a used to specify which selection string to get from the TSA. The selection option bit mask is used to set the selection type bit map. The path is entered by the user or the engine.

There are two methods for setting the selection type:

  • The engine sets the bits for the chosen selection type.

    For example, if a user selects Include Directories, the engine knows that it is the second string of the first selection type and sets bit 0 to equal 1 and bit 2 is also set.

  • The engine uses the masks defined by SMS.

    NWSMTSGetTargetSelectionTypeStr is passed a sequence number (selection type number) which indexes a string table. The sequence number is converted to a bit map or mask before being used.

Selection options are defined by NWSMTSScanDataSetBegin, NWSMTSScanNextDataSet, and NWSMTSSetRestoreOptions which act as data set filters.

Wild cards are used only in the terminal path node. The terminal path node can be a child or a parent.