1.1 Backing Up and Restoring

Backing up and restoring follow the same general steps as outlined below. The Defining Data Sets and Backing Up and Restoring Data sections contain slightly different steps, depending upon whether you want to backup or restore data.

1.1.1 Connecting to a TSA

  1. Call NWSMListSMDRs to select an SMDR. Then call NWSMListTSAs using the returned SMDR name to find the available TSAs.

    The fastest method to find the TSAs is to list all active SMDRs and then list the TSAs that are local to that SMDR.

    You can also call NWSMListTSAs by itself to find all the active TSAs on the network. This method can take over an hour to complete because each site with an SMDR must be connected to and scanned to see if it has a TSA.

  2. Call NWSMConnectToTSA to connect to a specific TSA.

    The actual connection to the TSA is made while connecting to Target Services.

1.1.2 Connecting to Target Services

After connecting to a TSA, you are now ready to list, select, and connect to the Target Service.

  1. Call NWSMTSListTargetServices to find the Target Service.

    You can call NWSMTSScanTargetServiceName for this step. However, it will return only one Target Service name at a time.

  2. Call NWSMTSConnectToTargetService or NWSMTSConnectToTargetServiceEx to connect to the Target Service and gain access to the Target Service data.

1.1.3 Defining Data Sets

After connecting to the Target Service, either a backup or restore operation can be performed. The following sections details how to define data sets for backup or restore,

Defining Backup Data Sets

The user or engine uses backup option lists to indicate how to proceed with the backup session and what data sets to back up.

  1. Call NWSMTSGetTargetScanTypeString to build the Scan Type Options List.

  2. Display the strings to the user to gather information about how to limit the scan.

    When the user selects a scan type option, the engine checks the associated disallowed bit map to see if the selected scan type can be used. If it can be used, the engine uses the associated scan type bit mask and allowed bit mask to set the bit into a scan type variable.These values are then set in the NWSM_SCAN_CONTROL structure by calling NWSMTSScanDataSetBegin to define the scanning criteria.

  3. Call NWSMTSOpenDataSetForBackup to define all backup open mode options and NWSMTSReadDataSet to define all reading mode options.

  4. Call NWSMTSGetOpenModeOptionString to retrieve the TSA-specific open mode strings.

  5. Display the string to the user for selection.

    The associated values for these selections are placed into a 32-bit variable. You must ensure that only one numeric open mode is selected. For more information on open mode, refer Section 2.2.1, Open Mode Options.

  6. Call NWSMTSGetTargetSelectionTypeStr to retrieve the selection option strings.

  7. Either let the engine set the bits for the chosen selection type or call NWSMTSGetTargetSelectionTypeStr to use an SMS-defined mask to set the selection types.

  8. Display the selection type string list to the user for selection.

Including Directories

If the user wants to include a certain directory in a backup, the engine allows the user to walk through the file system tree and builds the path as each resource (such as a primary resource, directory, and file) is selected as follows:

  1. Call NWSMTSListTSResources to return a list of primary resources to the user for selection.

    NWSMTSScanTargetServiceResource can be called to return one primary resource name at a time.

  2. Call NWSMTSScanDataSetBegin, NWSMTSScanNextDataSet, and NWSMTSScanDataSetEnd to display a list of all immediate secondary resources under the selected primary resource to the user for selection.

  3. If the secondary resource is a parent, scan for all immediate secondary resources under the selected secondary resource.

  4. Append each resource name and the appropriate separator to a path string.

  5. Repeat Steps 1-4 until the user find the desired data set.

Defining Restore Data Sets

After establishing connections to the TSA and Target Services, you need to build the restore option lists.

  1. Call NWSMTSGetOpenModeOptionString to retrieve the TSA-specific open mode option strings.

    When the engine is ready to restore the data set, it informs the TSA of the chosen open modes to use by sending the 32-bit variable to the TSA by calling NWSMTSOpenDataSetForRestore.

  2. If the restore data sets contain paths, call the NWSMTSFixDataSetName to ensure the paths have the proper syntax and form.

1.1.4 Backing Up and Restoring Data

Backing Up Data

Before backing up data, make sure the backup options and the data sets names to be backed up are selected.The following flowchart summarizes the steps outlined in this section:

Figure 1-1 Backing up data

Backing up data

Figure 1-2 Backing up data

