om_put(3xom) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
om_put − Places copies of the attribute values of a private or public object into a private object.
Syntax
OM_return_code om_put(destination, modification, source, included_types, initial_value, limiting_value)
| Argument | Data Type | Access |
| destination | OM_private_object | read |
| modification | OM_modification | read |
| source | OM_object | read |
| included_types | OM_type_list | read |
| initial_value | OM_value_position | read |
| limiting_value | OM_value_position | read |
| return_code | OM_return_code |
C Binding
OM_return_code om_put (destination, modification, source, included_types, initial_value, limiting_value)
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
Arguments
DestinationThe object into which you want to put attribute values. This function does not affect the class of the destination.
ModificationA list of modifications to the attributes selected for copying. The modifications you request determine how the function modifies the destination object with the attributes, that is, where it puts them.
The Modification argument can have one of the following values:
OM_INSERT_AT_BEGINNING
The Service inserts the source values before all existing destination values. This does not affect the existing destination values.
OM_INSERT_AT_CERTAIN_POINT
The Service inserts the source values before the value at a specified position in the destination attribute. This does not affect the existing destination values.
OM_INSERT_AT_END
The Service inserts the source values after all existing destination values. This does not affect the existing destination values.
OM_REPLACE_ALL
The Service replaces any destination values with the source values, and discards the original destination values.
OM_REPLACE_CERTAIN_VALUES
The Service replaces the values at specified positions in the destination attribute with values from the source. The Service discards the original destination attribute values at those positions.
SourceThe object from which you want to copy attribute values. This function ignores the class of the source.
Included TypesThe types of attributes that should be copied to the destination, if they appear in the source. If you do not specify a value for this argument, the Service copies all attributes from the source to the destination.
Initial ValueYou need to pass a value for this argument when you select the OM_INSERT_AT_CERTAIN_POINT modification or the OM_REPLACE_CERTAIN_VALUES modification. The following table shows what the Initial Value argument represents in each of these cases.
insert-at-certain-points
The position within each destination attribute at which the Service should insert source values
replace-certain-values
The first value that the Service should replace
If you give this argument a value that is greater than the number of values present in a destination attribute, or if you use the value OM_ALL_VALUES, the Service takes Initial Value to be equal to the number of values present in the destination attribute.
Limiting ValueYou need to pass a value for this argument when you select the OM_REPLACE_CERTAIN_VALUES modification. The argument specifies the position within each destination attribute that is one beyond that of the last value to be replaced. The value of Limiting Value must be greater than that of Initial Value.
If you give this argument a value that is greater than the number of values present in a destination attribute, or if you use the value OM_ALL_VALUES, the Service takes Limiting Value to be equal to the number of values present in the destination attribute.
Description
This function places in one private object, the destination, copies of the attribute values of another object, the source. The source can be a public or private object.
You must specify that the Service does one of the following:
Replace all the values in the destination with values from the source.
Replace specified values in the destination with values from the source.
Insert values from the source in a particular position in the destination.
Only use om_put to copy attributes from the source that occur in the definition of the class to which the destination belongs.
The Service first converts all string values that are in the local representation into the non-local representation for that syntax.
There is no attribute of type C in the source object. The destination object therefore contains no attributes of this type, even though type C is specified in the Included Types argument.
The destination object contains an attribute, D, which is not affected by om_put.
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_CLASS | There is an undefined class identifier |
| OM_NO_SUCH_MODIFICATION | There is an undefined modification identifier |
| OM_NO_SUCH_OBJECT | You have specified a nonexistent object, or an invalid Handle for an object |
| OM_NO_SUCH_SYNTAX | There is an undefined syntax identifier |
| OM_NO_SUCH_TYPE | There is an undefined type identifier |
| OM_NOT_CONCRETE | There is an abstract class where there should be a concrete class |
| OM_NOT_PRESENT | An expected attribute value is missing |
| 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 |
| OM_TOO_MANY_VALUES | An implementation limit prevents the addition to an object of another attribute value |
| OM_VALUES_NOT_ADJACENT | The descriptors for the values of a particular attribute are not adjacent |
| OM_WRONG_VALUE_LENGTH | There is an attribute with a value that violates the value length constraints in force |
| OM_WRONG_VALUE_MAKEUP | There is an attribute with a value that violates a constraint of its syntax |
| OM_WRONG_VALUE_NUMBER | There is an attribute with a value that violates the value number constraints in force |
| OM_WRONG_VALUE_POSITION | The position specified for an attribute value is invalid |
| OM_WRONG_VALUE_SYNTAX | There is an attribute value with an illegal syntax |
| OM_WRONG_VALUE_TYPE | There is an attribute value with an illegal type |
Examples
The following example shows how to create an object of the X.400 class Submitted Message and then add to this private object using om_put.
result = om_create ( MH_C_SUBMITTED_MESSAGE,
OM_TRUE,
workspace,
&submitted_message);
OMX_CLASS_DESC (attribute_list[0], MH_C_SUBMITTED_MESSAGE);
OMX_ENUM_DESC (attribute_list[1], MH_T_PRIORITY, priority);
OMX_INTEGER_DESC (attribute_list[2], MH_T_CONTENT_TYPE, MH_CTI_P2_1988);
OMX_BOOLEAN_DESC (attribute_list[3], MH_T_DISCLOSURE_ALLOWED, OM_TRUE);
OMX_OM_NULL_DESC (attribute_list[4]);
result = om_put ( submitted_message,
OM_REPLACE_ALL,
attribute_list,
NULL,
0,
0 );