OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-26
Transferring Out a Root Object
the call to GPI_MT_TRANSFER_OUT_ fails. A subsequent call to GPI_STATUS_
indicates the specific cause of the failure.
Parameters for GPI_MT_TRANSFER_OUT_ are:
session (input)
object (input)
local-identifier (output)
local-identifier-length (output)
retain (input; optional)
session specifies the identifier of the established session from which the root object is
transferred out.
object specifies the identifier of the root object that is to be transferred out (the class
of the object must be a message, probe, report, or P1-encoded object.
retain is a Boolean that specifies whether you want to retain the root object in the
GPI memory space after the procedure call completes.
•
OM-TRUE specifies that the root object is to be retained and a copy of the object is
to be transferred out. All GPI resources associated with the retained object remain
allocated. The retained object is the responsibility of the client program, which can
modify it.
•
OM-FALSE specifies the root object is not to be retained.
local-identifier is a local identifier that uniquely identifies the object being
transferred out. If this procedure is successful, the GPI returns the local identifier,
which is a string of up to 32 alphanumeric characters. You can use the local identifier as
part of an MTS identifier for the root object. This parameter remains unchanged if the
object being transferred is an instantiation of class MH-C-P1-ENCODED-PDU. For
additional information on the local identifier, refer to the GPI Reference Manual.
local-identifier-length is the length (in octets) of the local identifier.
The following TAL example shows a call to GPI_MT_TRANSFER_OUT_ .
Parameter definitions:
INT
status, -- STATUS code
session, -- ID of session
local_identifier_length := 0; -- Length of local_identifier
INT(32)
object_id, -- ID of outbound root object
retain := OM_FALSE; -- Do not retain root object
-- in memory
Note. The time to complete GPI_MT_TRANSFER_OUT_ is proportional to the size and
complexity of the root object being transferred.