Modules
	GRM Errors

	GRM Messages

	GRM Type

Data Structures
struct	GRM_list_relation_input_s

struct	GRM_relation_s

Macros
#define	GRM_class_name_c "ImanRelation"

#define	GRM_relationtype_name_size_c 32

Typedefs
typedef struct GRM_list_relation_input_s *	GRM_list_relation_input_p_t

typedef struct GRM_list_relation_input_s	GRM_list_relation_input_t

typedef struct GRM_relation_s *	GRM_relation_p_t

typedef struct GRM_relation_s	GRM_relation_t

Functions
TCCORE_API int	GRM_ask_primary (tag_t relation, tag_t *primary_object)

TCCORE_API int	GRM_ask_relation_type (tag_t relation, tag_t *relation_type)

TCCORE_API int	GRM_ask_secondary (tag_t relation, tag_t *secondary_object)

TCCORE_API int	GRM_ask_user_data (tag_t relation, tag_t *user_data)

TCCORE_API int	GRM_create_relation (tag_t primary_object, tag_t secondary_object, tag_t relation_type, tag_t user_data, tag_t *relation)

TCCORE_API int	GRM_create_relation_type (const char relation_type_name, tag_t relation_type)

TCCORE_API int	GRM_delete_relation (tag_t relation)

TCCORE_API int	GRM_delete_relation_type (tag_t relation_type)

TCCORE_API int	GRM_find_relation (tag_t primary_object, tag_t secondary_object, tag_t relation_type, tag_t *relation)

TCCORE_API int	GRM_find_relation_type (const char relation_type_name, tag_t relation_type)

TCCORE_API int	GRM_list_all_related_objects (tag_t match_object, int count, GRM_relation_t *related_object_list)

TCCORE_API int	GRM_list_all_related_objects_only (tag_t match_object, int count, tag_t *related_objects)

TCCORE_API int	GRM_list_primary_objects (tag_t secondary_object, tag_t relation_type, int count, GRM_relation_t *primary_list)

TCCORE_API int	GRM_list_primary_objects_in_bulk (int input_count, const GRM_list_relation_input_t inputs, int count, GRM_relation_t **primary_list)

TCCORE_API int	GRM_list_primary_objects_only (tag_t secondary_object, tag_t relation_type, int count, tag_t *primary_objects)

TCCORE_API int	GRM_list_primary_objects_with_primary_object_type_only (tag_t secondary_object, tag_t relation_type, const char primary_type_name, int count, tag_t **primary_objects)

TCCORE_API int	GRM_list_relation_types (int count, tag_t *relation_type_list)

TCCORE_API int	GRM_list_relations (tag_t primary_object, tag_t secondary_object, tag_t relation_type, tag_t user_data, int count, tag_t *relation_list)

TCCORE_API int	GRM_list_secondary_objects (tag_t primary_object, tag_t relation_type, int count, GRM_relation_t *secondary_list)

TCCORE_API int	GRM_list_secondary_objects_in_bulk (int input_count, const GRM_list_relation_input_t inputs, int count, GRM_relation_t **secondary_list)

TCCORE_API int	GRM_list_secondary_objects_only (tag_t primary_object, tag_t relation_type, int count, tag_t *secondary_objects)

TCCORE_API int	GRM_save_relation (tag_t relation)

TCCORE_API int	GRM_set_user_data (tag_t relation, tag_t new_user_data)

Detailed Description

The GRM module supports the concept of explicit relationships. A dataset can be directly and explicitly related to an Item Revision with, as an example, a specification relationship. With GRM, you can define and enforce specific rules pertaining to relationships, as well as separate the maintenance of relationships from the data itself.

Common Return Values

Return Value	Description
CXPOM_invalid_tag	Invalid tag supplied.
GRM_duplicate_relation_type	The type you propose to create already exists in the system.
GRM_internal_error	The GRM module has detected an internal inconsistency and therefore should not be used.
GRM_invalid_primary_object	Specified tag for the primary_object is not valid.
GRM_invalid_relation_type	Specified tag for relation_type is not valid.
GRM_invalid_secondary_object	Specified tag for the secondary_object is not valid.
GRM_invalid_user_data	Specified tag for user_data is not valid.
GRM_not_initialized	The GRM module was not initialized.
GRM_relation_already_exists	The relation being saved already exists.
GRM_relation_does_not_exist	Relation does not exist.
GRM_undefined_relation_type	The type you propose to delete does not exist.

Returned Tag Structure

Several GRM list functions return a list of tag quadruplets defined by the structure GRM_relation_t. The tag structure includes the tags of the primary_object, secondary_object, relation_type, and the user_data. The tag of a specific element of the structure can be referenced as follows:

