XBinder  Version 2.6.x
Macros | Functions
Error Formatting and Print Functions

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. More...

Macros

#define LOG_RTERR(pctxt, stat)   rtxErrSetData(pctxt,stat,__FILE__,__LINE__)
 This macro is used to log a run-time error in the context. More...
 
#define OSRTASSERT(condition)   if (!(condition)) { rtxErrAssertionFailed(#condition,__LINE__,__FILE__); }
 This macro is used to check an assertion. More...
 
#define OSRTCHECKPARAM(condition)   if (condition) { /* do nothing */ }
 This macro check a condition but takes no action. More...
 
#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. More...
 

Functions

EXTERNRT OSBOOL rtxErrAddCtxtBufParm (OSCTXT *pctxt)
 This function adds the contents of the context buffer to the error information structure in the context. More...
 
EXTERNRT OSBOOL rtxErrAddDoubleParm (OSCTXT *pctxt, double errParm)
 This function adds a double parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddErrorTableEntry (const char *const *ppStatusText, OSINT32 minErrCode, OSINT32 maxErrCode)
 This function adds a set of error codes to the global error table. More...
 
EXTERNRT OSBOOL rtxErrAddElemNameParm (OSCTXT *pctxt)
 This function adds an element name parameter to the context error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddIntParm (OSCTXT *pctxt, int errParm)
 This function adds an integer parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddInt64Parm (OSCTXT *pctxt, OSINT64 errParm)
 This function adds a 64-bit integer parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddSizeParm (OSCTXT *pctxt, OSSIZE errParm)
 This function adds a size-typed parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddStrParm (OSCTXT *pctxt, const char *pErrParm)
 This function adds a character string parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddStrnParm (OSCTXT *pctxt, const char *pErrParm, size_t nchars)
 This function adds a given number of characters from a character string parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddUIntParm (OSCTXT *pctxt, unsigned int errParm)
 This function adds an unsigned integer parameter to an error information structure. More...
 
EXTERNRT OSBOOL rtxErrAddUInt64Parm (OSCTXT *pctxt, OSUINT64 errParm)
 This function adds an unsigned 64-bit integer parameter to an error information structure. More...
 
EXTERNRT void rtxErrAssertionFailed (const char *conditionText, int lineNo, const char *fileName)
 This function is used to record an assertion failure. More...
 
EXTERNRT const char * rtxErrFmtMsg (OSRTErrInfo *pErrInfo, char *bufp, size_t bufsiz)
 This function formats a given error structure from the context into a finished status message including substituted parameters. More...
 
EXTERNRT void rtxErrFreeParms (OSCTXT *pctxt)
 This function is used to free dynamic memory that was used in the recording of error parameters. More...
 
EXTERNRT char * rtxErrGetText (OSCTXT *pctxt, char *pBuf, size_t *pBufSize)
 This function returns error text in a memory buffer. More...
 
EXTERNRT char * rtxErrGetTextBuf (OSCTXT *pctxt, char *pbuf, size_t bufsiz)
 This function returns error text in the given fixed-size memory buffer. More...
 
EXTERNRT char * rtxErrGetMsgText (OSCTXT *pctxt)
 This function returns error message text in a memory buffer. More...
 
EXTERNRT char * rtxErrGetMsgTextBuf (OSCTXT *pctxt, char *pbuf, size_t bufsiz)
 This function returns error message text in a static memory buffer. More...
 
EXTERNRT OSRTErrInfortxErrNewNode (OSCTXT *pctxt)
 This function creates a new empty error record for the passed context. More...
 
EXTERNRT void rtxErrInit (OSVOIDARG)
 This function is a one-time initialization function that must be called before any other error processing functions can be called. More...
 
EXTERNRT int rtxErrReset (OSCTXT *pctxt)
 This function is used to reset the error state recorded in the context to successful. More...
 
EXTERNRT void rtxErrLogUsingCB (OSCTXT *pctxt, OSErrCbFunc cb, void *cbArg_p)
 This function allows error information to be logged using a user-defined callback routine. More...
 
EXTERNRT void rtxErrPrint (OSCTXT *pctxt)
 This function is used to print the error information stored in the context to the standard output device. More...
 
EXTERNRT void rtxErrPrintElement (OSRTErrInfo *pErrInfo)
 This function is used to print the error information stored in the error information element to the standard output device. More...
 
EXTERNRT int rtxErrSetData (OSCTXT *pctxt, int status, const char *module, int lineno)
 This function is used to record an error in the context structure. More...
 
