OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-44
GPI_OM_WRITE_
If you omit this parameter and the attribute can have more than one syntax, the
procedure call fails. Otherwise, the string syntax defined for the attribute type is
used.
Considerations
•
Table 4-4 summarizes the ways you can use the GPI_OM_WRITE_ procedure. For
each type of write operation, the table indicates what values to specify for the
string-offset and value-position parameters.
By replacing all or part of a value, you can lengthen or shorten the value. The new
string segment overwrites any existing segments beyond the string offset you
specify. For more information about string offsets, see String Buffers on page 2-9.
•
If the attribute to which segments are being added does not already exist,
GPI_OM_WRITE_ adds the attribute to the object.
•
If the string offset is greater than or equal to 0, the maximum value position allowed
is the last existing value position.
•
If the string offset is ZGPI-NEW-VALUE, the maximum value position allowed is
OM-POSITION-AT-END (or last existing value position + 1), unless no value exists
for the attribute. If no value exists, the value is added in the first value position
(position 0).
You cannot add a value when the maximum number of values for the attribute
already exist. For example, you cannot add a ninth attribute to a multivalued
attribute that can have at most eight values, or add a value to a single-valued
attribute when a value already exists.
•
When generating large messages, applications can specify the syntax OM-S-
ONFILE-STRING. Specifying this syntax reduces memory requirements and avoids
Table 4-4. Writing String Segments
Write Operation String Offset Value Position
Add new value to end of value
list starting at string offset 0.
ZGPI-NEW-VALUE OM-POSITION-AT-END or
(last value position + 1)
Insert new value preceding an
existing value and shift
subsequent values one position.
ZGPI-NEW-VALUE Existing value position
Append string segment to an
existing value.
OM-POSITION-AT-END Existing value position
Replace entire value with string
segment.
0 Existing value position
Replace and overwrite existing
value with string segment
beginning at specified string
offset. (You can shorten or
lengthen value.)
String offset greater than
0 but less than maximum
length allowed for value.
Existing value position