top of page
Search
  • Writer's pictureadmin
    • Sep 8, 2021
    • 3 min read

ITK Customizations - Part2

Continuation of Teamcenter Server-side Customization (ITK)



Class Hierarchy in ITK APIs

  • As Teamcenter is an object oriented system, it is not necessary to have a function for every action on every class.

  • Usually, functions associated with a particular class work with instances for any subclasses.

  • The AOM module and the WSOM module consist of functions that correspond to the methods of the POM_application_object and WorkspaceObject abstract classes respectively.

  • AOM functions work for all application objects and WSOM functions work for all workspace objects.

  • As mentioned in Part 1, understanding of Teamcenter datamodel helps you to find the correct API for an requirement.




Include Files

  • All ITK programs must include tc/tc.h as this header file contains the basic definition of Teamcenter like

  • Standard datatypes

  • Constants

  • Basic functions and definitions like MEM_free, tag_t, ITK_ok, etc.

  • For all the ITK API used in the file, its corresponding header file should be called. Eg: item.h, folder.h, grm.h.

  • The include files are located in subdirectories of the <TC_ROOT>/include directory.

  • We must include the subdirectory when calling a include file. For example, when calling epm.h include file, locate the include file subdirector in TC ROOT and call it as,



   #include <epm/epm.h>

  • There are header files for many of the major modules that contain constants and include all of the header files for the classes in that module.

  • In the below example, we can use sa/sa.h header file to include all the module headers or call each class header files based on the usage of that particular sub class.

Example:
	#include <sa/sa.h>
	
		or we could use these statements
		
	#include <sa/am.h>
	#include <sa/sa_errors.h>
	#include <sa/person.h>
	#include <sa/role.h>
	#include <sa/group.h>
	#include <sa/groupmember.h>
	#include <sa/user.h>
	#include <sa/site.h>

tag_t

  • All objects in the ITK are identified by tags of C type tag_t.

  • tag_t is a run-time unique identifier.

  • As an object is loaded into memory, it is identified via a dynamic tag which is unique for the session.

  • Tags can be compared by use of C language == and != operators.

  • An unset tag_t variable is assigned the NULLTAG null value.

  • In ITK code, objects can be identified using this tags. If two tags are of same value, then they refer the same object in Teamcenter.



Memory Management

  • Memory is allocated by a Teamcenter function and returned to the caller in a pointer variable.

  • This is indicated in the code by the /* <OF> */ following the argument definition. In the below example, object_type is an OF variable.

  • This OF variable memory should be freed by passing the address to MEM_free function or SAFE_SM_FREE function.

tag_t tRootTask		= NULLTAG;
int iTargetCount	= 0;
int retcode		= ITK_ok;
tag_t *tTargetAttachments = NULL;
			
/* Get target attachment */
retcode = EPM_ask_attachments(tRootTask, EPM_target_attachment, &iTargetCount, &tTargetAttachments);
if (retcode != ITK_ok)
{
	cout<< "ERROR: EPM_ask_attachments is failed." << endl;
	SAFE_SM_FREE(tTargetAttachments);
	return retcode;
}

  • If MEM_free is used to free memory then in order to use the same variable again the variable should be declared to NULL again. This is taken care internally if SAFE_SM_FREE is used.

  • In below SAFE_SM_FREE screenshot from ITK API reference, you can see MEM_free is called internally as well the variable is declared as NULL.


D


Error Handling

  • Teamcenter stores errors on a central error stack.

  • All ITK functions returns integer as the return type. If ITK function is executed successfully then the return value is Zero or ITK_ok (ITK_ok is a constant with value is 0) or if it has failed it returns the integer number for the error which is called as error code.

  • ITK functions always return the top error from the stack if there is one.

  • The Error Message Handler (EMH) ITK functions enable to access the full error stack and decode individual Teamcenter error codes into the internationalized texts that are defined in the XML code and displayed in the error windows at the user interface.

  • EMH ITK functions are defined in the tc/emh.h header file.

  • They give the ability to store errors, access errors on the stack, and decode error codes into internationalized text.

  • It is good practice to acknowledge that you have received and handled an error reported by an ITK call by clearing the error store with a call to the EMH_clear_errors function.

  • EMH_store_error_s1 - To store error with one string argument. For the ifail value which is error code, it replaces the %1$ in the xml with string argument passed in this function. 


	EMH_clear_errors();
	EMH_store_error_s1(EMH_severity_error, iFail, objStr);
	return iFail;

  • Similar to s1 api, we have store error apis to pass upto 7 string arguments.

  • Error codes can be found in TC_ROOT/lang/textserver.


  • Let's see who the store_error_s1 api works, consider an ITK API returns the value as 525001.

  • For 525001, the en_US localization message is "AM internal error %1$" this can be found by searing in the folder.

  • We want custom message "Check your access" to be displayed, so the code snipper will look like:

EMH_clear_errors();
EMH_store_error_s1(EMH_severity_error, 525001, "Check your access");
return 525001;

  • %1$ will be replaced with the message from API.

bottom of page