ObjectStore does not support the use of the C++ exception handling for error conditions that occur during an ObjectStore operation. Instead, ObjectStore provides the TIX exception-handling facility, which includes an error-reporting mechanism and services for handling ObjectStore exceptions.

This chapter discusses the following topics:

• TIX Exceptions
• Establishing a TIX Exception Handler
• Using the TIX Classes

Note

• Chapter 2, Class Library
• Chapter 4, System-Supplied Macros
• Chapter 5, Predefined TIX Exceptions

Predefined Exceptions

The predefined exceptions are organized into groups. Each group has a parent exception; the exceptions within the group are referred to as child exceptions. Parent exceptions can be used where you would use child exceptions, but they are most useful when specified in a TIX exception handler to catch a group of child exceptions; see Handling Multiple Exceptions.

Parent exceptions are organized hierarchically, as illustrated in the following diagram. Note the following relationships among the parent exceptions:

• Every TIX exception is a descendent of all_exceptions.
• Every TIX exception signaled by ObjectStore is itself a child of err_objectstore, which is a child of all_exceptions.
• Every TIX exception signaled from the remote procedure call (RPC) mechanism, which ObjectStore uses for all its network communications, is a child of err_rpc, which is a child of err_objectstore.

User-Defined Exceptions

DEFINE_EXCEPTION(name, "message", pointer-to-parent ); 
DECLARE_EXCEPTION(name ); 

Arguments

message is the error message to display when the exception is signaled. As shown in the syntax statement, this argument must be enclosed in quotation marks.

pointer-to-parent is the address of a parent exception, which thus becomes the new exception's parent. For information about parent exceptions, see Predefined Exceptions. Supply 0 for this argument if you do not want your exception to have a parent.

Defining and declaring

Signaling

For reference information about signal(), see objectstore_exception::signal() in the C++ API Reference.

Example

The exception is defined in the definitions file, bookclub.cc.

DEFINE_EXCEPTION(err_no_entry_point, 
      "No entry-point object for", 0); 

DECLARE_EXCEPTION(err_no_entry_point); 

err_no_entry_point.signal( 
      "%s - use os_database_root::set_value()", argv[1]); 

In this example, the exception is not handled and the program aborts. However, you can handle user-defined as well as predefined exceptions in a TIX exception handler, as described in Establishing a TIX Exception Handler.

Establishing a TIX Exception Handler

TIX_HANDLE (exception) 
TIX_HANDLE_IF (flag, exception) 
TIX_EXCEPTION 
TIX_END_HANDLE 

• Predefined exception; see Predefined Exceptions.
• User-defined exception; see User-Defined Exceptions.
• Parent exception; see Predefined Exceptions.

An exception handler generally requires two statement blocks, the block in which the exception can occur and the block that actually handles the exception. When establishing a TIX exception handler, use TIX_HANDLE and TIX_END_HANDLE to enclose both blocks and TIX_EXCEPTION to separate them:

TIX_HANDLE(exception) { 
      // exception block 
} TIX_EXCEPTION { 
      // handler block 
} TIX_END_HANDLE 

If the exception is signaled during execution of the statements in the exception block, control passes from the statement that caused the exception to the first statement in the handler block. Otherwise, control passes from the last statement in the exception block to the first statement following TIX_END_HANDLE. For a simple example, see the exception handler used in main.cc, lines 20-28, listed in An Example Application.

If the specified exception is signaled but there is no handler block, control passes directly to the first statement following the TIX_END_HANDLE macro, as if the exception were handled. See Handling Exceptions Outside a Handler.

For reference information about the TIX exception handler macros, see the following in the C++ API Reference:

• TIX_HANDLE()
• TIX_HANDLE_IF()
• TIX_EXCEPTION
• TIX_END_HANDLE

