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)

Argument	Data Type	Access
subject	OM_private_object	read
type	OM_type	read
value_position	OM_value_position	read
local_string	OM_boolean	read
string_offset	OM_string_length	read-write
elements	OM_string	write
return_code	OM_return_code

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

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

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

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

Local StringIf 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 OffsetIf 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.

ElementsA 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 shows the initial values that you should give to these components.

Elements

Pointer to a buffer

Length

The number of octets required to contain the segment that the function returns

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

OM_SUCCESS	The function has completed its task successfully
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_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_SYNTAX	There is an attribute value with an illegal syntax

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.

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, /∗ obj with value to be read ∗/
                  IM_TEXT,   /∗ attrib from wh val is to be read ∗/
                  0,         /∗ position of value to read from ∗/
                  OM_FALSE, /∗ no trans into local char set ∗/
                  &offset,   /∗ string offset of seg to be read ∗/
                  &message); /∗ 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