OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide

Writing Your Program
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001
5-37
Retrieving Information From a Root Object
Parameters for GPI_OM_EXAMINE_ are:
object (input)
values (input)
attribute-position (input)
maximum-number (input)
descriptor-list (output)
total-number (output)
actual-number (output; optional)
string-buffer (output; optional)
string-buffer-length (input; optional)
actual-string-length (output; optional)
total-string-length (output; optional)
object specifies the identifier of the object to be examined.
values specifies whether or not to return the value and syntax of any single-valued
attributes, as follows:
•
OM-TRUE requests return of the syntax and value.
•
OM-FALSE requests return of the attribute type only.
attribute-position specifies the position within the object of the first attribute to
be examined. The first attribute in the object is at position 0. The value of this
parameter must be less than the number of attributes in the object; that is, the specified
position must be within the range of attribute positions for the object.
maximum-number specifies the number of descriptors to be returned. If the value of
this parameter exceeds the number of attributes available, the number available is used.
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 they appear in the object. Each
descriptor includes an attribute type. If the attribute is single-valued and you specify
OM-TRUE for values, a syntax and value are returned. If the procedure call is
unsuccessful or the value of maximum-number is 0, the buffer is unchanged.
total-number is the total number of attributes present in the object (including the
OM-T-CLASS attribute). This number is not affected by the value of attribute-
position or maximum-number. 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 of the 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.