Before you begin any restore or retrieve operation, first query the Tivoli Storage Manager server to determine what objects you can receive from storage.
To send the query, the application must enter the parameter lists and structures for the dsmBeginQuery call. The structure must include the file space that the query examines and pattern-match entries for the high-level and low-level name fields. If the session was initialized with a NULL owner name, you do not need to specify the owner field. However, if the session was initialized with an explicit owner name, only objects that are associated with that owner name are returned.
The point-in-time BackupQuery query provides a snapshot of the system at a specific time. By specifying a valid date, you can query all files that are backed up to that time. Even if an object has an active backup from a later date, point-in-time overrides an object state so that the previous inactive copy is returned. For more information, see the following example: pitDate. You must be connected to at least a Version 3 server to use the point-in-time BackupQuery query.
A query returns all information that is stored with the object, in addition to the information in the following table.
| Field | Description |
|---|---|
| copyId | The copyIdHi and copyIdLo values provide an 8-byte number that uniquely identifies this object for this node in Tivoli Storage Manager storage. Use this ID to request a specific object from storage for restore or retrieve processing. |
| restoreOrderExt | The restoreOrderExt value provides a mechanism for receiving objects from Tivoli Storage Manager storage in the most efficient manner possible. Sort the objects to restore on this value to ensure that tapes are mounted only one time and are read from front to back. |
You must keep some or all of the query information for later processing. Keep the copyId and restoreOrderExt fields because they are needed for the actual restore operation. You must also keep any other information needed to open a data file or identify a destination.
Call dsmEndQuery to finish the query operation.