EXTERNRT int rtxErrSetNewData (OSCTXT *pctxt, int status, const char *module, int lineno)
 This function is used to record an error in the context structure. More...
 
EXTERNRT int rtxErrGetFirstError (const OSCTXT *pctxt)
 This function returns the error code, stored in the first error record. More...
 
EXTERNRT int rtxErrGetLastError (const OSCTXT *pctxt)
 This function returns the error code, stored in the last error record. More...
 
EXTERNRT OSSIZE rtxErrGetErrorCnt (const OSCTXT *pctxt)
 This function returns the total number of error records. More...
 
EXTERNRT int rtxErrGetStatus (const OSCTXT *pctxt)
 This function returns the status value from the context. More...
 
EXTERNRT int rtxErrResetLastErrors (OSCTXT *pctxt, OSSIZE errorsToReset)
 This function resets last 'errorsToReset` errors in the context. More...
 
EXTERNRT int rtxErrCopy (OSCTXT *pDestCtxt, const OSCTXT *pSrcCtxt)
 This function copies error information from one context into another. More...
 
EXTERNRT int rtxErrAppend (OSCTXT *pDestCtxt, const OSCTXT *pSrcCtxt)
 This function appends error information from one context into another. More...
 
EXTERNRT int rtxErrInvUIntOpt (OSCTXT *pctxt, OSUINT32 ident)
 This function create an 'invalid option' error (RTERR_INVOPT) in the context using an unsigned integer parameter. More...
 

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
pctxtA pointer to a context structure.
statError status value from rtxErrCodes.h

Definition at line 79 of file rtxError.h.

◆ 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_pA pointer to the main context data structure.
statThe error status.
mem_pThe memory pointer allocated for encoding/decoding.
Returns
The result of logging the error to the global context.

Definition at line 145 of file rtxError.h.

◆ 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
conditionCondition to check (for example, "(ptr != NULL)")

Definition at line 102 of file rtxError.h.

◆ 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
conditionCondition to check (for example, "(ptr != NULL)")

Definition at line 111 of file rtxError.h.

Function Documentation

◆ rtxErrAddCtxtBufParm()

EXTERNRT 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
pctxtA pointer to a context structure.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddDoubleParm()

EXTERNRT OSBOOL rtxErrAddDoubleParm ( OSCTXT pctxt,
double  errParm 
)

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

Parameters
pctxtA pointer to a context structure.
errParmThe double error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddElemNameParm()

EXTERNRT 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
pctxtA pointer to a context structure.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddErrorTableEntry()

EXTERNRT 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
ppStatusTextPointer to table of error status text messages.
minErrCodeMinimum error status code.
maxErrCodeMaximum error status code.
Returns
The status of the operation (TRUE if entry sucessfully added to table).

◆ rtxErrAddInt64Parm()

EXTERNRT 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
pctxtA pointer to a context structure.
errParmThe 64-bit integer error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddIntParm()

EXTERNRT 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
pctxtA pointer to a context structure.
errParmThe integer error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddSizeParm()

EXTERNRT 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
pctxtA pointer to a context structure.
errParmThe integer error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddStrnParm()

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

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

Parameters
pctxtA pointer to a context structure.
pErrParmThe character string error parameter.
ncharsNumber of characters to add from pErrParm.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddStrParm()

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

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

Parameters
pctxtA pointer to a context structure.
pErrParmThe character string error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddUInt64Parm()

EXTERNRT OSBOOL rtxErrAddUInt64Parm ( OSCTXT pctxt,
OSUINT64  errParm 
)

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

Parameters
pctxtA pointer to a context structure.
errParmThe unsigned 64-bit integer error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAddUIntParm()

EXTERNRT OSBOOL rtxErrAddUIntParm ( OSCTXT pctxt,
unsigned int  errParm 
)

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

Parameters
pctxtA pointer to a context structure.
errParmThe unsigned integer error parameter.
Returns
The status of the operation (TRUE if the parameter was sucessfully added).

◆ rtxErrAppend()

EXTERNRT 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
pDestCtxtPointer to destination context structure to receive the copied error information.
pSrcCtxtPointer 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()

EXTERNRT 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
conditionTextThe condition that failed (for example, ptr != NULL)
lineNoLine number in the program of the failure.
fileNameName of the C source file in which the assertion failure occurred.

◆ rtxErrCopy()

