OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-37
GPI_OM_LIST_
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 maximum-number or
value-position parameters.
Considerations
•
The procedure fills in a list of attribute descriptors with the information you request.
Each descriptor corresponds to one attribute value of the type you specify and
contains the attribute type, syntax, and value.
•
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-S-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 specified for the GPI_INITIALIZE_ procedure), or
if a short string does not fit in the buffer, GPI_OM_LIST_ 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_LIST_ again and specify a larger buffer
(string-buffer-length).
If an attribute following one for which a value is not returned has a shorter string
value that fits in the buffer, that value is returned. You should continue examining
the descriptor list after detecting OM-ELEMENTS-UNSPECIFIED to check the
remaining contents of the string buffer.
•
You can use this procedure to retrieve the value of a single-valued attribute by
specifying value-position 0.
•
If a multivalued attribute appears in the object with only one value,
GPI_OM_LIST_ retrieves that value.