OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-46
Retrieving Information From a Root Object
data-string specifies a buffer in your program’s memory space to which you want
the segment returned. The buffer must be long enough to contain the number of octets
specified by maximum-number.
If the procedure call is not successful or the value of maximum-number is 0, the
buffer is unchanged.
actual-number returns the actual number of octets read. If the procedure call is not
successful, the parameter is unchanged.
approx-total-number is the total number of octets in the value. If the procedure
call is not successful, approx-total-number is unchanged.
Determining the Number of Octets in a String Value
To determine the total number of octets in the value without retrieving any octets,
specify 0 for maximum-number. The total number of octets in the value is returned in
approx-total-number.
Figure 5-12 shows use of the GPI_OM_READ_ procedure. Conditions before the
procedure call are shown to the left of the vertical bracket; those after the call are to the
right. In this simplified example, you are reading from a buffer that contains a string
element of the first value (value 0) of a multivalued attribute of type A. The attribute is
contained in an object whose identifier is OBJECT_X_ID.
As shown before the procedure call, the string buffer for value 0 contains 40 octets of
string data. The value for string-offset indicates the read will start after the first
10 octets. The value for maximum-number indicates that 20 octets will be read.
After the call, Buffer_Z contains the string that was read. The actual-number
indicates 20 octets were read. approx-total-number indicates that 40 octets could
have been read. A string offset of 30 is returned as the starting point for a subsequent
GPI_OM_READ_ .
Figure 5-12. Using GPI_OM_READ_
512CDT .CDD
Input Parameters
object: OBJECT_X_ID
maximum-number: 20
string-offset: 10
value-position: 0
attribute-type: Attribute Type A
Output Parameter
string offset: 30
data-string: Buffer_Z
actual-number: 20
approx-total-number: 40
GPI_OM_WRITE_ String Buffer (Buffer_Y)
01020 304050octets
String Buffer for Attribute A, Value 0 (of Object X)
0 1020304050octets