Error Handling

Most of the SmartSockets functions return FALSE on failure, and TRUE on success. The corresponding C++ member functions instead set a status flag in the object. A block written in C looks similar to this:

if (!TipcMsgAppendStr(msg, "voltage")) { 
    TutOut("Could not append first field.\n"); 
    return T_EXIT_FAILURE; 
} 

In C++, this same program looks similar to this:

msg << "voltage"; 
if (!msg) { 
    TutOut("Could not append first field.\n"); 
    return T_EXIT_FAILURE; 
} 

The question arises, what does the ! operator do when applied to a C++ object such as msg? The answer is contained in the declaration of the Tobj class at the root of the C++ class library hierarchy, as in this example:

#include <rtworks/ipc.h> 
 
class Tobj { 
protected: 
    T_BOOL    _status; 
 
    Tobj(); 
    virtual Tobj() {} 
 
public: 
    // ------------------------------------------ 
    //  Methods for accessing status 
    // ------------------------------------------ 
    T_BOOL operator!() const { return !_status; } 
    T_BOOL Status() const { return _status; } 
}; 

As shown above, the Tobj class manages a status flag, which is set to TRUE at construction. Each object derived from Tobj inherits its own private version of this status flag. You gain access to the status flag value by calling either the overloaded operator!() or the Status() member function. In this way, Tobj permits value return function calls without precluding the ability to error-check each call to the underlying C API. To see how this is accomplished, consider TipcMsg::Dest():

First, TipcMsg::Dest() calls the C API’s TipcMsgGetDest(). Then it sets the status flag of TipcMsg to the status value returned by TipcMsgGetDest(). Finally, it returns the value of the destination field of the message as the member function’s return value. This is illustrated in this example by using T_BOOL TipcMsg::Dest().

// ===============================================================  
//..TipcMsg::Dest -- get the destination property of a message  
T_STR TipcMsg::Dest() 
{ 
  T_STR dest_return = "";  // initialize variable 
 
  _status = TipcMsgGetDest(_msg, &dest_return); 
  return dest_return; 
} 

When using TipcMsg::Dest(), you access the status by using either the ! operator or the Status() member function. For example:

TipcMsg msg; 
 
T_STR the_dest = msg.Dest(); 
 
// one way to access the status 
if (!msg) { 
   // handle the error 
} 
 
// another way to access the status 
if (!msg.Status()) { 
   // handle the error 
} 

Typically, C++ class library member functions that access information return a value. Otherwise, class library member functions return the status and set the internal status flag. This is illustrated by T_BOOL TipcMsg::Dest(T_STR dest):

// ===============================================================   
//..TipcMsg::Dest -- set the destination property of a message   
T_BOOL TipcMsg::Dest(T_STR dest) 
{ 
  _status = TipcMsgSetDest(_msg, dest); 
  return _status; 
} 

The use of the C API’s status return convention can be avoided by using Tobj::operator!() or Tobj::Status(). The only exception to this is when using static member functions. See Error Checking and Static Member Functions.

Because the Tobj constructor is protected, the class is rendered into an abstract base class. Users of the C++ class library interact with derived classes of Tobj only.

Error Checking and Static Member Functions

Because a static member function call involves no C++ this pointer, there is also no corresponding Tobj base class instance in which to store a result status should a static member function fail. Therefore, to perform accurate error checking after static member function calls, consult the global SmartSockets error number.