TIX_HANDLE(exception1) { 
      TIX_HANDLE(exception2) { 
            . . . 
            TIX_HANDLE(exceptionN) { 
                  // exception block 
            } TIX_EXCEPTION { 
                  // handler block for exceptionN 
            } TIX_END_HANDLE 
      } TIX_EXCEPTION { 
            // handler block for exception2 
      } TIX_END_HANDLE 
} TIX_EXCEPTION {
      // handler block for exception1 
} TIX_END_HANDLE 

TIX_HANDLE(parent-exception) { 
      // exception block 
} TIX_EXCEPTION { 
      // handler block for all child exceptions under parent-exception 
} TIX_END_HANDLE 

TIX_HANDLE(parent-exception) { 
      TIX_HANDLE(child-exception1) { 
            TIX_HANDLE(child-exception2) { 
                  . . . 
                  TIX_HANDLE(child-exceptionN) { 
                        // exception block 
                  } TIX_EXCEPTION { 
                        // handler block for child-exceptionN 
                  } END_TIX_HANDLE 
            } TIX_EXCEPTION { 
                  // handler block for child-exception2 
            } TIX_END_HANDLE 
      } TIX_EXCEPTION { 
            // handler block for child-exception1 
      } TIX_END_HANDLE 
} TIX_EXCEPTION { 
      // handler block for all other children of parent-exception 
} TIX_END_HANDLE 

#include <ostore/ostore.hh> 
#include <fstream.h> 

main(int argc, char **argv) 
{ 
      objectstore::initialize(); 
      TIX_HANDLE (err_objectstore) { // parent exception 
            // the next two exceptions are descended from err_objectstore 
            TIX_HANDLE (err_database_not_found) { // bad name 
                  TIX_HANDLE (err_invalid_pathname)  { // no argument (null) 
                        os_database* db = os_database::open(argv[1]); 
                        db->close(); 
                        cout << "The database named " << argv[1] << " exists.\n"; 
                  } TIX_EXCEPTION { 
                        cout << "Usage:  " << argv[0] << " <database name>\n";
                  } TIX_END_HANDLE 
            } TIX_EXCEPTION { 
                  cout << "Sorry, no such database. Try again.\n"; 
            } TIX_END_HANDLE 
      } TIX_EXCEPTION { 
            // get a full report on the exception 
            cout << tix_handler::get_report(); 
      } TIX_END_HANDLE 
} 

$ tix_nest 
Usage:  tix_nest <database name> 
$ tix_nest stuff 
Sorry, no such database. Try again. 
$ tix_nest real_db 
The database named real_db exists. 

• $OS_ROOTDIR/examples/doc_demos/ug6/tix_nest.cc (UNIX)
• %OS_ROOTDIR%\examples\doc_demos\ug6\tix_nest.cpp (Windows)

As mentioned in Establishing a TIX Exception Handler, the handler block can be omitted from a TIX exception handler. If an exception occurs in a handler that does not have a handler block, program control passes from the statement in the exception block that caused the exception to the first statement outside the handler. This behavior effectively clears the exception.

To illustrate, consider a handler that prompts the user for a file name if the application fails to open either of two database files with the supplied names. The handler can never prompt for the names of both files, even if the names are both wrong. The reason is that the exception generated by the failed attempt to open the first file would prevent the application from trying to open the second file.

The solution is to enclose the statements that open the database files each in its own handler, without supplying a handler block for either one. Without the handler block, the application tries opening both files, even if it fails to open the first. The code to handle the error conditions follows the second handler, where the application tests whether the files were opened successfully. Following is the coding for the handler:

Example

// no_hndlr.cc: Uses a handler-less TIX exception handler 
// to handle exception signaled if one or the other or both of the 
// databases specified on command line do not exist 
#include <ostore/ostore.hh> 
#include <fstream.h> 

main(int argc, char** argv) 
{ 
      OS_ESTABLISH_FAULT_HANDLER { 
            if(argc!=3) { // check for two command-line arguments 
                  cout << "Usage:  " << argv[0]  << " <db1> <db2>\n"; 
                  return 1; 
            } 

            objectstore::initialize(); 
            // set both os_database pointers to 0 so we can check later to 
            // see which database we were able to open, if any 
            os_database *db1 = 0, *db2 = 0; 
            TIX_HANDLE (err_database_not_found) { 
                  db1 = os_database::open(argv[1]); // open first db 
            } TIX_EXCEPTION { 
                  // no handler code 
            } TIX_END_HANDLE 
            TIX_HANDLE (err_database_not_found) { 
                  db2 = os_database::open(argv[2]); // open second db 
            } TIX_EXCEPTION { 
                  // no handler code 
            } TIX_END_HANDLE 
            // check if files were opened; null means the open failed 
            if (!db1 || !db2) { 
                  cerr << "Cannot open "; 
                  if (db2) 
                        cerr << argv[1]; // failed to open first db 
                  else if (db1) 
                        cerr << argv[2]; // failed to open second db 
                  else // couldn't open either one 
                        cerr << argv[1] << " or " << argv[2]; 
                  cerr << endl; 
                  return 1; 
            } 
            else // both databases exist 
                  cout << "Opened " << argv[1] << " and " << argv[2] << endl; 
      } OS_END_FAULT_HANDLER 
      return 0; 
} 

$ no_hndlr no_db1 real_db2 
Cannot open no_db1 
$ no_hndlr real_db1 no_db2 
Cannot open no_db2 
$ no_hndlr no_db1 no_db2 
Cannot open no_db1 or no_db2 

• $OS_ROOTDIR/examples/doc_demos/ug6/no_hndlr.cc (UNIX)
• %OS_ROOTDIR%\examples\doc_demos\ug6\no_hndlr.cpp (Windows)

basic_undo 
objectstore_exception 
os_lock_timeout_exception 
tix_context 
tix_exception 
tix_handler 

For detailed information about the TIX classes and their member functions, see the following in the C++ API Reference:

• basic_undo
• objectstore_exception
• os_lock_timeout_exception
• tix_context
• tix_exception
• tix_handler

The signal() function is useful when the application can detect an error condition before ObjectStore can. Instead of performing superfluous processing, it signals the exception. For example, an application can detect that a string that holds the name of a database is empty. Instead of trying to open the file, it can signal err_invalid_pathname or any other appropriate exception, as follows:

if (!*name) 
      err_invalid_pathname.signal("The string you supplied for 
filename is empty."); 

signal() also performs printf-like formatting for any additional messages you might want to display. signal() thus enables you to give more specific information about the exception and program state at the time of the exception.

The message is displayed only if the exception is not handled. If you call signal() inside a handler, you can supply an empty string ("") for the message argument.

For more information about signal(), see objectstore_exception::signal() in the C++ API Reference.

Displaying Additional Error Information

• tix_context
• tix_handler

Consider, for example, the following declaration of tc_var:

{ // block A 
      . . . 
      { // block B 
            tix_context tc_var("Hello, world\n"); 
            . . . 
            { // block C 
                  . . . 
            } 
      }
} 

tix_context can be useful as a debugging tool, similar to the printf statement. That is, you can declare tix_context variables in different parts of your program that you suspect of causing an exception, so that a formatted message is displayed only if an exception occurs in the same scope.

tix_handler

For more information about get_report() and get_report0(), see the following in the C++ API Reference:

• tix_handler::get_report()
• tix_handler::get_report0()

TIX_HANDLE (err_database_not_found) { 
      db1 = os_database::open(path); 
} TIX_EXCEPTION { 
      // cerr << tix_handler::get_report(); 
      cerr << "Bad file name\n"; 
} TIX_END_HANDLE 

Bad file name 

The database was not found 
handcuff:/h/handcuff/2/jimmy/debug/test_tix/stuff 
(err_database_not_found) 
Bad file name 

Updated: 03/09/99 13:54:54