Detailed Description

This component gives access to the errors occurring during any processing when using the MapLink API classes. All member functions are static.

A history of errors is maintained. When a fault occurs, an error code and category is logged in the error stack. The history can be cleared by the user by a call to the 'clear' member function. The last error code is returned by a call to the 'lastError' member function. To iterate through the stack, use the 'first', 'next' and 'previous' members functions.

Errors are organised into categories (tslerrorcategory.h). The member functions can be used to query/manipulate the different categories either individually or as a bitmask mask of categories, by specifying the category you wish to query or manipulate.

You should iterate over one category or one set of categories (defined by a single mask) at a time as there is only one concept of current error (all errors are stored on one stack to maintain an order of occurrence).

The associated error description can be queried by calling lookup(errorNumber, category, description). The descriptions are contained in message files in the MapLink config directory (allmaplinkerrors.msg, ddoerrors.msg, maplinkerr.msg, tgmerrors.msg, tmserrors.msg).

If the message files can not be found the descriptions of the errors will be blank. The user will not be informed of this as this may be the desired behaviour given that the descriptions are maintained in memory.

In addition the error codes and a textual description may be found in the "tgmerror.h", "tmserror.h", "MapLinkErr.h" files.

If there is insufficient space in the stack errors are removed from the bottom of the stack.

Static Public Member Functions
static void	clear (const int category=TSLErrorCategoryAll)

static void	errorCallback (TSLMapLinkErrorCallback *callbackObject, TSLErrorCategory errorCategory=TSLErrorCategoryAll)

