OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-9
Initializing the GPI Environment
Remember that, for each session required by the GPI process, a separate GIP is required.
Therefore GIP_memory must be multiplied by num_sessions to determine the total
amount of calculable GIP memory space needed.
Setting Short String Length
GPI procedures process two types of data strings: short strings and long strings. Short
strings can be processed intact in “one shot” by procedures that pass attribute
descriptors. Long strings must be processed in segments by two special-purpose
procedures that read and write long strings.
The procedures that process short strings are:
•
GPI_OM_FETCH_
•
GPI_OM_EXAMINE_
•
GPI_OM_LIST_
•
GPI_OM_INSERT_
The procedures that process long strings are:
•
GPI_OM_READ_
•
GPI_OM_WRITE_
The setting for max-string-length can be adjusted to match the content of root
objects processed by your gateway. As a guideline, the minimum value (1024 octets) is
adequate for most types of content, except perhaps for non-interpersonal message
content or for content associated with a large body part.
Example: Initializing the Environment
The following TAL example shows a call to GPI_INITIALIZE_ . In this case, input
parameters are not specified; the procedure uses internal defaults.
Data Declaration:
INT
status; -- STATUS code
Procedure call:
status := GPI_INITIALIZE_ ();
Note. Additional GIP memory is allocated internally for encoding and decoding messages. It
is allocated when GPI_MT_TRANSFER_OUT_ or GPI_MT_START_TRANSFER_IN_ are
called (and it is freed immediately after the encoding or decoding has completed). This
memory space can be from two to ten times the size of an encoded message, depending on
the number of recipients (however, it is rarely more than two times encoded message size).
The only accurate way to determine the amount of this memory is to track average message
size at your gateway. Because this memory space is hard to determine and is freed
automatically, it is not included in the formula for total GIP memory above.