structure_name.primary	To reference the primary object.
structure_name.secondary	To reference the secondary object.
structure_name.relation_type	To reference the relation type.
structure_name.user_data	To reference the user data.

Constraint Handler Registration and Execution

User-written constraint handlers should be registered in the USER_register_handlers user exit. This user exit is called during initialization for both interactive and ITK modes. This ensures that constraint handling is enforced in a consistent manner.

If constraint handlers are also registered in your ITK program (as well as in USER_register_handlers), then both sets of constraint handlers are called in the order they were registered. Since USER_register_handlers is called before your main ITK program, any handler you register in your ITK program is executed after the handlers registered using USER_register_handlers.

Additionally, it is possible that an internal Teamcenter handler is also registered for a give relation type and action combination. Such a handler is normally registered by a Teamcenter module or application to enforce certain rules before the user exit USER_register_handlers is called. Internal handlers are always executed before any user-written handler.

Multi-Level Handlers

Several levels of constraint handlers can exist for a particular relation type and action combination. There are internal handlers which a Teamcenter developer may have registered. For example, a new module in Teamcenter (i.e., MYITEM) may register a set of internal handlers for creating a relation of type reference to ensure that the primary object is either an item or an item revision.

The System Administrator of an installation could also register handlers using the user exit USER_register_handlers to enforce the rule that the user must be the owner of the item or item revision to allow the creation of such a relation. Additionally, an ITK program can register another set of handlers to enforce the rule that the secondary object cannot be another item or item revision.

For multi-level handlers, the order of execution is as follows:

internal pre-condition handler
user exit pre-condition handler
ITK program pre-condition handler
internal pre-action handler
user exit pre-action handler
ITK program pre-action handler
base action (the main operation performed by Teamcenter)
internal post-action handler
user exit post-action handler
ITK program post-action handler

If a handler that executes first returns an error condition, then the other registered handlers will not execute. For example, if the internal pre-condition handler returns an error, none of the other handlers will execute; this includes the base action.

Macro Definition Documentation

#define GRM_class_name_c "ImanRelation"

Definition at line 115 of file grm.h.

#define GRM_relationtype_name_size_c 32

Definition at line 116 of file grm.h.

Typedef Documentation

typedef struct GRM_list_relation_input_s * GRM_list_relation_input_p_t

typedef struct GRM_list_relation_input_s GRM_list_relation_input_t

Provides a list of Primary/Secondary objects and Generic Relationship Management (GRM) Relations to search for.

typedef struct GRM_relation_s * GRM_relation_p_t

typedef struct GRM_relation_s GRM_relation_t

Function Documentation

TCCORE_API int GRM_ask_primary	(	tag_t	relation,
		tag_t *	primary_object
	)

Returns the primary object tag of the specified relation.

Parameters

relation	(I) Tag of the relation
primary_object	(O) Tag of the primary object in the specified relation

TCCORE_API int GRM_ask_relation_type	(	tag_t	relation,
		tag_t *	relation_type
	)

Returns the relation type of the specified relation.

Parameters

relation	(I) Tag of the relation
relation_type	(O) Tag of the relation type in the specified relation

TCCORE_API int GRM_ask_secondary	(	tag_t	relation,
		tag_t *	secondary_object
	)

Returns the secondary object tag of the specified relation.

Parameters

relation	(I) Tag of the relation
secondary_object	(O) Tag of the secondary object in the specified relation

TCCORE_API int GRM_ask_user_data	(	tag_t	relation,
		tag_t *	user_data
	)

Returns the tag of the user data of the specified relation.

Parameters

relation	(I) Tag of the relation
user_data	(O) Tag of the user data the specified relation

TCCORE_API int GRM_create_relation	(	tag_t	primary_object,
		tag_t	secondary_object,
		tag_t	relation_type,
		tag_t	user_data,
		tag_t *	relation
	)

Creates a relation of the specified type.

Restrictions:

The primary_object, secondary_object, and relation_type must all be valid tags. The user_data can be a NULLTAG but if it is not a NULLTAG, then it must be a valid tag. To create the relation in the database, GRM_save_relation must be called after this function. It is highly recommended that GRM_find_relation be called first to determine if the relation already exists before calling this function; otherwise, the attempt to create a duplicate relation will be detected only during GRM_save_relation.

Parameters

