Name

om_read - Reads a segment of a string in a private object

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

subjectThe subject that remains accessible. 

typeIdentifies the type of the attribute, one of whose values is read. 

value_position
The position within the attribute of the value read.

local_stringThis 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 OSF DCE Application Development Guide—Directory Services. 

Input/Output

string_offsetOn 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. 

elementsOn 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

The following describes a partial list of messages (or errors) that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

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

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

       •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