Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

dsmBeginQuery

The dsmBeginQuery function call starts a query request to the server for information about one of the following items:

The query data that is returned from the call is obtained by one or more calls to dsmGetNextQObj. When the query is complete, the dsmEndQuery call is sent.

Syntax

dsInt16_t dsmBeginQuery  (dsUint32_t        dsmHandle,
   dsmQueryType  queryType,
   dsmQueryBuff  *queryBuffer);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsmQueryType queryType (I)
Identifies the type of query to perform. Select from one of the following:
qtArchive Queries archived objects.
qtBackup Queries backed-up objects.
qtBackupActive Queries active, backed-up objects only for the entire filespace name that you pass. This is referred to as "fast path" and is an efficient way to query active objects from storage.
Note:
You must be a root user on a UNIX operating system.
qtFilespace Queries registered file spaces.
qtMC Queries defined management classes.
qtBackupGroups Queries groups that are closed.
qtOpenGroups Queries groups that are open.

dsmQueryBuff *queryBuffer (I)
Identifies a pointer to a buffer that is mapped to a particular data structure. This structure is associated with the query type that you pass. These structures contain the selection criteria for each query type. Complete the fields in each structure to specify the scope of the query that you want to perform. The first field of each structure is stVersion, the structure version number.

The data structures and their related fields include:

qryArchiveData:
objName The complete object name. You can use a wildcard character, such as an asterisk (*) or question mark (?), in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of the objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.
owner The owner name of the object.
insDateLowerBound The lower boundary for the archive insert date (the date the object was archived). To obtain the default lower boundary, set the year component to DATE_MINUS_INFINITE.
insDateUpperBound The upper boundary for the archive insert date (the date the object was archived). To obtain the default upper boundary, set the year component to DATE_PLUS_INFINITE.
expDateLowerBound The lower boundary for the expiration date. The default values for both expiration date fields are the same as for the insert date fields.
expDateUpperBound The upper boundary for the expiration date.
descr The archive description. Enter an asterisk (*) to search on all descriptions.
qryBackupData:
objName The complete object name. You can use a wildcard character, such as an asterisk (*) or question mark (?) in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.
owner The object owner name.
objState This field can have one of three values: DSM_ACTIVE, DSM_INACTIVE, or DSM_ANY_MATCH.
pitDate The point-in-time value. A query using this field returns the latest object that was backed up before this date and time. The objState can be active or inactive. Objects that were deleted before the pitDate will not be returned. For example:
   Mon - backup ABC(1), DEF, GHI
   Tue - backup ABC(2), delete DEF
   Thr - backup ABC(3)

On Friday, call the query with a point-in-time value of Wednesday at 12:00:00 a.m. It returns the following information:

    ABC(2) - an Inactive copy
    GHI    - an Active copy

It does not return DEF because it was deleted.

qryABackupData:
objName The complete object name. You can use a wildcard character, such as an asterisk (*) or question mark (?) in the high- or low-level portion of the name. See High-Level and Low-Level Names. An asterisk matches zero or more characters, and a question mark matches exactly one character. The objType field of objName can be DSM_OBJ_FILE, DSM_OBJ_DIRECTORY, or DSM_OBJ_ANY_TYPE.
qryFSData:
fsName Enter the name of a specific file space in this field, or enter an asterisk (*) to retrieve information about all registered file spaces.
qryMCData:
mcName Enter the name of a specific management class, or enter an empty string (" ") to retrieve information about all management classes.
Note:
You cannot use an asterisk (*).
mcDetail This field has a value of bTrue or bFalse. The value determines whether information on the backup and archive copy groups of the management class is returned.

qryBackupGroup:

groupType The group type is DSM_GROUPTYPE_PEER
fsName The File Space name
owner The owner ID
groupLeaderObjId The group leader object ID
objType The object type

Return Codes

The return code numbers are provided in parentheses ( ).

Table 18. Return Codes for dsmBeginQuery

Return Code Explanation
DSM_RC_NO_MEMORY (102) There is no RAM remaining to complete the request.
DSM_RC_FILE_SPACE_NOT_FOUND (124) The specified file space was not found.
DSM_RC_NO_POLICY_BLK (2007) Server policy information was not available.
DSM_RC_INVALID_OBJTYPE (2010) Invalid object type.
DSM_RC_INVALID_OBJOWNER (2019) Invalid object owner name.
DSM_RC_INVALID_OBJSTATE (2024) Invalid object condition.
DSM_RC_WRONG_VERSION_PARM (2065) The API version of the application client is different from the TSM library version.


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