OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-38
Retrieving Information From a Root Object
string-buffer-length 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 string-buffer.
actual-string-length is the actual number of octets of string data returned. If
the procedure is not successful, the parameter is unchanged.
total-string-length is the total number of octets of string data available in the
descriptors of the attributes you requested with respect to attribute-position or
maximum-number.
Determining the Number of Attributes Present in an Object
To determine the total number of attributes in the object without retrieving any
descriptors, specify 0 as the value of maximum-number. The total number of
attributes in the object is returned through total-number.
Examining Values of Single-Valued Attributes
If single-valued attributes are present, the values are returned only if you specify
OM-TRUE for the values parameter. If you specify OM-FALSE, the procedure
returns a syntax of OM-S-UNSPECIFIED and a value of OM-ELEMENTS-
UNSPECIFIED.
If you specify OM-FALSE for the values parameter, you cannot determine whether
an attribute is single-valued or multivalued by checking its syntax and value.
Examining Values of Multivalued Attributes
For multivalued attributes, GPI_OM_EXAMINE_ returns the type and a syntax of
OM-S-UNSPECIFIED. No values are returned. You can retrieve the values by using
the GPI_OM_LIST_ procedure. To retrieve a value that is a long string, use the
GPI_OM_READ_ procedure.
Examining String Values of Single-Valued Attributes
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. For details on
descriptor fields, refer to the GPI Reference Manual.
If a string is a long string (the total length of the string is greater than the maximum-
string-length value you specified for the GPI_INITIALIZE_ procedure), or if a 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
Note. 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.