Module Simula
Package simula.runtime

Class RTS_Directbytefile

java.lang.Object
simula.runtime.RTS_RTObject
simula.runtime.RTS_ENVIRONMENT
simula.runtime.RTS_BASICIO
simula.runtime.RTS_CLASS
simula.runtime.RTS_File
simula.runtime.RTS_Bytefile
simula.runtime.RTS_Directbytefile
All Implemented Interfaces:
Runnable
public class RTS_Directbytefile extends RTS_Bytefile
System class Directbytefile. This class defines a byte-oriented direct file. 
  bytefile class Directbytefile;
        begin integer LOC, MAXLOC; Boolean LOCKED;
        Boolean procedure endfile; endfile:=OPEN and then LOC>lastloc;
        integer procedure location; location := LOC;
        integer procedure maxloc; maxloc := MAXLOC;
        Boolean procedure locked; locked := LOCKED;
        Boolean procedure open;
        Boolean procedure close;
        integer procedure lastloc;
        procedure locate(i); integer i;
        short integer procedure inbyte;
        procedure outbyte(x); short integer x; 
        Boolean procedure checkpoint; 
        integer procedure lock(t,i,j); real t; integer i,j;
        Boolean procedure unlock;
        procedure intext(t); text t;
        procedure outtext(t); text t; 
           ...
 end Directbytefile;
An object of the class "Directbytefile" is used to represent an external file in which the individual bytes are addressable by ordinal numbers.

The variable LOC is defined to represent such ordinal numbers. When the file is closed, the value of LOC is zero.

In this implementation LOC is maintained by the underlying file system.

Link to GitHub: Source File.

