Error Message Handler
[Integration Tool Kit]

Detailed Description

The Error Message Handler (EMH) ITK interface is defined in file emh.h.

New Error Handling For V3.2

Teamcenter stores errors on a central stack. An error may be posted at a low level and each layer of the code handles the error reported by the level below, potentially adding a new error of its own to the top of the stack to add more contextual information to the exception being reported.

This stack of errors is what you see displayed in the Teamcenter error window at the UIF. ITK functions always return the top error from the stack (if there is one - if everything is ok ITK_ok is returned). These functions enable you to access the full error stack, and also to decode individual Teamcenter error codes ('ifails') into the internationlized (I18N) texts that are defined in the UIL and displayed in the error windows at the UIF.

Note:: It is desirable to inform Teamcenter that you have handled an error received from the ITK interface by calling EMH_clear_errors.
For compatibility with other ITK calls (unless otherwise specifically noted below) EMH functions return ITK_ok, they do not return failure codes.

Migration From pre-V3.2 Error Handling

Prior to V3.2 errors were attached to individual objects, so the pre-V3.2 EMH functions needed the tag of an Teamcenter object as an argument. For V3.2 these functions are still supported, the tag argument is ignored and NULLTAG may be supplied. However please do not use these functions for new code. (With due notice) they may be phased out sometime in the future.

Note:: EMH_get_error_string was the only officially documented and supported EMH error function published prior to V3.2. There were however additional functions declared in emh.h which we are attempting to provide migration for.

Error Severity

Teamcenter errors are classified according to their severity. They can be errors, warnings, or information. Where an argument to an EMH function refers to severity, this can take values EMH_severity_information, EMH_severity_warning and EMH_severity_error. The topmost severity is used as the title of any error window we display. EMH_severity_error is the usual one to use.

User-Defined Error Codes

You can add you own error messages to Teamcenter ITK. Teamcenter has reserved an error message range expressly for this purpose. The reserved range for these user-defined error messages is: 919000 thru 919999.

Return Values

The EMH functions do not return failure codes, but for compatibility with other ITK calls (unless specifically noted otherwise) these functions always return the token ITK_ok.

Customizing Error Messages in Portal

The procedure for creating custom error messages in Portal is as follows:

Update your code to include emh_const.h.

Add the #define statement for your error message. For example:

            #define CONNECT_FAILURE (EMH_USER_error_base + 10)

Copy %TC_MSG_ROOT%\<desired_locale>\ue_errors.xml to your %TC_USER_MSG_DIR%.
Add a line to define the text string corresponding to your custom message in ue_errors.xml. For example, <error id = "100"> Unable to connect </error>.

Modules

Functions

TC_API int EMH_store_error (int severity, int ifail)
TC_API int EMH_store_error_s1 (int severity, int ifail, const char *s1)
TC_API int EMH_store_error_s2 (int severity, int ifail, const char *s1, const char *s2)
TC_API int EMH_store_error_s3 (int severity, int ifail, const char *s1, const char *s2, const char *s3)
TC_API int EMH_store_error_s4 (int severity, int ifail, const char *s1, const char *s2, const char *s3, const char *s4)
TC_API int EMH_store_error_s5 (int severity, int ifail, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5)
TC_API int EMH_store_error_s7 (int severity, int ifail, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5, const char *s6, const char *s7)
TC_API int EMH_store_initial_error (int severity, int ifail)
TC_API int EMH_store_initial_error_s1 (int severity, int ifail, const char *s1)
TC_API int EMH_store_initial_error_s2 (int severity, int ifail, const char *s1, const char *s2)
TC_API int EMH_store_initial_error_s3 (int severity, int ifail, const char *s1, const char *s2, const char *s3)
TC_API int EMH_store_initial_error_s4 (int severity, int ifail, const char *s1, const char *s2, const char *s3, const char *s4)
TC_API int EMH_store_initial_error_s5 (int severity, int ifail, const char *s1, const char *s2, const char *s3, const char *s4, const char *s5)
TC_API int EMH_ask_last_error (int *ifail)
TC_API int EMH_ask_errors (int *n_ifails, const int **severities, const int **ifails, const char ***texts)
TC_API int EMH_clear_errors (void)
TC_API int EMH_clear_last_error (int ifail)
TC_API int EMH_set_protect_mark (int *mark)
TC_API int EMH_clear_protect_mark (int mark)
TC_API int EMH_ask_error_text (int ifail, char **text)
TC_API int EMH_get_error_string (tag_t tag, int ifail, char **text)

Function Documentation

TC_API int EMH_ask_error_text	(	int	ifail,
		char **	text
	)

Returns the internationalized (I18N) text associated with the specified ifail code. Note the storage associated with this string must be freed after use by MEM_free or TC_free_text.

Note:: This function operates outside the context of your current session. It simply translates a code into its equivalent text without filling in object properties specific to your session. If you require details of your current errors, use EMH_ask_errors to print the error stack.

Parameters:

ifail	(I) Integer ifail code
text	(OF) I18N text message corresponding to the ifail

TC_API int EMH_ask_errors	(	int *	n_ifails,
		const int **	severities,
		const int **	ifails,
		const char ***	texts
	)

