mariadb/ndb/include/ndbapi/NdbError.hpp

/* Copyright (C) 2003 MySQL AB

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */

#ifndef NDB_ERROR_HPP
#define NDB_ERROR_HPP

/**
 * @struct NdbError
 * @brief Contains error information
 *
 * A NdbError consists of five parts:
 * -# Error status         : Application impact
 * -# Error classification : Logical error group
 * -# Error code           : Internal error code
 * -# Error message        : Context independent description of error 
 * -# Error details        : Context dependent information 
 *                           (not always available)
 *
 * <em>Error status</em> is usually used for programming against errors.
 * If more detailed error control is needed, it is possible to 
 * use the <em>error classification</em>.
 *
 * It is not recommended to write application programs dependent on
 * specific <em>error codes</em>.
 *
 * The <em>error messages</em> and <em>error details</em> may
 * change without notice.
 * 
 * For example of use, see @ref ndbapi_example3.cpp.
 */
struct NdbError {
  /**
   * Status categorizes error codes into status values reflecting
   * what the application should do when encountering errors
   */
  enum Status {
    /**
     * The error code indicate success<br>
     * (Includes classification: NdbError::NoError)
     */
    Success = 0,

    /**
     * The error code indicates a temporary error.
     * The application should typically retry.<br>
     * (Includes classifications: NdbError::InsufficientSpace, 
     *  NdbError::TemporaryResourceError, NdbError::NodeRecoveryError,
     *  NdbError::OverloadError, NdbError::NodeShutdown 
     *  and NdbError::TimeoutExpired.)
     */
    TemporaryError = 1,
    
    /**
     * The error code indicates a permanent error.<br>
     * (Includes classificatons: NdbError::PermanentError, 
     *  NdbError::ApplicationError, NdbError::NoDataFound,
     *  NdbError::ConstraintViolation, NdbError::SchemaError,
     *  NdbError::UserDefinedError, NdbError::InternalError, and, 
     *  NdbError::FunctionNotImplemented.)
     */
    PermanentError = 2,
  
    /**
     * The result/status is unknown.<br>
     * (Includes classifications: NdbError::UnknownResultError, and
     *  NdbError::UnknownErrorCode.)
     */
    UnknownResult = 3
  };
  
  /**
   * Type of error
   */
  enum Classification {
    /**
     * Success.  No error occurred.
     */
    NoError = 0,  

    /**
     * Error in application program.
     */
    ApplicationError = 1,  

    /**
     * Read operation failed due to missing record.
     */
    NoDataFound = 2,

    /**
     * E.g. inserting a tuple with a primary key already existing 
     * in the table.
     */
    ConstraintViolation = 3,

    /**
     * Error in creating table or usage of table.
     */
    SchemaError = 4,

    /**
     * Error occurred in interpreted program.
     */
    UserDefinedError = 5,
    
    /**
     * E.g. insufficient memory for data or indexes.
     */
    InsufficientSpace = 6,

    /**
     * E.g. too many active transactions.
     */
    TemporaryResourceError = 7,

    /**
     * Temporary failures which are probably inflicted by a node
     * recovery in progress.  Examples: information sent between
     * application and NDB lost, distribution change.
     */
    NodeRecoveryError = 8,

    /**
     * E.g. out of log file space.
     */
    OverloadError = 9,

    /**
     * Timeouts, often inflicted by deadlocks in NDB.
     */
    TimeoutExpired = 10,
    
    /**
     * Is is unknown whether the transaction was committed or not.
     */
    UnknownResultError = 11,
    
    /**
     * A serious error in NDB has occurred.
     */
    InternalError = 12,

    /**
     * A function used is not yet implemented.
     */
    FunctionNotImplemented = 13,

    /**
     * Error handler could not determine correct error code.
     */
    UnknownErrorCode = 14,

    /**
     * Node shutdown
     */
    NodeShutdown = 15
  };
  
  /**
   * Error status.  
   */
  Status status;

  /**
   * Error type
   */
  Classification classification;
  
  /**
   * Error code
   */
  int code;

  /**
   * Error message
   */
  const char * message;

  /**
   * The detailed description.  This is extra information regarding the 
   * error which is not included in the error message.
   *
   * @note Is NULL when no details specified
   */
  char * details;

  NdbError(){
    status = UnknownResult;
    classification = NoError;
    code = 0;
    message = 0;
    details = 0;
  }
};

class NdbOut& operator <<(class NdbOut&, const NdbError &);
class NdbOut& operator <<(class NdbOut&, const NdbError::Status&);
class NdbOut& operator <<(class NdbOut&, const NdbError::Classification&);
#endif