OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-28
GPI_OM_EXAMINE_
You must include this parameter if you specify a value greater than 0 for the
string-buffer-length parameter.
string-buffer-length input
INT(32):value
specifies the maximum number of octets of string data that string-buffer can
contain. The minimum value you can specify is 0. You must specify this parameter
if you specify the string-buffer parameter.
actual-string-length output
INT(32) .EXT:ref:1
is the actual number of octets of string data returned. If the procedure call is
unsuccessful, the parameter is unchanged.
total-string-length output
INT(32) .EXT:ref:1
is the total number of octets of string data available in the attribute descriptors of the
attributes you requested with respect to the attribute-position or
maximum-number parameters.
Considerations
•
For multivalued attributes, GPI_OM_EXAMINE_ returns the attribute type, syntax
OM-S-UNSPECIFIED, and element OM-S-ELEMENTS-UNSPECIFIED. No
values are returned. You can retrieve the values by using the GPI_OM_LIST_
procedure.
•
Attributes that are defined as multivalued attributes but appear in the object with
only a single value are treated as single-valued attributes by this procedure.
•
The elements of an attribute value that has a syntax of OM-S-xxx-STRING are
returned in the string buffer you specify. The starting address of each value is
returned in the OM-string elements field of the descriptor value field for that
attribute.
•
If a string is a long string (the total length of the string is greater than the max-
string-length value you specified for the GPI_INITIALIZE_ procedure), or if a
regular string does not fit in the buffer, GPI_OM_EXAMINE_ does the following:
•
Returns the length of the value in the string-length field of the descriptor value
field for the attribute
•
Returns OM-ELEMENTS-UNSPECIFIED in the string elements field
If you detect either of these situations, you can retrieve the string by making another
procedure call. To retrieve a long string, call the GPI_OM_READ_ procedure. To
retrieve other strings, call GPI_OM_EXAMINE_ again and specify a larger buffer