OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Procedure Calls
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
4-32
GPI_OM_FETCH_
Considerations
•
GPI_OM_FETCH_ arranges the descriptors in the descriptor-list-out
buffer in the same order as the descriptors in the descriptor-list-in buffer.
To determine whether an attribute is present, check the output descriptor type field.
If the attribute is present, the type from the input list is copied to the output list. If
the attribute is not present, the type is OM-T-UNSPECIFIED (and the value field is
undefined).
•
For single-valued attributes that 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.
For multivalued attributes that are present, the values are not returned. The
procedure returns a syntax of OM-S-UNSPECIFIED and a value of
OM-ELEMENTS-UNSPECIFIED. You can retrieve the values by using the
GPI_OM_LIST_ procedure.
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.
•
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-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 regular
string does not fit in the buffer, GPI_OM_FETCH_ 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_FETCH_ 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.