/*
 * STRUCT: SE_REQUIREMENT
 *
 *   Describes a relationship between two classes.  One class, the 'from'
 *   class or 'current' class, is taken from a context outside of this
 *   structure, while the 'to' class is identified in this structure. The
 *   relationship from the 'from' class to the 'to' class is defined by this
 *   structure.
 *
 *   The relationship being described may be an association, aggregation,
 *   or component relationship.  Each class has a list of its association
 *   requirements, a list of its aggregation requirements, and a list of
 *   its component requirements. These lists are accessed via
 *   SE_AssociationsList(), SE_AggregatesList(), and SE_ComponentsList()
 *   (see). The SE_REQUIREMENT struct defined here is used as an
 *   entry in those lists.
 *
 *   token - the ID of the 'to' class, always meaningful.
 *
 *   multiplicity - the multiplicity of the 'to' side of the relationship,
 *                  always meaningful.  It answers the question "How many
 *                  of the 'to' class objects are required to be related
 *                  to a 'from' class object?"
 *
 *   ordered - when more than one object of the 'to' class is allowed,
 *             this ordered flag indicates whether or not the ordering of
 *             those 'to' objects is important.  This ordered flag is
 *             meaningful only when the multiplicity allows more than
 *             one 'to' class object (i.e. - this ordered flag should be
 *             SE_FALSE, but should also be ignored and is not meaningful
 *             when the multiplicity is SE_EXACTLY_ONE or SE_ZERO_OR_ONE).
 *
 *   lower_limit - the lower limit for the number of 'to' class objects.
 *     Only meaningful for multiplicity values of SE_EXACTLY_N,
 *     SE_BOUNDED_ARRAY, and SE_UNBOUNDED_ARRAY. The meaning of lower_limit
 *     is:
 *               for SE_EXACTLY_N, the lower_limit equals N,
 *                                 requiring exactly N 'to' objects
 *               for SE_BOUNDED_ARRAY, the lower_limit is the minimum
 *                                     number of 'to' objects required
 *               for SE_UNBOUNDED_ARRAY, the lower_limit is the minimum
 *                                      number of 'to' objects required
 *
 *   upper_limit - the upper limit for the number of 'to' class objects.
 *     Only meaningful for multiplicity values of SE_EXACTLY_N,
 *     SE_BOUNDED_ARRAY, and SE_UNBOUNDED_ARRAY.  The meaning of
 *     upper_limit is:
 *               for SE_EXACTLY_N, the upper_limit equals N,
 *                                 requiring exactly N 'to' objects
 *                                 (the value N is stored in both the
 *                                  lower_limit and upper_limit for
 *                                  multiplicity SE_EXACTLY_N)
 *               for SE_BOUNDED_ARRAY, the upper_limit is the maximum
 *                                     number of 'to' objects required
 *               for SE_UNBOUNDED_ARRAY, there is no upper limit for the
 *                                       number of 'to' objects required,
 *                                       so upper_limit is set to the
 *                                       sentinel value SE_NO_UPPER_BOUND
 *
 *  another way to describe lower_limit and upper_limit:
 *
 *     For fixed size arrays,
 *           multiplicity == SE_EXACTLY_N
 *           lower_limit  == upper_limit == (value of N)
 *
 *     For bounded arrays (at least N, at most M),
 *           multiplicity == SE_BOUNDED_ARRAY
 *           lower_limit  == (N, the lower bound value)
 *           upper_limit  == (M, the upper bound value)
 *
 *     For unbounded arrays (at least N, no upper bound),
 *           multiplicity == SE_UNBOUNDED_ARRAY
 *           lower_limit  == (N, lower bound value)
 *           upper_limit  == SE_NO_UPPER_BOUND (-1)
 *
 *   link_class_token - set to the link class, if the relationship has one;
 *     otherwise, set to SE_NULL_TOKEN
 *
 *   next_ptr - a pointer to the next SE_REQUIREMENT struct in this
 *     singly-linked list of requirements; NULL if end-of-list.
 *
 *   For example, consider the relationship from <Transmittal Root> to
 *   <Sound Library> (in the OMT diagram of the SEDRIS DRM).  There is an
 *   open circle at the <Sound Library> end of the line.  An open circle
 *   circle represents a 'multiplicity' of 0 or 1.  The open circle next to
 *   the <Sound Library> class shows that a <Transmittal Root> has 0 or 1
 *   <Sound Libraries>, which can also be stated as a <Transmittal Root>
 *   optionally has a <Sound Library>.  The 'from' class is the <Transmittal
 *   Root>, because we are currently dealing with the list of requirements
 *   for the <Transmittal Root> class.  The 'to' class is the <Sound Library>,
 *   so the "token" field is SE_SOUND_LIBRARY_TOKEN. The multiplicity enum
 *   value which corresponds to the open circle multiplicity symbol is the
 *   enum value SE_ZERO_OR_ONE, so that's the value of the "multiplicity"
 *   field.  Since it is a 0 or 1 multiplicity, the "ordered", "lower_limit",
 *   and "upper_limit" fields do not apply. There is no link class object for
 *   this relationship, so the "link_class_token" field is left with the value
 *   SE_NULL_TOKEN.
 *
 *   Finally, the "next_ptr" field points to the next requirement with the
 *   <Transmittal Root> still being the 'from' class.
 *
 *       The <Transmittal Root> to <Sound Library> Relationship
 *       {
 *           token             = (SE_INT32)SE_SOUND_LIBRARY_TOKEN,
 *           multiplicity      = SE_ZERO_OR_ONE,
 *           ordered           = SE_FALSE, (left at 0, value ignored),
 *           lower_limit       = 0,        (left at 0, value ignored),
 *           upper_limit       = 0,        (left at 0, value ignored),
 *           link_class_token  = (SE_INT32)SE_NULL_TOKEN,
 *           next_ptr          = pointer to next <Transmittal Root> requirement
 *       }
 *
 *   For another example, consider the relationship from <Polygon> to
 *   <Vertex>.  At the <Vertex> side of the relationship, the data model
 *   diagram shows a closed circle with the annotation 3+ {ordered}.  The
 *   closed circle with the 3+ indicates an unbounded array containing at
 *   least 3 ordered entries. (A <Polygon> must have at least 3 <Vertices>,
 *   and the order of the <Vertices> is important).  The "multiplicity" is
 *   indicated by the enum value SE_UNBOUNDED_ARRAY.  The fact that a
 *   <Polygon> must have at least 3 <Vertices> will be recorded in the
 *   "lower_limit" field.  The fact that there is no limit to the number
 *   of <Vertices> a <Polygon> can have will be indicated by a value of
 *   SE_NO_UPPER_BOUND in the "upper_limit" field. The fact that the
 *   order of the entries is important will be recorded in the "ordered"
 *   field.  And the "next_ptr" field will point to the next <Polygon>
 *   requirement.
 *
 *       The <Polygon> to <Vertex>
 *       {
 *           token             = (SE_INT32)SE_VERTEX_TOKEN,
 *           multiplicity      = SE_UNBOUNDED_ARRAY,
 *           ordered           = SE_TRUE,
 *           lower_limit       = 3,
 *           upper_limit       = SE_NO_UPPER_BOUND,
 *           link_class_token  = (SE_INT32)SE_NULL_TOKEN,
 *           next_ptr          = pointer to next <Polygon> requirement
 *       }
 */