![]() |
![]() |
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:
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:
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 | | | +--------------------------------------------------------------------------------+