om_remove(3xom) — Subroutines

Name

om_remove − Removes and discards specified values of an attribute of a private object.

Syntax

OM_return_code om_remove(subject, type, initial_value, limiting_value)

subject@OM_private_object@T{ read T} type@OM_type@T{ read T} initial_value@OM_value_position@T{ read T} limiting_value@OM_value_position@T{ read T} return_code@T{ OM_return_code T}

C Binding

OM_return_code om_remove(subject, type, initial_value, limiting_value)

OM_private_object subject,

OM_type type,

OM_value_position initial_value,

OM_value_position limiting_value

Arguments

Subject

The private object from which you want to remove attribute values. The function does not affect the class of the subject.

Type

The type of the attribute from which you want to remove values. The type must not be OM_CLASS.

Initial Value

The position within the attribute of the first value to be removed.

If the value of Initial Value is OM_ALL_VALUES, or if it exceeds the number of values present in the attribute, the Service takes this argument to be equal to the number of values present in the attribute.

Limiting Value

The position within the attribute one beyond that of the last value to be removed. If this argument is less than the Initial Value argument, no values are removed.

If the value of Limiting Value is OM_ALL_VALUES, or if the value exceeds the number of values present in an attribute, the Service takes this argument to be equal to the number of values present in the attribute.

Description

This function removes and discards particular values of an attribute of a private object, the subject. If no values remain in an attribute after removal of the values you specify, the Service removes the attribute. If one of the values you specify is a subobject, the Service removes that value, and then applies om_delete to make the subobject inaccessible.

Return Values

The function has completed its task successfully T} OM_FUNCTION_DECLINED@T{ The function does not apply to the object to which it is addressed T} OM_FUNCTION_INTERRUPTED@T{ The function was aborted by external intervention T} OM_MEMORY_INSUFFICIENT@T{ There is not enough memory to complete the function T} OM_NETWORK_ERROR@T{ The Service cannot use the underlying network T} OM_NO_SUCH_OBJECT@T{ You have specified a nonexistent object, or an invalid Handle for an object T} OM_NO_SUCH_TYPE@T{ There is an undefined type identifier T} OM_NOT_PRIVATE@T{ There is a public object where there should be a private object T} OM_PERMANENT_ERROR@T{ The Service encountered a permanent problem for which there is no defined error code T} OM_POINTER_INVALID@T{ An invalid pointer was supplied as a function argument T} OM_SYSTEM_ERROR@T{ The Service cannot use the operating system T} OM_TEMPORARY_ERROR@T{ The Service encountered a temporary problem for which there is no defined error code T}

Examples

The first example shows a single value being removed from a private object of MH class Message (message). MH_T_LATEST_DELIVERY_TIME is the attribute type whose value is removed. This attribute has one value. The function therefore removes the value and deletes the attribute.

The second example shows a range of values being removed from a private object of the X.500 class Entry-Information-Selection (select_info). DS_ATTRIBUTES_SELECTED is the attribute type whose values are removed. If this attribute has five values (positions 0 to 4), then this function removes the second, third and fourth values.

Exhibit 0-0.

OM_private_object    message;

OM_return_code       result;

     result = om_remove (message,
                             /∗ object from which to remove value ∗/
                         MH_T_LATEST_DELIVERY_TIME,
                             /∗ attribute to remove ∗/
                         0,1));
                             /∗ position of single value to remove ∗/