Function Name: Add Symbolic Associate

Definition

Adds an object as an associate of another object using a reference symbol.

An object may or may not have been assigned to the reference symbol at this point. If not, then the API will use forward referencing. "Forward referencing", in this context, means creating association relationships when no object has been assigned to the reference symbol; the API keeps track of the symbolic relationships, then creates them when an object is assigned to the reference symbol.

The from_object (and link_object, if the latter is provided) must be resolved. (See comments for SE_OBJECT.)

NOTE: At some point before the reference symbol is freed by SE_FreeReferenceSymbol(), an object must be assigned to it, so that the symbolic association created by SE_AddSymbolicAssociate() can be resolved; otherwise the actual relationship cannot be created.

Returns

SE_SUCCESS - and the requested symbolic association is added, if valid parameters were passed in and all operations succeeded. Please note that the actual association is not added unless and until the to_object has been assigned to an actual object; see SE_AssignReferenceSymbolToObject() for details.

SE_INVALID_OR_NULL_OBJECT - and no changes are made, if

  1. from_object is NULL or does not belong to a valid SDRM class, or
  2. link_object is provided but does not belong to a valid SDRM class.

SE_UNRESOLVED_START_OBJECT - and no changes are made, if

  1. from_object is an unresolved object (see comments for SE_OBJECT for the conditions under which an object is unresolved), or
  2. link_object is provided but is an unresolved object.

SE_INVALID_OR_NULL_REFERENCE_SYMBOL - and no changes are made, if to_object is not a handle to a valid SE_REFERENCE_SYMBOL created by one of the create-reference-symbol functions.

SE_INVALID_ACCESS_MODE - and no changes are made, if the transmittal (or if ITR is involved, any of the transmittals) containing the from_object, link_object (if present), and/or the object represented by to_object (if to_object has been assigned to an object) were opened in read-only mode.

SE_FAILURE - and no changes are made, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype


extern SE_STATUS_CODE_ENUM
SE_AddSymbolicAssociate
(
SE_OBJECT from_object, (notes)
SE_REFERENCE_SYMBOL to_object, (notes)
SE_OBJECT link_object, (notes)
SE_BOOLEAN make_two_way (notes)
);

Parameters Notes

from_object

 object to which an associate is being added; must
    be a resolved object.

to_object

 reference symbol to associate object being added -
    may or may not be assigned to an object at this point.

link_object

 the link object that will be traversed to reach
    reach the associate object, if applicable; must be a resolved object,
    if provided.

make_two_way

 if true, then if the SDRM defines the association as a
    bidirectional association then the other half of the association
    (to_object -> from_object) is also created by this function.
Prev: Add Component Relationship. Next: Add Symbolic Component. Up:Index.