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,	(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_RET_CODE_SUCCESS and the requested association relationship is added, if valid parameters were passed in and all operations succeeded.

SE_RET_CODE_FAILURE and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS set upon successful completion.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_INVALID_ACCESS_MODE set upon failure because:

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_INACTIONABLE_FAILURE set upon failure because:

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

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_RET_CODE_SUCCESS	and the requested association relationship is added, if valid parameters were passed in and all operations succeeded.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_INVALID_ACCESS_MODE	set upon failure because: 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_INACTIONABLE_FAILURE	set upon failure because: 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 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.