NAME

SYNOPSIS

#include <xom.h>

OM_return_code om_write(
        OM_private_object subject,
        OM_type type,
        OM_value_position value_position,
        OM_syntax syntax,
        OM_string_length *string_offset,
        OM_string elements);

PARAMETERS

Input

subject

The subject that remains accessible.

type

Identifies the type of the attribute, one of whose values is written.

value_position

The position within the above attribute of the value to be written. The value position can neither be negative nor exceed the number of values present. If it equals the number of values present, the segment is inserted into the attribute as a new value.

syntax

If the value being written is not already present in the subject, this identifies the syntax that the value has. It must be a permissible syntax for the attribute of which this is a value. If the value being written is already present in the subject, then that value's syntax is preserved and this parameter is ignored.

elements

The string segment to be written. A copy of this segment occupies a position within the string value being written, starting at the offset given by the string_offset input parameter. Any values already at or beyond this offset are discarded.

Input/Output

string_offset

On input this parameter contains the offset, in octets, of the start of the string segment to be written. If it exceeds the current length of the string value being written, the parameter is taken to be equal to that current length.

On output it contains the offset, in octets, after the last string segment written. This result is present if, and only if, the OM_return_code result is OM_SUCCESS. The value returned in string_offset can be used as the input string_offset parameter the next time this function is called. This enables sequential writing of the value of a long string.

DESCRIPTION

The om_write() function writes a segment of an attribute value in a private object, the subject parameter.

The segment supplied is a segment of the string value that is supplied if the complete value is written in a single call.

The written segment is made the value's last. The function discards any values whose offset equals or exceeds the string_offset result. If the value being written is in the local representation, it is converted to the nonlocal representation (which may entail the loss of information and which may yield a different number of elements than that provided).

Note that this function enables the client to write an arbitrarily long value without having to place a copy of the entire value in memory.

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; whereas, if the function fails, it has one of the values listed under ERRORS.

The exact constants for OM_return_code are defined in the xom.h header file (see the xom.h(4xom) reference page later in this chapter).

ERRORS

OM_FUNCTION_DECLINED

OM_FUNCTION_INTERRUPTED

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

OM_NO_SUCH_OBJECT

OM_NO_SUCH_SYNTAX

OM_NO_SUCH_TYPE

OM_NOT_PRESENT

OM_NOT_PRIVATE

OM_PERMANENT_ERROR

OM_POINTER_INVALID

OM_SYSTEM_ERROR

OM_TEMPORARY_ERROR

OM_WRONG_VALUE_LENGTH

OM_WRONG_VALUE_MAKEUP

OM_WRONG_VALUE_POSITION

OM_WRONG_VALUE_SYNTAX