OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-25
GPI_OM_DELETE_
GPI_OM_DELETE_
This procedure deletes an object by invalidating the object identifier and releasing all
resources allocated by the GPI for the object.
All subobjects of the deleted object are also deleted.
status returned value
INT:value
indicates the outcome of the call. A value of OM-RC-SUCCESS indicates a
successful call. For additional values of status, see Appendix B, Return Codes
.
object input
INT(32):value
specifies the object identifier of the object to be deleted.
Considerations
•
If GPI_OM_DELETE_ returns successfully, your client application can no longer
access the object by using its object identifier. Further references to the object
identifier result in an error.
•
Normally, you use the GPI_OM_DELETE_ procedure to delete objects you have
created or copied and the GPI_MT_FINISH_TRANSFER_IN_ procedure to delete
an object from the input queue. If you use the GPI_OM_DELETE_ procedure to
delete a reserved root object from the input queue, the result is the same as calling
GPI_MT_FINISH_TRANSFER_IN_ with remove specified as MH-CANCEL.
The object becomes unreserved, and its object identifier becomes invalid. However,
the object remains in the input queue of the GPI service, which assumes
responsibility for the object.
The object remains at the beginning of the input queue. You cannot reserve the next
object on the queue until you have reserved the first one again by calling
GPI_MT_START_TRANSFER_IN_. In this case, the GPI assigns a new object
identifier to the newly reserved object. To remove the object permanently from the
queue, you can call GPI_MT_FINISH_TRANSFER_IN_ and specify a remove
value of MH-REMOVE or MH-ARCHIVE.
•
If you delete a subobject, the object is no longer an attribute of its superobject. An
attempt to delete a reserved subobject results in an error.
status := GPI_OM_DELETE_ ( object ) ; ! I