Solstice Enterprise Manager 4.1 Developing C++ Applications | ![]() ![]() ![]() ![]() ![]() |
Performing Management Operations on Object Collections
An object collection is a group of managed objects that your application can treat as a single entity. An object collection simplifies bulk operations by enabling you to select multiple managed objects to be the subject of a management operation. Any management operation that your application performs on an object collection is performed on every managed object in the object collection.
This chapter explains how to perform management operations on object collections.
- Section 6.1 Grouping Managed Objects
- Section 6.2 Creating a Container for an Object Collection
- Section 6.3 Defining the Membership of an Object Collection
- Section 6.4 Tracking Changes to an Object Collection
- Section 6.5 Accessing All Objects in an Object Collection
- Section 6.6 Accessing Individual Objects in an Object Collection
- Section 6.7 Obtaining All Object Collections for an Object
6.1 Grouping Managed Objects
You are free to choose the managed objects you group into an object collection. However, to ensure that an object collection you create is useful, group objects that are related in a way that is meaningful to your application.
Identify which managed objects are suitable for grouping into an object collection by:
- Considering the management operations your application will perform
- Analyzing your object model to find out which objects you want to perform the same management operation on simultaneously
- Identifying the management operations you want to perform on any object collections you create
For example, to lock all unlocked channels from a satellite, create an object collection that consists of all instances of the channel managed object class with the administrativeState attribute set to unlocked that are contained in a particular instance of satellite. After you have created the object collection, set the administrativeState attribute of all satellites in the object collection to locked.
Note Solstice EM allows you to define a managed object to be a member of any number of object collections.
6.2 Creating a Container for an Object Collection
To group objects into an object collection, an application must create a container for the object collection. To create a container for an object collection, create and initialize an instance of the Album class. An instance of the Album class is a container for the managed objects in an object collection. It also provides functions for performing management operations on an object collection.
Solstice EM allows a managed object to be a member of any number of object collections.
Each managed object in an object collection is represented by an instance of the Image class. For more information on the Image class, refer to Chapter 5.
When you call the constructor of the Album class, you must specify a nickname for the Album instance. The nickname uniquely identifies the Album instance. It must be a text string. Spaces are permitted in a nickname.
Code for creating and initializing an instance of the Album class is shown in CODE EXAMPLE 6-1.
CODE EXAMPLE 6-1 Creating and Initializing an Album Instance
... #include <pmi/hi.hh> // High Level PMI ... satellites = Album("collection of all satellites"); ...In this example, an Album instance is created and initialized with the nickname collection of all satellites.
6.3 Defining the Membership of an Object Collection
Defining the membership of an object collection selects managed objects to be grouped into the object collection. Depending where the managed objects are located in the management information tree (MIT), you can define the membership of an object collection by:
- Derivation to select managed objects in a subtree of the MIT
- Enumeration to select individual managed objects or object collections
If you want an object collection to contain a subtree of the MIT and individual objects or object collections, define the membership of the object collection by using a combination of derivation and enumeration.
6.3.1 Defining the Membership by Derivation
If the managed objects in your object collection are in a subtree of the MIT, define the membership of the object collection by derivation.
Defining the membership of an object collection by derivation involves:
- Setting a derivation string
- Starting the derivation
6.3.1.1 Setting a Derivation String
A derivation string selects one or more managed objects in a subtree of the MIT by specifying a base managed object, a scope, and a filter. To set a derivation string, call the set_derivation function of the Album class.
In the call to set_derivation you have to specify the derivation string. For details of the format of a derivation string, refer to Section 6.3.2 Format of a Derivation String.
Calling the set_derivation function does not cause your application to communicate with the MIS. Consequently, the set_derivation returns immediately after it is called, provided no errors occur.
Code for setting a derivation string is shown in CODE EXAMPLE 6-2.
In this example, a derivation string is set up to select all instances of the satellite managed object class that are one level below the system object in the MIT. The system object is identified by the value of the server variable.
To enable the server variable for the host name to be included, the derivation string is constructed using a Rogue Wave RWCString object in this example. The server variable has already been initialized to a text string that contains the host name of the machine on which the MIS is running. The initialization of the server variable is not shown in this example.
6.3.1.2 Starting the Derivation
When you have set the derivation sting, start the derivation to define the membership of the object collection. To start the derivation, call the derive function of the Album class.
Calling the derive function causes your application to retrieve information from the MIS. If a large number of managed objects is selected by the derivation string, your application will become blocked for a long time while it waits for derive to return. If you want your application to continue with other processing during a lengthy derivation, start the derivation asynchronously as described in Chapter 8.
Code for starting a derivation is shown in CODE EXAMPLE 6-3.
CODE EXAMPLE 6-3 Starting a Derivation
... #include <pmi/hi.hh> // High Level PMI ... if (!satellites.derive()) { cout << "Derive failed." << endl; cout << satellites.get_error_string() << endl; return; } ...6.3.2 Format of a Derivation String
A derivation string selects one or more managed objects in a subtree of the MIT by specifying a base managed object, a scope, and a filter. The format of a derivation string is as follows:
baseMO/scope/filter
- baseMO is the base managed object.
- scope is the scope.
- filter is the filter.
A forward slash(/) separates the base managed object from the scope, and the scope from the filter.
6.3.2.1 Base Managed Object
The base managed object is the root object of the subtree you want to select. Depending on the scope and the filter, the base managed object may not be one of the managed objects selected by the derivation string.
The base managed object is identified by one of the following:
- Its fully distinguished name (FDN). The first character in an FDN must be a forward slash.
- Its local distinguished name (LDN). The first character in an LDN may be any character except the forward slash.
The base managed object is optional. If you omit it, the system object is assumed. If you omit the base managed object, also omit the slash required to separate the base managed object from the scope.
6.3.2.2 Scope
The scope selects one or more managed objects in the subtree rooted at the base managed object. The scope is defined with reference to the base managed object. Set the scope in a derivation string to one of the values given in TABLE 6-1.
TABLE 6-1 Scope Values in a Derivation String ALL The base managed object and its entire subtree. LV(n) Only level n subordinates of the base managed object, where n is an integer. TO(n) The base managed object and all its subordinates to level n, where n is an integer. * Only first-level subordinates of the base managed object. Equivalent to LV(1). */* Only second-level subordinates of the base managed object. Equivalent to LV(2). */*/* Only third-level subordinates of the base managed object. Equivalent to LV(3).
The scope is optional. If you omit the scope, only the base managed object is selected.
If the subtree contains a large number of managed objects, setting the scope to ALL could cause your application to be timed out while it retrieves information from the MIS during a derivation. If possible, select fewer managed objects by changing the scope or by specifying a filter to prevent your application from being timed out.
The effects of these scope values are illustrated in FIGURE 6- 1. In FIGURE 6- 1, selected objects are shaded.
![]()
FIGURE 6-1 Scope Values6.3.2.3 Filter
The filter selects or rejects objects based on the presence and values of specific attributes. The filter is a boolean expression, which may be a single test or a combination of multiple tests.
The filter is optional. If you omit it, all managed objects identified by the base managed object and scope are selected. If you omit the filter, also omit the slash required to separate the scope from the filter.
When a scope and a filter are combined, the scope is applied first, then the filter. An example of combining a scope and a filter is shown in FIGURE 6- 2. In FIGURE 6- 2, selected objects are shaded.
![]()
FIGURE 6-2 Combination of a Scope and a FilterA filter contains an optional filter operator and one or more filter items. A filter item can in turn be a filter.
The format of a filter in a derivation string is as follows:
CMISFilter([filterOperator:] {filterItemList})
- filterOperator is the filter operator. filterOperator is followed by a colon (:).
- filterItemList is a list of filter items. filterItemList is enclosed in braces. Each filter item in the list is separated by a comma.
The filter operator and the list of filter items are enclosed in parentheses.
Note This format is the ASN.1 type CMISFilter that is defined in the ASN.1 module for ITU-T X.711/ISO-9596-1 Common Management Information Protocol Specification (/opt/SUNWconn/em/etc/asn1/x711.asn1).
Filter Operator
The filter operator is a logical operator for grouping elements in a filter that contains multiple filter items. Set the filter operator to one of the keywords given in TABLE 6-2 .
TABLE 6-2 Filter Operator Keywords and Apply boolean and to the filter items that follow it. or Apply boolean or to the filter items that follow it. not Apply boolean not to the filter items that follow it. It can be applied only to one filter item.
The filter operator is optional. If you omit it, only one filter item is allowed in the filter. If you omit the filter operator, also omit the colon that follows it.
Filter Item
A filter item is a single test within a filter. The syntax of a filter item depends on whether you want to filter on substrings.
The syntax of a filter item without substrings is as follows:
item:comparison:{attributeId[,value]}
- comparison is the comparison made when the filter is applied. Set it to one of the keywords given in TABLE 6-3 . comparison is followed by a colon (:).
- attributeId is the attribute identifier of the attribute to be tested when the filter is evaluated.
- value is the value against which the attribute specified in attributeId is tested when the filter is evaluated. It is not required when comparison is present. If you specify a value, it must be separated from attributeId by a comma (,).
The attribute identifier and the value are enclosed in braces.
TABLE 6-3 Comparison Keywords in a Filter Without Substrings equality The managed object contains an attribute of type attributeId that has a value equal to value. greaterOrEqual value is greater than or equal to the value of an attribute of type attributeId that the managed object contains. lessOrEqual value is less than or equal to the value of an attribute of type attributeId that the managed object contains. present The managed object contains an attribute of type attributeId. subsetOf value is a subset of a set-valued attribute of type attributeId that the managed object contains. supersetOf value is a superset of a set-valued attribute of type attributeId that the managed object contains. nonNullSetIntersection The managed object contains a set-valued attribute of type attributeId and the intersection of its value and value is not empty.
The syntax of a filter item that includes substrings is as follows:
item:substrings:{substringItemList}Where substringItemList is a list of substring items. substringItemList is enclosed in braces. Each substring item in the list is separated by a comma.
The syntax of a substring item is as follows:
part:{attributeId,value}
- part is the part of the attribute value that must match the value specified in the filter. Set it to one of the keywords given in TABLE 6-4 . part is followed by a colon (:).
- attributeId is the attribute identifier of the attribute to be tested when the filter is evaluated.
- value is the value against which the attribute specified in attributeId is tested when the filter is evaluated.
The attribute identifier and the value are separated by a comma and enclosed in braces.
TABLE 6-4 Part Keywords in a Substring initialString The managed object contains an attribute of type attributeId the start of the value of which matches the string specified in value. anyString The managed object contains an attribute of type attributeId any part of the value of which matches the string specified in value. finalString The managed object contains an attribute of type attributeId the end of the value of which matches the string specified in value.
6.3.2.4 Example Derivation Strings
CODE EXAMPLE 6-4 shows the derivation string for selecting all log objects.
CODE EXAMPLE 6-4 Selecting All log Objects
LV(1)/CMISFilter(item: equality: {objectClass, log})The object model defines that instances of log are contained in the system object. Therefore, the base managed object is not specified in this example because it is the system object, which is the default.
CODE EXAMPLE 6-5 shows the derivation string for selecting all enabled log objects.
CODE EXAMPLE 6-5 Selecting All Enabled Instances of log
LV(1)/CMISFilter( and: { item: equality: {objectClass, log}, item: equality: {operationalState, enabled} } )In this example, two filter items are combined using the and filter operator. The first filter item selects all log objects. The second filter item tests the value of the operationalState attribute to select only log objects that are enabled.
CODE EXAMPLE 6-6 shows the derivation string for selecting all objects that are not instances of the log class.
CODE EXAMPLE 6-6 Selecting all Objects That are not Instances of log
ALL/CMISFilter(not:{item:equality:{objectClass,log}})The derivation strings shown in CODE EXAMPLE 6-7 are all equivalent.
CODE EXAMPLE 6-7 Equivalent Derivation Strings
/systemId="mako"/LV(1)/CMISFilter(item:equality:{objectC lass,log}) LV(1)/CMISFilter(item:equality:{objectClass,log}) */CMISFilter(item:equality:{objectClass,log})In this example, each of the derivation strings selects all log objects that are one level below the system object in the MIT.
6.3.3 Defining the Membership by Enumeration
If the managed objects in your object collection are distributed throughout the MIT, or if you want to add an existing object collection, define the membership of the object collection by enumeration.
Note If you define the membership of an object collection by enumeration, you have to maintain the membership of the object collection manually. For more information, refer to Section 6.4.1 Maintaining the Membership of an Object Collection.
To define the membership of the object collection by enumeration, call the include function of the Album class. The include function adds a managed object or an object collection to an object collection.
In the call to the include function you have to specify one of the following:
- The Image instance that represents the managed object you want to add
- The Album instance that contains the object collection you want to add
6.4 Tracking Changes to an Object Collection
Tracking changes to an object collection updates an Album instance with changes to the object collection that the instance contains. Tracking changes ensures that:
- Your network management application has access to current data about your managed resources.
- Any network management operations you perform on an object collection are performed on the required group of managed objects.
Tracking changes to an object collection involves:
- Maintaining the membership of an object collection
- Setting the mode of an object collection
6.4.1 Maintaining the Membership of an Object Collection
Maintaining the membership of an object collection ensures that the object collection accurately reflects the current state of your network. In a live network, managed objects are continually created and deleted as managed resources are added to and removed from the network management environment. Attribute values change as a result of activity on the network. All of these changes affect the membership of an object collection.
Depending on your performance requirements, you can maintain the membership of an object collection automatically or manually. Automatically maintaining the membership requires you to write less code but is less efficient than manually tracking changes. Furthermore, when you maintain the membership of an object collection automatically, all historical information on the membership the object collection is lost.
6.4.1.1 Automatically Maintaining the Membership of an Object Collection
Automatically maintaining the membership of an object collection causes the Album instance that contains the object collection to update the object collection by:
- Adding an object that satisfies the selection criteria of the object collection whenever such an object is created
- Removing an object that has been deleted
- Adding or removing an object if changes to its attribute values make it eligible or ineligible to be a member of the object collection
Maintain the membership of an object collection automatically in any of the following circumstances:
- You want to simplify the application development process (for example during the prototype phase).
- The performance of your application is not critical.
- You do not require historical information on the membership the object collection.
Note If you want to maintain the membership of the object collection automatically, you must define the membership of the object collection by derivation. For more information, refer to Section 6.3.1 Defining the Membership by Derivation.
To maintain the membership of an object collection automatically, set the TRACKMODE property of the Album instance to TRACK. To set the TRACKMODE property of an Album instance, call the set_prop function of the Album class before defining the membership of the object collection that the instance contains.
Code for setting the TRACKMODE property to TRACK is shown in CODE EXAMPLE 6-8.
CODE EXAMPLE 6-8 Setting the TACKMODE Property of an Album Instance
... #include <pmi/hi.hh> // High Level PMI ... // Automatically add Image objects to the Album object // based on derivation rules // if (!satellites.set_prop(duTRACKMODE, duTRACK)) { cout << satellites.get_error_string() << endl; return; } ...6.4.1.2 Manually Maintaining the Membership of an Object Collection
Maintain the membership of an object collection manually if you need fast response from your application, or if you need to preserve historical information on the membership the object collection.
Maintaining the membership of an object collection manually involves:
- Setting the TRACKMODE property of the Album instance to SNAP
- Using callback functions to update the membership of the object collection
If you maintain the membership of an object collection manually, you have to write in your callback functions code for adding objects to or removing objects from the object collection. Having to write your own code makes coding your application more complicated. But it gives you control over which changes you update the object collection with, and enhances the performance of your application.
Use the following functions of the Album class in your callbacks to add objects to or remove objects from an object collection:
- include - To add an object or an object collection to an object collection
- exclude - To remove an object or an object collection from an object collection
In the call to the include or exclude function you have to specify one of the following:
- The Image instance that represents the object you want to add or remove
- The Album instance that contains the object collection you want to add or remove
Note Every time you call the derive function you lose all information on the membership of the previous version of the object collection. To avoid losing any historical information, maintain the membership of the object collection by calling only the include and exclude functions.
Code for using callback functions to update the membership of the object collection is shown in CODE EXAMPLE 6-9.
CODE EXAMPLE 6-9 Using Callback Functions With an Object Collection
... #include <pmi/hi.hh> // High Level PMI #include <rw/cstring.h> // Rogue Wave RWCString ... // Register for callbacks when a new Image object is deleted. // if (!satellites.when("OBJECT_DESTROYED", Callback(remove_cb,0))) { cout << satellites.get_error_string() << endl; return; } ... void remove_cb( Ptr, Ptr calldata) { CurrentEvent ce(calldata); ce.do_something(); cout << "*****Removing from the Album "; RWCString event_class(ce.get_objclass().chp()); Image tmpimage(ce.get_objname()); if (event_class.contains("dish")) { cout << "dishes*****" << endl; dishes.exclude(tmpimage); } else if (event_class.contains("channel")) { cout << "channels*****" << endl; channels.exclude(tmpimage); } ... }In this example, the remove_cb callback is called whenever the application receives a notification that a managed object has been deleted. When the remove_cb callback is called, the application extracts from the event information required to determine if the managed object is a member of an object collection maintained by the application. If it is, the exclude function of the Album class is called to remove the object from the object collection.
For more information on how to use callback functions, refer to Section 7.2 Processing Information in Event Notifications.
6.4.2 Setting the Mode of an Object Collection
The mode of an object collection specifies how Image instances are activated and tracked when they are added to an object collection. The mode is one of the following:
- Automatic. When the mode is set to automatic:
- The Image instance that represents the managed object is activated when the object is added to the object collection.
- Changes to the managed object are tracked automatically, even if the properties of Image instance specify manual tracking.
- Manual. When the mode is set to manual:
For more information, refer to Section 5.2.2 Activating the Instance of Image and Section 5.9 Tracking Changes to an Object.
To set the mode of an object collection, set the AUTOIMAGE property of the Album instance as follows:
- YES to set the mode to automatic
- NO to set the mode to manual
To set the AUTOIMAGE property of an Album instance, call the set_prop function of the Album class before defining the membership of the object collection that the instance contains.
Code for setting the mode of an object collection is shown in CODE EXAMPLE 6-10.
CODE EXAMPLE 6-10 Setting the Mode of an Object Collection
... #include <pmi/hi.hh> // High Level PMI ... // By default, an Image object is in the down state and // read only. // Specify automatic activation of new Image objects // which are children of the derivation FDN // if (!satellites.set_prop(duAUTOIMAGE, duYES)) { cout << satellites.get_error_string() << endl; return; } ...In this example, the overloaded NOT (!) operator acts on the call to set_prop to verify that the mode of the object collection was set to automatic. If the mode was not set, an error message explaining the reason for the failure is displayed.
6.5 Accessing All Objects in an Object Collection
Accessing all objects in an object collection enables you to perform the same management operation on several managed objects simultaneously. You access all the objects in an object collection by performing management operations on the object collection. Any management operation performed on an object collection is performed on every managed object in the object collection.
The following management operations are permitted on an object collection:
- Adding all objects in an object collection to the management information server (MIS)
- Deleting all objects in an object collection
- Setting attribute values of all objects in an object collection
- Performing an action on an all objects in an object collection
These management operations are described in detail for individual managed objects in Chapter 5.
When you perform a management operation on an object collection you have to set the synchronization of the object collection. The synchronization specifies how the collection reacts to a management operation that only some objects in the collection are able to perform.
6.5.1 Adding All Objects in an Object Collection to the MIS
Each object in an object collection is represented by an instance of the Image class. An instance of the Image class is a local representation of an object. A local representation is cached within your network management application. The actual object is in the MIS. If the managed objects in a collection do not already exist in the MIS, you can add them to the MIS in a single operation. To add all objects in an object collection to the MIS, call the all_create function of the Album class.
In the call to the all_create function, you can set an optional timeout to specify the maximum length of time allowed for adding an object in the object collection to the MIS. The timer used for this timeout is reset each time an object in the object collection is added to the MIS.
6.5.2 Deleting All Objects in an Object Collection
Deleting all objects in an object collection removes the managed resources represented by the objects in the collection from the network management environment. The conditions under which an object in an object collection is permitted to be deleted are defined in the GDMO specification of the managed object. For more information, refer to Section 5.5 Deleting a Managed Object.
To delete all objects in an object collection, call the all_destroy function of the Album class. The all_destroy function removes all objects in the object collection from the MIS.
In the call to the all_destroy function, you can set an optional timeout to specify the maximum length of time allowed for deleting an object in the object collection. The timer used for this timeout is reset each time an object in the object collection is deleted.
Note The Album instance that contains the object collection remains in existence after all objects in the object collection have been deleted.
6.5.3 Setting Attribute Values of All Objects in an Object Collection
To control the managed resources represented by the objects in an object collection, an application sets attribute values of all objects in the collection. Setting attribute values of all objects in an object collection applies the same control operation to all objects in the collection.
The conditions under which an object attribute is permitted to be set are defined in the GDMO specification of the managed object. For more information, refer to Section 5.7 Setting Attribute Values of an Object.
Setting an attribute value of all objects in an object collection involves:
- Setting an attribute value in the Image instances
- Updating the MIS with the changed values
6.5.3.1 Setting an Attribute Value in the Image Instances
To set an attribute value in the Image instances that represent the objects in an object collection, call one of the functions of the Album class listed in TABLE 6-5 , depending on the data type of the attribute.
TABLE 6-5 Functions for Setting Attribute Values in an Object Collection String all_set_str Integer all_set_long Real all_set_dbl Arbitrarily long integer all_set_gint Any complex ASN.1 type all_set_raw
In the call to a function for setting an attribute value, you have to specify:
- The name of the attribute you want to set (see Section 5.7.1.1 Attribute Name)
- The value you want to set the attribute to (see Section 5.7.1.2 Attribute Value)
- The operation that you want to be carried out to set the attribute (see Section 5.7.1.3 Operation)
6.5.3.2 Updating the MIS With the Changed Values
After you have set the attribute in the Image instances, update the MIS with the changed values to propagate the changes to the managed objects themselves. To update the MIS with the changed values, call the all_store function of the Album class.
6.5.4 Performing an Action on an All Objects in an Object Collection
An action is an operation that cannot be modelled by a pre-defined operation such as getting or setting an attribute. An action enables you to implement specialized behavior, for example, changing attributes of one or many objects in a single operation or providing the results of a query in a particular format.
To send an action request to an object collection, call the all_call function of the Album class.
In the call to all_call, specify:
- The name of the action you want to perform. The action name must be specified exactly as it appears in the GDMO specification of the managed object. Action names are case sensitive.
- The action parameter. The syntax of the action parameter must be as specified exactly in the GDMO specification of the managed object.
- An optional timeout. The timeout specifies the maximum length of time allowed for performing the action on an object in the object collection. The timer used for this timeout is reset each time the action is performed on an object in the object collection.
6.5.5 Setting the Synchronization of an Object Collection
The synchronization of an object collection specifies whether a management operation has to be successful for all the objects in the object collection if it is to be performed. The synchronization is one of the following:
- Best effort. The operation is performed even if it is successful only for some of the objects in the object collection.
- Atomic. The operation is performed only if all objects in the object collection can perform it.
To set the synchronization of an object collection, set the BEST_EFFORT property of the Album instance as follows:
- YES to set the synchronization to best effort
- NO to set the synchronization to atomic
To set the BEST_EFFORT property of an Album instance, call the set_prop function of the Album class before defining the membership of the object collection that the instance contains.
6.6 Accessing Individual Objects in an Object Collection
Access individual objects in an object collection if you want to:
- Perform a management operation on some, but not all, objects in an object collection
- Perform a management operation that must be performed separately on each object in an object collection (for example incrementing the value of the same attribute of all objects in an object collection)
Accessing individual objects in an object collection also provides information on the membership of an object collection.
To access individual objects in an object collection, use the AlbumImage class to retrieve each object from an object collection. An instance of the AlbumImage class represents the current Image instance in a list of Image instances or the current Album instance in a list of Album instances.
Retrieving each object from an object collection involves:
- Creating and initializing an instance of the AlbumImage class
- Calling the first_image function of the Album class to retrieve the first object in the object collection
- Calling the next_image function of the AlbumImage class to retrieve the second and later objects in the object collection
Code for retrieving each object from an object collection is shown in CODE EXAMPLE 6-11.
CODE EXAMPLE 6-11 Retrieving Objects From an Object Collection
... #include <pmi/hi.hh> // High Level PMI ... Album dishes; // Collection of dish objects ... // Get and print each object in the Album object. AlbumImage ali; for (ali = dishes.first_image(); ali; ali = ali.next_image()) { Image im(ali); if (im.get_error_type() != PMI_SUCCESS) { cout << im.get_error_string() << endl; exit(8); } DU objname = im.get_objname(); cout << endl; cout << "Dish Name: "; cout << objname.chp() << endl; } ...In this example, an instance of Image is created for each object in the object collection as follows:
- A for loop is initialized with the first object in an object collection.
- The next_image function of the AlbumImage class is called in the for loop to retrieve the second and later objects in the object collection.
- Each of the AlbumImage instances returned by the first_image and next_image functions is passed in turn to the copy constructor of Image.
The FDN of each Image instance created is obtained by calling the get_objname function of the Image class. Each FDN obtained is printed.
When the final Image instance has been reached, the next_image function returns NULL, thereby terminating the for loop.
6.7 Obtaining All Object Collections for an Object
Obtaining all object collections for an object keeps track of which object collections a managed object is a member of. By keeping track of which object collections a managed object is a member of, you can exclude a managed object from a collection when you no longer want operations on the collection to be applied to the managed object.
Obtaining all object collections for an object involves:
- Creating and initializing an instance of the AlbumImage class
- Calling the first_album function of the Image class to retrieve the first object collection that the object is a member of
- Calling the next_album function of the AlbumImage class to retrieve the second and later object collections that the object is a member of
Code for obtaining all object collections for an object is shown in CODE EXAMPLE 6-12.
CODE EXAMPLE 6-12 Obtaining all Object Collections for an Object
... #include <pmi/hi.hh> // High Level PMI ... Image img (DU(fdn)); // Managed object already exists,so no MOC ... // Get and print each Album instance that contains the object AlbumImage albimg; for (albimg = img.first_album(); albimg; albimg = albimg.next_album()) { Album alb(albimg); if (alb.get_error_type() != PMI_SUCCESS) { cout << alb.get_error_string() << endl; exit(8); } DU albname = alb.get_prop(duNICKNAME); cout << endl; cout << "Album Nickname: "; cout << albname.chp() << endl; } ...In this example, an instance of Album is created for each object collection that the object is a member of as follows:
- A for loop is initialized with the first object collection that the object is a member of.
- The next_image function of the AlbumImage class is called in the for loop to retrieve the second and later object collections that the object is a member of.
- Each of the AlbumImage instances returned by the first_album and next_album functions is passed in turn to the copy constructor of Album.
The nickname of each Album instance created is obtained by calling the get_prop function of the Album class. Each nickname obtained is printed.
When the final Album instance has been reached, the next_album function returns NULL, thereby terminating the for loop.
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |