CONVENTIONS FOR HANDLING ERRORS

No exception handling is supported, so the following scheme has been
implemented in the code. It has been designed to keep error handling
simple and should allow simple porting to exception-handling platforms
in the future.

Errors associated with a given class fall into two categories:

1. Errors in state

   These errors mean that the object is in a bad state. Information
   provided by this object should not be trusted, and the object may
   very well not perform actions requested of it because of these
   errors. These errors include allocation and several other types of
   errors.

   Many of these errors can occur during construction or during an
   operator call (such as operator=()), but neither of these allow
   error information to be passed back to the calling code. Therefore,
   a special error() method has been provided for these cases. It is
   intended that the error() method ONLY be called after these
   situations, although the information should be valid at any time.

   When exceptions are supported, the error() method will likely be
   dropped.

   Examples:

   LogExtentList lel(5);
   if ( lel.error() ) {
       <<handle error>>;
   }

   lel = tmpEL;
   if ( lel.error() ) {
       <<handle error>>;
   }

2. Operational Errors

   These errors indicate that an action or operation which has been
   requested of the object was not able to successfully complete.
   These include errors associated solely with the task requested, but
   also errors in state (see above). For example, if a write action is
   requested of an extent which was not properly allocated, it will
   indicate that its operational error was an allocation error.

   All methods which perform an operation have as their last argument
   a reference to an Error object. This is an OUT parameter, in that
   its initial value is ignored by the method. The value of error
   which the method returns should be checked immediately after the
   function returns.

   It is possible that some operational errors will introduce errors
   in state during their execution. If this occurs, the object will be
   placed into an error state, and subsequent calls to error() will
   return the problem. Note that the user is not expected to call
   error(), however. Rather, the next operation which requires that
   the object not be in that error state will return it as its
   operational error as well.

   When exceptions are supported, these methods will likely drop the
   error argument.

   Examples:

   Error err;
   lel.fromADTable(adt,err);
   if ( err ) {
       <<handle error>>;
   }

   LogExtent * lep;
   lep = lel.at(0,err);
   if ( err ) {
       <<handle error>>;
   }
   lep->read(buf,len,err);
   if ( err ) {
       <<handle error>>;
   }

Several methods do not introduce any errors in state, and do not have
any operational errors. These are typically methods which simply
provide access to state information in the object, such as access to
data members. These are closely tied to the notion of errors in
state. Thus, it is expected that if all construction and operator
calls are followed by a call to error(), and the error is checked
after each operation, these methods should have no error-handling
concerns.

Examples:

UINT32 blockNum;
start  = lep->startBlock();
length = lep->infoLen();




