Incremental Change

Modules
	IC Errors

Macros
#define	IC_PRT_folder_contents   "Folder::contents"
#define	IC_PRT_occ_predecessor   "PSOccurrence::pred_list"

Typedefs
typedef enum IC_change_type_e	IC_change_type_t
typedef enum IC_list_type_e	IC_list_type_t

Enumerations
enum	IC_change_type_e { IC_add = 1, IC_remove }
enum	IC_list_type_e { IC_list_none = 0, IC_list_adds = 1, IC_list_removes = 2, IC_list_both = 3 }

Functions
ECM_API int	IC_ask_ice_affected_object (tag_t ice, tag_t *affected_obj, tag_t *parent_obj, char **pseudo_reln_type)
ECM_API int	IC_ask_ice_change_type (tag_t ice, IC_change_type_t *change_type)
ECM_API int	IC_create_ice (tag_t ic_rev_tag, tag_t affected_obj, IC_change_type_t change_type, tag_t *ice)
ECM_API int	IC_create_ice_pr (tag_t ic_rev_tag, tag_t child_obj, tag_t parent_obj, const char *pseudo_reln_type, IC_change_type_t change_type, tag_t *ice)
ECM_API int	IC_delete_ice (tag_t ice)
ECM_API int	IC_find_ice (tag_t ic_rev_tag, tag_t affected_obj, tag_t *ice)
ECM_API int	IC_find_ice_pr (tag_t ic_rev_tag, tag_t child_obj, tag_t parent_obj, const char *pseudo_reln_type, tag_t *ice)
ECM_API int	IC_find_ices_affecting_obj (tag_t affected_obj, int *n_ices, tag_t **ices)
ECM_API int	IC_find_ices_affecting_pr (tag_t child_obj, tag_t parent_obj, const char *pseudo_reln_type, int *n_ices, tag_t **ices)
ECM_API int	IC_how_configured (tag_t affected_obj, tag_t rev_rule, logical *is_configured, tag_t *how_configured)
ECM_API int	IC_how_configured_pr (tag_t child_obj, tag_t parent_obj, const char *pseudo_reln_type, tag_t rev_rule, logical *is_configured, tag_t *how_configured)
ECM_API int	IC_is_configured (tag_t affected_obj, tag_t rev_rule, logical *is_configured)
ECM_API int	IC_is_configured_pr (tag_t child_obj, tag_t parent_obj, const char *pseudo_reln_type, tag_t rev_rule, logical *is_configured)
ECM_API int	IC_list_ices_of_ic_rev (tag_t ic_rev_tag, int *n_ices, tag_t **ices)
ECM_API int	IC_split_ic (tag_t ic_rev, int n_ices, tag_t *ices, tag_t ic_rev_target)

Detailed Description

Common return values

IC_duplicate_ice	An affected object cannot be linked more than once to the same IC revision.
IC_no_write_ic_rev	Creating an ICE requires write access to the parent IC revision. This error is returned if you do not have that access.
IC_cannot_delete_affected_object	The ICE was the only Add referencing the affected object, so an attempt was made to delete the affected object as well, but was blocked due to some other reason, e.g. another reference.

Macro Definition Documentation

#define IC_PRT_folder_contents   "Folder::contents"

Predefined pseudo-relation type (PRT). Follow "<class_name>::<attr_name>" convention to ensure uniqueness.

Definition at line 83 of file ic.h.

#define IC_PRT_occ_predecessor   "PSOccurrence::pred_list"

Predefined pseudo-relation type (PRT). Follow "<class_name>::<attr_name>" convention to ensure uniqueness.

Definition at line 89 of file ic.h.

Typedef Documentation

typedef enum IC_change_type_e IC_change_type_t

typedef enum IC_list_type_e IC_list_type_t

Enumeration Type Documentation

enum IC_change_type_e

Enumerator
IC_add	For backwards compatability with V8.1/V9.0 definitions.
IC_remove

Definition at line 59 of file ic.h.

enum IC_list_type_e

Enumerator
IC_list_none
IC_list_adds
IC_list_removes
IC_list_both

Definition at line 70 of file ic.h.

Function Documentation

