View source for Mustering DCE Registry Objects with the Managed Object Class Library

''by [[Theodore Shrader]] and [[Gregg Wilson]]''

The version of Distributed Computing Environment (DCE) included in the IBM Directory and Security Server (DSS) for OS/2 Warp provides a mature and robust foundation for distributed systems. It supports many of the requirements of distributed applications, including security, Remote Procedure Call (RPC), time, and directory services. Yet given its vast capability, developers must choose from a myriad of APIs, data structures, and approaches to fulfill their tasks.

Fortunately, this latest release of DCE from IBM also provides the Managed Object Class Library (MOCL), which sits on top of DCE. This object-oriented framework hides much of the complexity in DCE, yet exploits its richness by providing a consistent and extensible interface to DCE's administrative and management capabilities.

Note: This article and accompanying sample code are based on the pre-release version of MOCL. The interface may be enhanced in the final release. DSS is one of the IBM Software Servers described in "[[Go Cross Platform With the Developer Connection]]", on page 1.

MOCL was implemented in the System Object Model (SOM) and C++. Its classes can generally be divided into functional categories:
* The DCE (or instance) object category provides managed object wrappers around such DCE objects as accounts and servers.
* Instance manager classes make up the instance manager category ,and they supervise the creation and retrieval of the instance objects.
For example, developers could use the DCE_AccountIM instance manager object to perform such tasks as creating DCE_Account objects and retrieving a list of all the account objects in the DCE security registry database. Whereas you can create many instance objects, such as DCE_Accounts, MOCL will only allow one instance manager per type or per DCE cell, depending on the kind of the instance manager, for each object instance class type. This uniqueness guarantees a consistent instance management object on which to perform management tasks.

Other MOCL objects exist such as the Base_Library, which you can use to gain access to instance managers and thus the object instances that they supervise.

==Focus on Registry Objects==
One of MOCL's main strengths lies in its ability to shield the developer from needing to know the various DCE APIs and data structures required for different tasks, such as querying or defining properties. This is especially true with the DCE registry objects, namely principals, groups, organizations, and accounts. Principals are objects that can be members of one or more groups and one or more organizations. Administrators can create accounts by assigning a principal to a primary group and organization, as well as providing a password and additional account-specific properties to the newly created account.

[[Image:MusteringDCE-Fig-1.gif]]

MOCL defines classes for three of the registry objects - groups, organizations (which MOCL has renamed to Policy Groups), and accounts - but it does not provide a separate class for principals. Because principals are so closely tied to accounts in DCE, and this tends to be a source of confusion for most developers, MOCL marries the two into the DCE_Account class. A DCE_Account object can be inactive (which means that it only exists as a principal in the DCE security registry database) or active (which means that both the principal and account for the DCE_Account object reside on the DCE security registry database). Active DCE_Account objects can also be in the states of enabled or disabled for network login.

This design provides a distinct advantage because you don't need to keep track of two separate DCE entities. You can just use the DCE_Account object and MOCL will make the distinction as to whether it physically exists as a principal or both a principal and an account in the DCE security registry database, and perform actions accordingly.

MOCL implements groups in the DCE_Group class and organizations in the DCE_PolicyGroup class. Their corresponding instance manager classes are DCE_GroupIM and DCE_PolicyGroupIM.

==Different Types of Registry Properties==
The Open Systems Foundation (OSF) DCE 1.1 release allows administrators and developers to define extended registry attributes (ERA). These attributes are properties that are in addition to the fixed attributes already predefined for OSF registry objects, such as account lifetime (acctlife) for accounts. Pre-DCE 1.1 releases did not allow administrators to add to the set of fixed properties. With the inclusion of ERAs, the pool of properties that administrators can define, store values in, and control access to has greatly expanded.

However, to support ERAs, DCE had to augment its set of APIs with a new set prefixed with sec_rgy_attr*. (Fixed registry properties can be accessed and defined with sec_rgy_* calls.) This places a burden on the developer. Depending on the property type, the DCE application will need to call a different API with different parameters and data structures. MOCL lifts this burden by shielding you from needing to know if a property is fixed or an ERA. MOCL accomplishes this through its object-oriented architecture and its implementation of standards, such as the Object Management Group's (OMG) Property Service specification.

You can use the Properties interface to dynamically store a list of properties that need to be defined or queried from a registry object. The Properties interface was specified by OMG and implemented in MOCL. By using it, you can quickly create lists of properties without needing to distinguish whether the property is fixed or an ERA. After the list is constructed, you can call the define_properties or get_properties method on a DCE_Account object to set or retrieve properties, for example.

Best of all, the paradigm doesn't shift between MOCL objects. If you needed to define a set of properties for a DCE server object, such as DCE_dtsd, you would just need to construct your sequence of properties and invoke the define_properties method on the server object. 

