You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
508 lines
25 KiB
508 lines
25 KiB
/*==============================================================================
|
|
Copyright (c) 2003-2005 UGS Corporation
|
|
Unpublished - All Rights Reserved
|
|
==============================================================================*/
|
|
|
|
/**
|
|
@file
|
|
|
|
This header file declares all data types and constants to be used by clients of the GRM module
|
|
*/
|
|
|
|
/* */
|
|
|
|
#ifndef GRM_H
|
|
#define GRM_H
|
|
|
|
#include <tccore/grm_errors.h>
|
|
#include <fclasses/tc_basic.h>
|
|
#include <stdarg.h>
|
|
#include <common/tc_deprecation_macros.h>
|
|
#include <tccore/libtccore_exports.h>
|
|
|
|
/**
|
|
@defgroup GRM Generic Relationship Manager (GRM)
|
|
|
|
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.
|
|
|
|
<b>Common Return Values</b>
|
|
|
|
<table>
|
|
<tr><td>Return Value </td><td>Description </td></tr>
|
|
<tr><td>#CXPOM_invalid_tag </td><td>Invalid tag supplied. </td></tr>
|
|
<tr><td>#GRM_duplicate_relation_type </td><td>The type you propose to create already exists in the system.</td></tr>
|
|
<tr><td>#GRM_internal_error </td><td>The GRM module has detected an internal inconsistency and
|
|
therefore should not be used. </td></tr>
|
|
<tr><td>#GRM_invalid_primary_object </td><td>Specified tag for the primary_object is not valid. </td></tr>
|
|
<tr><td>#GRM_invalid_relation_type </td><td>Specified tag for relation_type is not valid. </td></tr>
|
|
<tr><td>#GRM_invalid_secondary_object</td><td>Specified tag for the secondary_object is not valid. </td></tr>
|
|
<tr><td>#GRM_invalid_user_data </td><td>Specified tag for user_data is not valid. </td></tr>
|
|
<tr><td>#GRM_not_initialized </td><td>The GRM module was not initialized. </td></tr>
|
|
<tr><td>#GRM_relation_already_exists </td><td>The relation being saved already exists. </td></tr>
|
|
<tr><td>#GRM_relation_does_not_exist </td><td>Relation does not exist. </td></tr>
|
|
<tr><td>#GRM_undefined_relation_type </td><td>The type you propose to delete does not exist. </td></tr>
|
|
</table>
|
|
|
|
<b>Returned Tag Structure</b>
|
|
|
|
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:
|
|
|
|
<table>
|
|
<tr><td>structure_name.primary </td><td>To reference the primary object. </td></tr>
|
|
<tr><td>structure_name.secondary </td><td>To reference the secondary object.</td></tr>
|
|
<tr><td>structure_name.relation_type</td><td>To reference the relation type. </td></tr>
|
|
<tr><td>structure_name.user_data </td><td>To reference the user data. </td></tr>
|
|
</table>
|
|
|
|
<b>Constraint Handler Registration and Execution</b>
|
|
|
|
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.
|
|
|
|
<b>Multi-Level Handlers</b>
|
|
|
|
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:
|
|
<ol>
|
|
<li>internal pre-condition handler
|
|
<li>user exit pre-condition handler
|
|
<li>ITK program pre-condition handler
|
|
<li>internal pre-action handler
|
|
<li>user exit pre-action handler
|
|
<li>ITK program pre-action handler
|
|
<li>base action (the main operation performed by Teamcenter)
|
|
<li>internal post-action handler
|
|
<li>user exit post-action handler
|
|
<li>ITK program post-action handler
|
|
</ol>
|
|
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.
|
|
|
|
@{
|
|
*/
|
|
|
|
#define GRM_class_name_c "ImanRelation"
|
|
#define GRM_relationtype_name_size_c 32
|
|
|
|
typedef struct GRM_relation_s
|
|
{
|
|
tag_t the_relation;
|
|
tag_t primary;
|
|
tag_t secondary;
|
|
tag_t relation_type;
|
|
tag_t user_data;
|
|
} GRM_relation_t, *GRM_relation_p_t;
|
|
|
|
/**
|
|
Provides a list of Primary/Secondary objects and Generic Relationship Management (GRM) Relations to search for.
|
|
*/
|
|
typedef struct GRM_list_relation_input_s
|
|
{
|
|
int object_count; /**< Number of primary/secondary objects to search for.*/
|
|
tag_t* objects; /**< object_count The list of such objects.*/
|
|
int relation_type_count; /**< Number of relation types to search for.*/
|
|
tag_t* relation_types; /**< relation_type_count List of relation types.*/
|
|
} GRM_list_relation_input_t, *GRM_list_relation_input_p_t;
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"{
|
|
#endif
|
|
|
|
/**
|
|
Creates a relation of the specified type.
|
|
|
|
<b>Restrictions:</b>
|
|
|
|
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.
|
|
The user_data can be the tag of any valid POM object that the user wants to access through the GRM relation.
|
|
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.
|
|
*/
|
|
extern TCCORE_API int GRM_create_relation(
|
|
tag_t primary_object, /**< (I) Direction-setting object in the relation;
|
|
it is usually the independent object in the relation. */
|
|
tag_t secondary_object, /**< (I) This object is usually the dependent object in the relationship */
|
|
tag_t relation_type, /**< (I) This is a tag of the specified relationship type */
|
|
tag_t user_data, /**< (I) This is a tag that identifies some user data; must be set to #NULLTAG if not used. */
|
|
tag_t* relation /**< (O) Tag of new relation, if successfully created. */
|
|
);
|
|
|
|
/**
|
|
Saves a relation.
|
|
Before calling save, the object must first be loaded or refreshed for modify.
|
|
*/
|
|
extern TCCORE_API int GRM_save_relation(
|
|
tag_t relation /**< (I) Tag of relation to be saved */
|
|
);
|
|
|
|
/**
|
|
Deletes a relation.
|
|
*/
|
|
extern TCCORE_API int GRM_delete_relation(
|
|
tag_t relation /**< (I) Tag of relation to be deleted */
|
|
);
|
|
|
|
/**
|
|
Looks for a relation and returns its tag if it exists.
|
|
|
|
<b>Restrictions:</b>
|
|
|
|
None of the input parameters can be a #NULLTAG and all should be valid tags.
|
|
*/
|
|
extern TCCORE_API int GRM_find_relation(
|
|
tag_t primary_object, /**< (I) Direction-setting object in the relation;
|
|
it is usually the independent object in the relation. */
|
|
tag_t secondary_object, /**< (I) This object is usually the dependent object in the relationship */
|
|
tag_t relation_type, /**< (I) This is a tag of the specified relationship type; this cannot be a #NULLTAG. */
|
|
tag_t* relation /**< (O) Tag of the relation, if found. */
|
|
);
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
extern TCCORE_API int GRM_list_relations(
|
|
tag_t primary_object, /**< (I) Tag of primary object to be searched for */
|
|
tag_t secondary_object, /**< (I) Tag of secondary object to be searched for */
|
|
tag_t relation_type, /**< (I) Tag of relation type to be searched for */
|
|
tag_t user_data, /**< (I) Tag of user data to be searched for */
|
|
int* count, /**< (O) Number of objects found */
|
|
tag_t** relation_list /**< (OF) count List of tags of all relations that match the search */
|
|
);
|
|
|
|
/**
|
|
Returns a list and count of all secondary objects with a specified relation type to the specified primary object.
|
|
*/
|
|
extern TCCORE_API int GRM_list_secondary_objects(
|
|
tag_t primary_object, /**< (I) Tag of primary object to search for */
|
|
tag_t relation_type, /**< (I) Tag of relation type to search for; #NULLTAG means all relation types. */
|
|
int* count, /**< (O) Number of objects found */
|
|
GRM_relation_t** secondary_list /**< (OF) count List of tag quadruplet
|
|
(primary, secondary, relation_type, user_data)
|
|
as defined by the structure #GRM_relation_t. */
|
|
);
|
|
|
|
/**
|
|
Retrieves in bulk the list of all secondary objects with a specified relation types to the specified primary objects.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
|
|
<li>#GRM_invalid_set_of_arguments if any of the input arguments are invalid.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_list_secondary_objects_in_bulk(
|
|
int input_count, /**< (I) Number of structures to use for the search */
|
|
const GRM_list_relation_input_t* inputs, /**< (I) input_count List of search structures, which contain the primary objects and GRM relations */
|
|
int* count, /**< (O) Number of objects found */
|
|
GRM_relation_t** secondary_list /**< (OF) count List of #GRM_relation_t structures
|
|
{which contains a tag quadruplet: primary, secondary, relation_type, user_data). */
|
|
);
|
|
|
|
/**
|
|
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 <b>does not load the relations</b>.
|
|
This means it is likely to be more efficient than #GRM_list_secondary_objects.
|
|
*/
|
|
extern TCCORE_API int GRM_list_secondary_objects_only(
|
|
tag_t primary_object, /**< (I) Tag of primary object to search for */
|
|
tag_t relation_type, /**< (I) Tag of relation type to search for;
|
|
#NULLTAG means all relation types. */
|
|
int* count, /**< (O) Number of objects found */
|
|
tag_t** secondary_objects /**< (OF) count Array of secondary objects found */
|
|
);
|
|
|
|
/**
|
|
Returns a list and count of all primary objects with a specified relation type to the specified secondary_object.
|
|
*/
|
|
extern TCCORE_API int GRM_list_primary_objects(
|
|
tag_t secondary_object, /**< (I) Tag of secondary object to search for */
|
|
tag_t relation_type, /**< (I) Tag of relation type to search for; #NULLTAG means all relation types. */
|
|
int* count, /**< (O) Number objects found */
|
|
GRM_relation_t** primary_list /**< (OF) count List of tag quadruplet
|
|
{primary_object, secondary_object, relation_type, user_data}
|
|
as defined by the structure #GRM_relation_t. */
|
|
);
|
|
|
|
/**
|
|
Retrieves in bulk the list of all primary objects with a specified relation types to the specified secondary objects.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
|
|
<li>#GRM_invalid_set_of_arguments if any of the input arguments are invalid.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_list_primary_objects_in_bulk(
|
|
int input_count, /**< (I) Number of structures to use for the search */
|
|
const GRM_list_relation_input_t* inputs, /**< (I) input_count List of search structures, which contain the secondary objects and GRM relations */
|
|
int* count, /**< (O) Number of objects found */
|
|
GRM_relation_t** primary_list /**< (OF) count List of #GRM_relation_t structures
|
|
{which contains a tag quadruplet: primary, secondary, relation_type, user_data). */
|
|
);
|
|
|
|
/**
|
|
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 <b>does not load the relations</b>.
|
|
This means it is likely to be more efficient than #GRM_list_primary_objects.
|
|
*/
|
|
extern TCCORE_API int GRM_list_primary_objects_only(
|
|
tag_t secondary_object, /**< (I) Tag of secondary object to search for */
|
|
tag_t relation_type, /**< (I) Tag of relation type to search for;
|
|
#NULLTAG means all relation types. */
|
|
int* count, /**< (O) Number of objects found */
|
|
tag_t** primary_objects /**< (OF) count Array of primary objects found */
|
|
);
|
|
|
|
/**
|
|
Retrieves the list and count of all objects of the specified primary object type with a
|
|
specified relation type to the specified secondary object.
|
|
<br>This function differs from #GRM_list_primary_objects_only in that it returns only objects of the specified type,
|
|
and <b>does not load the relations</b>. A NULL relation_type means all relatoin types. If the secondary_object
|
|
is NULL or invalid, the function will return nothing.
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#TYPE_unknown_type if the specified primary object type does not exist.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_list_primary_objects_with_primary_object_type_only(
|
|
tag_t secondary_object, /**< (I) Tag of secondary object used for the search */
|
|
tag_t relation_type, /**< (I) Tag of relation type used for the search. Provide #NULLTAG in order to look for all relation types */
|
|
const char* primary_type_name, /**< (I) Name of primary object type used for the search */
|
|
int* count, /**< (O) Number of found objects */
|
|
tag_t** primary_objects /**< (OF) count Array of found primary objects */
|
|
);
|
|
|
|
/**
|
|
Retrieves the list of all objects (both primary and secondary) that are related to the specified object.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
|
|
<li>#GRM_internal_error if the input object is #NULLTAG or an invalid tag.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_list_all_related_objects(
|
|
tag_t object, /**< (I) The object for which related objects must be retrieved */
|
|
int* count, /**< (O) Number of objects found */
|
|
GRM_relation_t** related_object_list /**< (OF) count List of tag quadruplet
|
|
{primary, secondary, relation_type, user_data}
|
|
as defined by the structure #GRM_relation_t. */
|
|
);
|
|
|
|
/**
|
|
Retrieves the list of all objects (both primary and secondary) that are related to the specified object.
|
|
<br/>It differs from #GRM_list_all_related_objects in that it returns only the objects themselves,
|
|
and <b>does not load the relations</b>.
|
|
<br/>This means it is likely to be more efficient than #GRM_list_all_related_objects.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#GRM_not_initialized if the Generic Relationship Management (GRM) module is not initialized.
|
|
<li>#GRM_internal_error if the input object is #NULLTAG or an invalid tag.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_list_all_related_objects_only(
|
|
tag_t object, /**< (I) The object for which related objects must be retrieved */
|
|
int* count, /**< (O) Number of objects found */
|
|
tag_t** related_objects /**< (OF) count Array of related_object found */
|
|
);
|
|
|
|
/**
|
|
Returns the primary object tag of the specified relation.
|
|
*/
|
|
extern TCCORE_API int GRM_ask_primary(
|
|
tag_t relation, /**< (I) Tag of the relation */
|
|
tag_t* primary_object /**< (O) Tag of the primary object in the specified relation */
|
|
);
|
|
|
|
/**
|
|
Returns the secondary object tag of the specified relation.
|
|
*/
|
|
extern TCCORE_API int GRM_ask_secondary(
|
|
tag_t relation, /**< (I) Tag of the relation */
|
|
tag_t* secondary_object /**< (O) Tag of the secondary object in the specified relation */
|
|
);
|
|
|
|
/**
|
|
Returns the relation type of the specified relation.
|
|
*/
|
|
extern TCCORE_API int GRM_ask_relation_type(
|
|
tag_t relation, /**< (I) Tag of the relation */
|
|
tag_t* relation_type /**< (O) Tag of the relation type in the specified relation */
|
|
);
|
|
|
|
/**
|
|
Returns the tag of the user data of the specified relation.
|
|
*/
|
|
extern TCCORE_API int GRM_ask_user_data(
|
|
tag_t relation, /**< (I) Tag of the relation */
|
|
tag_t* user_data /**< (O) Tag of the user data the specified relation */
|
|
);
|
|
|
|
/**
|
|
Sets the value of the relation's user data to that of the specified new_user_data.
|
|
|
|
<b>Restrictions:</b>
|
|
|
|
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.
|
|
*/
|
|
extern TCCORE_API int GRM_set_user_data(
|
|
tag_t relation, /**< (I) Tag of the relation */
|
|
tag_t new_user_data /**< (I) Tag of the new user data */
|
|
);
|
|
|
|
/**
|
|
Returns the tags of all relation types in the system.
|
|
*/
|
|
extern TCCORE_API int GRM_list_relation_types(
|
|
int* count, /**< (O) Count of relation types in system */
|
|
tag_t** relation_type_list /**< (OF) count Tag list of relation types in system */
|
|
);
|
|
|
|
/**
|
|
Retrieves the relation type for the given relation type name.
|
|
@note This API does not return an error if the relation type is not found, for this case @p relation_type would be a #NULLTAG
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok always
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_find_relation_type(
|
|
const char* relation_type_name, /**< (I) Name of relation type to find. */
|
|
tag_t* relation_type /**< (O) Tag of relation type.
|
|
<br\>This will be a #NULLTAG if no relation type is found for @p relation_type_name. */
|
|
);
|
|
|
|
/**
|
|
@deprecated #GRM_create_relation_type deprecated in Teamcenter 12.4.
|
|
<br/>A relation type should be created in BMIDE.
|
|
|
|
Creates a new relation type in the system.
|
|
*/
|
|
TC_DEPRECATED_NO_REPLACEMENT( "12.4", "GRM_create_relation_type")
|
|
extern TCCORE_API int GRM_create_relation_type(
|
|
const char* relation_type_name, /**< (I) Name of relation type */
|
|
tag_t* relation_type /**< (O) Tag of created relation type */
|
|
);
|
|
|
|
/**
|
|
Deletes a relation type from the system.
|
|
*/
|
|
extern TCCORE_API int GRM_delete_relation_type(
|
|
tag_t relation_type /**< (I) Tag of relation type to be deleted */
|
|
);
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
Creates a relation of the specified type and Copy Stable ID.
|
|
|
|
<b>Restrictions:</b>
|
|
|
|
The primary_object, secondary_object, and relation_type must all be valid tags.
|
|
<br/>If the Copy Stable ID is NULL, a Copy Stable Id will be generated by the system.
|
|
<br/>The user_data can be a #NULLTAG but if it is not a #NULLTAG, then it must be a valid tag.
|
|
<br/>The user_data can be the tag of any valid POM object that the user wants to access through the GRM relation.
|
|
<br/>To create the relation in the database, #GRM_save_relation must be called after this function.
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#TYPE_unknown_type if the Relation type name is invalid.
|
|
<li>#GRM_relation_already_exists if the Relation already exists between the primary and secondary.
|
|
<li>#GRM_duplicate_copy_stable_relation if a Relation already exists for the primary with the copy stable id.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_create_copy_stable_relation(
|
|
tag_t primary_object, /**< (I) Tag of primary object on the relation. */
|
|
tag_t secondary_object, /**< (I) Tag of secondary object on the relation. */
|
|
const char * relation_type, /**< (I) Name of the relation type. */
|
|
tag_t user_data, /**< (I) Tag of the user data attached to the relation.*/
|
|
const char * copy_stable_id, /**< (I) String Copy Stable Identifier */
|
|
tag_t* relation /**< (O) Tag of the new relation. */
|
|
);
|
|
|
|
/**
|
|
Returns a list and count of all relations which satisfy the search criteria as defined by the input parameters.
|
|
|
|
<b>Restrictions:</b>
|
|
When a value is not supplied for an input paramenter it acts as a wildcard;
|
|
<br/>for example, if the relation type is #NULLTAG, all relation types will be returned.
|
|
<br/>A value must be supplied for at least one of the input parameters.
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success.
|
|
<li>#GRM_invalid_set_of_arguments if at least one of the input paramaters is not supplied.
|
|
</ul>
|
|
*/
|
|
extern TCCORE_API int GRM_find_copy_stable_relations(
|
|
tag_t primary_object, /**< (I) Tag of primary object on the relation. */
|
|
tag_t secondary_object, /**< (I) Tag of secondary object on the relation. */
|
|
const char* copy_stable_id, /**< (I) String Copy Stable Identifier */
|
|
tag_t relation_type, /**< (I) Name of the relation type. */
|
|
tag_t user_data, /**< (I) Tag of the user data attached to the relation.*/
|
|
int* count, /**< (O) Number of relations matching the criteria. */
|
|
tag_t** relation_list /**< (OF) Tags of the relations matching the criteria */
|
|
);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#include <tccore/libtccore_undef.h>
|
|
|
|
#endif
|