![]() |
![]() |
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.
Once a session is established with the TSM server, use the following procedure to restore or retrieve data:
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:
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.
Once the backup or archive query has been performed, the application client must determine which objects, if any, are to be restored or retrieved.
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.
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.
Repeat this call as many times as necessary until the object has been received from the TSM server.
The BSAEndData call signifies that there is no more data for a particular object.
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.
Figure 24 displays the flowchart for performing restore or retrieve operations.
Figure 24. Flowchart for Restore and Retrieve Operations