Author:
SIMULA Standards Group, Øystein Myhre Andersen

  • Field Details

    • _MAXLOC

      int _MAXLOC
      The variable MAXLOC indicates the maximum possible location on the external file. If this is not meaningful MAXLOC has the value of "maxint"-1. The procedure "maxloc" gives access to the current MAXLOC value.

    • _LOCKED

      boolean _LOCKED
      The variable "LOCKED" indicates whether the file is currently locked by the executing program. The procedure "locked" returns the current value.

    • randomAccessFile

      private RandomAccessFile randomAccessFile
      The RandomAccessFile used.

    • fileLock

      private FileLock fileLock
      The FileLock

    • INITIAL_LAST_LOC

      private int INITIAL_LAST_LOC
      The initial value of LAST_LOC

  • Constructor Details

    • RTS_Directbytefile

      public RTS_Directbytefile(RTS_RTObject SL, RTS_TXT FN)
      Create a new _Directbytefile.
      Parameters:
      SL - staticLink
      FN - file name

  • Method Details

    • _STM

      public RTS_Directbytefile _STM()
      Description copied from class: RTS_RTObject
      Method representing the Statements in this Block
      This method is virtual and must be redefined in blocks.
      Overrides:
      _STM in class RTS_Bytefile
      Returns:
      a pointer to this _RTObject

    • endfile

      public boolean endfile()
      The procedure endfile.

      It returns true whenever LOC indicates an address greater than "lastloc". 

                      Boolean procedure endfile; endfile:=OPEN and then LOC>lastloc;
      Returns:
      the resulting boolean.

    • location

      public int location()
      The procedure location.

      It returns the current value of LOC.

      In this implementation file.getFilePointer() is used for this purpose.

      Returns:
      the current read/write position.

    • maxloc

      public int maxloc()
      The procedure maxloc. 
        integer procedure maxloc;
     if not OPEN then error("..." ! file closed; )
     else  maxloc := MAXLOC;
      The value assigned to MAXLOC at "open" is either a maximum length determined from the external file, or it is "maxint"-1 if no such length exists.
      Returns:
      the value _MAXLOC.

    • locked

      public boolean locked()
      Returns the value _LOCKED.
      Returns:
      the value _LOCKED.

    • open

      public boolean open()
      The procedure open. 
       Boolean procedure open;
    if ... then begin ...
       LOC      := 1;
       MAXLOC   := ...; ! fixed size, or maxint-1;
       BYTESIZE := ... ! value of access mode BYTESIZE;
       open     := OPEN := true;
 end open;
      Returns:
      true:ok, false:error

    • close

      public boolean close()
      The procedure close. 
       Boolean procedure close;
    if OPEN then begin ...
       MAXLOC := 0;
       OPEN   := false;
       close  := true;
 end close;
      Returns:
      true:ok, false:error

    • locate

      public void locate(int p)
      The procedure locate.

      It is used to assign a given value to the variable LOC. A parameter value to "locate" which is less than one or greater than MAXLOC constitutes a run-time error. 

        procedure locate(p); integer p;
     if p<1 or p>MAXLOC then error("..." ! Parameter out of range; )
     else begin
        LOC:= p;
         ... ;
  end locate;    *
      In this implementation we use the method seek(p) which sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.

      Parameters: pos - the offset position, measured in bytes from the beginning of the file, at which to set the file pointer.

      Throws: IOException - if pos is less than 0 or if an I/O error occurs.

      Parameters:
      p - desired location.

    • lastloc

      public int lastloc()
      The procedure lastloc. 
       integer procedure lastloc;
    if not OPEN then error("..." ! file closed; )
    else lastloc := ...;
      The procedure "lastloc" indicates the largest location of any written image. For a new file the value returned is zero.
      Returns:
      The current last written location.

    • inbyte

      public int inbyte()
      The procedure inbyte.

      It reads one byte, returning its integer value. The result of "inbyte" from an unwritten LOC is zero.

      In this implementation the file.read() read a byte starting at the file pointer and advance the file pointer past the bytes read. I.e. LOC is maintained by the underlying file system. 

       short integer procedure inbyte;
    if not OPEN then error("..." !file closed; )
    else if LOC <= lastloc
    then begin
       inbyte := ... ! next byte of size BYTESIZE;...;
       LOC := LOC+1
 end inbyte;
      Returns:
      the byte value read.

    • outbyte

      public void outbyte(int b)
      The procedure outbyte.

      It outputs a byte according to the given parameter value.

      In this implementation the file.write() writes a byte starting at the file pointer and advance the file pointer past the byte written. I.e. LOC is maintained by the underlying file system. 

       procedure outbyte(x);  short integer x;
    if not OPEN then error("..." !file closed; )
    else if x < 0 or else x >= 2**BYTESIZE
    then error("..." ! Outbyte, illegal byte value ;);
    else if LOC > MAXLOC then error("..." !file overflow; )
    else begin
         ... ! output of x;
         LOC := LOC + 1
 end outbyte;
      Parameters:
      b - the byte value to be written.

    • checkpoint

      public boolean checkpoint()
      The procedure checkpoint.

      All files producing output (sequential output or direct files) contain a Boolean procedure "checkpoint". The procedure causes the environment to attempt to secure the output produced so far. Depending on the nature of the associated external device, this causes completion of output transfer (i.e. intermediate buffer contents are transferred).

      If this is not possible or meaningful, "checkpoint" is a dummy operation in which case the value false is returned.

      Returns:
      true:ok, false:error

    • lock

      public int lock(float timelimit, int loc1, int loc2)
      The procedure lock.

      Direct File Locking

      Procedure "lock" enables the program to get exclusive access to all or part of the file. The effect of a "lock" call while the file is locked ("LOCKED" is true) is that the previous lock is immediately released (prior to the new locking attempt).

      The parameter "timelimit" is the (clock) time in seconds that is the maximum waiting time for the resource. If "timelimit" is less than or equal to zero, the procedure returns immediately without performing any actions upon the file.

      The parameters "loc1" and "loc2" identify the part of the file to be locked, by giving the ordinal numbers of two external images (bytes). The program is given exclusive access to a part of the file which includes the requested region. If the two parameters are both zero, this implies locking the whole file. Otherwise, the size of the part of the file that is actually locked, is implementation-dependent; it may even include the entire file.

      A return value of zero indicates a successful "lock" operation. The value -1 indicates that "timelimit" was exceeded (or was zero or negative). A negative value less than -1 indicates "lock" failure and its interpretation is implementation-defined. 

       integer procedure lock(timelimit,loc1,loc2);
                     real timelimit; integer loc1,loc2;
            begin
               lock := -1;
               if timelimit>0.0 then begin
                  if LOCKED then unlock;
                  ... ! try to lock indicated part of file, see below;
                  if !success; then begin LOCKED := true; lock := 0 end
               end
            end lock;
      The procedures "lock" and "unlock" (see 10.2.2) provide locking mechanisms. The last two parameters of "lock" indicate the minimum range of (byte) locations to be locked (inclusive).

      It is implemented using: 

       public abstract FileLock lock(long position,long size,boolean shared) throws IOException
      With Parameters:
      • position - The position at which the locked region is to start; must be non-negative
      • size - The size of the locked region; must be non-negative, and the sum position + size must be non-negative
      • shared - true to request a shared lock, in which case this channel must be open for reading (and possibly writing); false to request an exclusive lock, in which case this channel must be open for writing (and possibly reading)
      And Returns: A lock object representing the newly-acquired lock
      Parameters:
      timelimit - argument timelimit
      loc1 - argument loc1
      loc2 - argument loc2
      Returns:
      code, 0:OK otherwise error

    • unlock

      public boolean unlock()
      The procedure unlock. 
       Boolean procedure unlock;
 begin
    unlock := checkpoint;
    if LOCKED then begin !release file; LOCKED := false end
 end unlock;
      Returns:
      the resulting boolean value

    • intext

      public RTS_TXT intext(RTS_TXT t)
      The procedure intext.

      It fills the frame of the parameter "t" with successive input bytes. 

       text procedure intext(t);   text t;
    begin
       t.setpos(1);
       while t.more and not ENDFILE do t.putchar(char(inbyte));
       if ENDFILE then t.setpos(t.pos-1);
       intext:- t.sub(1,t.pos-1)
 end intext;
      Parameters:
      t - the argument text
      Returns:
      the resulting text

    • outtext

      public void outtext(RTS_TXT t)
      The procedure outtext. It outputs all characters in the parameter "t" as bytes. 
       procedure outtext(t);   text t;
    begin
       t.setpos(1);
       while t.more do outbyte(rank(t.getchar))
 end outtext;
      Parameters:
      t - the argument text