gcc/m2/gm2-libs-iso/RndFile.def

   1 (* Library module defined by the International Standard
   2    Information technology - programming languages
   3    BS ISO/IEC 10514-1:1996E Part 1: Modula-2, Base Language.
   4
   5    Copyright ISO/IEC (International Organization for Standardization
   6    and International Electrotechnical Commission) 1996-2021.
   7
   8    It may be freely copied for the purpose of implementation (see page
   9    707 of the Information technology - Programming languages Part 1:
  10    Modula-2, Base Language.  BS ISO/IEC 10514-1:1996).  *)
  11
  12 DEFINITION MODULE RndFile;
  13
  14   (* Random access files *)
  15
  16 IMPORT IOChan, ChanConsts, SYSTEM;
  17
  18 TYPE
  19    ChanId = IOChan.ChanId;
  20    FlagSet = ChanConsts.FlagSet;
  21    OpenResults = ChanConsts.OpenResults;
  22
  23    (* Accepted singleton values of FlagSet *)
  24
  25 CONST
  26    (* input operations are requested/available *)
  27    read = FlagSet{ChanConsts.readFlag};
  28    (* output operations are requested/available *)
  29    write = FlagSet{ChanConsts.writeFlag};
  30    (* a file may/must/did exist before the channel is opened *)
  31    old = FlagSet{ChanConsts.oldFlag};
  32    (* text operations are requested/available *)
  33    text = FlagSet{ChanConsts.textFlag};
  34    (* raw operations are requested/available *)
  35    raw = FlagSet{ChanConsts.rawFlag};
  36
  37 PROCEDURE OpenOld (VAR cid: ChanId; name: ARRAY OF CHAR; flags: FlagSet;
  38                    VAR res: OpenResults);
  39   (* Attempts to obtain and open a channel connected to a stored random
  40      access file of the given name.
  41      The old flag is implied; without the write flag, read is implied;
  42      without the text flag, raw is implied.
  43      If successful, assigns to cid the identity of the opened channel,
  44      assigns the value opened to res, and sets the read/write position
  45      to the start of the file.
  46      If a channel cannot be opened as required, the value of res indicates
  47      the reason, and cid identifies the invalid channel.
  48   *)
  49
  50 PROCEDURE OpenClean (VAR cid: ChanId; name: ARRAY OF CHAR; flags: FlagSet;
  51                      VAR res: OpenResults);
  52   (* Attempts to obtain and open a channel connected to a stored random
  53      access file of the given name.
  54      The write flag is implied; without the text flag, raw is implied.
  55      If successful, assigns to cid the identity of the opened channel,
  56      assigns the value opened to res, and truncates the file to zero length.
  57      If a channel cannot be opened as required, the value of res indicates
  58      the reason, and cid identifies the invalid channel.
  59   *)
  60
  61 PROCEDURE IsRndFile (cid: ChanId): BOOLEAN;
  62   (* Tests if the channel identified by cid is open to a random access file. *)
  63
  64 PROCEDURE IsRndFileException (): BOOLEAN;
  65   (* Returns TRUE if the current coroutine is in the exceptional execution
  66      state because of the raising of a RndFile exception; otherwise returns
  67      FALSE.
  68   *)
  69
  70 CONST
  71    FilePosSize = SIZE(LONGINT) ;
  72    (* <implementation-defined whole number greater than zero>; *)
  73
  74 TYPE
  75    FilePos = LONGINT ;  (* ARRAY [1 .. FilePosSize] OF SYSTEM.LOC; *)
  76
  77 PROCEDURE StartPos (cid: ChanId): FilePos;
  78   (* If the channel identified by cid is not open to a random access file,
  79      the exception wrongDevice is raised; otherwise returns the position of
  80      the start of the file.
  81   *)
  82
  83 PROCEDURE CurrentPos (cid: ChanId): FilePos;
  84   (* If the channel identified by cid is not open to a random access file,
  85      the exception wrongDevice is raised; otherwise returns the position
  86      of the current read/write position.
  87   *)
  88
  89 PROCEDURE EndPos (cid: ChanId): FilePos;
  90   (* If the channel identified by cid is not open to a random access file,
  91      the exception wrongDevice is raised; otherwise returns the first
  92      position after which there have been no writes.
  93   *)
  94
  95 PROCEDURE NewPos (cid: ChanId; chunks: INTEGER; chunkSize: CARDINAL;
  96                   from: FilePos): FilePos;
  97   (* If the channel identified by cid is not open to a random access file,
  98      the exception wrongDevice is raised; otherwise returns the position
  99      (chunks * chunkSize) relative to the position given by from, or
 100      raises the exception posRange if the required position cannot be
 101      represented as a value of type FilePos.
 102   *)
 103
 104 PROCEDURE SetPos (cid: ChanId; pos: FilePos);
 105   (* If the channel identified by cid is not open to a random access file,
 106      the exception wrongDevice is raised; otherwise sets the read/write
 107      position to the value given by pos.
 108   *)
 109
 110 PROCEDURE Close (VAR cid: ChanId);
 111   (* If the channel identified by cid is not open to a random access file,
 112      the exception wrongDevice is raised; otherwise closes the channel,
 113      and assigns the value identifying the invalid channel to cid.
 114   *)
 115
 116 END RndFile.