Methods

Modules
	Canned Methods

Data Structures
struct	METHOD_id_s
struct	METHOD_message_s

Macros
#define	METHOD_PROP_MESSAGE_OBJECT(msg, objectTag)   (objectTag) = (msg)->object_tag;
#define	METHOD_PROP_MESSAGE_PROP_NAME(msg, propName)   (propName) = (msg)->prop_name;
#define	METHOD_SETUP_PROP_MESSAGE(msg_name, property_name, msg_id)

Typedefs
typedef enum METHOD_action_type_e	METHOD_action_type_t
typedef int(*	METHOD_function_t )(METHOD_message_t *, va_list)
typedef struct METHOD_id_s	METHOD_id_t
typedef struct METHOD_message_s	METHOD_message_t

Enumerations
enum	METHOD_action_type_e { METHOD_pre_action_type, METHOD_post_action_type }

Functions
TCCORE_API int	METHOD__is_prop_registered (tag_t objTag, const char *methodName, const char *propName, logical *registered)
TCCORE_API int	METHOD__register_operationFn (const char *type_name, const char *msg_name, METHOD_function_t base_action, TC_argument_list_t *user_args, METHOD_id_t *method_id)
TCCORE_API int	METHOD__register_prop_operationFn (const char *type_name, const char *property_name, const char *msg_name, METHOD_function_t base_action, TC_argument_list_t *user_args, METHOD_id_t *method_id)
TCCORE_API int	METHOD_call_post_action (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_call_post_action_message (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_call_pre_action (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_call_pre_action_message (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_check_pre_conditions (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_check_pre_conditions_message (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_execute (tag_t object, int msg_id,...)
TCCORE_API int	METHOD_execute_using (tag_t object, tag_t tc_type, int msg_id,...)
TCCORE_API int	METHOD_find_prop_method (const char *type_name, const char *property_name, const char *msg_name, METHOD_id_t *method_id)
TCCORE_API int	METHOD_get_message_property_descriptor (const METHOD_message_t *message, tag_t *property_descriptor)
TCCORE_API int	METHOD_get_prop_message_id (const char *msg_name, const char *property_name, int *msg_id)
TCCORE_API int	METHOD_merge_prop_message_id (int merge_msg_id, const char *property_name, int *msg_id)
TCCORE_API int	METHOD_register_prop_method (const char *type_name, const char *property_name, const char *msg_name, METHOD_function_t base_action, TC_argument_list_t *user_args, METHOD_id_t *method_id)

METHOD Execution Functions
Note Execution of registered methods is implemented in Teamcenter core code for all Teamcenter defined messages. ITK is only only required to define custom messages.
TCCORE_API int	METHOD_get_message_id (const char *msg_name, int *msg_id)
TCCORE_API int	METHOD_get_message_name (int msg_id, char **method_name)
TCCORE_API int	METHOD_get_prop_message_name (int msg_id, const char *property_name, char **method_name)
#define	METHOD_SETUP_MESSAGE(msg_name, msg_id)

METHOD Registration Functions
TCCORE_API int	METHOD_attach_action (const char *typeName, const char *methodName, int prePostFlag, METHOD_function_t fn, TC_argument_list_t *userData)
TCCORE_API int	METHOD_register_method (const char *type_name, const char *msg_name, METHOD_function_t base_action, TC_argument_list_t *user_args, METHOD_id_t *method_id)
TCCORE_API int	METHOD_add_pre_condition (METHOD_id_t method_id, METHOD_function_t pre_condition_handler, TC_argument_list_t *user_args)
TCCORE_API int	METHOD_add_action (METHOD_id_t method_id, METHOD_action_type_t action_type, METHOD_function_t action_handler, TC_argument_list_t *user_args)
TCCORE_API int	METHOD_add_action2 (METHOD_id_t method_id, METHOD_action_type_t action_type, METHOD_function_t action_handler, TC_argument_list_t *user_args, logical auto_dispatched)
TCCORE_API int	METHOD_find_method (const char *type_name, const char *msg_name, METHOD_id_t *method_id)
TCCORE_API int	METHOD_find_dynamic_method (const char *type_name, const char *msg_name, METHOD_id_t *method_id)

Detailed Description

Methods control the behavior of Teamcenter objects. Methods are registered for combinations of object type and message (save, create, etc). The ITK allows additional control of primary Teamcenter types and custom types.

Methods' ITK functions are logically grouped and presented in this topic as follows:

Prototypes for methods functions are found in the method.h header file

Teamcenter system messages (e.g., save, delete) are defined with their arguments in tc_msg.h

Module-specific messages are defined in <module>_msg.h, (e.g., ITEM_create_msg is defined in item_msg.h).

Macro Definition Documentation

#define METHOD_PROP_MESSAGE_OBJECT	(		msg,
			objectTag
	)		(objectTag) = (msg)->object_tag;

Definition at line 498 of file method.h.

#define METHOD_PROP_MESSAGE_PROP_NAME	(		msg,
			propName
	)		(propName) = (msg)->prop_name;

Definition at line 500 of file method.h.

#define METHOD_SETUP_MESSAGE	(		msg_name,
			msg_id
	)

Value:

static int  (msg_id) = 0;                                                           \
if ( (msg_id) == 0 )                                                                \
{                                                                                   \
    int  setup_err = METHOD_get_message_id( (msg_name), &(msg_id) );                \
    if ( setup_err != ITK_ok )                                                      \
    {                                                                               \
        TC_write_syslog ("No method defined for message name '%s'\n", msg_name);  \
        EMH_store_error( EMH_severity_error, setup_err );                           \
        return setup_err;                                                           \
    }                                                                               \
}

This macro can be used to setup a static message id in your routines to save repeated lookups. Note that if lookup fails it will cause the function you are invoking it from to return an ifail code: so your function must be returning an int.

Definition at line 125 of file method.h.

#define METHOD_SETUP_PROP_MESSAGE	(		msg_name,
			property_name,
			msg_id
	)

Value:

static int  (msg_id) = 0;                                                                   \
if ( (msg_id) == 0 )                                                                        \
{                                                                                           \
    int setup_err = METHOD_get_prop_message_id( (msg_name), (property_name), &(msg_id) );   \
    if ( setup_err != ITK_ok ) return setup_err;                                            \
    else if ((msg_id) == 0)                                                                 \
{ TC_write_syslog ("File %s; Line # %d; no message '%s' registered for property '%s'",    \
                     __FILE__, __LINE__, (msg_name), (property_name));                      \
        return ITK_general_user_error;                                                      \
      }                                                                                     \
}                                                                                           \
else                                                                                        \
{                                                                                           \
    int setup_err = METHOD_merge_prop_message_id( (msg_id), (property_name), &(msg_id) );   \
    if ( setup_err != ITK_ok ) return setup_err;                                            \
}

This macro can be used to setup a static message id in your routines to save repeated lookups.

Definition at line 480 of file method.h.

Typedef Documentation

typedef enum METHOD_action_type_e METHOD_action_type_t

typedef int(* METHOD_function_t)(METHOD_message_t *, va_list)

All functions registered as base, pre or post actions, or pre condition handlers must be of this type. Return value should be ITK_ok to indicate1 success, or the value of the top error from the error store to indicate failure.

Definition at line 71 of file method.h.

typedef struct METHOD_id_s METHOD_id_t

Identifies a registered method, e.g. to add a pre/post action to it.

typedef struct METHOD_message_s METHOD_message_t

Contextual information passed with a message to a function registered as an action for a method.

Enumeration Type Documentation

enum METHOD_action_type_e

Enumerator
METHOD_pre_action_type
METHOD_post_action_type

Definition at line 76 of file method.h.

Function Documentation

TCCORE_API int METHOD__is_prop_registered	(	tag_t	objTag,
		const char *	methodName,
		const char *	propName,
		logical *	registered
	)

TCCORE_API int METHOD__register_operationFn	(	const char *	type_name,
		const char *	msg_name,
		METHOD_function_t	base_action,
		TC_argument_list_t *	user_args,
		METHOD_id_t *	method_id
	)

Parameters

type_name	(I) Name of the Teamcenter type that is registering this method
msg_name	(I) Identifies the message being registered
base_action	(I) Base action function invoked by this method
user_args	(I) List of static arguments that pass values to every invocation of the base action in this session
method_id	(O) Identifies the newly registered method (e.g., add pre- or post-actions, add a pre-condition)

TCCORE_API int METHOD__register_prop_operationFn	(	const char *	type_name,
		const char *	property_name,
		const char *	msg_name,
		METHOD_function_t	base_action,
		TC_argument_list_t *	user_args,
		METHOD_id_t *	method_id
	)

Parameters

type_name	(I) Name of the Teamcenter type for which this method is being registered
property_name	(I) Identifies the message being registered
msg_name	(I) Name of the property for which this method is being registered
base_action	(I) Base action function invoked by this method
user_args	(I) List of static arguments that pass values to every invocation of the base action in this session
method_id	(O) Identifies the newly registered method (e.g., add pre- or post-actions, add a pre-condition)

TCCORE_API int METHOD_add_action	(	METHOD_id_t	method_id,
		METHOD_action_type_t	action_type,
		METHOD_function_t	action_handler,
		TC_argument_list_t *	user_args
	)

Adds a pre- or post- action to an existing method. These will be executed before and after the base action, respectively.

Parameters

method_id	(I) Identifies the method that the action will be added to
action_type	(I) METHOD_pre_action_type or METHOD_post_action_type
action_handler	(I) Pre- or post- action function
user_args	(I) List of static arguments whose values are passed to every invocation of this action in this session

TCCORE_API int METHOD_add_action2	(	METHOD_id_t	method_id,
		METHOD_action_type_t	action_type,
		METHOD_function_t	action_handler,
		TC_argument_list_t *	user_args,
		logical	auto_dispatched
	)

Adds a pre- or post- action to an existing method. These will be executed before and after the base action, respectively.

Additional logical input argument: auto_dispatched is used to specify if the post-action function attached to the create message of Item, ItemRevision, ImanRelation and Dataset is not auto-dispatched as post-action on save operation.

Parameters

method_id	(I) Identifies the method that the action will be added to
action_type	(I) METHOD_pre_action_type or METHOD_post_action_type
action_handler	(I) Pre- or post- action function
user_args	(I) List of static arguments whose values are passed to every invocation of this action in this session
auto_dispatched	(I) true if method is to be autodispatced to save operation

TCCORE_API int METHOD_add_pre_condition	(	METHOD_id_t	method_id,
		METHOD_function_t	pre_condition_handler,
		TC_argument_list_t *	user_args
	)

Registers the given function as a pre-condition handler for this method. This function should check entry conditions for the method, returning ITK_ok if it is OK to proceed and execute the actions.

Parameters

method_id	(I) Identifies the method that a pre-condition will be added to
pre_condition_handler	(I) Pre-condition handler function
user_args	(I) List of static arguments whose values are passed to every invocation of this pre-condition in this session

TCCORE_API int METHOD_attach_action	(	const char *	typeName,
		const char *	methodName,
		int	prePostFlag,
		METHOD_function_t	fn,
		TC_argument_list_t *	userData
	)

This ITK can only be used to add pre/post on meta operation not for legacy operations The existing APIs have to be used to add pre/post for legacy operations and should not be used to add meta operations. Valid value for prePostFlag are follows: 1 for pre-condition 2 for pre-action 3 for post_action

Parameters

typeName	(I) Name of the Teamcenter type
methodName	(I) Name of the meta operation
prePostFlag	(I) Type of the meta operation
fn	(I) condition handler function
userData	(I) List of static arguments that pass values to every invocation of the condition handler function in this session

TCCORE_API int METHOD_call_post_action	(	tag_t	object,
		int	msg_id,
			...
	)

Enables calling post action method without calling the base method itself.

Parameters

object	(I)
msg_id	(I)

TCCORE_API int METHOD_call_post_action_message	(	tag_t	object,
		int	msg_id,
			...
	)

Enables calling post action method without calling the base method itself.

Note

This function is a variation of METHOD_call_post_action but without calling function invoker. Function invoker shall only be used to call legacy extension with new metaframework opertion.

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

Parameters

object	(I)
msg_id	(I)

TCCORE_API int METHOD_call_pre_action	(	tag_t	object,
		int	msg_id,
			...
	)

Enables calling pre action method without calling the base method itself.

Parameters

object	(I) Tag of the object or property that will be passed the message
msg_id	(I) Run-time identifier for the message passed to the object or property

TCCORE_API int METHOD_call_pre_action_message	(	tag_t	object,
		int	msg_id,
			...
	)

Enables calling pre action method without calling the base method itself.

Note

This function is a variation of METHOD_call_pre_action but without calling function invoker. Function invoker shall only be used to call legacy extension with new metaframework opertion.

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

Parameters

object	(I) Tag of the object or property that will be passed the message
msg_id	(I) Run-time identifier for the message passed to the object or property

TCCORE_API int METHOD_check_pre_conditions	(	tag_t	object,
		int	msg_id,
			...
	)

Checks the entry conditions for a method without executing the method.

Note

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

Parameters

object	(I) Tag of the object or property that will be passed the message
msg_id	(I) Run-time identifier for the message passed to the object or property

TCCORE_API int METHOD_check_pre_conditions_message	(	tag_t	object,
		int	msg_id,
			...
	)

Checks the entry conditions for a method without executing the method.

Note

This function is a variation of METHOD_check_pre_conditions but without calling function invoker. Function invoker shall only be used to call legacy extension with new metaframework opertion.

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

Parameters

object	(I) Tag of the object or property that will be passed the message
msg_id	(I) Run-time identifier for the message passed to the object or property

TCCORE_API int METHOD_execute	(	tag_t	object,
		int	msg_id,
			...
	)

Sends a message to an object or property. The specified method will be executed depending on the message and the type of the object or property.

Note

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

If this message does not apply to a specific instance (e.g., create, find) use METHOD_execute_using.

Parameters

object	(I) Tag of the object or property to which you want to pass the message
msg_id	(I) Run-time identifier for the message you want passed to the object or property

TCCORE_API int METHOD_execute_using	(	tag_t	object,
		tag_t	tc_type,
		int	msg_id,
			...
	)

Dispatches a message qualified by an explicit type. The specified method will be executed depending on the message and the type.

Note

This function can operate on an object or a property depending on the method executed. Property methods only operate on properties; other methods operate on objects.

Parameters

object	(I) Tag of the object or property to which you want to pass the message. If this message is not applicable to a specific instance (e.g., create, find) pass NULLTAG.
tc_type	(I) Type to execute the message for
msg_id	(I)

TCCORE_API int METHOD_find_dynamic_method	(	const char *	type_name,
		const char *	msg_name,
		METHOD_id_t *	method_id
	)

Finds the identifer of the message that is programmatically registered at the specified type.

Note

METHOD_find_method should be used to find the identifier of the message or operation that is defined in BMIDE.

Parameters

type_name	(I) Name of the Teamcenter type that is dynamically registering this method
msg_name	(I) Identifies the message for which the method is dynamically registered
method_id	(O) Returns an identifier for the method found

TCCORE_API int METHOD_find_method	(	const char *	type_name,
		const char *	msg_name,
		METHOD_id_t *	method_id
	)

Looks for the registered method used to implement the specified type/message combination. This is useful for registering pre- or post-actions or a pre-condition for a method created elsewhere in the system.

Note

METHOD_find_method will return ITK_ok even if there are no registered methods for the type/message combination. You should perform the check mentioned in the code fragment below, to ascertain if the method is registered for the type/message combination or not.

If method_id.id == 0 , it implies, that we do not have methods implemented on type_name for msg_name

if (method_id.id == 0)
{
    ...this means that the method is not registered for the specified type/message
}

Parameters

type_name	(I) Name of the Teamcenter type that is registering this method
msg_name	(I) Identifies the message for which the method is registered
method_id	(O) Returns an identifier for the method found

TCCORE_API int METHOD_find_prop_method	(	const char *	type_name,
		const char *	property_name,
		const char *	msg_name,
		METHOD_id_t *	method_id
	)

Looks for the registered property method used to implement the specified type/property message combination. This is useful for registering pre- or post-actions or a pre-condition for a method created elsewhere in the system.

Parameters

type_name	(I) Name of the Teamcenter type that is registering this method
property_name	(I) Name of the property for which this method is being registered
msg_name	(I) Identifies the message for which the method is registered
method_id	(O) Returns an identifier for the method found

TCCORE_API int METHOD_get_message_id	(	const char *	msg_name,
		int *	msg_id
	)

A message (e.g., save, delete) is passed to an object in order to execute the method registered for the relevant combination of message and object type. Messages are uniquely defined by a text string, but for efficiency at run-time we use an integer message identifier. This function returns the integer ID associated with the given message name.

The macro METHOD_SETUP_MESSAGE will declare a static int in function, cache the msg_id and look it up on the first pass and return an integer failure code if the lookup failed. This will save time by eliminating the need to look up the msg_id each time a message is dispatched.

Parameters

msg_name	(I) Text identifier for the message, as defined in a <module>_msg.h include file
msg_id	(O) Run-time identifier for the message

TCCORE_API int METHOD_get_message_name	(	int	msg_id,
		char **	method_name
	)

TCCORE_API int METHOD_get_message_property_descriptor	(	const METHOD_message_t *	message,
		tag_t *	property_descriptor
	)

Retrieves the property descriptor embedded in the METHOD_message_t message.

Note

This function is a variation of METHOD_PROP_MESSAGE_OBJECT or METHOD_PROP_MESSAGE_PROP_NAME which retrieves other information embedded in the METHOD_message_t message.

Returns

• ITK_ok on success.
  If no property descriptor can be found, the returned parameter property_descriptor is NULLTAG.
• METHOD_invalid_type if an invalid value is provided for the message parameter.

Parameters

message	(I) The message whose contextual information contains the property
property_descriptor	(O) The tag of the property descriptor

TCCORE_API int METHOD_get_prop_message_id	(	const char *	msg_name,
		const char *	property_name,
		int *	msg_id
	)

A property message (e.g., ask, set) is passed to an object in order to execute the method registered for the relevant combination of message, property and object type. Messages are uniquely defined by a text string, but for efficiency at run-time we use an integer message identifier. This function returns the integer ID associated with the given message name.

The macro METHOD_SETUP_PROP_MESSAGE will declare a static int in function, cache the msg_id and look it up on the first pass, and return an integer failure code if the lookup failed. This will save time by eliminating the need to look up the msg_id each time a message is dispatched.

Parameters

msg_name	(I) Text identifier for the message, as defined in a <module>_msg.h include file
property_name	(I) Name of the property associated with the message ID
msg_id	(O) Run-time identifier for the message

TCCORE_API int METHOD_get_prop_message_name	(	int	msg_id,
		const char *	property_name,
		char **	method_name
	)

TCCORE_API int METHOD_merge_prop_message_id	(	int	merge_msg_id,
		const char *	property_name,
		int *	msg_id
	)

This function is here so that we can use it in the macros. Users should use the macro instead of using it directly.

Parameters

merge_msg_id	(I)
property_name	(I)
msg_id	(O)

TCCORE_API int METHOD_register_method	(	const char *	type_name,
		const char *	msg_name,
		METHOD_function_t	base_action,
		TC_argument_list_t *	user_args,
		METHOD_id_t *	method_id
	)

Registers a method base action. The given function becomes the base action used to implement the specified type/message combination.

Note

This function cannot be used to replace the registered base action of a default Teamcenter type. This function can only be used to register base actions for new types.

Parameters

type_name	(I) Name of the Teamcenter type that is registering this method
msg_name	(I) Identifies the message being registered
base_action	(I) Base action function invoked by this method
user_args	(I) List of static arguments that pass values to every invocation of the base action in this session
method_id	(O) Identifies the newly registered method (e.g., add pre- or post-actions, add a pre-condition)

TCCORE_API int METHOD_register_prop_method	(	const char *	type_name,
		const char *	property_name,
		const char *	msg_name,
		METHOD_function_t	base_action,
		TC_argument_list_t *	user_args,
		METHOD_id_t *	method_id
	)

Suppport for Property-specific methods. Registers a property method base action. The given function becomes the base action used to implement the specified type/property/message combination.

Note

In version Tc8 and later, Property Operation should be configured in BMIDE. Please refer to the section: Add a Property Operation in Business Modeler IDE Guide for details.

Parameters

type_name	(I) Name of the Teamcenter type for which this method is being registered
property_name	(I) Identifies the message being registered
msg_name	(I) Name of the property for which this method is being registered
base_action	(I) Base action function invoked by this method
user_args	(I) List of static arguments that pass values to every invocation of the base action in this session
method_id	(O) Identifies the newly registered method (e.g., add pre- or post-actions, add a pre-condition)