Gives the severities, ifail codes, and associated internationalized texts for each error on the error store.

Errors are in historical order (i.e., ifails[0] is from the bottom of the stack).

The returned pointers are only valid until the next call is made to the ITK. You should not hang on to these pointers after this, or attempt to modify their contents in any way. texts[n_ifails-1] is the message corresponding to the most recent error

Parameters:

n_ifails	(O) Number of errors in the error store
severities	(O) n_ifails EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifails	(O) n_ifails Integer code for each error in the store
texts	(O) n_ifails Internationalized text strings for each error in the store

TC_API int EMH_ask_last_error ( int * ifail )

Gives the ifail on top of the error store.

This will be the same as the last ifail code returned by an ITK call.

If the error store is currently empty ifail will be returned zero.

Parameters:

ifail

(O) Ifail code from the top of the error stack

TC_API int EMH_clear_errors ( void )

Clears the entire error store up to the last protected mark. To clear errors before a protected mark you must clear the protect mark first.

Ideally this should be called once you have handled an error condition reported by an ITK call.

TC_API int EMH_clear_last_error ( int ifail )

Removes the ifail currently at the top of the error store (i.e., the one stored most recently).

You must give the ifail you intend removing, as confirmation that you have received and understood the error before removing it.

Parameters:

ifail

(I) Ifail code on the top of the error stack that you wish to remove

TC_API int EMH_clear_protect_mark ( int mark )

Parameters:

mark

(I) Identifies the error protect mark

TC_API int EMH_get_error_string	(	tag_t	tag,
		int	ifail,
		char **	text
	)

Deprecated:: This function is obsolescent pre-V3.2 functionality. Please use EMH_ask_error_text or EMH_ask_errors instead for new code. This function is still supported for migration purposes. If tag is NULLTAG, the given ifail is translated to internationalized (I18N) text as per EMH_ask_error_text above. If tag is not NULLTAG, all the error messages currently on the error store are returned (separated by \n's) as one MEM_alloc()ed string.

Note:: This is a change from pre-V3.2 where the error stack of the object identified by tag was given.
The error messages are placed in the text string with the lowest-level error first.

Parameters:

tag	(I)
ifail	(I)
text	(OF)

TC_API int EMH_set_protect_mark ( int * mark )

An error protect mark protects the current state of the error store against being cleared or overwritten. This is useful if you must make another ITK call (which theoretically may post errors of its own) as part of handling an error, for which you then want to display the error stack. For example:

        tag_t object;
        int mark;

        if ( ITK_call( object ) != ITK_ok )
        {
            char* name;
            EMH_set_protect_mark( &mark );
            ITK_ask_name( object, &name );

            EMH_clear_protect_mark( mark );
            EMH_ask_errors( ... );
            display_my_error( ... );
            EMH_clear_errors();
        }

Parameters:

mark

(O) Identifies the error protect mark

TC_API int EMH_store_error	(	int	severity,
		int	ifail
	)

Adds the specified error code to the top of the error store.

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored

TC_API int EMH_store_error_s1	(	int	severity,
		int	ifail,
		const char *	s1
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_error_s2	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_error_s3	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_error_s4	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3,
		const char *	s4
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code
s4	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_error_s5	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3,
		const char *	s4,
		const char *	s5
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code
s4	(I) Character string being substituted into the internationalized message associated with this ifail code
s5	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_error_s7	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3,
		const char *	s4,
		const char *	s5,
		const char *	s6,
		const char *	s7
	)

Adds the specified error code to the top of the error store.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code
s4	(I) Character string being substituted into the internationalized message associated with this ifail code
s5	(I) Character string being substituted into the internationalized message associated with this ifail code
s6	(I) Character string being substituted into the internationalized message associated with this ifail code
s7	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_initial_error	(	int	severity,
		int	ifail
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored

TC_API int EMH_store_initial_error_s1	(	int	severity,
		int	ifail,
		const char *	s1
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_initial_error_s2	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_initial_error_s3	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_initial_error_s4	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3,
		const char *	s4
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code
s4	(I) Character string being substituted into the internationalized message associated with this ifail code

TC_API int EMH_store_initial_error_s5	(	int	severity,
		int	ifail,
		const char *	s1,
		const char *	s2,
		const char *	s3,
		const char *	s4,
		const char *	s5
	)

Resets the error store and stores the specified ifail code as the start of a new stack of errors. Equivalent to EMH_clear_errors followed by EMH_store_error.

String arguments are substituted into the translated UIL string when the error is displayed in an error window, where %n$ in the UIL string gives the n'th argument to substitute (XPG3 printf).

Parameters:

severity	(I) EMH_severity_error, EMH_severity_warning, or EMH_severity_information
ifail	(I) Code of the error being stored
s1	(I) Character string being substituted into the internationalized message associated with this ifail code
s2	(I) Character string being substituted into the internationalized message associated with this ifail code
s3	(I) Character string being substituted into the internationalized message associated with this ifail code
s4	(I) Character string being substituted into the internationalized message associated with this ifail code
s5	(I) Character string being substituted into the internationalized message associated with this ifail code

Error Message Handler [Integration Tool Kit]

Detailed Description

Modules

Functions

Function Documentation

Error Message Handler
[Integration Tool Kit]