OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-54
Editing a Root Object
Copying an Object
You call the GPI_OM_COPY_ procedure to create a new object that is an exact but
independent copy of a specified object. The new object includes all objects contained in
the object you are copying.
The copied object is identical to the original, except that it has a different object
identifier. The unique object identifier makes it possible to insert the copy in the same
root object as the original. When you copy an unmodifiable object in GPI library
memory, the object copy is modifiable.
You can copy a subobject that is already inserted into its superobject. To find that
object, you can use GPI_OM_FETCH_ .
Parameters for GPI_OM_COPY_ are:
original (input)
copy (output)
copy-root-object (input; optional)
copy-session (input; optional)
original specifies the object identifier of the object to be copied.
copy-root-object specifies the object identifier of the root object with which the
copied object is to be associated. The specified root object must already exist. You
must specify this parameter if the object you are copying is not a root object. If the
object you are copying is a root object, this parameter is ignored.
copy-session specifies the session identifier of the session with which the copied
root object is to be associated. The session must already be established. If the original
object to be copied is a root object, you must specify a value for this parameter. If the
object you are copying is not a root object, this parameter is ignored.
copy is the object identifier of the newly copied object. If the procedure is not
successful, this parameter is unchanged.
The following TAL example shows a call to GPI_OM_COPY_ .
Data declarations:
INT
status; -- STATUS code
INT(32)
original_id, -- ID of original object
copy_id, -- ID of object copy
root_id; -- ID of root object to which copy
-- is to be associated
Note. If you specify OM-TRUE for retain, the root object will be retained in the GPI library
space and made modifiable. This makes GPI_OM_COPY_ unnecessary. Extra copies affect
performance and occupy additional space in the GPI library process. This is an especially
important consideration in the case of a P1-EXIT type gateway, which receives all X.400 traffic
relayed to the local MTA.