Module Simula
Package simula.runtime

Class RTS_Directfile

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_Imagefile
simula.runtime.RTS_Directfile
All Implemented Interfaces:
Runnable
public class RTS_Directfile extends RTS_Imagefile
System class Directfile. 
  imagefile class directfile;
     begin integer LOC, MAXLOC; Boolean ENDFILE, LOCKED;
        integer procedure location; location:= LOC;
        Boolean procedure endfile; endfile := ENDFILE;
        Boolean procedure locked; locked  := LOCKED;
        Boolean procedure open(fileimage); text fileimage;
        Boolean procedure close;
        integer procedure lastloc;
        integer procedure maxloc;
        procedure locate(i); integer i; 
        procedure inimage; 
        procedure outimage; 
        Boolean procedure deleteimage; 
        character procedure inchar; 
        integer procedure lock(t,i,j); real t; integer i,j; 
        Boolean procedure unlock; 
        Boolean procedure checkpoint; 
        Boolean procedure lastitem; 
        text procedure intext; 
        integer procedure inint; 
        long real procedure inreal; 
        integer procedure infrac; 
        procedure outchar(c); character c; 
        procedure outtext(t); text t; 
        text procedure FIELD(w); integer w;
        procedure outint(i,w); integer i,w; 
        procedure outfix(r,n,w); long real r; integer n,w; 
        procedure outreal(r,n,w); long real r; integer n,w; 
        procedure outfrac(i,n,w); integer i,n,w; 
 
        ENDFILE:= true
        ...
  end directfile;
An object of the class "directfile" is used to represent an image-oriented direct file in which the individual images 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.

Link to GitHub: Source File.

Author:
SIMULA Standards Group, Øystein Myhre Andersen

  • Field Details

    • _LOC

      int _LOC
      The variable LOC contains the current ordinal number. When the file is closed, the value of LOC is set to zero. The procedure "location" gives access to the current value of LOC.

    • _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.

    • _RECORDSIZE

      int _RECORDSIZE
      The variable "RECORDSIZE" is the fixed size of all external images. It is set by "open" and subdivide the external file into series of external images, without any image separating characters.

    • 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_Directfile

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

  • Method Details

    • _STM

      public RTS_Directfile _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_Imagefile
      Returns:
      a pointer to this _RTObject

    • location

      public int location()
      The procedure "location" returns the current value of LOC.
      Returns:
      the current read/write position.

    • endfile

      public boolean endfile()
      The variable ENDFILE is true when the file is closed or when an image with location greater than "lastloc" has been input (through "inimage"). It is set after each "inimage" statement. The procedure "endfile" returns the current value.
      Returns:
      the resulting boolean.

    • locked

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

    • open

      public boolean open(RTS_TXT IMAGE)
      The procedure open. 
        Boolean procedure open(fileimage);  text fileimage;
     if ... then begin ...  ! see 10.1.2;
        MAXLOC := ... ; ! See below;
        image  :- fileimage;
        setpos(1);
        locate(1);
        open   := OPEN := true;
        end open;
      The procedure "open" locates the first image of the file. The length of "image" must, at all "inimage" and "outimage" statements, be identical to the length of "image" at the "open" call. 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.
      Parameters:
      IMAGE - the file's image.
      Returns:
      true:ok, false:error

    • close

      public boolean close()
      The procedure close. 
       Boolean procedure close;
    if OPEN then begin ...
       image :- notext;
       if LOCKED then unlock;
       LOC   := MAXLOC := 0;
       ... ;
       OPEN  := false;
       close := ENDFILE := true;
 end close;
      Returns:
      true:ok, false:error

    • locate

      public void locate(int p)
      The procedure locate.

      The procedure "locate" 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(i); integer i;
     if i<1 or i>MAXLOC then error("..." ! Parameter out of range; )
     else begin
        LOC:= i;
         ... ;
  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.
      Throws:
      RTS_SimulaRuntimeError - when unable to perform the operation.

    • 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.
      Throws:
      RTS_SimulaRuntimeError - when unable to perform the operation.

    • 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.
      Throws:
      RTS_SimulaRuntimeError - if the file is not open.

    • inimage

      public void inimage()
      The Procedure Inimage. 
       procedure inimage;
    if not OPEN then error("..." !file closed; )
    else begin
       setpos(1);
       ENDFILE:= LOC > lastloc;
       if ENDFILE then image:= "!25!" else
       if ... ! external written image at LOC exists ; then
          ... ! transfer to "image";...
       else begin
          while more do image.putchar('!0!')
          ! Note: now pos = length+1;
       end not written;
       locate(LOC+1)   ! Location for *next* image;
 end inimage;
      The procedure "inimage" transfers into the text "image" a copy of the external image as currently identified by the variable LOC. If the file does not contain an image with an ordinal number equal to the value of LOC, the effect of the procedure "inimage" is as follows. If the location indicated is greater than "lastloc", then ENDFILE is set to true and the end of file text ("!25!") is assigned to "image". Otherwise, if the image is a non-written image but there exists at least one written image whose LOC is greater than current LOC, then the "image" is filled with NUL ('!0!') characters and the position indicator is set to "length"+1 (i.e. "more" becomes false). Finally the value of LOC is incremented by one through a "locate" call.
      Overrides:
      inimage in class RTS_Imagefile
      Throws:
      RTS_SimulaRuntimeError - when unable to perform the operation.

    • outimage

      public void outimage()
      The procedure outimage. 
       procedure outimage;
    if      not OPEN     then error("..." !file closed; )
    else if LOC > MAXLOC then error("..." ! file overflow; );
    else begin
        ... ; ! output "image" to external image at LOC;
       locate(LOC+1);
       image := notext;
       setpos(1)
 end outimage;
      The procedure "outimage" transfers a copy of the text value "image" to the external image, thereby storing in the file an external image whose ordinal number is equal to the current value of LOC. If the file contains another image with the same ordinal number, that image is overwritten. The value of LOC is then incremented by one through a "locate" call.
      Overrides:
      outimage in class RTS_Imagefile
      Throws:
      RTS_SimulaRuntimeError - when unable to perform the operation.

    • deleteimage

      public boolean deleteimage()
      The procedure deleteimage. 
       Boolean procedure deleteimage;
            if OPEN and then ... ! image LOC was written;
            then begin
               ... ; ! attempt to delete image;
               if ... ! delete operation successful;
               then begin
                  deleteimage := true;
                  locate(LOC+1);
               end successful
            end deleteimage;
      The Boolean procedure "deleteimage" makes the image identified by the current value of LOC effectively un-written. Irrespective of any physical differences on the external medium between never-written images and deleted ones, there is no difference from the program's point of view. Note that this means that "deleteimage" may decrement the value returned by "lastloc" (in case LOC was equal to "lastloc").

      Note: Outputting a NUL-filled image at location "lastloc" in the file does not necessarily decrement the "lastloc" value; explicit writing (outimage) of such images should be avoided.

      Returns:
      true:ok, false:error
      Throws:
      RTS_SimulaRuntimeError - when unable to perform the operation.

    • 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