OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-42
Retrieving Information From a Root Object
descriptor-list 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 maximum-number.
The descriptors are returned in the order in which the values appear in the attribute. If
the procedure is not successful or the value of maximum-number is 0, the buffer is
unchanged.
total-number is the total number of values in the attribute. This number is not
affected by maximum-number or value-position. If the procedure is not
successful, the parameter is unchanged.
actual-number is the actual number of descriptors returned. If the procedure is not
successful, the parameter is unchanged.
string-buffer is a buffer in your program’s memory space to which elements of
any string values 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 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 maximum-number or
value-position.
Determining the Number of Values Present in an Attribute
To determine the total number of values in the attribute without retrieving any
descriptors, specify 0 as the value of maximum-number. The total number of values
in the attribute is returned in total-number.
Listing Values of Single-Valued Attributes
You can use this procedure to retrieve the value of a single-valued attribute by
specifying value-position as 0.
Listing String Values
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. 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 specified for the GPI_INITIALIZE_ procedure) or if a string does
not fit in the buffer, GPI_OM_LIST_ does the following: