Modules
	TE Errors

Macros
#define	TE_CFG_FILE "te.cfg"

#define	TE_LOG_FILE "te.log"

#define	TE_LW "Latest Working"

#define	TE_MAXLINELEN 256

#define	TE_PACK 0

#define	TE_PACK_PREF 2

#define	TE_UNPACK 1

Typedefs
typedef TE_decision(*	TE_handler_t )(char *, tag_t, int)

Enumerations
enum	HandlerTypes { TE_NODE_SELECTOR, TE_REG_HANDLER, TE_ROOT_ENTRY, TE_ROOT_EXIT, TE_AT_NODE, TE_FORWARD_ENTRY, TE_FORWARD_EXIT, TE_REVERSE_ENTRY, TE_REVERSE_EXIT }

enum	Output { TE_LOG, TE_STDOUT, TE_LOGANDSTDOUT }

enum	TE_decision { TE_CONTINUE, TE_STOP, TE_SKIPCHILDREN, TE_GOBACK, TE_SKIP }

Functions
ITK_API int	TE_exit_module (void)

ITK_API int	TE_get_preference (const char sym, char *pref)

ITK_API int	TE_get_preference_list (const char sym, int nofound, char ***stlist)

ITK_API int	TE_get_statistics (int warn_cnt, int skipchild_cnt, int skip_cnt, int total_cnt)

ITK_API int	TE_init_module ()

ITK_API int	TE_node_get_data (int *childnodes, char type[ITEM_desc_size_c])

ITK_API int	TE_node_get_data2 (int childnodes, char *type)

ITK_API int	TE_node_set_type (const char *ntype)

ITK_API int	TE_parentnode_get_data (int childnodes, char type, tag_t tag, int depth)

ITK_API int	TE_parentnode_set_type (const char *ntype)

ITK_API int	TE_PS_fill_and_traverse_tree ()

ITK_API int	TE_PS_fill_tree ()

ITK_API int	TE_PS_get_config_params (char viewtype, char variant, char revrule, char sub)

ITK_API int	TE_PS_get_config_params_with_pack (char viewtype, char variant, char revrule, char alt, int *packstate)

ITK_API int	TE_PS_initialize (const char itemid, const char rev)

ITK_API int	TE_PS_set_config (const char viewtype, const char variant, const char revrule, const char sub)

ITK_API int	TE_PS_set_config_with_pack (const char viewtype, const char variant, const char revrule, const char alt, int packstate)

ITK_API int	TE_PS_traverse_tree ()

ITK_API int	TE_PS_ui_get_data (char itemid[ITEM_id_size_c+1], char itemrev[ITEM_id_size_c+1], char logfile[IMF_filename_size_c+1], char configfile[IMF_filename_size_c+1])

ITK_API int	TE_PS_ui_get_data2 (char itemid, char itemrev, char logfile, char configfile)

ITK_API int	TE_register_node_handler (int handlertype, TE_handler_t afun)

ITK_API int	TE_table_get_float (const char key, float afloat)

ITK_API int	TE_table_store_float (const char *key, float sfloat)

ITK_API int	TE_ui_get_logfile_pointer (FILE **logfileptr)

ITK_API int	TE_ui_increment_warnings ()

ITK_API int	TE_ui_print_message (int output, int warn, int ifail, const char *msg)

ITK_API int	TE_ui_set_configfile (const char *fname)

ITK_API int	TE_ui_set_logfile (const char *fname)

ITK_API int	TE_ui_set_validate_args ()

Detailed Description

The Traversal Engine

The Traversal Engine (TE) is a module that is distributed as a shared library, and as callable subroutines (TE API calls). It is a framework that will enable you to develop utilities that traverse Teamcenter structures such as Product Structure (PS), without the requirement to write a traversal algorithm.

The Traversal Engine allows you to develop Product Structure (PS) traversing applications by providing you with exits for various traversal stages. You can register custom-defined functions at these stages thus achieving common business tasks involving PS traversing without writing traversal algorithms. Also included is a utilty ps_traverse developed using this framework. This utility can be used to generate reports in text format and perform some common actions, such as Transfer Ownership and Apply Release Status for an assembly.

Typical common tasks include:

Generate reports
Release assemblies
Transfer ownership of Teamcenter objects that constitute the product structure

The Traversal Engine manages the traversal, while you are only required to develop simple ITK programs. The Traversal Engine allows you to register these functions at different stages of the traversal. These functions are executed at each node and contain the information of the nodes, which can be processed.

The core module is programmed in Object Oriented Programing (OOP), so the framework can be expanded by adding new classes at a later date, and can also be extended to traverse any Teamcenter structure such as Product Structure or Folders etc. Presently the core module relates to PS only.

A utility $TC_ROOT/bin/ps_traverse has also been developed to demonstrate the use of TE.

Basic Features

The features of the Traversal Engine are:

Representation of the Teamcenter structure as a tree data structure with each node representing the Teamcenter object.
Provides user exits at different stages and allows the registration of user defined functions known as Handlers and Selectors.
Allows the Handlers and Selectors to return statuses that determine the creation of the tree and the traversal direction.
Allows PS configuration through Revision Rules and saved Variant Rule during the creation of the tree.
Allows inputs from the command line and configuration file.
Allows you to store/retrieve float value with a key as a string, typically used for summing up functionality.

Using these features you can develop programs which:

Generate reports
Apply task release
Release assembly /Set assembly precise and other similar tasks

User Exits

User Exits are provided to register Selectors and Handlers, that are executed at different stages of the traversal activity such as creation of the tree, traversing in the forward direction, traversing in the reverse direction etc.

Selectors and Handlers are user-defined functions that need to be developed following a template. These functions return the decisions that determine the traversal direction. These are registered at different stages of the Traversal and are executed during the creation and the traversal of the tree. The Selectors are run during the creation of the tree nodes. These determine the values stored in each node and decide whether a particular branch needs to be traversed or not. The Handlers are run during the tree traversal. The handlers have the information of the node and the information pertaining to the Teamcenter object that the node represents.

Minimum Requirements

You need the following minimum requirements to be able to run the Traversal Engine:

The Teamcenter ITK development environment
To develop new programs in TE, knowledge of writing ITK programs will be required

Installation

To confirm that you have installed TE successfully, check if the following have been added to their respective directories.

Library libitk.<libraryextension> in $ITC_ROOT/lib
ps_traverse in $TC_ROOT/bin
ps_traverse.cfg and te_template_itk_main.c in $TC_ROOT/sample/examples

Developing a Traversal Program

Once you custom develop your Selectors and Handlers by using the ITK functions and the TE API calls, you can compile them into an executable by using the compile and linkitk scripts in the tools $TC_ROOT/sample directory.

API calls are classified into:

Initializing/Terminating calls. TE modules have to be initialized to use any TE Call.
Configure PS. These configure the PS using revision rule or saved variant. View type to traverse also can be specified.
Register Handlers/Selectors. These register the provided the functions as Selector or Handler.
Fill/Traverse. These create the Tree and Traverse the Tree.
User Interface calls. These write messages to the log file and console, and receive input from the configuration file and the command line arguments.

Refer to the header file te.h in the $TC_ROOT/include directory.

Compiling and Linking

Once you have written the new program using the TE API and the Selectors and Handlers, you can use the compile and linkitk scripts in the $TC_ROOT/sample directory as you normally do for an ITK program.

Sample Implementation

The $TC_ROOT/sample/examples/te_template_itk_main.c demonstrate TE functionality. These could be compiled and studied to understand how new utilities can be developed.

Traversal Engine Selectors

One type of Selector called called TE_NODE_SELECTOR is provided in TE, which is executed at each node during the creation of the tree. This determines whether a particular branch needs to be built or not.

