Tivoli Header

Tivoli Storage Manager Using the Application Program Interface


File Grouping

Note:
This function is new in version 5.1.0 for the API and the TSM server. It will not work for previous versions of either.

The Tivoli Storage Manager API has a logical file grouping protocol that relates several individual objects together. You can reference and manage these groups as a logical group on the server. A logical group requires all group members and the group leader belong to the same node and filespace on the server. Each logical group has a group leader. If the group leader is deleted, the group is deleted. You cannot delete a member if it is part of a group. Expiration of all members in a group is dependent on the group leader. For example, if a member is marked for expiration, it will not expire unless the group leader expires. However, if a member is not marked for expiration, and the group leader is expired, then all members are expired.

The dsmGroupHandler call groups the operations. The dsmGroupHandler must be called from within a transaction. Most group error conditions are caught on either the dsmEndTxn call or the dsmEndTxnEx call.

The out structure in dsmEndTxnEx includes a new field, groupLeaderObjId. This field contains the object ID of the group leader if a group was opened in that transaction. You can create a group across more than one transaction. A group is not commited, or saved, on the TSM server until a close is performed. The dsmGroupHandler is an interface that can accept five different operations. They include:

The dsmGroupHandler function call can perform the following actions:

OPEN
Creates a new group. The next object that is sent will be the group leader. All objects after the first object become members that are added to the group. To create a group, open a group and pass in a unique string to identify the group. This unique identifier allows several groups with the same name to be opened. After the group is opened, the next object that is sent is the group leader. All other objects that are sent are group members.

CLOSE
Commits and saves an open group. To close the group, pass in the object name and the unique string that is used in the open operation.
Note:
The application must check for open groups and, if neccessary, close or delete them. A group is not commited or saved until a close of the group is performed. You cannot close a new group with the same name as an existing open group. This will cause the CLOSE action to fail.

ADD
Appends an object to a group. All objects that are sent after the ADD action are assigned to the group.

ASSIGNTO
Permits the client to assign objects that exist on the server to the declared peer group. This is similar to the ADD action except that the add applies to objects within an in-flight transaction and the ASSIGNTO action applies to an object that is on the server. This transaction sets up the PEER group relationship.

REMOVE
Removes a member, or a list of members, from a group. A group leader cannot be removed from a group. A group member must be removed before it can be deleted.

There are two new query types for group support:

The qtBackupGroups will query groups that are closed while qtOpenGroups will query groups that are open. The query buffer for the new types has fields for groupLeaderObjId and objType. The query performs differently depending on the values for these two fields. The following table includes some query possibilities:

Table 14. Examples of Queries

groupLeaderObjId.hi groupLeaderObjId.lo objType Result
0 0 NULL Returns a list of all group leaders
grpLdrObjId.hi grpLdrObjId.lo 0 Returns a list for all group members that are assigned to the specificied group leader (grpLdrObjId).
grpLdrObjId.hi grpLdrObjId.lo objType Returns a list (using BackQryRespEnhanced3) for each group member that is assigned to the specificied group leader (grpLdrObjId), and matching the object type (objType).

The response structure (qryRespBackupData) from dsmGetNextQObj includes two fields for group support:

These are Boolean flags. The following example displays the creation of the group, adding members to the group, and closing the group to commit it on the TSM server. Refer to the sample group program (dsmgrp.c) that is included in the API sampsrc directory for an actual code example.

Figure 15. Example of Pseudo-code to Create a Group

+--------------------------------------------------------------------------------+
|dsmBeginTxn                                                                     |
|	dsmGroupHandler (PEER, OPEN, leader, uniqueId)                                 |
|	dsmBeginSendObj                                                                |
|		dsmSendData                                                                   |
|	dsmEndSendObj                                                                  |
|dsmEndTxnEx (With objId of leader)                                              |
|                                                                                |
|Loop for multiple txns                                                          |
|{                                                                               |
|	dsmBeginTxn                                                                    |
|		dsmGroupHandler (PEER, ADD, member, groupLeaderObjID)                         |
|		Loop for multiple objects                                                     |
|		{                                                                             |
|			dsmBeginSendObj                                                              |
|			Loop for data                                                                |
|			{                                                                            |
|				dsmSendData                                                                 |
|			}                                                                            |
|			dsmEndSendObj                                                                |
|		}                                                                             |
|	dsmEndTxn                                                                      |
|}                                                                               |
|                                                                                |
|dmBeginTxn                                                                      |
|	dsmGroupHandler(CLOSE)                                                         |
|dsmEndTxn                                                                       |
|                                                                                |
+--------------------------------------------------------------------------------+


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