==MOCL in Action==
The GENERALS.CPP program illustrates the advantages of using MOCL, especially in dealing with the two different types of properties on registry objects. The program demonstrates how DCE Registry ERAs can be created and properties set and retrieved from registry objects. The full listing of the program is available on the DevCon for OS/2 CD-ROM. It can be found in the Developer Connection for OS/2 catalog, in the category "Source Code from The Developer Connection News," or on disc 1 in the \source\devnews\vol10\dcereg directory.

The program starts by getting a handle to the MOCL library object with the MOCL_getLibrary call. Before creating the account object, the program needs to get a handle to a cell object and the default policy region. It also needs to create the account instance manager. These three objects are all MOCL objects.

The program creates the cell object using a proxy method that does not require the cell instance manager. Because the DCE cell already exists, the MOCL DCE_Cell instance manager was not needed to create one. This cell object will be used to provide the location during the creation of the schema entry and account objects later in the program. (Note: the cell was specified as "/.:" for the local cell, but the program could be expanded to support other named cells. MOCL will normalize the cell name if needed.)

The following is an example of creating a DCE_Cell proxy object:
 pcell = new DCE_Domain_DCE_Cell(ev, pszcellname, pszcellname);
After creating the cell proxy object, the program retrieves a handle to the default policy region object from the MOCL library object. The default policy region object was automatically created by MOCL when the program called the MOCL_getLibrary function. Policy regions can be used to define validation behavior for attributes on the MOCL registry objects. Because our program does not need special validation routines, we can just use the default policy region.

If our program needed to create a new policy region, we would also need to get a handle to the policy region instance manager. Only one policy region instance manager and default policy region can exist per process, but client programs, like this one, can create additional policy region objects. Like the cell object, the policy region object will be used during account creation.

The following is an example of getting the default policy region:
 pdefaultpr = (Base_PolicyRegions_Base_PolicyRegion *)
 
 ((void *)(bl->get_default_policy_region(ev)));
To create the ERA, the program first creates the registry schema instance manager. Client applications can have more than one registry schema instance manager, but only one per cell. To indicate that the registry schema instance manager should be created against the local cell, its LabelidProperty is set to the normalized cell name retrieved from the cell object created earlier. (Note that the label ID could have been set to "/.:" and MOCL would automatically normalize the cell name when it creates the registry schema instance manager.):
 my_nvp->name = LabelidProperty;
 
 my_nvp->value._type = TC_string;
 
 my_nvp->value._value = psznormalizedcellname;
Before the program creates the army command (armycommand) schema entry, it first tries to find it by sending the lookup_object method against the registry schema instance manager. If it can't find the schema entry, the program infers that it hasn't yet been defined in the security registry database, and the program creates it:
 psch = (DCE_SecurityRegistry_DCE_RegistrySchemaEntry*)
 
 ((void *)(pschim->create_object(ev, NULL, &my_criteria)));
If everything is successful thus far, the program creates the account instance manager. Like the registry schema instance manager, client applications can have more than one account instance manager, but only one per cell. The account instance manager will be used to create account objects.

With all the preparation objects now created, the program can now create two accounts, one for Ulysses S. Grant (grant) and Robert E. Lee (lee), if they do not already exist. The program creates the objects by calling the create_object method against the account instance manager. The program next defines values for two attributes on the accounts. The first is a fixed account attribute, DescriptionProperty, and the second is the ERA defined earlier, armycommand. Note how the program does not make any distinction between the two attribute types:
<code>
 property.property_name = DescriptionProperty;
 property.property_value._type = TC_string;
 property.property_value._value = pszacctpropername;
 sequence_add(&properties, Property, property, 1);
 property.property_name = ARMY_COMMAND_ERA;
 property.property_value._type = TC_string;
 property.property_value._value = pszeradescription;
 sequence_add(&properties, Property, property, 1);
 pacct->define_properties(ev, &properties);
</code>
Lastly, these two properties and the FullNameProperty are queried from the accounts and displayed. Again, the program does not make a distinction between the two attribute types in its call to get_properties on the account objects:
 sequence_add(&names, PropertyName, DescriptionProperty, 1);
 sequence_add(&names, PropertyName, FullNameProperty, 1);
 sequence_add(&names, PropertyName, ARMY_COMMAND_ERA, 1);
 pacct->get_properties(ev, 2, &names, &properties, &propiterator);

==Conclusion==
Not only does MOCL provide an object-oriented framework for DCE registry objects, but the same architecture and methods are available on other DCE MOCL objects, such as DCE servers or cells. MOCL frees you from needing to know the underlying implementation of DCE, and instead allows you to concentrate on solving your distributed application requirements. You can use MOCL as one of your trusted commanders for your distributed development campaigns.

{{IBM-Reprint}}
[[Category:Developer Connection News Volume 10]]