OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-45
Retrieving Information From a Root Object
Reading a Long String From an Attribute Value
You call the GPI_OM_READ_ procedure to read a segment of a long string from a
specific value of a multivalued or single-valued attribute. A segment is a portion of a
string made up of zero or more contiguous octets. You call this procedure as many
times as needed to read all segments of the value. Each call returns a next position,
which you can use as the starting position (string offset) of the next call.
You use this procedure as a supplement to the following procedures, none of which can
read long string values:
•
GPI_OM_FETCH_
•
GPI_OM_EXAMINE_
•
GPI_OM_LIST_
After one of these procedures has determined that a value is a long string, you call
GPI_OM_READ_ as many times as necessary to read all segments of the string.
Parameters for GPI_OM_READ_ are:
object (input)
attribute-type (input)
value-position (input)
string-offset (input/output)
maximum-number (input)
data-string (output; optional)
actual-number (output; optional)
approx-total-number (output)
object specifies the identifier of the object containing the attribute whose value you
want to read.
attribute-type specifies the type of the attribute whose value you want to read.
value-position specifies the position within the attribute of the value you want to
read.
string-offset, on input, specifies the offset (in octets) of the start of the string
element to be read. The offset of the first octet in a string is 0. The value of this
parameter must be less than the actual number of octets in the attribute’s value.
On output, string-offset is the offset of the next string segment to be read (one
octet beyond the number of octets currently read). If the buffer contains no string data,
the value of string offset on output is the same as that specified on input.
maximum-number specifies the maximum number of octets to read. If maximum-
number exceeds the number of octets available, the number available is used.
Note. GPI_OM_READ_ is designed specifically for long strings; however, you can also use it
to read short strings.