primary_object	(I) Direction-setting object in the relation; it is usually the independent object in the relation.
secondary_object	(I) This object is usually the dependent object in the relationship
relation_type	(I) This is a tag of the specified relationship type
user_data	(I) This is a tag that identifies some user data; must be set to NULLTAG if not used.
relation	(O) Tag of new relation, if successfully created.

TCCORE_API int GRM_create_relation_type	(	const char *	relation_type_name,
		tag_t *	relation_type
	)

Creates a new relation type in the system.

Parameters

relation_type_name	(I) Name of relation type
relation_type	(O) Tag of created relation type

TCCORE_API int GRM_delete_relation ( tag_t relation )

Deletes a relation.

Parameters

relation (I) Tag of relation to be deleted

TCCORE_API int GRM_delete_relation_type ( tag_t relation_type )

Deletes a relation type from the system.

Parameters

relation_type (I) Tag of relation type to be deleted

TCCORE_API int GRM_find_relation	(	tag_t	primary_object,
		tag_t	secondary_object,
		tag_t	relation_type,
		tag_t *	relation
	)

Looks for a relation and returns its tag if it exists.

Restrictions:

None of the input parameters can be a NULLTAG and all should be valid tags.

Parameters

primary_object	(I) Direction-setting object in the relation; it is usually the independent object in the relation.
secondary_object	(I) This object is usually the dependent object in the relationship
relation_type	(I) This is a tag of the specified relationship type; this cannot be a NULLTAG.
relation	(O) Tag of the relation, if found.

TCCORE_API int GRM_find_relation_type	(	const char *	relation_type_name,
		tag_t *	relation_type
	)

Returns the relation type tag specifying the name of the relation type.

Parameters

relation_type_name	(I) Name of relation type to find. Set to NULLTAG if no relation type matching the given name was found.
relation_type	(O) Tag of relation type

TCCORE_API int GRM_list_all_related_objects	(	tag_t	match_object,
		int *	count,
		GRM_relation_t **	related_object_list
	)

Returns a list and count of all objects (both primary and secondary) that are related to the specified match_object.

Parameters

match_object	(I) Tag of object to use for matching
count	(O) Number of objects found
related_object_list	(OF) count List of tag quadruplet {primary, secondary, relation_type, user_data} as defined by the structure GRM_relation_t.

TCCORE_API int GRM_list_all_related_objects_only	(	tag_t	match_object,
		int *	count,
		tag_t **	related_objects
	)

Returns a list and count of all objects (both primary and secondary) that are related to the specified match_object. Differs from GRM_list_all_related_objects in that it returns only the objects themselves, and does not load the relations. This means it is likely to be more efficient than GRM_list_all_related_objects.

Parameters

match_object	(I) Tag of object to use for matching
count	(O) Number of objects found
related_objects	(OF) count Array of related_object found

TCCORE_API int GRM_list_primary_objects	(	tag_t	secondary_object,
		tag_t	relation_type,
		int *	count,
		GRM_relation_t **	primary_list
	)

Returns a list and count of all primary objects with a specified relation type to the specified secondary_object.

Parameters

secondary_object	(I) Tag of secondary object to search for
relation_type	(I) Tag of relation type to search for; NULLTAG means all relation types.
count	(O) Number objects found
primary_list	(OF) count List of tag quadruplet {primary_object, secondary_object, relation_type, user_data} as defined by the structure GRM_relation_t.

TCCORE_API int GRM_list_primary_objects_in_bulk	(	int	input_count,
		const GRM_list_relation_input_t *	inputs,
		int *	count,
		GRM_relation_t **	primary_list
	)

Retrieves in bulk the list of all primary objects with a specified relation types to the specified secondary objects.

Returns

ITK_ok on success.
GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
GRM_invalid_set_of_arguments if any of the input arguments are invalid.

Parameters

input_count	(I) Number of structures to use for the search
inputs	(I) input_count List of search structures, which contain the primary, secondary objects and GRM relations
count	(O) Number of objects found
primary_list	(OF) count List of GRM_relation_t structures {which contains a tag quadruplet: primary, secondary, relation_type, user_data).

TCCORE_API int GRM_list_primary_objects_only	(	tag_t	secondary_object,
		tag_t	relation_type,
		int *	count,
		tag_t **	primary_objects
	)

Returns a list and count of all primary objects with a specified relation type to the specified secondary object. Differs from GRM_list_primary_objects in that it returns only the objects themselves, and does not load the relations. This means it is likely to be more efficient than GRM_list_primary_objects.

Parameters

secondary_object	(I) Tag of secondary object to search for
relation_type	(I) Tag of relation type to search for; NULLTAG means all relation types.
count	(O) Number of objects found
primary_objects	(OF) count Array of primary objects found