The user has to program a Selector similar to the following template:

TE_Decision function_name( char*, tag_t, int );
TE_Decision function_name( char* node_type, tag_t bom_line_tag, int depth )
{
    printf( "Bom Line Tag is %d", bom_line_tag  );
    return CONTINUE ;
}

The first argument is a string set for each node. The second argument is the BOM Line tag for each node of the PS and the third is the depth of the node in the PS.

A TE API call is provided to register this function as the node selector.

Return Statuses for Selectors

TE_CONTINUE - Creation of Tree proceeds normally
TE_STOP - Stops the tree creation
TE_SKIP - Skip this Node and its branch
TE_SKIPCHILDREN - Processes this Node but skips its child nodes
TE_GOBACK - This decision is ignored and TE_CONTINUE is assumed

TE Module Calls

The traverse engine module presents an interface that allows developing programs that do traversal of Teamcenter structures.

The calls will allow you to:

Initialize traversing by setting the top root (this involves PS configuration for PS Traversal)
Register different handlers (possibly associating with Node type)
Start traversal
Retrieve node information
Store, retrieve and process node information
Obtain preferences from configuration file
Display messages to console and log file, to give warnings etc

For the PS traversal utility, calls will be provided for:

PS Configuration (variants, substitutes, pack/unpack settings etc)

If the function call is not successful, the returned integer can be used to get the error message from the EMH module. TE errors and other ITK error codes are also possible.

Common Return Values

TE_initialize_failed - TE initialize failed
TE_PS_initialize_failed - TE PS module not initialize or failed to initialize
TE_file_could_not_be_opened - Specified log/config file could not be opened.
TE_could_not_write_to_file - Could not write to file
TE_set_null_value - Trying to set a null value
TE_could_not_find_sp_item - Could not find specified item
TE_could_not_find_sp_item_rev - Could not find specified revision of the item. Error Notes to Teamcenter logfile
TE_bad_return_status - Bad return status from the handler
TE_node_selector_not_set - Node Selector not set
TE_rt_entry_handler_not_set - Root Entry Handler not set
TE_rt_exit_handler_not_set - Root Exit Handler not set
TE_at_node_handler_not_set - At Node Handler not set
TE_reg_handler_not_set - Registry Handler not set
TE_fw_entry_handler_not_set - Forward Entry Handler not set
TE_fw_exit_handler_not_set - Forward Exit Handler not set
TE_rv_entry_handler_not_set - Reverse Entry Handler not set
TE_rv_exit_handler_not_set - Reverse Exit Handler not set
TE_entry_not_found_inconfig - Entry not found in config file

Macro Definition Documentation

#define TE_CFG_FILE "te.cfg"

Definition at line 249 of file te.h.

#define TE_LOG_FILE "te.log"

Definition at line 248 of file te.h.

#define TE_LW "Latest Working"

Definition at line 247 of file te.h.

#define TE_MAXLINELEN 256

Definition at line 244 of file te.h.

#define TE_PACK 0

Definition at line 254 of file te.h.

#define TE_PACK_PREF 2

Definition at line 256 of file te.h.

#define TE_UNPACK 1

Definition at line 255 of file te.h.

Typedef Documentation

typedef TE_decision( * TE_handler_t)(char *, tag_t, int)

Typdef for TE function pointer

Definition at line 304 of file te.h.

Enumeration Type Documentation

enum HandlerTypes

Types of Handlers

Enumerator
TE_NODE_SELECTOR
TE_REG_HANDLER
TE_ROOT_ENTRY
TE_ROOT_EXIT
TE_AT_NODE
TE_FORWARD_ENTRY
TE_FORWARD_EXIT
TE_REVERSE_ENTRY
TE_REVERSE_EXIT

Definition at line 283 of file te.h.

enum Output

Possible input for TE_ui_print_message()

Enumerator
TE_LOG
TE_STDOUT
TE_LOGANDSTDOUT

