Required Input Parameters

· A private object

· A set of exclusions

· A set of OM attributes to be included in the copy

· A flag to indicate whether local string processing is required

· The position of the first value to be copied (the base value)

· The position within each OM attribute that is one beyond the last attribute to be included in the copy (indicating the scope of the copy)

The om_get( ) call returns the following output parameters:

· The public object that is a copy of the private object

· The number of OM attribute descriptors returned in the public object

In the code fragment from example.h, the private object result is input to om_get( ).

The next parameter, the exclusions parameter, reduces the copy to a prescribed portion of the original. The exclusions apply to the OM attributes of the object, but not to those of subobjects. The possibilities for determining the combinations of types, values, subobjects, and descriptors to be excluded depend on the creativity of the programmer. For a detailed description of all the exclusion possibilities, refer to the OSF DCE Application Development Reference. The values chosen for the om_get( ) calls in example.h are simplified for clarity. These exclusion values are as follows:

· OM_EXCLUDE_ALL_BUT_THESE_TYPES

· OM_EXCLUDE_SUBOBJECTS

Each value indicates an exclusion, as defined by om_get( ), and is chosen from the set of exclusions; alternatively, the single value OM_NO_EXCLUSIONS may be chosen, which selects the entire object. Each value, except OM_NO_EXCLUSIONS, is represented by a distinct bit, the presence of the value being represented as 1, and its absence as 0 (zero). Multiple exclusions are requested by adding or ORing the values that indicate the individual exclusions.

OM_EXCLUDE_ALL_THESE_TYPES indicates that the OM attributes included are only the ones defined in the list of included types supplied in the next parameter, entry_list. OM_EXCLUDE_SUBOBJECTS indicates that for each value whose syntax is OM_S_OBJECT, a descriptor containing an object handle for the original private subobject is returned, rather than a public copy of it. This handle makes that subobject accessible for use in subsequent function calls. This exclusion provides a means to examine an object one level at a time. The object the handle points to is used in the next om_get( ) call to get the next level.

The entry_list parameter is declared in example.h as data type OM_type and initialized as a two-cell array with values DS_ENTRY and a NULL terminator. DS_ENTRY specifies the single OM attribute type included for that om_get(~) call. This call only limits processing to the one directory entry; only one entry was defined previously in the program, the distinguished name of Peter Piper. The 0 (zero) marks the end of the OM attribute list.

The next parameter, OM_FALSE, indicates that mapping to a local string format is not required. The next two parameters set the initial and limiting value to 0 (zero), meaning that no specific values are to be excluded.

The final two parameters are output parameters: entry, a pointer to a service-generated public object deposited by om_get( ) in the workspace, and total_num, an integer. Both entry and total_num are available for examination by the application program.