OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-33
Retrieving Information From a Root Object
descriptor-list-in is a list of descriptors specifying the types of attributes you
want to fetch. Each descriptor must specify an attribute type; the syntax and value fields
are ignored.
descriptor-count specifies the number of descriptors you are supplying.
descriptor-list-out is a buffer in your program’s memory space to which you
want the descriptors returned. The area must be large enough to contain the number of
descriptors specified by descriptor-count. The descriptors appear in the order
that you specify the types in descriptor-list-in.
If the attribute is present, the type from the input list is copied to the output list. If the
attribute is not present, the output descriptor type field contains OM-T-UNSPECIFIED,
and the value field is undefined.
If the attribute is single-valued and you specify OM-TRUE for the values parameter, a
syntax and value are returned. If the procedure call is unsuccessful, the buffer is
unchanged.
string-buffer is a buffer in your program’s memory space to which any string
values of single-valued attributes are returned. This buffer can be in your program’s
stack segment or in any extended data segment. You must include this parameter if you
specify a value greater than 0 for string-buffer-length.
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 string-buffer-length if you specify string-buffer.
actual-string-length is the actual number of octets of string data returned. If
the procedure call is unsuccessful, 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.
Fetching 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.
Fetching Values of Multivalued Attributes
If multivalued attributes 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.
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.