TCCORE_API int GRM_list_primary_objects_with_primary_object_type_only	(	tag_t	secondary_object,
		tag_t	relation_type,
		const char *	primary_type_name,
		int *	count,
		tag_t **	primary_objects
	)

Retrieves the list and count of all objects of specified primary object type with a specified relation type to the specified secondary object.
This function differs form GRM_list_primary_objects_only in that it returns only the objects of specified type, and does not load the relations.

This function returns:

ITK_ok on success.
TYPE_unknown_type, if the specified primary object type does not exist.

Parameters

secondary_object	(I) Tag of secondary object used for the search
relation_type	(I) Tag of relation type used for the search. Provide NULLTAG in order to look for all relation types
primary_type_name	(I) Name of primary object type used for the search
count	(O) Number of found objects
primary_objects	(OF) count Array of found primary objects

TCCORE_API int GRM_list_relation_types	(	int *	count,
		tag_t **	relation_type_list
	)

Returns the tags of all relation types in the system.

Parameters

count	(O) Count of relation types in system
relation_type_list	(OF) count Tag list of relation types in system

TCCORE_API int GRM_list_relations	(	tag_t	primary_object,
		tag_t	secondary_object,
		tag_t	relation_type,
		tag_t	user_data,
		int *	count,
		tag_t **	relation_list
	)

Returns a list and count of all relations which satisfy the search criteria as defined by the input parameters. Each input tag can be a NULLTAG, which effectively acts as a wildcard identifier; for example, if the relation type is a NULLTAG, then it means match all relation types. If all the input are NULLTAG, then all relations in the system will be returned.

Parameters

primary_object	(I) Tag of primary object to be searched for
secondary_object	(I) Tag of secondary object to be searched for
relation_type	(I) Tag of relation type to be searched for
user_data	(I) Tag of user data to be searched for
count	(O) Number of objects found
relation_list	(OF) count List of tags of all relations that match the search

TCCORE_API int GRM_list_secondary_objects	(	tag_t	primary_object,
		tag_t	relation_type,
		int *	count,
		GRM_relation_t **	secondary_list
	)

Returns a list and count of all secondary objects with a specified relation type to the specified primary object.

Parameters

primary_object	(I) Tag of primary object to search for
relation_type	(I) Tag of relation type to search for; NULLTAG means all relation types.
count	(O) Number of objects found
secondary_list	(OF) count List of tag quadruplet (primary, secondary, relation_type, user_data) as defined by the structure GRM_relation_t.

TCCORE_API int GRM_list_secondary_objects_in_bulk	(	int	input_count,
		const GRM_list_relation_input_t *	inputs,
		int *	count,
		GRM_relation_t **	secondary_list
	)

Retrieves in bulk the list of all secondary objects with a specified relation types to the specified primary objects.

Returns

ITK_ok on success.
GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
GRM_invalid_set_of_arguments if any of the input arguments are invalid.

Parameters

input_count	(I) Number of structures to use for the search
inputs	(I) input_count List of search structures, which contain the primary, secondary objects and GRM relations
count	(O) Number of objects found
secondary_list	(OF) count List of GRM_relation_t structures {which contains a tag quadruplet: primary, secondary, relation_type, user_data).

TCCORE_API int GRM_list_secondary_objects_only	(	tag_t	primary_object,
		tag_t	relation_type,
		int *	count,
		tag_t **	secondary_objects
	)

Returns a list and count of all secondary objects with a specified relation type to the specified primary object. Differs from GRM_list_secondary_objects in that it returns only the objects themselves, and does not load the relations. This means it is likely to be more efficient than GRM_list_secondary_objects.

Parameters

primary_object	(I) Tag of primary object to search for
relation_type	(I) Tag of relation type to search for; NULLTAG means all relation types.
count	(O) Number of objects found
secondary_objects	(OF) count Array of secondary objects found

TCCORE_API int GRM_save_relation ( tag_t relation )

Saves a relation. Before calling save, the object must first be loaded or refreshed for modify.

Parameters

relation (I) Tag of relation to be saved

TCCORE_API int GRM_set_user_data	(	tag_t	relation,
		tag_t	new_user_data
	)

Sets the value of the relation's user data to that of the specified new_user_data.

Restrictions:

The tag supplied in new_user_data can be a NULLTAG. However, if it is not a NULLTAG, then it must be a valid POM tag.

The relation must be locked before this function is called and then later unlocked.

For the new value to be reflected in the database, AOM_save must be called.

Parameters

relation	(I) Tag of the relation
new_user_data	(I) Tag of the new user data

Modules

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation