File grouping

Edit online

The IBM® Storage Protect 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 that all group members and the group leader belong to the same node and file space 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 that 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, the member does 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.

File groups contain backup data only, and cannot contain archive data. Archive objects can use the Archive Description field to facilitate a type of grouping if required by an application.

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

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 committed, or saved, on the server until a close is performed. The dsmGroupHandler is an interface that can accept five different operations. They include:

  • DSM_GROUP_ACTION_OPEN
  • DSM_GROUP_ACTION_CLOSE
  • DSM_GROUP_ACTION_ADD
  • DSM_GROUP_ACTION_ASSIGNTO
  • DSM_GROUP_ACTION_REMOVE
Table 1 lists the dsmGroupHandler function call actions:
Table 1. dsmGroupHanlder functions
Action Description
OPEN The OPEN action creates a group. The next object that is sent becomes the group leader. The group leader cannot have content. 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 The CLOSE action 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. The application must check for open groups and, if necessary, close or delete the groups. A group is not committed or saved until the group is closed. A CLOSE action fails in the following conditions:
  • The group that you are trying to close has the same name as an existing open group.
  • A management class incompatibility exists between the current closed group and the new group to be closed of the same name. In this case, complete the following steps:
    1. Query the previous closed group.
    2. If the management class of the existing closed group is different from the management class associated with the current open group, issue a dsmUpdateObject with type DSM_BACKUPD_MC. This command updates the existing group to the new management class.
    3. Issue the CLOSE action.
ADD The ADD action appends an object to a group. All objects that are sent after the ADD action are assigned to the group.
ASSIGNTO The ASSIGNTO action permits the client to assign objects that exist on the server to the declared peer group. This transaction sets up the PEER group relationship. The ASSIGNTO action is similar to the ADD action, with the following exceptions:
  • The ADD action applies to objects within an in-flight transaction.
  • The ASSIGNTO action applies to an object that is on the server.
REMOVE The REMOVE action 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 the member can be deleted.

Use the following query types for group support:

  • qtBackupGroups
  • qtOpenGroups
The qtBackupGroups queries groups that are closed while qtOpenGroups queries 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 2. 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 specified group leader (grpLdrObjId).
grpLdrObjId.hi grpLdrObjId.lo objType Returns a list by using BackQryRespEnhanced3, for each group member that is assigned to the specified group leader (grpLdrObjId), and matching the object type (objType).

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

  • isGroupLeader
  • isOpenGroup
These fields are Boolean flags. The following example displays the creation of the group, adding members to the group, and closing the group to commit the group on the IBM Storage Protect server.
Figure 1. Example of pseudo-code that is used to create a group
dsmBeginTxn
	dsmGroupHandler (PEER, OPEN, leader, uniqueId) 
	dsmBeginSendObj
		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

For a code example, see the sample group program dsmgrp.c that is included in the API sampsrc directory.