-- DBEnvironment.mesa
-- Common definitions for public DB interface.  This is the only Cypress interface upon
-- which recompilation of the external DB interface is dependent.
-- Last edited by
--   MBrown on February 22, 1983 11:24 am
--   Cattell on June 6, 1983 3:12 pm
--   Willie-Sue on February 10, 1983 11:31 am

DIRECTORY
    -- AlpineEnvironment USING [OpenFileID, TransID],
    File USING [Capability],
    Rope USING [ROPE],
    Transaction USING [Handle];

DBEnvironment: CEDAR DEFINITIONS = BEGIN


-- Entity and Relship object type

  TupleObject: TYPE;

-- Other useful types

  FirstLast: TYPE = {First, Last};
  Version: TYPE = {OldOnly, NewOnly, NewOrOld};

-- Transaction Handles

  PilotTrans: TYPE = REF PilotTransRecord;
  PilotTransRecord: TYPE = RECORD [
    trans: Transaction.Handle
    ];

  PilotOpenFileHandle: TYPE = REF PilotOpenFileRecord;
  PilotOpenFileRecord: TYPE = RECORD [
    trans: PilotTrans,
    file: File.Capability
    ];

  -- AlpineTrans: TYPE = REF AlpineTransRecord;
  -- AlpineTransRecord: TYPE = RECORD [
  --   t: AlpineEnvironment.TransID
  --   ];

  -- AlpineOpenFileHandle: TYPE = REF AlpineOpenFileRecord;
  -- AlpineOpenFileRecord: TYPE = RECORD [
  --   f: AlpineEnvironment.OpenFileID
  --   ];

  
-- Cypress signal definitions (these signals are exported by DBModelSystemImpl to here and DB)
  
Error: SIGNAL[code: ErrorCode]; -- Exported to be same as DB.Error

-- The Error signal is generated when an illegal operation is requested by the Cypress client.
-- This error may be due to a programming error, bad data in the database, etc.

-- Error is defined as SIGNAL rather than ERROR so that database operations can
-- sometimes be recovered by proceeding despite problems, but they are not generally
-- RESUMEable unless specified to be such here.  The client can CONTINUE from a signal 
-- and retry, if that makes any kind of sense for the particular kind of error. 
  
ErrorCode: TYPE = {
  AlreadyExists, -- DeclareEntity, DeclareRelship: already exists, but version=NewOnly
  DatabaseNotInitialized, -- Attempt to perform operation without calling DB.Initialize
  DictionaryUpdate, -- Attempt to modify a dictionary relship or entity:
  EntityOrRelshipSetsOpen, -- Excessive Domain/RelationSubsets still open (CloseTransaction).
  FileNotFound, -- No existing segment found with given file name, and version=OldOnly
  IllegalAttribute, -- Attribute not of the given relship's Relation or not attribute
  IllegalDomain, -- Argument is not actually a domain
  IllegalFileName, -- No directory or machine given for segment, or invalid chars in name
  IllegalEntity, -- Argument to GetP, or etc., is not an Entity
  IllegalRelship, -- Argument to GetF, or etc., is not a Relship
  IllegalRelation, -- Argument is not a relation
  IllegalSegment, -- Segment passed to DeclareDomain, or etc., not yet declared.
  IllegalString, -- Nulls not allowed in ROPEs passed to the database system
  IllegalSuperType, -- Can't define subtype of domain that already has entities
  IllegalValue, -- Value is not REF INT, ROPE, REF BOOL, or Entity
  IllegalValueType, -- Type passed DeclareAttribute is not datatype or domain
  MismatchedProperty, -- aOf and aIs attribute not from the same relation
  MismatchedAttributeValueType, -- Value not same type as required (SetF)
  MismatchedExistingAttribute, -- Existing attribute is different (DeclareAttribute)
  MismatchedExistingSegment, -- Existing segment has different # or name
  MismatchedPropertyCardinality, -- Did GetP with aOf that is not a Key
  MismatchedSegment, -- Attempt to create reference across segment boundary (e.g., SetF)
  MismatchedValueType, -- value passed V2E, V2I, etc. not of expected type
  MultipleMatch, -- More than one relationship satisfied avl on DeclareRelship.
  MustSetKeyAttributeFirst, -- For now, must set key attribute of a Relship before others
  NonUniqueEntityName, -- Entity in domain with that name already exists
  NonUniqueKeyValue, -- Relship already exists with same value for a key attribute
  NotFound, -- Version is OldOnly but no such Entity, Relation, or etc found
  NotImplemented, -- Action requested is not currently implemented
  NILArgument, -- Attempt to perform operation on NIL argument
  NullifiedArgument, -- Entity or relationship has been deleted, or invalidated by trans abort
  ProtectionViolation, -- Read or write to segment file not permitted this user.
  SegmentNotDeclared, -- Attempt to open transaction on segment with no DeclareSegment
  ServerNotFound, -- File server does not exist or does not respond
  TransactionNotOpen, -- Attempt to perform operation with no transaction open
  TransactionAlreadyOpen, -- Attempt to open transaction on segment already associated w/one
  WriteNotAllowed, -- Attempt to write data but DeclareSegment specified read-only
  Unknown -- Unknown or not yet assigned error code
  };