Backing up data

  1. Call NWSMTSBuildResourceList to initialize the TSA.

    The TSA will only scan the components of the internal primary resource list so the list must be updated in this step.

  2. Call NWSMTSScanDataSetBegin to begin the scan.

    If a failover or failback occurs, call NWSMTSScanDataSetEnd, reconnect to the TSA and call NWSMTSScanDataSetBegin.

  3. Call NWSMTSOpenDataSetForBackup to open a data set.

    If a failover or failback occurs, call NWSMTSScanDataSetEnd, reconnect to the TSA and call NWSMTSScanDataSetContinue only if the last successfully backed-up data set exists. If NWSMTSOpenDataSetForBackup fails in the first data set, call NWSMTSScanDataSetBegin.

  4. Call NWSMTSReadDataSet to retrieve the first data set to backup.

    If you need to retrieve a name from the data set name list, call the following functions:

    If a failover or failback occurs, reconnect to the TSA and call NWSMTSScanDataSetContinue only if the last successfully backed-up data set exists. If NWSMTSReadDataSet fails in the first data set, call NWSMTSScanDataSetBegin.

  5. Call NWSMSDSessionWriteData to allocate memory for the transfer buffer.

  6. Call NWSMSetNewRecordHeader and NWSMUpdateRecordHeader (see the example code for NWSMTSScanDataSetBegin) to prepare the data set (according to SIDF) for storage on the media.

    These functions fill the transfer buffer with the scan information and data set information and automatically take care of data sets that span transfer buffers.

  7. Call NWSMSDSessionWriteData to write the data set to the media.

  8. Call NWSMTSSetArchiveStatus to reset the archive status of the data set.

  9. Call NWSMTSCloseDataSet to close the data set.

    NWSMTSCloseDataSet will restore the original access attributes of the data set.

  10. Call NWSMTSScanNextDataSet to get the next data set to backup and continue with Step 3.

    If a failover or failback occurs, reconnect to the TSA and call NWSMTSScanDataSetContinue only if the last successfully backed-up data set exists. If NWSMTSScanNextDataSet fails in the first data set, call NWSMTSScanDataSetBegin.

    To prematurely terminate the scan, call NWSMTSScanDataSetEnd. If an error was returned from NWSMTSScanDataSetBegin or NWSMTSScanNextDataSet, NWSMTSScanDataSetEnd should not be called.

Restoring Data

The following flowchart summarizes the steps outlined in this section:

Figure 1-3 Restoring Data

Restoring Data

  1. Call NWSMTSSetRestoreOptions to set the restore options.

  2. Retrieve a data set name from the backup session that needs to be restored.

    If a name was successfully retrieved, continue with Step 3. Otherwise, follow the steps outlined in Section 1.1.5, Terminating a Process.

  3. Call NWSMTSIsDataSetExcluded to check if the data set has been excluded from the restore session.

    If the data set is excluded, go to Step 2. Otherwise, continue with Step 4.

  4. Call NWSMTSOpenDataSetForRestore to open the data set.

  5. Call NWSMGetRecordHeaderOnly and NWSMGetDataSetInfo to retrieve the data set information from the SIDF medium transfer buffers.

    You can also call the following functions to retrieve the data set's name from the NWSM_DATA_SET_NAME_LIST structure:

  6. Call NWSMTSWriteDataSet to write the data set to Target Services.

  7. Call NWSMTSCloseDataSet to close the data set.

    If no error occurred, loop to Step 2. Otherwise, handle the error.

This restore method consists of three loops. The first loop gets the next data set name and checks if it is excluded from the restore session. The second loop gets the buffers (containing the data set) from the medium and writes it to the Target Service. The outer loop goes back to the top and gets the next data set name.

1.1.5 Terminating a Process

When a backup or restore task completes, release the connections and free the allocated memory by following these steps:

  1. Call NWSMTSReleaseTargetService to disconnect Target Service from the TSA.

  2. Call NWSMReleaseTSA to disconnect the engine from the TSA.

  3. Call the following functions (as needed) to free allocated memory.

    NWSMDestroyList frees the memory allocated to the NWSM_LIST_PTR structure.

    NWSMFreeString frees the memory allocated by NWSMTSCatDataSetName, SMSTSFixDataSetName, NWSMTSGetNameSpaceTypeInfo, and NWSMTSSeparateDataSetName for the STRING_BUFFER structure.

    NWSMFreeList frees the memory allocated for the NWSM_NAME_LIST structure by calling the following functions:

    • NWSMListSMDRs
    • NWSMListTSAs
    • NWSMTSListTargetServices
    • NWSMTSListTSResources
    • NWSMTSListSupportedNameSpaces

    free is a C-language function that frees the memory allocated by NWSMTSParseDataSet for the UINT16_BUFFER structure.