om_write(3xom) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
om_write − Writes a segment of a string to an attribute in a private object.
Syntax
OM_return_code om_write(subject, type, value_position, syntax, string_offset, elements )
| Argument | Data Type | Access |
| subject | OM_private_object | read |
| type | OM_type | read |
| value_position | OM_value_position | read |
| syntax | OM_syntax | read |
| string_offset | OM_string_length | read-write |
| elements | OM_string | read |
| return_code | OM_return_code |
C Binding
OM_return_code om_write(subject, type, value_position, syntax, string_offset, elements ) OM_private_object subject,
OM_type type,
OM_value_position value_position,
OM_syntax syntax,
OM_string_length ∗string_offset,
OM_string elements
Arguments
SubjectThe object into which you want to write the string segment.
TypeThe type of the attribute to which you want to write the string segment.
Value PositionIn a multi-valued attribute, the position of the value in which you want to place the string. This argument must have a positive value, and it must not exceed the number of values present in the attribute. If it equals the number of values present, the Service inserts the segment at the end of the attribute as a new value.
SyntaxIf you are writing a new value to an attribute, identify in this argument the syntax that you want the new value to have. It must be a permissible syntax for the attribute to which you are writing. To check that the syntax is permissible, consult the definition of the class of which the subject is an instance.
If you are overwriting or amending a value that is already present in the subject, the Service preserves the syntax of that value, so you can supply a null value.
String OffsetIf supplied by the Client, this argument denotes the position, p, within the attribute value at which you want the first segment written. The position is specified as an offset in octets relative to the start of the string value.
If this argument has a value greater than the number of elements in the attribute value, the Service takes the argument to be equal to that number.
If returned by the Service, this argument denotes the position of the end of the last segment written. The position is specified as an offset in octets relative to the start of the string value.
The value returned by the Service as the position of the end of the last segment written can be specified as the position from which to start writing the next segment. This enables you to write segments sequentially.
ElementsThe string segment that you want to write to the attribute, n elements in number. Copies of these elements occupy the positions, within the value, in the interval between p and (p) + n. The function discards any elements already in or beyond these positions.
The elements are bits, octets, or characters, depending on the nature of the string.
Description
This function writes a segment of an attribute value in a private object, the subject. The segment that the Service writes becomes the last segment in the attribute value. The function discards any segments in the attribute value whose offsets are equal to or greater than the offset specified in String Offset.
If the segment that the Service writes is in the local representation, the Service converts it to the non-local representation. This can result in loss of information and may result in a different number of elements than that specified.
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_SYNTAX | There is an undefined syntax identifier |
| OM_NO_SUCH_TYPE | There is an undefined type identifier |
| 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_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_POSITION | The usage of value position(s) identified in the argument(s) of a function is invalid |
| OM_WRONG_VALUE_SYNTAX | There is an attribute value with an illegal syntax |
Examples
The following example shows data being read from an input file and written to an IA5 Text Body Part. The data is read and written until the end of the input file is reached.
char buff[BUFFER_LENGTH];
int length,
read_status;
OM_return_code om_sts;
OM_value_position position;
OM_string om_string_val;
length = position = 0;
om_string_val.elements = buff;
while (!(read_status = read_input_data (buffer, &length)))
{
om_string_val.length = length;
om_sts = om_write (bodypart, /∗ Object with string segment ∗/
IM_TEXT, /∗ Attrib with string segment ∗/
0, /∗ Pos’n of value to be written
to the attribute ∗/
OM_S_IA5_STRING, /∗ Syntax of value ∗/
&position, /∗ Start pos’n in value (updated
by Service after each om_write)∗/
om_string_val /∗ String segment to be written ∗/
);
if (om_sts != OM_SUCCESS)
break;
length = 0; }