Definition at line 273 of file te.h.

enum TE_decision

Traversal Decisions

Enumerator
TE_CONTINUE
TE_STOP
TE_SKIPCHILDREN
TE_GOBACK
TE_SKIP

Definition at line 261 of file te.h.

Function Documentation

ITK_API int TE_exit_module ( void )

Called at the end of the program.

ITK_API int TE_get_preference	(	const char *	sym,
		char **	pref
	)

Same as TE_get_preference_list(), but returns only one entry for the specified token.

Parameters

sym	(I) Required token in config file, which is given as input
pref	(OF) Entry under the given token

ITK_API int TE_get_preference_list	(	const char *	sym,
		int *	nofound,
		char ***	stlist
	)

Gets values from the configuration file specified by the fg=option or the API call. Takes the token as the first argument and returns the number of the entries under this token and the string lists for these entries.

Parameters

sym	(I) Required token in config file, which is given as input
nofound	(O) Number of entries under the given token
stlist	(OF) nofound String list for the entries under the given token

ITK_API int TE_get_statistics	(	int *	warn_cnt,
		int *	skipchild_cnt,
		int *	skip_cnt,
		int *	total_cnt
	)

This function gets the statistics like number of warnings, number of child nodes skipped, number of nodes skipped, number of nodes processed etc.

Parameters

warn_cnt	(O) Count of number of warnings that occurred
skipchild_cnt	(O) Count of number of child nodes skipped
skip_cnt	(O) Count of number of nodes skipped
total_cnt	(O) Count of total number of nodes processed

ITK_API int TE_init_module ( )

Specifies which preferences you want to consider when asking for values.

ITK_API int TE_node_get_data	(	int *	childnodes,
		char	type[ITEM_desc_size_c]
	)

Deprecated:: This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use TE_node_get_data2

Returns the data regarding the node. This returns the nodes number of children. For nodes whose children are to be skipped this is ?. Also returns the node type.

Parameters

childnodes	(O) Number of children for a given node
type	(O) Type of the given node

ITK_API int TE_node_get_data2	(	int *	childnodes,
		char **	type
	)

Returns the data regarding the node. This returns the nodes number of children. For nodes whose children are to be skipped this is ?. Also returns the node type.

Parameters

childnodes	(O) Number of children for a given node
type	(OF) Type of the given node

ITK_API int TE_node_set_type ( const char * ntype )

Sets the node type to that of the argument. This is just an additional attribute for each node.

Parameters

ntype (I) Node type to be set

ITK_API int TE_parentnode_get_data	(	int *	childnodes,
		char *	type,
		tag_t *	tag,
		int *	depth
	)

Returns the data regarding the parent node. Returns the nodes parent number of children, parent node type and parent node depth.

Parameters

childnodes	(O) Number of children for a given node
type	(O) Type of the given node
tag	(O) Tag of the parent node
depth	(O) Depth of the parent node

ITK_API int TE_parentnode_set_type ( const char * ntype )

Sets the node parent node type to that of the argument.

Parameters

ntype (I) Type to be set for the Parent Node

ITK_API int TE_PS_fill_and_traverse_tree ( )

This function is used to build and traverse a tree structure simultaneously. This is combination of the TE_PS_fill_tree() and TE_PS_traverse_tree().

ITK_API int TE_PS_fill_tree ( )

This creates the tree data structure similar to the PS. Runs the function set as TE_NODE_SELECTOR. The return status for this function determines whether a branch needs to be built or not.

Possible return status for the function registered as TE_NODE_SELECTOR are TE_CONTINUE, TE_SKIP and TE_SKIPCHILDREN.

ITK_API int TE_PS_get_config_params	(	char **	viewtype,
		char **	variant,
		char **	revrule,
		char **	sub
	)

Gets the BOM view type, saved variant, revision rule set by the API call or the command line and the substitute setting.

Parameters

viewtype	(OF) BOM view type returned
variant	(OF) Variant rule returned
revrule	(OF) Revision rule returned
sub	(OF) Substitute setting that is returned

ITK_API int TE_PS_get_config_params_with_pack	(	char **	viewtype,
		char **	variant,
		char **	revrule,
		char **	alt,
		int *	packstate
	)

Gets the BOM view type, saved variant, revision rule, pack option set by the API call or the command line and the alternate setting.

Parameters

viewtype	(OF) BOM view type returned
variant	(OF) Variant rule returned
revrule	(OF) Revision rule returned
alt	(OF) Alternate setting that is returned
packstate	(O) Pack the structure

ITK_API int TE_PS_initialize	(	const char *	itemid,
		const char *	rev
	)

Used for PS traversal. Opens a BOM window internally using the itemid and revision. The revision rule, BOM view type and variant that govern the creation of the BOM window must have been set using corresponding API calls.

Parameters

itemid	(I) Item identification number
rev	(I) Identification of the Item Revision

ITK_API int TE_PS_set_config	(	const char *	viewtype,
		const char *	variant,
		const char *	revrule,
		const char *	sub
	)

Sets the bom view type. The saved variant object in Teamcenter database will be retrieved and the BOM window configured with this object. If multiple objects are found then the first one will be taken and corresponding warning issued. Sets the revision rule for the BOM window. Default is Latest Working. Sets the substitute to es or o. It is a switch and later needs to be referred by the selectors or handlers and as such does not have a function.

Parameters

viewtype	(I) BOM view type to be set
variant	(I) Variant rule to be set
revrule	(I) Revision rule to be set
sub	(I) Substitute to be set

ITK_API int TE_PS_set_config_with_pack	(	const char *	viewtype,
		const char *	variant,
		const char *	revrule,
		const char *	alt,
		int	packstate
	)

Sets the bom view type. The saved variant object in Teamcenter Engineering database will be retrieved and the BOM window configured with this object. If multiple objects are found then the first one will be taken and corresponding warning issued. Sets the revision rule for the BOM window. Default is Latest Working. Sets the alternate to es or o. It is a switch and later needs to be referred by the selectors or handlers and as such does not have a function. Sets the pack option on the bomlines. The default is unpacked structure

Parameters

viewtype	(I) BOM view type to be set
variant	(I) Variant rule to be set
revrule	(I) Revision rule to be set
alt	(I) Alternate to be set
packstate	(I) Pack the structure

ITK_API int TE_PS_traverse_tree ( )

This traverses the built tree and executes the functions registered and the following handlers:

TE_ROOT_ENTRY - Executed when entering the root node.
TE_ROOT_EXIT - Executed when exiting the root node.
TE_AT_NODE - Executed between entry and exit at each node.
TE_FORWARD_ENTRY - Executed when a node is entered from another in forward direction
TE_FORWARD_EXIT - Executed when a node is left for another in forward direction
TE_REVERSE_ENTRY - Executed when a node is entered from another in reverse direction.
TE_REVERSE_EXIT - Executed when a node is left for another in Reverse direction

The return of these functions determines the traversal direction. Possible return status are TE_CONTINUE, TE_SKIP and TE_GOBACK.

ITK_API int TE_PS_ui_get_data	(	char	itemid[ITEM_id_size_c+1],
		char	itemrev[ITEM_id_size_c+1],
		char	logfile[IMF_filename_size_c+1],
		char	configfile[IMF_filename_size_c+1]
	)

Deprecated:: This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use TE_PS_ui_get_data2

Returns the values entered at the command line or set by the corresponding API call for itemid, itemrev, logfile and configfile.

Parameters

itemid	(O) Returns itemid set by command line or corresponding api call
itemrev	(O) Returns item revision set by command line or corresponding api call
logfile	(O) Returns logfile name set by command line or corresponding api call
configfile	(O) Returns configfile by command line or corresponding api call

ITK_API int TE_PS_ui_get_data2	(	char **	itemid,
		char **	itemrev,
		char **	logfile,
		char **	configfile
	)

Returns the values entered at the command line or set by the corresponding API call for itemid, itemrev, logfile and configfile.

Parameters

itemid	(OF) Returns itemid set by command line or corresponding api call
itemrev	(OF) Returns item revision set by command line or corresponding api call
logfile	(OF) Returns logfile name set by command line or corresponding api call
configfile	(OF) Returns configfile by command line or corresponding api call

ITK_API int TE_register_node_handler	(	int	handlertype,
		TE_handler_t	afun
	)

Takes the handler type and the function name as the arguments, and sets the function for the required handler.

Parameters

handlertype (I) Handler to which function is to be attached.
TE_NODE_SELECTOR - Executed while creation of tree nodes.
TE_ROOT_ENTRY - Executed when entering the root node.
TE_ROOT_EXIT - Executed when exiting the root node.
TE_AT_NODE - Executed between entry and exit at each node.
TE_FORWARD_ENTRY - Executed when a node is entered from another in forward direction.
TE_FORWARD_EXIT - Executed when a node is left for another in forward direction.
TE_REVERSE_ENTRY - Executed when a node is entered from another in reverse direction.
TE_REVERSE_EXIT - Executed when a node is left for another in reverse direction.

afun (I) Function pointer

ITK_API int TE_table_get_float	(	const char *	key,
		float *	afloat
	)

Takes in the key (String) as the argument and returns the float value which was stored earlier.

Parameters

key	(I) String value, which is used as a key to store the float value in a table
afloat	(O) Value stored for the key

ITK_API int TE_table_store_float	(	const char *	key,
		float	sfloat
	)

Stores the float value in the memory with the given key which is a string.

Parameters

key	(I) String value, which is used as a key to store the float value in a table
sfloat	(O) Float value, which is stored in the table

ITK_API int TE_ui_get_logfile_pointer ( FILE ** logfileptr )

Parameters

logfileptr (O)

ITK_API int TE_ui_increment_warnings ( )

Increments the Warning Count by 1, each time a warning arises. Number of warnings can be found with TE_get_statistics().

ITK_API int TE_ui_print_message	(	int	output,
		int	warn,
		int	ifail,
		const char *	msg
	)

Displays the string passed as argument to the stdout/logfile or both.

Parameters

output	(I) TE_STDOUT: Prints message to stdout only TE_LOG: Prints message to TE log file only TE_LOGANDSTDOUT: Prints message to te log file and stdout.
warn	(I) TRUE: Increments Warning message count FALSE: Does not increment message count
ifail	(I) The ERROR code returned by an ITK call. If not zero then the Error message corresponding to the code also is printed.
msg	(I) String to be printed

ITK_API int TE_ui_set_configfile ( const char * fname )

Sets the given file fname as the config file, which will be used as configuration file for input by the traversal utility. This call opens the specified config file in read only mode and returns a non ITK_ok status if this fails. If TE_ui_set_validate_args() is not used then this must be called before using the TE_ui_xxx calls.

Parameters

fname (I)

ITK_API int TE_ui_set_logfile ( const char * fname )

Sets the given file fname as the log file for output. This calls opens the log file and returns a non ITK_ok status if it is unable to open. If TE_ui_set_validate_args() is not used then this must be called before using the TE_ui_xxx calls.

Parameters

fname (I) Name of the file to be used as logfile

ITK_API int TE_ui_set_validate_args ( )

This call reads in the command line arguments, and stores them internally. It also validates the command line arguments and takes in default values when none are provided. It will set the log and config file for output and input and must be called before any of the TE_ui_xx calls are called. It should be used when you are using the command line arguments. If it is not, then other api calls must be used to set the required input for traversing.

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

The Traversal Engine

Developing a Traversal Program

Traversal Engine Selectors

TE Module Calls

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation