Error Formatting and Print Functions

Macros
#define	LOG_RTERR(pctxt, stat)   rtxErrSetData(pctxt,stat,__FILE__,__LINE__)
#define	LOG_RTERRNEW(pctxt, stat)   rtxErrSetNewData(pctxt,stat,__FILE__,__LINE__)
#define	OSRTASSERT(condition)   if (!(condition)) { rtxErrAssertionFailed(#condition,__LINE__,__FILE__); }
#define	OSRTCHECKPARAM(condition)   if (condition) { /* do nothing */ }
#define	LOG_RTERR1(pctxt, stat, a)   (a,LOG_RTERR (pctxt, stat),stat)
#define	LOG_RTERRNEW1(pctxt, stat, a)   (a,LOG_RTERRNEW (pctxt, stat),stat)
#define	LOG_RTERR2(pctxt, stat, a, b)   (a,b,LOG_RTERR (pctxt, stat),stat)
#define	LOG_RTERRNEW2(pctxt, stat, a, b)   (a,b,LOG_RTERRNEW (pctxt, stat),stat)
#define	LOG_RTERR_AND_FREE_MEM(ctxt_p, stat, mem_p)   rtxMemFreePtr ((ctxt_p),(mem_p)), LOG_RTERR(ctxt_p, stat)

Typedefs
typedef int(*	OSErrCbFunc) (const char *ptext, void *cbArg_p)

Functions
OSBOOL	rtxErrAddCtxtBufParm (OSCTXT *pctxt)
OSBOOL	rtxErrAddDoubleParm (OSCTXT *pctxt, double errParm)
OSBOOL	rtxErrAddErrorTableEntry (const char *const *ppStatusText, OSINT32 minErrCode, OSINT32 maxErrCode)
OSBOOL	rtxErrAddElemNameParm (OSCTXT *pctxt)
OSBOOL	rtxErrAddIntParm (OSCTXT *pctxt, int errParm)
OSBOOL	rtxErrAddInt64Parm (OSCTXT *pctxt, OSINT64 errParm)
OSBOOL	rtxErrAddSizeParm (OSCTXT *pctxt, OSSIZE errParm)
OSBOOL	rtxErrAddStrParm (OSCTXT *pctxt, const char *pErrParm)
OSBOOL	rtxErrAddStrnParm (OSCTXT *pctxt, const char *pErrParm, OSSIZE nchars)
OSBOOL	rtxErrAddUIntParm (OSCTXT *pctxt, unsigned int errParm)
OSBOOL	rtxErrAddUInt64Parm (OSCTXT *pctxt, OSUINT64 errParm)
void	rtxErrAssertionFailed (const char *conditionText, int lineNo, const char *fileName)
const char *	rtxErrFmtMsg (OSRTErrInfo *pErrInfo, char *bufp, OSSIZE bufsiz)
void	rtxErrFreeParms (OSCTXT *pctxt)
char *	rtxErrGetText (OSCTXT *pctxt, char *pBuf, OSSIZE *pBufSize)
char *	rtxErrGetTextBuf (OSCTXT *pctxt, char *pbuf, OSSIZE bufsiz)
char *	rtxErrGetMsgText (OSCTXT *pctxt)
char *	rtxErrGetMsgTextBuf (OSCTXT *pctxt, char *pbuf, OSSIZE bufsiz)
OSRTErrInfo *	rtxErrNewNode (OSCTXT *pctxt)
void	rtxErrInit (OSVOIDARG)
int	rtxErrReset (OSCTXT *pctxt)
int	rtxErrResetErrInfo (OSCTXT *pctxt)
void	rtxErrLogUsingCB (OSCTXT *pctxt, OSErrCbFunc cb, void *cbArg_p)
void	rtxErrPrint (OSCTXT *pctxt)
void	rtxErrPrintElement (OSRTErrInfo *pErrInfo)
int	rtxErrSetData (OSCTXT *pctxt, int status, const char *module, int lineno)
int	rtxErrSetNewData (OSCTXT *pctxt, int status, const char *module, int lineno)
void	rtxErrSetNonFatal (OSCTXT *pctxt)
int	rtxErrGetFirstError (const OSCTXT *pctxt)
int	rtxErrGetLastError (const OSCTXT *pctxt)
OSSIZE	rtxErrGetErrorCnt (const OSCTXT *pctxt)
int	rtxErrGetStatus (const OSCTXT *pctxt)
int	rtxErrResetLastErrors (OSCTXT *pctxt, OSSIZE errorsToReset)
int	rtxErrCopy (OSCTXT *pDestCtxt, const OSCTXT *pSrcCtxt)
int	rtxErrAppend (OSCTXT *pDestCtxt, const OSCTXT *pSrcCtxt)
int	rtxErrInvUIntOpt (OSCTXT *pctxt, OSUINT32 ident)

