NAME

SYNOPSIS

#include <xom.h>

OM_return_code om_read(
        OM_private_object subject,
        OM_type type,
        OM_value_position value_position,
        OM_boolean local_string,
        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 read.

value_position

The position within the attribute of the value read.

local_string

This Boolean parameter indicates whether conversion to local string format should be carried out or not. For further information on local strings please refer to the XDS Interface Description Chapter in the Directory Services part of the OSF DCE Application Development Guide.

Input/Output

string_offset

On input this parameter contains the offset, in octets, of the start of the string segment to be read. If it exceeds the total length of the string, the parameter is equal to the string length.

On output it contains the offset, in octets, of the start of the next string segment to be read, or 0 (zero) if the value's final segment is read. The result is present if, and only if, the OM_return_code is OM_SUCCESS. The value returned can be used as the input string_offset parameter in the next call of this function. This enables sequential reading of a value of a long string.

elements

On input, the space the client provides for the segment to be read. The string's contents are initially unspecified. The string's length is initially the number of octets required to contain the segment that the function is to read.

On output, the string's elements become the elements actually read. The string's length becomes the number of octets required to hold the segment actually read. This can be less than the initial length if the segment is the last in a long string.

DESCRIPTION

The om_read() function reads a segment of an attribute value in a private object, namely the subject.

The segment returned is a segment of the string value that is returned if the complete value is read in a single call.

Note that this function enables the client to read an arbitrarily long value without requiring that the service 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; if the function fails, it has one of the error values listed in this reference page.

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

ERRORS

OM_FUNCTION_INTERRUPTED

OM_MEMORY_INSUFFICIENT

OM_NETWORK_ERROR

OM_NO_SUCH_OBJECT

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_SYNTAX