static bool	errorString (TSLSimpleString &result, const char *hdr="", const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	first (int &errorCode, TSLSimpleString &info, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	first (int &errorCode, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	index (int idx, int &errorCode, TSLSimpleString &info, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	index (int idx, int &errorCode, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	last (int &errorCode, TSLSimpleString &info, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	last (int &errorCode, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static void	loadMessages (const TSLSimpleString &filename)

static bool	lookupMessage (const int errorNumber, int &category, TSLSimpleString &message)

static bool	next (int &errorCode, TSLSimpleString &info, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	next (int &errorCode, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	previous (int &errorCode, TSLSimpleString &info, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static bool	previous (int &errorCode, const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static void	setSize (const int newSize)

static int	size (const int category=TSLErrorCategoryError\|TSLErrorCategoryFatal)

static int	totalErrorsSinceLastClear (const int category=TSLErrorCategoryAll)

Member Function Documentation

◆ clear()

static void TSLThreadedErrorStack::clear ( const int category = TSLErrorCategoryAll )

static

Clear the current error stack and error string.

By default all categories are cleared from the error stack.

Parameters

category Bitmask of TSLErrorCategory values (default TSLErrorCategoryAll).

◆ errorCallback()

static void TSLThreadedErrorStack::errorCallback	(	TSLMapLinkErrorCallback *	callbackObject,
		TSLErrorCategory	errorCategory = TSLErrorCategoryAll )

static

This method registers a user supplied callback object.

The user should derive a new class from TSLMapLinkErrorCallback and implement the pure virtual methods.

There can only be one Error callback.

Parameters

callbackObject	A pointer to an instance of a class implementing the interface TSLMapLinkErrorCallback .
errorCategory	Mask of Error Categories to pass to the error method.

◆ errorString()

static bool TSLThreadedErrorStack::errorString	(	TSLSimpleString &	result,
		const char *	hdr = "",
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Create a basic error string from the error stack.

As an alternative to iterating over the error stack, this method allows a basic default error string to be constructed. The specified header is used, followed by all error codes and information, separated by comma.

Parameters

result	Resultant error list.
hdr	String to precede error list.
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: true on success, false if no errors in list.

◆ first() [1/2]

static bool TSLThreadedErrorStack::first	(	int &	errorCode,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the first error in the error stack.

This method allows the user to get the error code of the first error occurred during runtime since the last clear.

The error code is returned in errorCode.

Parameters

errorCode	Storage for error code returned
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if no error has been logged since the start of the program, or since the last clear, true otherwise.

◆ first() [2/2]

static bool TSLThreadedErrorStack::first	(	int &	errorCode,
		TSLSimpleString &	info,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the first error in the error stack.

This method allows the user to get the error code of the first error occurred during runtime since the last clear.

The error code is returned in errorCode and any useful information available, such as filenames, are returned via the info points

Parameters

errorCode	Storage for error code returned
info	Storage for additional information string
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if no error has been logged since the start of the program, or since the last clear, true otherwise.

◆ index() [1/2]

static bool TSLThreadedErrorStack::index	(	int	idx,
		int &	errorCode,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the error information at the specified index.

This method gives access to an error code logged at a particular position in the stack.

The error code is returned in err_code.

Parameters

idx	Zero-based index in the stack.
errorCode	Storage for error code logged at index in the stack.
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: true if successful, false if no error is logged at this position in the stack.

◆ index() [2/2]

static bool TSLThreadedErrorStack::index	(	int	idx,
		int &	errorCode,
		TSLSimpleString &	info,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the error information at the specified index.

This method gives access to an error code logged at a particular position in the stack.

The error code is returned in err_code and any useful information available, such as filenames, are returned via the info points

Parameters

idx	Zero-based index in the stack.
errorCode	Storage for error code logged at index in the stack.
info	Storage for additional information string
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: true if successful, false if no error is logged at this position in the stack.

◆ last() [1/2]

static bool TSLThreadedErrorStack::last	(	int &	errorCode,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get details of the last error occurring.

The error code is returned in errorCode.

Parameters

errorCode	Storage for error code returned
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if no error has been logged since the start of the program, or since the last clear, true otherwise.

◆ last() [2/2]

static bool TSLThreadedErrorStack::last	(	int &	errorCode,
		TSLSimpleString &	info,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get details of the last error occurring.

The error code is returned in errorCode and any useful information available, such as filenames, are returned via the info points

Parameters

errorCode	Storage for error code returned
info	Storage for additional information string
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if no error has been logged since the start of the program, or since the last clear, true otherwise.

◆ loadMessages()

static void TSLThreadedErrorStack::loadMessages ( const TSLSimpleString & filename )

static

Loads the specified messages file. Clears any previous error message mappings.

If the message file contains an 'INCLUDE_FILE' directive the file must be contained in the same directory as 'filename'

If the file can not be found the end user will not be informed.

By default '$MAPL_HOME/config/allmaplinkerrors.msg' is loaded.

Parameters

filename filename of the messages file to load.

◆ lookupMessage()

static bool TSLThreadedErrorStack::lookupMessage	(	const int	errorNumber,
		int &	category,
		TSLSimpleString &	message )

static

This method looks up the error description and error category.

Parameters

errorNumber	The error number to lookup up.
category	The category associated with the error number (from the message file)
message	The resultant error description

Returns

False is returned if

the message files can not be found in the MapLink config directory
the error number can not be found in the message files.

◆ next() [1/2]

static bool TSLThreadedErrorStack::next	(	int &	errorCode,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the next error code in the stack.

The error code is returned in errorCode.

Parameters

errorCode	Storage for error code returned
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if the current error in the stack is the last logged in the stack, true otherwise.

◆ next() [2/2]

static bool TSLThreadedErrorStack::next	(	int &	errorCode,
		TSLSimpleString &	info,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

Get the next error code in the stack.

The error code is returned in errorCode and any useful information available, such as filenames, are returned via the info points

Parameters

errorCode	Storage for error code returned
info	Storage for additional information string
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if the current error in the stack is the last logged in the stack, true otherwise.

◆ previous() [1/2]

static bool TSLThreadedErrorStack::previous	(	int &	errorCode,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

This method allows the user to get the previous error code in the stack.

The error code is returned in errorCode.

Parameters

errorCode	Storage for error code returned
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if the current error in the stack is the first logged in the stack, true otherwise.

◆ previous() [2/2]

static bool TSLThreadedErrorStack::previous	(	int &	errorCode,
		TSLSimpleString &	info,
		const int	category = TSLErrorCategoryError\|TSLErrorCategoryFatal )

static

This method allows the user to get the previous error code in the stack.

The error code is returned in errorCode and any useful information available, such as filenames, are returned via the info points

Parameters

errorCode	Storage for error code returned
info	Storage for additional information string
category	Bitmask of TSLErrorCategory values (default TSLErrorCategoryError \| TSLErrorCategoryFatal).

Returns: false if the current error in the stack is the first logged in the stack, true otherwise.

◆ setSize()

static void TSLThreadedErrorStack::setSize ( const int newSize )

static

Changes the size of the error stack.

If you change the size of the stack so that it is smaller then errors will be removed from the bottom of the stack so as to reduce the stack to the new size.

Parameters

newSize new size of error stack (default creation size is 100).

◆ size()

static int TSLThreadedErrorStack::size ( const int category = TSLErrorCategoryError|TSLErrorCategoryFatal )

static

Returns the current size of the error stack.

Parameters

category Bitmask of TSLErrorCategory values (default TSLErrorCategoryError | TSLErrorCategoryFatal).

◆ totalErrorsSinceLastClear()

static int TSLThreadedErrorStack::totalErrorsSinceLastClear ( const int category = TSLErrorCategoryAll )

static

Returns the number of errors that have occurred since the last clear for the categories specified.

Parameters

category Bitmask of TSLErrorCategory values

Detailed Description

Static Public Member Functions

Member Function Documentation

◆ clear()

◆ errorCallback()

◆ errorString()

◆ first() [1/2]

◆ first() [2/2]

◆ index() [1/2]

◆ index() [2/2]

◆ last() [1/2]

◆ last() [2/2]

◆ loadMessages()

◆ lookupMessage()

◆ next() [1/2]

◆ next() [2/2]

◆ previous() [1/2]

◆ previous() [2/2]

◆ setSize()

◆ size()

◆ totalErrorsSinceLastClear()