Detailed Description

Error formatting and print functions allow information about encode/decode errors to be added to a context block structure and then printed when the error is propagated to the top level.

Macro Definition Documentation

LOG_RTERR

#define LOG_RTERR	(		pctxt,
			stat
	)		rtxErrSetData(pctxt,stat,__FILE__,__LINE__)

This macro is used to log a run-time error in the context. It calls the rtxErrSetData function to set the status and error parameters. The C built-in FILE and LINE macros are used to record the position in the source file of the error.

Parameters

pctxt	A pointer to a context structure.
stat	Error status value from rtxErrCodes.h

Referenced by ASN1CType::append().

LOG_RTERR_AND_FREE_MEM

#define LOG_RTERR_AND_FREE_MEM	(		ctxt_p,
			stat,
			mem_p
	)		rtxMemFreePtr ((ctxt_p),(mem_p)), LOG_RTERR(ctxt_p, stat)

This logs an error to a global context and frees a memory pointer allocated for encoding or decoding.

Parameters

ctxt_p	A pointer to the main context data structure.
stat	The error status.
mem_p	The memory pointer allocated for encoding/decoding.

Returns

The result of logging the error to the global context.

OSRTASSERT

#define OSRTASSERT

(

condition

)

if (!(condition)) { rtxErrAssertionFailed(#condition,__LINE__,__FILE__); }

This macro is used to check an assertion. This is a condition that is expected to be true. The rtxErrAssertionFailed function is called if the condition is not true. The C built-in FILE and LINE macros are used to record the position in the source file of the failure.

Parameters

condition

Condition to check (for example, "(ptr != NULL)")

OSRTCHECKPARAM

#define OSRTCHECKPARAM

(

condition

)

if (condition) { /* do nothing */ }

This macro check a condition but takes no action. Its main use is to supress VC++ level 4 "argument not used" warnings.

Parameters

condition

Condition to check (for example, "(ptr != NULL)")

Function Documentation

rtxErrAddCtxtBufParm()

OSBOOL rtxErrAddCtxtBufParm

(

OSCTXT *

pctxt

)

This function adds the contents of the context buffer to the error information structure in the context. The buffer contents are assumed to contain only printable characters.

Parameters

pctxt

A pointer to a context structure.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddDoubleParm()

OSBOOL rtxErrAddDoubleParm	(	OSCTXT *	pctxt,
		double	errParm
	)

This function adds a double parameter to an error information structure.

Parameters

pctxt	A pointer to a context structure.
errParm	The double error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddElemNameParm()

OSBOOL rtxErrAddElemNameParm

(

OSCTXT *

pctxt

)

This function adds an element name parameter to the context error information structure. The element name is obtained from the context element name stack. If the stack is empty, a question mark characetr (?) is inserted for the name.

Parameters

pctxt

A pointer to a context structure.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddErrorTableEntry()

OSBOOL rtxErrAddErrorTableEntry	(	const char *const *	ppStatusText,
		OSINT32	minErrCode,
		OSINT32	maxErrCode
	)

This function adds a set of error codes to the global error table. It is called within context initialization functions to add errors defined for a specific domain (for example, ASN.1 encoding/decoding) to be added to the global list of errors.

Parameters

ppStatusText	Pointer to table of error status text messages.
minErrCode	Minimum error status code.
maxErrCode	Maximum error status code.

Returns

The status of the operation (TRUE if entry sucessfully added to table).

rtxErrAddInt64Parm()

OSBOOL rtxErrAddInt64Parm	(	OSCTXT *	pctxt,
		OSINT64	errParm
	)

This function adds a 64-bit integer parameter to an error information structure. Parameter substitution is done in much the same way as it is done in C printf statments. The base error message specification that goes along with a particular status code may have variable fields built in using '' modifiers. These would be replaced with actual parameter data.

Parameters

pctxt	A pointer to a context structure.
errParm	The 64-bit integer error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddIntParm()

OSBOOL rtxErrAddIntParm	(	OSCTXT *	pctxt,
		int	errParm
	)

This function adds an integer parameter to an error information structure. Parameter substitution is done in much the same way as it is done in C printf statments. The base error message specification that goes along with a particular status code may have variable fields built in using '' modifiers. These would be replaced with actual parameter data.

Parameters

pctxt	A pointer to a context structure.
errParm	The integer error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddSizeParm()

OSBOOL rtxErrAddSizeParm	(	OSCTXT *	pctxt,
		OSSIZE	errParm
	)

This function adds a size-typed parameter to an error information structure. Parameter substitution is done in much the same way as it is done in C printf statments. The base error message specification that goes along with a particular status code may have variable fields built in using '' modifiers. These would be replaced with actual parameter data.

Parameters

pctxt	A pointer to a context structure.
errParm	The integer error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddStrnParm()

OSBOOL rtxErrAddStrnParm	(	OSCTXT *	pctxt,
		const char *	pErrParm,
		OSSIZE	nchars
	)

This function adds a given number of characters from a character string parameter to an error information structure.

Parameters

pctxt	A pointer to a context structure.
pErrParm	The character string error parameter.
nchars	Number of characters to add from pErrParm.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddStrParm()

OSBOOL rtxErrAddStrParm	(	OSCTXT *	pctxt,
		const char *	pErrParm
	)

This function adds a character string parameter to an error information structure.

Parameters

pctxt	A pointer to a context structure.
pErrParm	The character string error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddUInt64Parm()

OSBOOL rtxErrAddUInt64Parm	(	OSCTXT *	pctxt,
		OSUINT64	errParm
	)

This function adds an unsigned 64-bit integer parameter to an error information structure.

Parameters

pctxt	A pointer to a context structure.
errParm	The unsigned 64-bit integer error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAddUIntParm()

OSBOOL rtxErrAddUIntParm	(	OSCTXT *	pctxt,
		unsigned int	errParm
	)

This function adds an unsigned integer parameter to an error information structure.

Parameters

pctxt	A pointer to a context structure.
errParm	The unsigned integer error parameter.

Returns

The status of the operation (TRUE if the parameter was sucessfully added).

rtxErrAppend()

int rtxErrAppend	(	OSCTXT *	pDestCtxt,
		const OSCTXT *	pSrcCtxt
	)

This function appends error information from one context into another. Error information is added to what previously existed in the destination context.

Parameters

pDestCtxt	Pointer to destination context structure to receive the copied error information.
pSrcCtxt	Pointer to source context from which error information will be copied.

Returns

Completion status of operation:

• 0(RT_OK) = success,
• negative return value is error

rtxErrAssertionFailed()

void rtxErrAssertionFailed	(	const char *	conditionText,
		int	lineNo,
		const char *	fileName
	)

This function is used to record an assertion failure. It is used in conjunction with the OTRTASSERT macro. It outputs information on the condition to stderr and then calls exit to terminate the program.

Parameters

conditionText	The condition that failed (for example, ptr != NULL)
lineNo	Line number in the program of the failure.
fileName	Name of the C source file in which the assertion failure occurred.

rtxErrCopy()

int rtxErrCopy	(	OSCTXT *	pDestCtxt,
		const OSCTXT *	pSrcCtxt
	)

This function copies error information from one context into another. Any error information that may have existed in the destination context prior to the operation is lost.

Parameters

pDestCtxt	Pointer to destination context structure to receive the copied error information.
pSrcCtxt	Pointer to source context from which error information will be copied.

Returns

Completion status of operation:

• 0(RT_OK) = success,
• negative return value is error

rtxErrFmtMsg()

const char* rtxErrFmtMsg	(	OSRTErrInfo *	pErrInfo,
		char *	bufp,
		OSSIZE	bufsiz
	)

This function formats a given error structure from the context into a finished status message including substituted parameters.

Parameters

pErrInfo	Pointer to error information structure.
bufp	Pointer to a destination buffer to receive text.
bufsiz	Size of the buffer.

Returns

Pointer to the buffer (bufp).

rtxErrFreeParms()

void rtxErrFreeParms

(

OSCTXT *

pctxt

)

This function is used to free dynamic memory that was used in the recording of error parameters. After an error is logged, this function should be called to prevent memory leaks.

Parameters

pctxt

A pointer to a context structure.

rtxErrGetErrorCnt()

OSSIZE rtxErrGetErrorCnt

(

const OSCTXT *

pctxt

)

This function returns the total number of error records, including non-fatal errors.

Parameters

pctxt

A pointer to a context structure.

Returns

The total number of error records in the context.

rtxErrGetFirstError()

int rtxErrGetFirstError

(

const OSCTXT *

pctxt

)

This function returns the error code, stored in the first error record.

Parameters

pctxt

A pointer to a context structure.

Returns

The first status code; zero if no error records exist.

rtxErrGetLastError()

int rtxErrGetLastError

(

const OSCTXT *

pctxt

)

This function returns the error code, stored in the last error record.

Parameters

pctxt

A pointer to a context structure.

Returns

The last status code; zero if no error records exist.

Referenced by OSRTContext::getStatus().

rtxErrGetMsgText()

char* rtxErrGetMsgText

(

OSCTXT *

pctxt

)

This function returns error message text in a memory buffer. It only returns the formatted error message, not the error status nor stack trace information. Memory is dynamically allocated using the rtxMemAlloc function. It should be freed using rtxMemFreePtr or it will be freed when the context is freed.

Parameters

pctxt

A pointer to a context structure.

Returns

A pointer to a buffer with error text. Dynamic memory will be allocated for this buffer using rtxMemAlloc. It should be freed using rtxMemFreePtr.

rtxErrGetMsgTextBuf()

char* rtxErrGetMsgTextBuf	(	OSCTXT *	pctxt,
		char *	pbuf,
		OSSIZE	bufsiz
	)

This function returns error message text in a static memory buffer. It only returns the formatted error message, not the error status nor stack trace information. If the formatted text will not fit in the buffer, it is truncated.

Parameters

pctxt	A pointer to a context structure.
pbuf	Pointer to a destination buffer to receive text.
bufsiz	Size of the buffer.

Returns

Pointer to the buffer (pbuf).

rtxErrGetStatus()

int rtxErrGetStatus

(

const OSCTXT *

pctxt

)

This function returns the status value from the context. It examines the error list to see how many fatal errors were logged. If none, OK (zero) is returned; if one, then the status value in that single error record is returned; if more than one, the special code RTERR_MULTIPLE is returned to indicate that multiple errors occurred. Non-fatal errors are entirely ignored.

Parameters

pctxt

A pointer to a context structure.

Returns

Status code corresponding to errors in the context.

rtxErrGetText()

char* rtxErrGetText	(	OSCTXT *	pctxt,
		char *	pBuf,
		OSSIZE *	pBufSize
	)

This function returns error text in a memory buffer. If buffer pointer and buffer size are specified in parameters (not NULL) then error text will be copied in the passed buffer. Otherwise, this function allocates memory using the 'rtxMemAlloc' function. This memory is automatically freed at the time the 'rtxMemFree' or 'rtxFreeContext' functions are called. The calling function may free the memory by using 'rtxMemFreePtr' function.

Parameters

pctxt	A pointer to a context structure.
pBuf	A pointer to a destination buffer to obtain the error text. If NULL, dynamic buffer will be allocated.
pBufSize	A pointer to buffer size. If pBuf is NULL and this parameter is not, it will receive the size of allocated dynamic buffer. If pBuf is not null, this is expcted to be set and hold the size of the buffer.

Returns

A pointer to a buffer with error text. If pBuf is not NULL, the return pointer will be equal to it. Otherwise, returns newly allocated buffer with error text. NULL, if error occurred.

rtxErrGetTextBuf()

char* rtxErrGetTextBuf	(	OSCTXT *	pctxt,
		char *	pbuf,
		OSSIZE	bufsiz
	)

This function returns error text in the given fixed-size memory buffer. If the text will not fit in the buffer, it is truncated.

Parameters

pctxt	A pointer to a context structure.
pbuf	Pointer to a destination buffer to receive text.
bufsiz	Size of the buffer.

Returns

Pointer to the buffer (pbuf).

rtxErrInit()

void rtxErrInit

(

OSVOIDARG

)

This function is a one-time initialization function that must be called before any other error processing functions can be called. It adds the common error status text codes to the global error table.

rtxErrInvUIntOpt()

int rtxErrInvUIntOpt	(	OSCTXT *	pctxt,
		OSUINT32	ident
	)

This function create an 'invalid option' error (RTERR_INVOPT) in the context using an unsigned integer parameter.

Parameters

pctxt	Pointer to context structure.
ident	Identifier which was found to be invalid.

rtxErrLogUsingCB()

void rtxErrLogUsingCB	(	OSCTXT *	pctxt,
		OSErrCbFunc	cb,
		void *	cbArg_p
	)

This function allows error information to be logged using a user-defined callback routine. The callback routine is invoked IMMEDIATELY; it is not a "callback" in the ordinary use of that word. The callback routine is invoked with error information in the context allowing the user to do application-specific handling (for example, it can be written to an error log or a Window display). After invoking the callback, this method will invoked rtxErrFreeParms to free memory associated with the error information.

The prototype of the callback function to be passed is as follows:

int cb (const char* ptext, void* cbArg_p);

where ptext is a pointer to the formatted error text string and cbArg_p is a pointer to a user-defined callback argument.

Parameters

pctxt	A pointer to a context structure.
cb	Callback function pointer.
cbArg_p	Pointer to a user-defined argument that is passed to the callback function.

rtxErrNewNode()

OSRTErrInfo* rtxErrNewNode

(

OSCTXT *

pctxt

)

This function creates a new empty error record for the passed context. rtxErrSetData function call with bAllocNew = FALSE should be used to set the data for this node. The new record will have fatal == TRUE.

Parameters

pctxt

A pointer to a context structure.

Returns

A pointer to a newly allocated error record; NULL, if error occurred.

rtxErrPrint()

void rtxErrPrint

(

OSCTXT *

pctxt

)

This function is used to print the error information stored in the context to the standard output device. Parameter substitution is done so that recorded parameters are added to the output message text.

Parameters

pctxt

A pointer to a context structure.

Referenced by OSRTContext::printErrorInfo().

rtxErrPrintElement()

void rtxErrPrintElement

(

OSRTErrInfo *

pErrInfo

)

This function is used to print the error information stored in the error information element to the standard output device. Parameter substitution is done so that recorded parameters are added to the output message text.

Parameters

pErrInfo

A pointer to an error information element.

rtxErrReset()

int rtxErrReset

(

OSCTXT *

pctxt

)

This function is used to reset the error state recorded in the context to successful. It is used in the generated code in places where automatic error correction can be done.

Parameters

pctxt

A pointer to a context structure.

Referenced by OSRTContext::resetErrorInfo().

rtxErrResetErrInfo()

int rtxErrResetErrInfo

(

OSCTXT *

pctxt

)

This function is used to reset the error state recorded in the context to successful. It is used in the generated code in places where automatic error correction can be done. This version differs from rtxErrReset in that it only resets error information within the context and not the element name and container stacks.

Parameters

pctxt

A pointer to a context structure.

rtxErrResetLastErrors()

int rtxErrResetLastErrors	(	OSCTXT *	pctxt,
		OSSIZE	errorsToReset
	)

This function resets last 'errorsToReset` errors in the context.

Parameters

pctxt	A pointer to a context structure.
errorsToReset	A number of errors to reset, starting from the last record.

Returns

Completion status of operation:

• 0(RT_OK) = success,
• negative return value is error

rtxErrSetData()

int rtxErrSetData	(	OSCTXT *	pctxt,
		int	status,
		const char *	module,
		int	lineno
	)

This function is used to record an error in the context structure. It is typically called via the LOG_RTERR macro in the generated code to trap error conditions. If no error has been logged, a new log entry is created. The new entry will have fatal = TRUE.

Parameters

pctxt	A pointer to a context structure.
status	The error status code from rtxErrCodes.h
module	The C source file in which the error occurred.
lineno	The line number within the source file of the error.

Returns

The status code that was passed in.

rtxErrSetNewData()

int rtxErrSetNewData	(	OSCTXT *	pctxt,
		int	status,
		const char *	module,
		int	lineno
	)

This function is used to record an error in the context structure. It is typically called via the LOG_RTERRNEW macro in the generated code to trap error conditions. It always allocates new error record with fatal = TRUE.

Parameters

pctxt	A pointer to a context structure.
status	The error status code from rtxErrCodes.h
module	The C source file in which the error occurred.
lineno	The line number within the source file of the error.

Returns

The status code that was passed in.

rtxErrSetNonFatal()

void rtxErrSetNonFatal

(

OSCTXT *

pctxt

)

This marks the last error recorded in the context as non-fatal. Non-fatal errors are ignored by rtxErrGetStatus but are otherwise treated the same as any other error. This is useful when recording, for example, canonical violations, which are errors but which don't force an operation to abort.