NAME

SYNOPSIS

#include <xom.h>
#include <xomext.h>

OM_return_code omX_extract(
        OM_private_object object,
        OM_type_list navigation_path,
        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 *values,
        OM_value_position *total_number);

PARAMETERS

Input

object

The object from which data is to be extracted.

navigation_path

Contains a NULL-terminated list of OM types that lead to the target object to be extracted. It does not include the OM type of the target object.

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 target 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.

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

values

The values parameter is only present if the return value from OM_return_code is OM_SUCCESS and the OM_EXCLUDE_DESCRIPTORS exclusion is not specified. It contains the array of OM descriptors extracted.

The memory space for values is provided by omX_extract(). It is the responsibility of the calling function to subsequently release this space through a call to om_delete().

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 values 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 values parameter. It excludes the special descriptor signaling the end of a public object.

DESCRIPTION

The omX_extract() function creates a new public object that is an exact, but independent, copy of an existing subobject in a private object. It is similiar to the om_get() function but includes an additional parameter, navigation_path which contains directions to the required object to be extracted. 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 values 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.

The parameters exclusions, included_types, local_strings, initial_value, and limiting_value only apply to the target object being extracted.

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 the xom.h(4xom) reference page.

ERRORS

Refer to xom.h(4xom) for a list of the possible error values that can be returned in OM_return_code.