ECM_API int IC_ask_ice_affected_object	(	tag_t	ice,
		tag_t *	affected_obj,
		tag_t *	parent_obj,
		char **	pseudo_reln_type
	)

Identifies the object affected by an ICE. If parent_obj is NULLTAG, then affected_obj gives the 'regular' affected object, and pseudo_reln_type may be ignored. Otherwise, this is a pseudo-relation, all three output values are required, affected_obj giving the child object.

Parameters

ice	(I) Tag of the ICE in question
affected_obj	(O) Affected object (if parent_obj NULLTAG), or child of pseudo-relation.
parent_obj	(O) If not NULLTAG, this is the tag of the parent object of a pseudo-relation.
pseudo_reln_type	(OF) If parent_obj is not NULLTAG, identifies the type of pseudo-relation affected.

ECM_API int IC_ask_ice_change_type	(	tag_t	ice,
		IC_change_type_t *	change_type
	)

Gives the change type (Add or Remove) of the ICE.

Parameters

ice	(I) Tag of the ICE in question
change_type	(O) IC_add or IC_remove

ECM_API int IC_create_ice	(	tag_t	ic_rev_tag,
		tag_t	affected_obj,
		IC_change_type_t	change_type,
		tag_t *	ice
	)

Creates an IncrementalChangeElement (ICE) to add or remove the affected object as part of the specified IC revision.

Parameters

ic_rev_tag	(I) Incremental Change (IC) revision that is to be the parent of this ICE
affected_obj	(I) Target object of this ICE
change_type	(I) IC_add or IC_remove
ice	(O) Tag of the newly created (unsaved) ICE

ECM_API int IC_create_ice_pr	(	tag_t	ic_rev_tag,
		tag_t	child_obj,
		tag_t	parent_obj,
		const char *	pseudo_reln_type,
		IC_change_type_t	change_type,
		tag_t *	ice
	)

Creates an IncrementalChangeElement (ICE) to add or remove a "pseudo relationship", identified by the combination of parent, child, and pseudo-relation type.

Parameters

ic_rev_tag	(I) Incremental Change (IC) revision that is to be the parent of this IC
child_obj	(I) Target child (i.e. referenced) object of the pseudo-relation to be affected by this ICE
parent_obj	(I) Target parent (i.e. referencing) object of the pseudo-relation to be affected by this ICE
pseudo_reln_type	(I) String identifying the reference attribute of parent that references child; conventionally formatted as "<class_name>::<attr_name>"
change_type	(I) IC_add or IC_remove
ice	(O) Tag of the newly created (unsaved) ICE

ECM_API int IC_delete_ice

(

tag_t

ice

)

Deletes a specific ICE. If the ICE is the sole remaining IC_add of an affected object, then it will also attempt to delete the affected object - and will error if it fails to do so.

Parameters

ice	(I) ICE to be deleted

ECM_API int IC_find_ice	(	tag_t	ic_rev_tag,
		tag_t	affected_obj,
		tag_t *	ice
	)

Finds the ICE identified by combination of IC revision and affected object ('regular' and pseudo-relation cases respectively).

Parameters

ic_rev_tag	(I) IC revision
affected_obj	(I) Affected object
ice	(O) ICE found

ECM_API int IC_find_ice_pr	(	tag_t	ic_rev_tag,
		tag_t	child_obj,
		tag_t	parent_obj,
		const char *	pseudo_reln_type,
		tag_t *	ice
	)

Finds the ICE identified by combination of IC revision and affected pseudo-relation.

Parameters

ic_rev_tag	(I) IC revision
child_obj	(I) Child of the affected pseudo-relation
parent_obj	(I) Parent of the affected pseudo-relation
pseudo_reln_type	(I) Identifies the type of pseudo-relation
ice	(O) ICE found

ECM_API int IC_find_ices_affecting_obj	(	tag_t	affected_obj,
		int *	n_ices,
		tag_t **	ices
	)

Find all ICEs affecting a given object ('regular' and pseudo-relation cases respectively).

Parameters

affected_obj	(I) Affected object
n_ices	(O) Number of ICEs found
ices	(OF) n_ices Array of tags of the ICEs found

ECM_API int IC_find_ices_affecting_pr	(	tag_t	child_obj,
		tag_t	parent_obj,
		const char *	pseudo_reln_type,
		int *	n_ices,
		tag_t **	ices
	)

