NAME

SYNOPSIS

#include <xom.h>

OM_return_code om_get(
        OM_private_object original,
        OM_exclusions exclusions,
        OM_type_list included_types,
        OM_boolean local_strings,
        OM_value_position initial_value,
        OM_value_position limiting_value,
        OM_public_object *copy,
        OM_value_position *total_number);

PARAMETERS

Input

original

The original that remains accessible.

exclusions

Explicit requests for zero or more exclusions, each of which reduces the copy to a prescribed portion of the original. The exclusions apply to the attributes of the object, but not to those of its subobjects.

Apart from OM_NO_EXCLUSIONS, each value is chosen from the following list. When multiple exclusions are specified, each is applied in the order in which it is displayed in the list with lower-numbered exclusions having precedence over higher-numbered exclusions. If, after the application of an exclusion, that portion of the object is not returned, no further exclusions need be applied to that portion.

• OM_EXCLUDE_ALL_BUT_THESE_TYPES The copy includes descriptors comprising only attributes of specified types.

  Note that this exclusion provides a means for determining the values of specified attributes, as well as the syntaxes of those values.

• OM_EXCLUDE_MULTIPLES The copy includes a single descriptor for each attribute that has two or more values, rather than one descriptor for each value. None of these descriptors contains an attribute value, and the OM_S_NO_VALUE bit of the syntax component is set.

  If the attribute has values of two or more syntaxes, the descriptor identifies one of those syntaxes; however, the syntax identified is not specified.

  Note that this exclusion provides a means for discerning the presence of multivalued attributes without simultaneously obtaining their values.

• OM_EXCLUDE_ALL_BUT_THESE_VALUES The copy includes descriptors comprising only values at specified positions within an attribute.

  Note that, when this exclusion is used in conjunction with the OM_EXCLUDE_ALL_BUT_THESE_TYPES exclusion, it provides a means for determining the values of a specified attribute, as well as the syntaxes of those values, one or more but not all attributes at a time.

• OM_EXCLUDE_VALUES The copy includes a single descriptor for each attribute value, but the descriptor does not contain the value, and the OM_S_NO_VALUE bit of the syntax component is set.

  Note that this exclusion provides a means for determining an object's composition; that is, the type and syntax of each of its attribute values.

• OM_EXCLUDE_SUBOBJECTS The copy includes, for each value whose syntax is OM_S_OBJECT, a descriptor containing an object handle for the original private subobject, rather than a public copy of it. This handle makes that subobject accessible for use in subsequent function calls.

  Note that this exclusion provides a means for examining an object one ``level'' at a time.

• OM_EXCLUDE_DESCRIPTORS When this exclusion is specified, no descriptors are returned and the copy result is not present. The total_number parameter reflects the number of descriptors that would be returned by applying the other inclusion and exclusion specifications.

  Note that this exclusion provides an attribute analysis capability. For instance, the total number of values in a multivalued attribute can be determined by specifying an inclusion of the specific attribute type, and exclusions of OM_EXCLUDE_DESCRIPTORS, OM_EXCLUDE_SUBOBJECTS, and OM_EXCLUDE_ALL_BUT_THESE_TYPES.

The OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion affects the choice of descriptors, while the OM_EXCLUDE_VALUES exclusion affects the composition of descriptors.

included_types

This parameter is present if and only if the OM_EXCLUDE_ALL_BUT_THESE_TYPES exclusion is requested; it identifies the types of the attributes to be included in the copy (provided that they are displayed in the original).

local_strings

This Boolean parameter indicates whether conversion to local string format should be carried out or not. For further information on local strings please refer to Chapter 10 of the OSF DCE Application Development Guide.

initial_value

This parameter is present if and only if the OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is requested; it specifies the position within each attribute of the first value to be included in the copy.

If it is OM_ALL_VALUES or exceeds the number of values present in an attribute, the parameter is taken to be equal to that number.

limiting_value

This parameter is present if and only if the OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion is requested; it specifies the position within each attribute one beyond that of the last value to be included in the copy. If this parameter is not greater than the initial_value parameter, no values are included (and no descriptors are returned).

If it is OM_ALL_VALUES or exceeds the number of values present in an attribute, the parameter is taken to be equal to that number.

Output

copy

The copy parameter is only present if the return value from OM_return_code is OM_SUCCESS and the OM_EXCLUDE_DESCRIPTORS exclusion is not specified.

The space occupied by the public object and every attribute value that is a string is service provided. If the client alters any part of that space, the effect upon the service's subsequent behavior is unspecified.

total_number

The number of attribute descriptors returned in the public object, but not in any of its subobjects, based on the inclusion and exclusion parameters specified. If the OM_EXCLUDE_DESCRIPTORS exclusion is specified, no copy result is returned and the total_number result reflects the actual number of attribute descriptors that would be returned based on the remaining inclusion and exclusion values.

Note that the total includes only the attribute descriptors in the copy parameter. It excludes the special descriptor signaling the end of a public object.

DESCRIPTION

The om_get() function creates a new public object (the copy) that is an exact, but independent, copy of an existing private object, the original parameter. The client can request certain exclusions, each of which reduces the copy to a part of the original.

One exclusion is always requested implicitly. For each attribute value in the original that is a string whose length exceeds an implementation-defined number, the copy parameter includes a descriptor that omits the elements (but not the length) of the string. The elements component of the string component in the descriptor's value component is OM_ELEMENTS_UNSPECIFIED, and the OM_S_LONG_STRING bit of the syntax component is set to OM_TRUE.

Note that the client can access long values by means of om_read().

RETURN VALUES

OM_return_code

Indicates whether the function succeeded and, if not, why not. If the function is successful, the value of OM_return_code is set to OM_SUCCESS; if the function fails, it has one of the error values listed in this reference page.

The exact constants for OM_return_code are defined in the xom.h header file (see the xom.h(4xom) reference page).

ERRORS

• OM_FUNCTION_INTERRUPTED
• OM_MEMORY_INSUFFICIENT
• OM_NETWORK_ERROR
• OM_NO_SUCH_EXCLUSION
• OM_NO_SUCH_OBJECT
• OM_NO_SUCH_TYPE
• OM_NOT_PRIVATE
• OM_PERMANENT_ERROR
• OM_POINTER_INVALID
• OM_SYSTEM_ERROR
• OM_TEMPORARY_ERROR
• OM_WRONG_VALUE_SYNTAX
• OM_WRONG_VALUE_TYPE