Main Page | Modules | Files | Functions | Code Elements | Data Structures | Deprecated

Methods

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).

Modules

Data Structures

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.

METHOD Registration Functions

Defines

Typedefs

Enumerations

Functions

Define Documentation

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

Definition at line 480 of file method.h.

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

Definition at line 482 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 462 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

typedef struct METHOD_message_s METHOD_message_t

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_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)