Function Name: Set Root Object

Definition

Given an SE_TRANSMITTAL, save the passed SDRM object as the root of the transmittal's object hierarchy. The previous root object is returned in the old_root_object_out_ptr parameter. If no root object has been set for a transmittal, NULL is returned in old_root_object_out_ptr.

CAUTION
Calling this function will permanently change the root object of the transmittal. In order to avoid orphaning objects within the transmittal, the old_root_object_out_ptr parameter is required in order to return the root object that was previously set. If this is a new transmittal, and the root object has never been set, * old_root_object_out_ptr will be set to NULL.

Returns

SE_SUCCESS - if valid parameters were passed in, the old root object was successfully returned (if there was one), and new_root_object_in has been successfully set to be the new root object of transmittal_in.

SE_NULL_REQUIRED_PARAMETER - and the output parameters are left unaltered, if old_root_object_out_ptr is NULL.

SE_INVALID_OR_NULL_TRANSMITTAL - and *old_root_object_out_ptr is set to NULL and transmittal_in is left unaltered, if transmittal_in is not a handle to a valid, active (i.e., open) SEDRIS transmittal.

SE_INVALID_OR_NULL_OBJECT - and the output parameters are set as for SE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a valid, active (i.e., unfreed) object, or already belongs to a transmittal.

SE_UNRESOLVED_OBJECT - and the output parameters are set as for SE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a resolved object.

SE_INVALID_ACCESS_MODE - and the output parameters are set as for SE_INVALID_OR_NULL_TRANSMITTAL, if transmittal_in was opened in read-only mode.

SE_OUT_OF_MEMORY - and the output parameters are set as for SE_INVALID_OR_NULL_TRANSMITTAL, if *old_root_object_out_ptr cannot be allocated.

SE_FAILURE - and the output parameters are set as for SE_INVALID_OR_NULL_TRANSMITTAL, 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_SetRootObject
(
SE_TRANSMITTAL transmittal_in, (notes)
SE_OBJECT new_root_object_in, (notes)
SE_OBJECT *old_root_object_out_ptr (notes)
);

Parameters Notes

transmittal_in

 a handle to the transmittal for which the root object
    is being set.

new_root_object_in

 a pointer to the SE_OBJECT handle of the new root
    object of the transmittal.

old_root_object_out_ptr

 a pointer to the SE_OBJECT handle to the
    previous root object of the transmittal.
Prev: Set General Callback For One Function. Next: Set SRF Parameters. Up:Index.