Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

Receiving Data from a Server

The X/Open API permits application clients to receive data from TSM storage using the restore and retrieve functions of the product. Restore accesses objects that were previously backed up, and retrieve accesses objects that were previously archived. All restore and retrieve operations must be performed within the bounds of a transaction. See The Transaction Model.

Note:
Only the API can restore or retrieve objects that were backed up or archived with API calls.

Once a session is established with the TSM server, use the following procedure to restore or retrieve data:

  1. Make the BSABeginTxn call to start a transaction.
  2. Make the BSAQueryObject call to query the TSM server for backup or archive data. (This step can be performed outside the transaction.)

    Before beginning a restore or retrieve operation, query the TSM server to determine what objects can be received from storage. To issue the query, first fill in the applicable fields in the QueryDescriptor structure with the desired search parameters. Then make the BSAQueryObject call with the QueryDescriptor.

    If the session was started with a NULL owner name, it is not necessary to specify the owner field. If the session was started with an explicit owner name, then only objects that explicitly have that owner name associated with them are returned.

    The query returns all information in an ObjectDescriptor structure. Different information is returned depending on whether the object was originally backed up or archived. For example, a query on backup objects returns information on whether an object is active or inactive, while a query on archive objects returns information such as the object descriptions.

    All queries return all information that was originally stored with the object, in addition to the following:

    copyid
    The copyid provides an eight-byte number that uniquely identifies this object for this node in TSM storage. Use this ID to request a specific object from storage for restore or retrieve processing.

    restoreOrder
    The restoreOrder provides a mechanism for receiving objects from TSM storage in the most efficient manner possible. Sort the objects to restore on this value to insure that tapes are mounted only once and are read from front to back.

    Keep some or all of the query information for later processing. Keep the copyid and restoreOrder fields because they are needed for the actual restore operation. Keep any other information that is needed to properly open a data file or identify a destination.

  3. Determine the objects to restore or retrieve from the server.

    Once the backup or archive query has been performed, the application client must determine which objects, if any, are to be restored or retrieved.

  4. If more than one object is selected, sort the objects on the restore order field.

    Once the objects to restore or retrieve are selected, they must be sorted in ascending order (low to high) by the restoreOrder field. This sorting is critical to the performance of the restore operation. Sorting the objects on the restoreOrder field means that the data is read from the server in the most efficient order. All data on disk is restored first, followed by data on media classes that require volume mounts (such as tape). The restoreOrder field also insures that data on tape is read in order with processing starting at the front of a tape and progressing towards the end.

    Properly sorting on the restoreOrder field means that duplicate tape mounts and unnecessary tape rewinds do not occur.

  5. Make the BSAGetObject call.

    The BSAGetObject call uses the copyType and copyid fields of the ObjectDescriptor to begin obtaining the first object from the system. The call begins a restore or retrieve operation by identifying the object that is requested from the data stream.

    BSAGetObject obtains the first block of data that is associated with the object. If the object has more data, go to the next step. If the return code is BSA_RC_NO_MORE_DATA, go to step 7.

  6. Make the BSAGetData call.

    Repeat this call as many times as necessary until the object has been received from the TSM server.

  7. Make the BSAEndData call.

    The BSAEndData call signifies that there is no more data for a particular object.

  8. If you want to receive more than one object from the TSM server, repeat steps 5 through 7 for each object.
  9. Make the BSAEndTxn call to end the transaction.

    After all data for all requested objects has been received, the BSAEndTxn call must be made. You can also use this call to discard any remaining data in the restore stream for objects not yet received.

Flowchart

Figure 24 displays the flowchart for performing restore or retrieve operations.

Figure 24. Flowchart for Restore and Retrieve Operations

REQTEXT


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]