EXTERNRT 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
pDestCtxtPointer to destination context structure to receive the copied error information.
pSrcCtxtPointer 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()

EXTERNRT const char* rtxErrFmtMsg ( OSRTErrInfo pErrInfo,
char *  bufp,
size_t  bufsiz 
)

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

Parameters
pErrInfoPointer to error information structure.
bufpPointer to a destination buffer to receive text.
bufsizSize of the buffer.
Returns
Pointer to the buffer (bufp).

◆ rtxErrFreeParms()

EXTERNRT 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
pctxtA pointer to a context structure.

◆ rtxErrGetErrorCnt()

EXTERNRT OSSIZE rtxErrGetErrorCnt ( const OSCTXT pctxt)

This function returns the total number of error records.

Parameters
pctxtA pointer to a context structure.
Returns
The total number of error records in the context.

◆ rtxErrGetFirstError()

EXTERNRT int rtxErrGetFirstError ( const OSCTXT pctxt)

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

Parameters
pctxtA pointer to a context structure.
Returns
The first status code; zero if no error records exist.

◆ rtxErrGetLastError()

EXTERNRT int rtxErrGetLastError ( const OSCTXT pctxt)

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

Parameters
pctxtA pointer to a context structure.
Returns
The last status code; zero if no error records exist.

◆ rtxErrGetMsgText()

EXTERNRT 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
pctxtA 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()

EXTERNRT char* rtxErrGetMsgTextBuf ( OSCTXT pctxt,
char *  pbuf,
size_t  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
pctxtA pointer to a context structure.
pbufPointer to a destination buffer to receive text.
bufsizSize of the buffer.
Returns
Pointer to the buffer (pbuf).

◆ rtxErrGetStatus()

EXTERNRT int rtxErrGetStatus ( const OSCTXT pctxt)

This function returns the status value from the context.

It examines the error list to see how many errors were logged. If none, OK (zero) is returned; if one, then the status value in the single error record is returned; if more than one, the special code RTERR_MULTIPLE is returned to indicate that multiple errors occurred.

Parameters
pctxtA pointer to a context structure.
Returns
Status code corresponding to errors in the context.

◆ rtxErrGetText()

EXTERNRT char* rtxErrGetText ( OSCTXT pctxt,
char *  pBuf,
size_t *  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
pctxtA pointer to a context structure.
pBufA pointer to a destination buffer to obtain the error text. If NULL, dynamic buffer will be allocated.
pBufSizeA 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()

EXTERNRT char* rtxErrGetTextBuf ( OSCTXT pctxt,
char *  pbuf,
size_t  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
pctxtA pointer to a context structure.
pbufPointer to a destination buffer to receive text.
bufsizSize of the buffer.
Returns
Pointer to the buffer (pbuf).

◆ rtxErrInit()

EXTERNRT 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()

EXTERNRT int rtxErrInvUIntOpt ( OSCTXT pctxt,
OSUINT32  ident 
)

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

Parameters
pctxtPointer to context structure.
identIdentifier which was found to be invalid.

◆ rtxErrLogUsingCB()

EXTERNRT 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
pctxtA pointer to a context structure.
cbCallback function pointer.
cbArg_pPointer to a user-defined argument that is passed to the callback function.

◆ rtxErrNewNode()

EXTERNRT 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.

Parameters
pctxtA pointer to a context structure.
Returns
A pointer to a newly allocated error record; NULL, if error occurred.

◆ rtxErrPrint()

EXTERNRT 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
pctxtA pointer to a context structure.

◆ rtxErrPrintElement()

EXTERNRT 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
pErrInfoA pointer to an error information element.

◆ rtxErrReset()

EXTERNRT 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
pctxtA pointer to a context structure.

◆ rtxErrResetLastErrors()

EXTERNRT int rtxErrResetLastErrors ( OSCTXT pctxt,
OSSIZE  errorsToReset 
)

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

Parameters
pctxtA pointer to a context structure.
errorsToResetA 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()

EXTERNRT 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.

Parameters
pctxtA pointer to a context structure.
statusThe error status code from rtxErrCodes.h
moduleThe C source file in which the error occurred.
linenoThe line number within the source file of the error.
Returns
The status code that was passed in.

◆ rtxErrSetNewData()

EXTERNRT 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.

Parameters
pctxtA pointer to a context structure.
statusThe error status code from rtxErrCodes.h
moduleThe C source file in which the error occurred.
linenoThe line number within the source file of the error.
Returns
The status code that was passed in.