om_read(3xom) — Subroutines

Name

om_read − Reads a segment of a string from a private object.

Syntax

OM_return_code om_read(subject, type, value_position, local_string, string_offset, elements)

subject@OM_private_object@T{ read T} type@OM_type@T{ read T} value_position@OM_value_position@T{ read T} local_string@OM_boolean@T{ read T} string_offset@OM_string_length@T{ read-write T} elements@OM_string@T{ write T} return_code@T{ OM_return_code T}

C Binding

OM_return_code om_read(subject, type, value_position, local_string, string_offset, elements)

OM_private_object subject,

OM_type type,

OM_value_position value_position,

OM_boolean local_string,

OM_string_length #string_offset,

OM_string #elements

Arguments

Subject

The private object from which you want to read the segment.

Type

The type of the attribute containing the value that you want to read.

Value Position

The position in a multi-valued attribute of the value that you want to read.

Local String

If you set this argument to OM_TRUE, the Service translates the attribute segment into the local character set. This translation may result in the loss of some information.

String Offset

If provided by the Client, this argument denotes the position within the attribute value of the first element that you want to read. If you give this argument a value that exceeds the number of elements present in the attribute value, the Service takes the argument to be equal to the number of elements present in the attribute value.

If returned by the Service, this argument denotes the position of the next segment within the attribute value, as an offset in octets. If the segment just read was the last in the string, then this argument is set to zero. The result is present only if the Return Code result is OM_SUCCESS.

The value indicating the next position can be specified in a subsequent call as the position to start from, enabling sequential reading of the segments in a string value.

Elements

A space into which the Service returns the segment of the attribute value that you want to read. This argument is a string with two components, Elements and Length.

The following table shows the initial values that you should give to these components.

Elements@T{ Pointer to a buffer T} Length@T{ The number of octets required to contain the segment that the function returns T}

You must make sure that the buffer is big enough to hold the number of octets.

The Service modifies the Elements argument. Each element that the function returns becomes an element in the string. The string’s length becomes the number of octets actually required to hold the segment read (which may be smaller than the length initially specified.)

If the value of Local Strings is OM_TRUE, the final length of the string may not be the same as the initial length of the string. This depends on the characteristics of the translation into the local character set.

Description

The function enables you to read a long string without requiring the Service to place a copy of the entire string in memory.

Return Values

The function has completed its task successfully T} OM_FUNCTION_INTERRUPTED@T{ The function was aborted by external intervention T} OM_MEMORY_INSUFFICIENT@T{ There is not enough memory to complete the function T} OM_NETWORK_ERROR@T{ The Service cannot use the underlying network T} OM_NO_SUCH_OBJECT@T{ You have specified a nonexistent object, or an invalid Handle for an object T} OM_NO_SUCH_TYPE@T{ There is an undefined type identifier T} OM_NOT_PRESENT@T{ An expected attribute value is missing T} OM_NOT_PRIVATE@T{ There is a public object where there should be a private object T} OM_PERMANENT_ERROR@T{ The Service encountered a permanent problem for which there is no defined error code T} OM_POINTER_INVALID@T{ An invalid pointer was supplied as a function argument T} OM_SYSTEM_ERROR@T{ The Service cannot use the operating system T} OM_TEMPORARY_ERROR@T{ The Service encountered a temporary problem for which there is no defined error code T} OM_WRONG_VALUE_SYNTAX@T{ There is an attribute value with an illegal syntax T}

Examples

The following example shows the reading of a string value from an object of the IM class IA5 Text Body Part (body_part). The Service will return 0 when there is no more text left to read.

Exhibit 0-0.

OM_private_object   body_part;

OM_return code      result;

OM_string           message;

OM_string_length    offset;

char                read_buffer[1024];

message.length = 1024

message.elements = read_buffer;

offset = 0;

     result = om_read (body_part,
                             /∗ object containing value to be read ∗/
                       IM_TEXT,
                             /∗ attribute from which value is to be read ∗/
                       0,
                             /∗ position of value to read from ∗/
                       OM_FALSE,
                             /∗ no translation into local char set ∗/
                       &offset,
                             /∗ string offset of segment to be read ∗/
                       &message);
                             /∗ the string read from the value ∗/

The type of the attribute read is IM_TEXT. The first element of the first value in this attribute is read into message.

Museum