Aborted: ERROR [trans: REF ANY];
  -- This signal is generated when a read or write operation is performed and the transaction
  -- trans is being aborted.  Client must explicitly call AbortTransaction and OpenTransaction
  -- to proceed.  Client must normally wants to block other database calls until this is done.
  -- Other database calls before AbortTransaction is complete will also get the Aborted signal.
  -- Other database calls after that but before OpenTransaction will get Error[NullifiedArgument].
  -- Database calls after that but on entities or relationships which have not been re-initialized
  -- will also get Error[NullifiedArgument].  NOTE: trans is defined a REF ANY instead of
  -- defining type Transaction because the compiler confuses the latter with the Transaction
  -- interface (of Pilot).   

    
Failure: ERROR [what: ATOM, info: Rope.ROPE];
  -- The errors which create this signal are not recoverable.  Clients must abort the
  -- execution of the system.  Argument "what" indicate the reason for the error.  The
  -- other can be used to pass some piece of information about the error.
  -- Note that there are two kinds of fatal errors.  One is machine malfunction such as a
  -- bad disk.  The other is resource exhaustion, such as memory space exhausted.
  -- See Rick or Mark for current definition of "what"; it is being changed weekly.


Fatal: ERROR [ec: FatalCode];
  -- This error will be replaced by Failure above; it is being phased out.

FatalCode: TYPE = MACHINE DEPENDENT {
  Unknown,
  ServerFailure, -- Random things that can go wrong with Alpine, for now...
  AllCachePagesLocked, -- DBCacheImpl.ReadPage, WritePage, NewPage
  FileTooLarge,
  FileClosed,
  TupleTooLong, -- Hint at number of refs given DeclareDomain not big enough.  Sorry!!!
  UserPineResultError, -- DBFileImpl
  LockResponseError,
  IllegalFileLength, -- DBFileImpl
  FileOverflow,
  SegmentTableOverflow,
  WriteoutCacheFailed -- SegmentImpl.CloseDatabase
  (LAST[CARDINAL]) };


InternalError: ERROR;
  -- This error should not be generated if there are no bugs in database system, all
  -- clients programs are safe, and there are no other system or hardware errors.
  -- Therefore, in normal use clients should not catch this signal,
  -- it is made visible for debugging purposes.  No error code is passed; comment
  -- should be in code at point of error generation giving more information.


END.

CHANGE LOG


Changed by Cattell on January 14, 1983 1:28 pm:
-- Got rid of old DBException interface created January 4, 1980 (!), moved all references to its contents to reference here.  Moved the Error signal from the DB interface to here.

Changed by Willie-Sue on February 10, 1983:
--  Took out references to Juniper

Changed by MBrown on February 10, 1983:
--  Flushed references to UserPine in FatalCode.  Commented-out all Alpine dependencies,
--since Alpine is not stable enough yet.

Changed by Cattell on June 6, 1983:
-- Added CommunicationFailure.