OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-31
Retrieving Information From a Root Object
encoded specifies whether an encoded or decoded object is returned. If the parameter
is not present, a value of OM-FALSE is assumed, and the returned object will be a
message, probe, or report in its fully decoded instantiation.
Reserving an Object
If the input queue contains several unreserved objects, the GPI service decides which
one to reserve and transfer in. It does so on the basis of the object’s priority and, within
a priority, on the object’s arrival time. Higher-priority items received at the earliest time
are reserved first. If all objects in the input queue are reserved, or there are no objects in
the queue, the call to GPI_MT_START_TRANSFER_IN_ fails.
Example: Starting Transfer of an Inbound Root Object
The following TAL example shows a call to GPI_MT_START_TRANSFER_IN_ .
Data declarations:
INT
status, -- STATUS code
session; -- ID of session from which
-- transfer-in is made
INT(32)
object_id; -- ID of inbound object
Procedure call:
status := GPI_MT_START_TRANSFER_IN_ ( session,
object_id,
encoded);
Retrieving Information From a Root Object
After transfer-in has been initiated, the root object in GPI library memory space can be
processed. Typically, this involves using inspecting procedures to identify the object
and retrieve all or parts of its content.
The tasks covered in this subsection are:
•
Inspecting an object for specific attribute types (using GPI_OM_FETCH_ )
•
Inspecting an object for all attribute types (using GPI_OM_EXAMINE_ )
Note. If a call to GPI_MT_START_TRANSFER_IN_ fails when attempting to transfer in and
decode a root object, and a subsequent call to GPI_STATUS_ returns an error class of ZGPI-
RC-CLASS-FAILED, most likely the inbound root object is partially or fully undecodable. If an
object identifier has been returned by GPI_MT_START_TRANSFER_IN_ , you can delete or
archive this root object by a call to GPI_MT_FINISH_TRANSFER_IN_ . For additional
information about archiving, refer to the description of GPI_MT_FINISH_TRANSFER_IN_ ,
later in this section.
Note. The encoded parameter for
GPI_MT_START_TRANSFER_IN_ is extensible. If it were
omitted in this example, the value would default to OM-FALSE, and the returned object would
be a message, probe, or report in its fully decoded instantiation.