SE AddAssociateRelationship

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE AddAssociateRelationship

extern SE_Return_Code
SE_AddAssociateRelationship
(
SE_Object	from_object,	¹
SE_Object	to_object,	²
SE_Object	link_object,	³
SE_Boolean	make_two_way	⁴
);

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 DRM object, or both shall be resolved DRM objects. If both from_object and to_object are resolved, then link_object (if provided) shall be a resolved DRM object; otherwise, link_object may be unresolved.
from_object shall reside in a transmittal that has been explicitly opened with either access mode SE_AM_CREATE or access mode SE_AM_UPDATE.
to_object if not in the same transmittal as from_object, shall be a published DRM object.
link_object, if not in the same transmittal as from_object, shall be a published DRM object.

It should be noted that relationships between DRM 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_RETCOD_SUCCESS	and the requested association relationship is added, if valid parameters were passed in and all operations succeeded.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

set upon successful completion.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNPUBLISHED_OBJECT	set upon failure because 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_STATCODE_UNRESOLVED_INPUT_OBJECT	set upon failure because: 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_STATCODE_INVALID_ACCESS_MODE	set upon failure because: from_object (and link_object if specified) is in a transmittal that is open in SE_AM_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_STATCODE_INACTIONABLE_FAILURE	set upon failure because: make_two_way was SE_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 DRM does not define a valid association relationship between the classes instanced by to_object and from_object; the relationship defined between to_object and from_object requires a link_object, but the link_object supplied was not of the class specified for the relationship; the relationship defined between to_object and from_object does not take a link_object, but one was supplied; or the function fails for any other reason.

Parameters Notes

¹ object to which an association relationship is being added

² associate object being connected

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

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