SEDRIS Reference Manual
APPENDIX A - LEVEL 0 READ and WRITE API
Functions
SE AddSymbolicAssociate
extern SE_Status_Code
SE_AddSymbolicAssociate
(
SE_Object from_object, (notes)
SE_Reference_Symbol to_object, (notes)
SE_Object link_object, (notes)
SE_Boolean make_two_way (notes)
);

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.)

The transmittal whose object is to be edited must be explicitly opened in UPDATE mode for this operation to succeed.

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_STAT_CODE_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_STAT_CODE_INVALID_OR_NULL_OBJECT and no changes are made, if
  1. from_object is NULL or does not belong to a valid DRM class, or
  2. link_object is provided but does not belong to a valid DRM class.
SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_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_STAT_CODE_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.

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 DRM 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: SE_AddComponentRelationship. Next: SE_AddSymbolicComponent. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™