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)

Argument	Data Type	Access
subject	OM_private_object	read
type	OM_type	read
initial_value	OM_value_position	read
limiting_value	OM_value_position	read
return_code	OM_return_code

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

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

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

Initial ValueThe 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 ValueThe 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

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

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.

OM_private_object    message;
OM_return_code       result;

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

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.

OM_private_object    select_info;
OM_return_code       result;

result = om_remove (select_info,            /∗ obj from which to rem val ∗/
                    DS_ATTRIBUTES_SELECTED, /∗ attribute to remove ∗/
                    1,4));                  /∗ range of values to remove ∗/

Museum