NAME

om_put - Places or replaces in one private object copies of the attribute values of another public or private object

SYNOPSIS

#include <xom.h>

OM_return_code om_put(
        OM_private_object destination,
        OM_modification modification,
        OM_object source,
        OM_type_list included_types,
        OM_value_position initial_value,
        OM_value_position limiting_value);

PARAMETERS

Input

destination
The destination that remains accessible. The destination's class is unaffected.

modification
The nature of the requested modification. The modification determines how om_put() uses the attribute values in the source to modify the object. In all cases, for each attribute present in the source, copies of its values are placed in the object's destination attribute of the same type. The data value is chosen from among the following:

OM_INSERT_AT_BEGINNING The source values are inserted before any existing destination values. (The latter are retained.)

OM_INSERT_AT_CERTAIN_POINT The source values are inserted before the value at a specified position in the destination attribute. (The latter are retained.)

OM_INSERT_AT_END The source values are inserted after any existing destination values. (The latter are retained.)

OM_REPLACE_ALL The source values are placed in the destination attribute. The existing destination values, if any, are discarded.

OM_REPLACE_CERTAIN_VALUES The source values are substituted for the values at specified positions in the destination attribute. (The latter are discarded.)

source
The source that remains accessible. The source's class is ignored. However, the attributes being copied from the source must be compatible with the destination's class definition.

included_types
If present, this parameter identifies the types of the attributes to be included in the destination (provided that they are displayed in the source); otherwise, all attributes are to be included.

initial_value
This parameter is present if and only if the modification parameter is OM_INSERT_AT_CERTAIN_POINT or OM_REPLACE_CERTAIN_VALUES. It specifies the position within each destination attribute at which source values are inserted, or of the first value replaced, respectively.

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

limiting_value
Present if and only if the modification parameter is OM_REPLACE_CERTAIN_VALUES. It specifies the position within each destination attribute one beyond that of the last value replaced. If this parameter is present, it must be greater than the initial_value parameter.

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

DESCRIPTION

The om_put() function places or replaces in one private object (that is, the destination) copies of the attribute values of another public or private object (that is, the source). The client can specify that the source's values replace all or particular values in the destination, or are inserted at a particular position within each attribute. All string values being copied that are in the local representation are first converted into the nonlocal representation for that syntax (which may entail the loss of some information).

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

© 1990-1996, Transarc Corporation