The TMCLibError library — API documentation

TMC Suite package. A small auxiliary static library — an "error carrier" (error-object). All signatures are taken from the sources in src/libs/TMCLibError/TmcLibError.cpp and the header src/Include/TmcLibError.h.

1. Purpose of the library

TMCLibError is a small auxiliary library that implements the "error-carrier object" pattern (error-object). Its single class CTmcLibError is a container passed by reference (CTmcLibError&) into the methods of the computational classes of other libraries. A method that detects an error writes a text message into this object, and the calling code then checks for the fact of the error and reads the message.

Key features of the model:

• the error is stored as text — a CString string (not a numeric code);
• only the last error is stored: a new message overwrites the previous one;
• there is no error stack and no numeric codes;
• the "error present / absent" state is reflected by the boolean flag BOOL bIsError.

Important: the library is not related to the numeric error codes from Error1.h. These are two independent subsystems (see section 7).

Besides the class, the header declares two free functions that generate temporary file names (see section 4).

2. Build composition

The TMCLibError.vcxproj build contains a single implementation file:

The included header is ..\..\INCLUDE\TmcLibError.h (the package's shared header, src/Include/TmcLibError.h).

Project parameters (TMCLibError.vcxproj):

Since UseOfMfc=Static and CharacterSet=MultiByte, the library uses MFC classes (in particular CString) and is compiled in a multibyte (non-Unicode) encoding.

The old project file in .vcproj format (legacy) is not considered in this documentation.

3. The CTmcLibError class

Declared in TmcLibError.h, implemented in TmcLibError.cpp.

class CTmcLibError
{
public:
    void PutErrorMessage( char *pszErrorMessage );
    void PutErrorMessage( CString csErrorMessage );
    CString GetErrorMessage( void );
    BOOL IsError( void );
    void Clear( void );
    CTmcLibError& operator=( CTmcLibError& cError1 );
    CTmcLibError();

public:
    virtual ~CTmcLibError();

private:
    CString csError;
    BOOL    bIsError;
};

3.1. Purpose of the class

CTmcLibError is an error-state container. An instance is created in a "clean" state (no error), then passed by reference into computational methods; those call PutErrorMessage(...) when necessary. The calling code uses IsError() and GetErrorMessage().

3.2. Fields (private)

Both fields are private and accessible only through the public methods.

3.3. Public methods

CTmcLibError()

CTmcLibError();

The constructor. Brings the object into the "no error" state:

• sets bIsError = FALSE;

• initializes csError with the string "Error:no" (via csError.Format(CTMCRTHERROR_0000)).

• Parameters: none.

• Return: none (a constructor).

virtual ~CTmcLibError()

virtual ~CTmcLibError();

The destructor. Its body is empty (return;) — no resources are freed manually (the CString memory is freed by MFC itself). It is declared virtual, which allows correct deletion through a base-class pointer under inheritance.

• Parameters: none.
• Return: none (a destructor).

void Clear( void )

void Clear( void );

Resets the error state to the initial one:

• bIsError = FALSE;
• csError ← "Error:no" (CTMCRTHERROR_0000).

The method body contains commented-out debugging calls to AfxMessageBox (tracing messages "Trace0", "Trace1", "Trace2") — they are inactive in the production build.

• Parameters: none.
• Return: void.

BOOL IsError( void )

BOOL IsError( void );

Checks for the presence of an error.

• Parameters: none.
• Return: the value of the bIsError field (TRUE — an error is set, FALSE — no error).

void PutErrorMessage( CString csErrorMessage )

void PutErrorMessage( CString csErrorMessage );

Set an error by passing the message as a CString object.

• sets bIsError = TRUE;

• assigns csError = csErrorMessage.

• Parameters:

• csErrorMessage (CString) — the text of the error message.
• Return: void.
• Behavior: overwrites any previous message (only the last one is stored).

void PutErrorMessage( char *pszErrorMessage )

void PutErrorMessage( char *pszErrorMessage );

An overload: set an error by passing the message as a C string.

• sets bIsError = TRUE;

• forms csError via csError.Format( "%s", pszErrorMessage ).

• Parameters:

• pszErrorMessage (char*) — a pointer to a null-terminated string.
• Return: void.
• Behavior: overwrites the previous message.

About the inactive overload PutErrorMessage( char *pszErrorMessage, ... ). In TmcLibError.cpp there is a fully commented-out variant with a variable number of arguments and formatting via vsprintf (with a buffer of length CTMCRTHERROR_STRLENMAX). It is not declared in the header and does not compile — it is mentioned here only for completeness. This method is absent from the production build.

CString GetErrorMessage( void )

CString GetErrorMessage( void );

Get the text of the last error.

• Parameters: none.
• Return: the value of the csError field (CString). If no error was set, the default string "Error:no" is returned.
• Note: the method returns the value regardless of bIsError; for correct interpretation, check IsError() first.

CTmcLibError& operator=( CTmcLibError& cError1 )

CTmcLibError& operator=( CTmcLibError& cError1 );

The assignment operator. Copies the error state from cError1 into the current object:

• bIsError = cError1.IsError();

• csError.Format( "%s", cError1.GetErrorMessage() );

• Parameters:

• cError1 (CTmcLibError&) — the source object (passed by non-const reference).
• Return: CTmcLibError& — a reference to the current object (*this), which allows chained assignments.

4. Free functions

Declared in TmcLibError.h and implemented in TmcLibError.cpp. They have no relation to the CTmcLibError class — they are utilities for forming temporary file names.

void MakeTempFileNameForBzCalcMn( CString& csTplFileName )

void MakeTempFileNameForBzCalcMn( CString & csTplFileName );

Appends the suffix "_for_Bz_Mn" to the passed file name (at the end of the string, via +=).

• Parameters:
• csTplFileName (CString&) — the file name; modified in place (in/out).
• Return: void (the result is in the parameter itself).
• Purpose (by the name): forming a temporary file name for computing the Bz component (the "minus" variant, Mn).

void MakeTempFileNameForBzCalcPl( CString& csTplFileName )

void MakeTempFileNameForBzCalcPl( CString & csTplFileName );

Appends the suffix "_for_Bz_Pl" to the passed file name.

• Parameters:
• csTplFileName (CString&) — the file name; modified in place (in/out).
• Return: void (the result is in the parameter itself).
• Purpose (by the name): forming a temporary file name for computing the Bz component (the "plus" variant, Pl).

5. Header macros

Defined in TmcLibError.h.

All the macros CTMCRTHERROR_0001..CTMCRTHERROR_0010 have the same value "Error:" and are not used anywhere.

6. The scheme of storing and passing errors

The error model in TMCLibError is extremely simple:

• State = one CString csError string + one BOOL bIsError flag.
• Only the last error. There is no stack, no history, no numeric codes — a repeated call of PutErrorMessage(...) overwrites the previous text.

The typical passing scheme (by reference). A CTmcLibError object is created by the calling code and passed by reference CTmcLibError& into the methods of computational classes, for example (the signatures are from the TMCIndan library, which uses TMCLibError):

Read( CString& , CTmcLibError& );
IsCorrectly( CTmcLibError& );
Search_1Param( ... , CTmcLibError& );

Inside such a method, on an error the following is called:

cError.PutErrorMessage( "error text" );

After the return the calling code checks the state:

if( cError.IsError() )
{
    CString msg = cError.GetErrorMessage();
    // display / handle the message
}

There is no connection with the numeric codes of Error1.h in this scheme — the message is always text.

7. Dependencies

MFC. The implementation includes stdafx.h (which usually pulls in afx.h / afxwin.h). From MFC the following are used:

• CString — storing and formatting the error text and file names;
• BOOL — the state flag;
• AfxMessageBox — only in the commented-out debugging code of Clear().

The header TmcLibError.h directly includes <cstringt.h> (the declaration of the ATL/MFC CString classes). The line #include <windows.h> in the header is commented out.

The package libraries complex, exprint, PREPR, SFILE95 are not used — there are no direct #includes from them in TMCLibError.

The separate Error1.h subsystem is NOT related to TMCLibError. Error1.h is an independent legacy error-handling subsystem with numeric codes and functions like put_error_messege, SetErrorFileName (with the _far / _fortran attributes — a win16 legacy). It has no relation to the CTmcLibError class. These two systems should not be confused: CTmcLibError stores the error as text, Error1.h operates on numeric codes.

8. Usage

Linking by the kernels. Both compute kernels — PlanarRT_H (tmc_rth.exe) and PlanarRT_X (tmc_rtx.exe) — list TMCLibError.lib in AdditionalDependencies (together with sfile95, prepr, exprint, TMCIndan).

Actual use — in the TMCIndan library. Although the kernels link against TMCLibError.lib directly, the CTmcLibError class is actually used inside the TMCIndan library, which in turn is used by the kernels. The places of use (from the TMCIndan sources):

• TmcRTH_IndanTopology.cpp;
• TmcRTH_IndanParam.cpp;
• TmcRTH_IndanOutput.cpp;
• FieldIntegrated.cpp — the CFieldIntegrated::GetError() method returns a CTmcLibError& (the error-carrier object is given to the caller by reference).

Do not confuse with CTmcTtoS. The viewers have a separate class of similar meaning, CTmcTtoS (TmcTtoS.cpp), with fields of the same purpose (bIsError / csError). It is not CTmcLibError and not part of the TMCLibError library — only the idea of an "error carrier" coincides. They should be distinguished.