Finds all ICEs affecting a given pseudo-relation.

Parameters

child_obj	(I) Child of the pseudo-relation
parent_obj	(I) Parent of the pseudo-relation
pseudo_reln_type	(I) Identifies the type of pseudo-relation
n_ices	(O) Number of ICEs found
ices	(OF) n_ices Array of tags of the ICEs found

ECM_API int IC_how_configured	(	tag_t	affected_obj,
		tag_t	rev_rule,
		logical *	is_configured,
		tag_t *	how_configured
	)

As IC_is_configured, but when is_configured=true, how_configured references an object that describes how the revision rule decided the affected object is configured. Where 'competing' configured affected objects arise, these can be passed to CFM_latest_of_latest which will tell you which one the revision rule considers to be 'latest'.

Special case:

If the target affected object is not qualified by any ICEs, then IC deems it to be 'always configured', regardless of revision rule. In this case is_configured=true and how_configured = NULLTAG; this value should not be passed to CFM_latest_of_latest, it should be handled by the caller of this function.

Parameters

affected_obj	(I) Affected object
rev_rule	(I) Revision rule
is_configured	(O) True if the affected object is configured in context of the rev rule
how_configured	(O) Describes how the revision rule decided the affected object is configured

ECM_API int IC_how_configured_pr	(	tag_t	child_obj,
		tag_t	parent_obj,
		const char *	pseudo_reln_type,
		tag_t	rev_rule,
		logical *	is_configured,
		tag_t *	how_configured
	)

As IC_is_configured_pr, but when is_configured=true, how_configured references an object that describes how the revision rule decided the pseudo-relation is configured. Where 'competing' configured affected objects arise, these can be passed to CFM_latest_of_latest which will tell you which one the revision rule considers to be 'latest'.

Special case:

If the target pseudo-relation is not qualified by any ICEs, then IC deems it to be 'always configured', regardless of revision rule. In this case is_configured = true and how_configured = NULLTAG; this value should not be passed to CFM_latest_of_latest, it should be handled by the caller of this function.

Parameters

child_obj	(I) Child of the pseudo-relation
parent_obj	(I) Parent of the pseudo-relation
pseudo_reln_type	(I) Identifies the type of pseudo-relation
rev_rule	(I) Revision rule
is_configured	(O) True if the pseudo-relation is configured in context of the rev rule
how_configured	(O) Describes how the revision rule decided the affected object is configured

ECM_API int IC_is_configured	(	tag_t	affected_obj,
		tag_t	rev_rule,
		logical *	is_configured
	)

Tells you if the affected object is configured by IC in context of the rev rule ('regular' affected object and pseudo-relation cases respectively).

Parameters

affected_obj	(I) Affected object
rev_rule	(I) Revision rule
is_configured	(O) True if the affected object is configured in context of the rev rule

ECM_API int IC_is_configured_pr	(	tag_t	child_obj,
		tag_t	parent_obj,
		const char *	pseudo_reln_type,
		tag_t	rev_rule,
		logical *	is_configured
	)

Tells you if the pseudo-relation is configured by IC in context of the revision rule.

Parameters

child_obj	(I) Child of the pseudo-relation
parent_obj	(I) Parent of the pseudo-relation
pseudo_reln_type	(I) Identifies the type of pseudo-relation
rev_rule	(I) Revision rule
is_configured	(O) True if the pseudo-relation is configured in context of the rev rule

ECM_API int IC_list_ices_of_ic_rev	(	tag_t	ic_rev_tag,
		int *	n_ices,
		tag_t **	ices
	)

List all ICEs belonging to an IC revision.

Parameters

ic_rev_tag	(I) IC revision
n_ices	(O) Number of ICEs found
ices	(OF) n_ices Array of tags of the ICEs found

ECM_API int IC_split_ic	(	tag_t	ic_rev,
		int	n_ices,
		tag_t *	ices,
		tag_t	ic_rev_target
	)

Split the list of ices in incrememtal change ic_rev into incremental change ic_rev_target

Parameters

ic_rev	(I)
n_ices	(I)
ices	(I)
ic_rev_target	(I)