SE AddAssociateRelationship

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE AddAssociateRelationship

extern SE_Status_Code
SE_AddAssociateRelationship
(
SE_Object	from_object,	(notes)
SE_Object	to_object,	(notes)
SE_Object	link_object,	(notes)
SE_Boolean	make_two_way	(notes)
);

Definition

Add an association relationship from from_object to to_object provided that the following criteria are met.

Either from_object or to_object shall be a resolved object, or both shall be resolved objects. If both from_object and to_object are resolved, then link_object (if provided) shall be a resolved object; otherwise, link_object may be unresolved.
from_object shall reside in a transmittal that has been explicitly opened with either SE_AC_MODE_CREATE or SE_AC_MODE_UPDATE.
to_object if not in the same transmittal as from_object, shall be a published object.
link_object, if not in the same transmittal as from_object, shall be a published object.

It should be noted that relationships between objects in different transmittals are NOT implicitly bi-directional, so the make_two_way parameter will have an effect in inter-transmittal referencing only if:

both the from_object and to_object are published,
both the from_object and to_object are resolved and,
both transmittals have been opened for writing or modification

If only the from_object is resolved, then the association can only be one way.

Returns

SE_STAT_CODE_SUCCESS and the requested association relationship is added, if valid parameters were passed in and all operations succeeded.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and no changes are made, if

from_object is invalid or is unsaved (i.e., has not yet been added to any transmittal),

to_object is invalid or is unsaved (i.e., has not yet been added to any transmittal),

link_object is non-NULL and either is unsaved (i.e., has not yet been added to the transmittal), or does not belong to a valid DRM class.

SE_STAT_CODE_UNPUBLISHED_OBJECT and no changes are made, if to_object is in another transmittal than from_object, but is not published by that transmittal (or vice-versa) and the make_two_way flag is set.

SE_STAT_CODE_UNRESOLVED_START_OBJECT and no changes are made, if

both from_object and to_object are unresolved, or

link_object is non-NULL, unresolved, and the from_object and to_object are both resolved.

SE_STAT_CODE_INVALID_ACCESS_MODE and no changes are made, if

from_object (and link_object if specified) is in a transmittal that is open in SE_AC_MODE_READ_ONLY mode;

to_object is in a transmittal that has not been opened for writing or modification, so no association could be created from to_object.

SE_STAT_CODE_FAILURE and no changes are made, if

make_two_way was true and the DRM defines the relationship as bidirectional, but to_object is unresolved, so no association could be created from to_object to from_object;

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 association relationship is being added

to_object

 associate object being connected

link_object

 the link object that will be traversed to reach the
     associate object, if applicable

make_two_way

 if true, then if the DRM defines the association as a
    bidirectional association and both the from_object and to_object
    are resolved, then the other half of the association (to_object ->
    from_object) is also created by this function.

SE_STAT_CODE_SUCCESS	and the requested association relationship is added, if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and no changes are made, if from_object is invalid or is unsaved (i.e., has not yet been added to any transmittal), to_object is invalid or is unsaved (i.e., has not yet been added to any transmittal), link_object is non-NULL and either is unsaved (i.e., has not yet been added to the transmittal), or does not belong to a valid DRM class.
SE_STAT_CODE_UNPUBLISHED_OBJECT	and no changes are made, if to_object is in another transmittal than from_object, but is not published by that transmittal (or vice-versa) and the make_two_way flag is set.
SE_STAT_CODE_UNRESOLVED_START_OBJECT	and no changes are made, if both from_object and to_object are unresolved, or link_object is non-NULL, unresolved, and the from_object and to_object are both resolved.
SE_STAT_CODE_INVALID_ACCESS_MODE	and no changes are made, if from_object (and link_object if specified) is in a transmittal that is open in SE_AC_MODE_READ_ONLY mode; to_object is in a transmittal that has not been opened for writing or modification, so no association could be created from to_object.
SE_STAT_CODE_FAILURE	and no changes are made, if make_two_way was true and the DRM defines the relationship as bidirectional, but to_object is unresolved, so no association could be created from to_object to from_object; the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.