OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-34
GPI_OM_INSERT_
specified type, and the value must satisfy the value length limits for the object’s
class. For lists of types allowed for specific classes, see Section 3, Object Classes
and Attribute Types.
GPI_OM_INSERT_ does some checking of the actual syntax of a value in relation
to the syntax represented by the integer in the syntax field of the descriptor. The
final checking is done when you transfer the root object out to the GPI service.
•
If the syntax of a value is OM-S-OBJECT, the value is the object identifier of the
subobject you are inserting as an attribute.
•
If the attribute is new and contains no existing values, the new values are inserted
starting at position ZGPI-POSITION-AT-BEGIN, the first value position in an
attribute, which is 0.
•
If you specify an attribute type that refers to a single-valued attribute and that
attribute is already present in the object when you call this procedure, an error is
returned. For example, this can occur if an attribute was inserted previously or was
initialized when the object was created. If you want to change the value, you can
call GPI_OM_REMOVE_ to remove it and then call GPI_OM_INSERT_ again.
•
GPI_OM_INSERT_ uses the value-position parameter to determine where to
place the first new value of a particular attribute type. The same position is used for
all attributes for which you are inserting values. GPI_OM_INSERT_ inserts values
in multivalued attributes, as follows:
•
If you supply contiguous values for a multivalued attribute, the procedure inserts
the additional values sequentially after the first new value.
•
If you supply noncontiguous values for the same multivalued attribute, value-
position is used to determine where to place the first new value of each
portion of the noncontiguous list of values. In other words, each portion of the
list is inserted at the same position and causes the positions of values already in
the attribute to be moved to higher-numbered positions.
You should not try to insert values for different types of multivalued attributes,
unless the value-position is appropriate for processing each attribute.
•
If you specify value-position 0 for a multivalued attribute, new values are
inserted before any initial value inserted in the object when GPI_OM_CREATE_
created it.
•
You cannot insert an attribute value that is a long string by using this procedure.
You must use the GPI_OM_WRITE_ procedure to add the value.
•
No subobject can be identified by the same object identifier as another subobject of
its superobject. If you try to insert an object that is already a subobject, an error is
returned.
You can insert a subobject that does not have all its attributes and insert more
attributes in the subobject later. You can insert attributes in an object, superobject,
or subobject at any time before it is transferred out, as long as none of the objects
are reserved.