Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/TBTREE.ZIP/PAGE.PAS

Pascal/Delphi Source File | 1988-07-25 | 36.6 KB | 977 lines

(* TBTree13             Copyright (c)  1988            Dean H. Farwell II    *)

unit Page;

(*****************************************************************************)
(*                                                                           *)
(*          P A G E  B U F F E R  H A N D L I N G  R O U T I N E S           *)
(*                                                                           *)
(*****************************************************************************)

(*  This unit handles the page buffer.  This buffer is used for keeping
    disk pages in memory.  The pages can be data, indexes, or bitmaps.
    The buffer uses a demand paging scheme in which the least recently used
    page is swapped out when a page is needed and the buffer is full.        *)

(* Version Information

   Version 1.1 - No Changes

   Version 1.2 - No Changes

   Version 1.3 - No Changes                                                  *)


(*////////////////////////// I N T E R F A C E //////////////////////////////*)

interface

uses
    Compare,
    FileBuff,
    FileDecs,
    Hex,
    MyPrint,
    Numbers,
    Printer,
    Strings,
    Time;

const
    PAGESIZE = 512;                  (* Number of bytes in a Physical Record *)

type
    BufferSizeType = 0 .. MAXWORD; (* used for number of pages in the buffer *)

    PageRange  = 1 .. PAGESIZE;    (* type used primarily for indexing a page
                                      byte by byte.                          *)

    SinglePage = Array [PageRange] of Byte;    (* type used to hold one page *)

(*\*)
(* This routine will check to see if a given physical record for a given file
   actually exists either on disk or in the buffer.  It first checks the
   buffer.  If its not in the buffer, it checks to see if it is past the
   end of the file.  It essentially replaces EOF.  EOF will not work properly
   if the pages reside in the buffer but have not been written to disk yet.

   Note - This routine is quite different than routines found in Files.Pas.
   Thes files.pas routines use bitmap files to see if a record is actively
   being used as opposed to existing and containing garbage.  PageExists
   only checks the physical existence of a physical record (BITMAP, INDEX,
   or DATA).  It does not check bitmaps like the others do.                  *)

function PageExists(fName : FnString;
                    prNum : PrNumber) : Boolean;


(* This function will fetch a page and return a copy of the page to the caller.
   It accomplishes this by first looking in the buffer itself.  If it can't
   locate it in the buffer, it checks to see if there is room in the buffer.
   If there is no available room, the least recently used page is written to
   disk.  That frees up that page for use.                                   *)

procedure FetchPage(fName : FnString;
                    prNum : PrNumber;
                    var pg : SinglePage);


(* This routine will store a page in the buffer.  It accomplishes this by
   seeing if an old version is in the buffer.  If it is not it creates a new
   page.  The page is stored, the dirty flag is set, and the timeUsed is
   set.

   This can be used to store a page even if the corresponding page does not yet
   exist.  It this case, the record will be created and stored in the buffer.
   It will be physically created in the file when the page is written to
   disk.

   note - This routine will immediately write this page to disk if the user
   has called SetImmediateDiskWrite with a value of true.  Using this feature
   ensure that current info is always on the disk but will greatly reduce
   efficiency                                                                *)

procedure StorePage(fName : FnString;
                    prNum : PrNumber;
                    pg : SinglePage);

(*\*)
(* Routine to write all dirty pages in buffer to disk.                       *)

procedure WriteEntireBufferToDisk;


(* This routine will all pages corresponding to the given file out to disk.
   The routine does not release the pages from the buffer.                   *)

procedure WriteBufferToDisk(fName : FnString);


(* This routine will release the page in the buffer for a given physical
   record in a given file.  Of course, the routine first checks to see
   if the record is in fact in the buffer.                                   *)


procedure ReleasePage(fName : FnString;
                      prNum : PrNumber);


(* This routine will release all pages in the buffer for the given file (fName)
   It is extremely important to realize that this DOES NOT write the buffer
   pages to disk prior to releasing them.  This must be done explicitly or they
   will be lost.  This routine is handy for deleting a file to ensure that no
   pages are left roaming around in the buffer.                              *)

procedure ReleaseAllPages(fName : FnString);


(* This routine will return the number of buffer pages currently in use.     *)

function CheckPagesInUse : BufferSizeType;


(* This routine will return the number of maximum buffer pages allowed       *)

function CheckMaxBufferPages : BufferSizeType;

(*\*)
(* This routine will allow the user to set the maximum number of buffer pages
   to be in use at one time.  This routine allows the user to change this while
   the program is running.  The program will check to ensure that the user is
   not setting the maximum number of pages in use to an illegal value.  An
   illegal value is zero or less.  The buffer must contain at least one
   page to function properly.  If the caller has specified a new setting which
   is below the number of pages in use, the routine will release pages
   randomly until the count of pages in use is reduced to n.  There is
   nothing fancy about the algorithm to chose pages to release.  The
   user can alleviate having the wrong pages swapped out by specifying
   certain pages to be swapped out prior to calling this.  For example,
   the user could save and release all pages for a file which won't be used for
   awhile.  Remember, swapping out the wrong pages will not cause errors, but
   it may temporarily affect performance as the pages will have to be read
   back in upon their next use.  As an aside, I did not swap out least
   recently used pages since a large number might be swapped out.  Each
   swap would entail going through the entire buffer to find the least
   recently used page.  This would cause too much overhead.

   note - notice use of Exit for exiting the routine.  The routine will not
   normally fall out the bottom.                                             *)

procedure SetMaxBufferPages(n : BufferSizeType);


(* This routine will allow the user to set whether stored pages will be
   immediately  written to disk during StorePage operations.  It will
   set an internal variable which keeps track of whether pages should
   be immediately written to disk or only stored in the buffer.  The
   variable cannot be accessed by the user.  The only way is to set
   it is to call this routine.  The routine is called at initialization
   time with x = FALSE which means that pages will not be written immediately
   to disk.  The user can change this at any time.  Once this is set to
   TRUE all dirty pages in the buffer (ones that have not yet been written
   to disk) will still be dirty (will not be automatically written).  All
   newly stored pages will be immediately written.  To ensure that all
   pages have been written to disk, use WriteEntireBufferToDisk.  Regardless
   of whether this is set to TRUE or FALSE, the page will still be in the
   buffer and will be available for FetchPage operations without going to
   disk.                                                                     *)

procedure SetImmediateDiskWrite(x : Boolean);

(*\*)
(* This routine will return TRUE if the parameter has been set forcing pages
   to be written to disk immediately on calling StorePage.  This is the only
   to check the variable since it is hidden in the implementation.           *)

function CheckImmediateDiskWrite : Boolean;

(* This routine will print the entire page buffer to the printer *)

procedure PrintPageBuffer;


(* This routine will print the buffer statistics                             *)

procedure PrintBufferStats;

(*\*)
(*///////////////////// I M P L E M E N T A T I O N /////////////////////////*)

(* the following declarations are for defining and storing the buffer *)

implementation

const
    POINTERARRAYSIZE = 199;          (* used to set up array of linked lists
                                         this number needs to be prime       *)

type
    PagePtr = ^PageEntry;

    PageEntry  = record
                 fName     : FnString;
                 prNum     : PrNumber;
                 dirty     : boolean;
                 timeUsed  : TimeArr;
                 page      : SinglePage;
                 nextPage  : PagePtr;
                 end;

    PointerArrayRange = 0 .. POINTERARRAYSIZE;


var
    pagesInUse : BufferSizeType;     (* value should never exceed the current
                                                     value of maxBufferPages *)

    pointerArray : Array [PointerArrayRange] of PagePtr;  (* Type of Array
                                                         holding the pointers
                                                         to the linked list of
                                                         pages in the
                                                         page buffer *)

    immediateDiskWrite : Boolean;         (* used to keep track of whether to
                                             store pages immediately to disk
                                             on all StorePage calls          *)

(*\*)
(* the following declarations are for keeping and printing statistics on
   buffer usage                                                              *)

type
    StatsRange = 0 .. MAXLONGINT;  (* used as type for many buffer stat vars *)

    BufferStats = record                   (* used to hold buffer statistics *)
                  pagesInUse : StatsRange;
                  maxPages : StatsRange;
                  attempts : StatsRange;
                  hits : StatsRange;
                  end;


var
    maxBufferPages : BufferSizeType;  (* Number of buffer pages in buffer.
                                         This can be set by the user to
                                         allow a flexible buffer size        *)


    bufferAttempts: StatsRange;     (* total attempts to fetch a page from the
                                       buffer                                *)

    bufferHits : StatsRange;        (* used for to keep track of attempts to
                                       fetch a physical record from the buffer
                                       in which the record was there         *)

(*\*)
(* This routine will initialize the pointer array to all NILS and will set
   the pages in the pagesInUse counter to zero.  This last item will reflect
   the fact that there are no pages active in the buffer.                    *)

procedure InitializePointerArray;

var
    cnt : PointerArrayRange;

    begin
    for cnt := 0 to POINTERARRAYSIZE do
        begin
        pointerArray[cnt] := NIL;
        end;
    pagesInUse := 0;
    end;                            (* end of InitializePointerArray routine *)


(* This routine will write a specified page to disk.  It will also change the
   Dirty flag to FALSE showing that the page is not dirty.                   *)

procedure WriteToDisk(pgPtr : PagePtr);

var
    tempFile : File;

    begin
    OpenUntypedFile(pgPtr^.fName,tempFile,PAGESIZE);
    Seek(tempFile,pgPtr^.prNum);
    BlockWrite(tempFile,pgPtr^.page,1);
    pgPtr^.dirty := FALSE;
    end;                                     (* end of WriteToDisk procedure *)

(*\*)
(* This routine will read in a specified page from disk.  It will change the
   Dirty flag to false showing that the page is not dirty.  It will also
   set the file name and set the physical record number.  It does not set the
   the time.  This will be done by the procedure which actually decides to
   fetch this record.                                                        *)

procedure ReadFromDisk(fName : FnString;
                       prNum : PrNumber;
                       pgPtr : PagePtr);

var
    tempFile : file;

    begin
    OpenUntypedFile(fName,tempFile,PAGESIZE);
    Seek(tempFile,prNum);
    BlockRead(tempFile,pgPtr^.page,1);
    pgPtr^.fName := fName;
    pgPtr^.prNum := prNum;
    pgPtr^.dirty := FALSE;
    end;                                    (* end of ReadFromDisk procedure *)


(* This routine will return the index to the pointerArray corresponding to the
   given file and physical record.                                           *)

function Hash(fName : FnString;
              prNum : PrNumber) : PointerArrayRange;

{$V-}
    begin
    Hash := (prNum + TotalString(fName)) Mod POINTERARRAYSIZE;
    end;                                              (* end of Hash routine *)
{$V+}

(*\*)
(* This routine will return a pointer pointing to the page corresponding to a
   given file and physical record number.  It will return NIL if the page is
   not in the buffer.                                                        *)

function GetPagePtr(fName : FnString;
                    prNum : PrNumber) : PagePtr;

var
    tempPtr : PagePtr;
    found : boolean;

    begin
    tempPtr := pointerArray[Hash(fName,prNum)];
    found := FALSE;
    while (not found) and (tempPtr <> NIL) do
        begin
        if (tempPtr^.fName = fName) and (tempPtr^.prNum = prNum) then
           begin
           found := TRUE;
           end
       else
           begin
           tempPtr := tempPtr^.nextPage;
           end;
       end;
   GetPagePtr := tempPtr;
   end;                                           (* end of FindPage routine *)


(* This routine will pull a page out of a page list.  It does not Dispose of
   the page.  This allows the page to be immediately reused.  The calling
   routine should either reuse it or Dispose it.                             *)

procedure DeletePgFromList(pgPtr : PagePtr);

var
    tempPtr : PagePtr;

    begin
    tempPtr := pointerArray[Hash(pgPtr^.fName,pgPtr^.prNum)];
    if tempPtr = pgPtr then
        begin                             (* page to delete is first in list *)
        pointerArray[Hash(pgPtr^.fName,pgPtr^.prNum)] := pgPtr^.nextPage;
        end
    else
        begin
        while tempPtr^.nextPage <> pgPtr do
            begin
            tempPtr := tempPtr^.nextPage;
            end;
        tempPtr^.nextPage := pgPtr^.nextPage;
        end;
    end;                                  (* end of DeletePgFromList routine *)

(*\*)
(* This routine will take a page and insert it into the proper place in the
   buffer.                                                                   *)

procedure InsertPgInList(fName : FnString;
                         prNum : PrNumber;
                         pgPtr : PagePtr);

var
    arrayIndex : PointerArrayRange;

    begin
    arrayIndex := Hash(fName,prNum);
    pgPtr^.nextPage := pointerArray[arrayIndex];  (* insert page as first    *)
    pointerArray[arrayIndex] := pgPtr;            (* page in page list       *)
    end;                                    (* end of InsertPgInList routine *)


(* This routine creates a new page and sets the file name and record number
   fields.  It then inserts the new page in the front of the appropriate
   page list.  It does not set the time nor dirty fields.  This routine does
   not check to see if there is a page available.   This is the responsibility
   of the caller.                                                            *)

procedure CreateNewPage(fName : FnString;
                        prNum : PrNumber;
                        var pgPtr : PagePtr);

    begin
    New(pgPtr);
    pagesInUse := pagesInUse + 1;                   (* one more page used up *)
    InsertPgInList(fName,prNum,pgPtr);               (* put page into proper
                                                             place in buffer *)
    end;                                     (* end of CreateNewPage routine *)

(*\*)
(* This routine will find the least recently used page, delete it from the
   page list and write it to disk.  The pointer to the page is then returned *)

function LRUPage : PagePtr;

var
    cnt : PointerArrayRange;
    tempPgPtr,
    leastPgPtr : PagePtr;
    minTime : TimeArr;

    begin
    SetMaxTime(minTime);
    for cnt := 0 to POINTERARRAYSIZE do
        begin
        tempPgPtr := pointerArray[cnt];
        while tempPgPtr <> NIL do
            begin
            if CompareTime(tempPgPtr^.timeUsed,mintime) = LESSTHAN then
                begin
                minTime := tempPgPtr^.timeUsed;
                leastPgPtr := tempPgPtr;
                end;
            tempPgPtr := tempPgPtr^.nextPage;
            end;
        end;
    WriteToDisk(leastPgPtr);                       (* write page out to disk *)
    DeletePgFromList(leastPgPtr);              (* pull page out of page list *)
    LRUPage := leastPgPtr;               (* return pointer to page to caller *)
    end;                                           (* end of LRUPage routine *)

(*\*)
(* This routine will check to see if a given physical record for a given file
   actually exists either on disk or in the buffer.  It first checks the
   buffer.  If its not in the buffer, it checks to see if it is past the
   end of the file.  It essentially replaces EOF.  EOF will not work properly
   if the pages reside in the buffer but have not been written to disk yet.

   Note - This routine is quite different than routines found in Files.Pas.
   Thes files.pas routines use bitmap files to see if a record is actively
   being used as opposed to existing and containing garbage.  PageExists
   only checks the physical existence of a physical record (BITMAP, INDEX,
   or DATA).  It does not check bitmaps like the others do.                  *)

function PageExists(fName : FnString;
                    prNum : PrNumber) : Boolean;

var
    tempFile : File;

    begin
    if GetPagePtr(fName,prNum) = NIL then            (* check to see if record
                                                                is in buffer *)
        begin
        OpenUntypedFile(fName,tempFile,PAGESIZE);
        if prNum <= FileSize(tempFile) - 1 then
            begin                             (* record not past end of file *)
            PageExists := TRUE;
            end
        else
            begin               (* record not in buffer and past end of file *)
            PageExists := FALSE;
            end;
        end
    else
        begin                    (* page is in buffer .. therefore it exists *)
        PageExists := TRUE;
        end;
    end;                                        (* end of PageExists routine *)

(*\*)
(* This function will fetch a page and return a copy of the page to the caller.
   It accomplishes this by first looking in the buffer itself.  If it can't
   locate it in the buffer, it checks to see if there is room in the buffer.
   If there is no available room, the least recently used page is written to
   disk.  That frees up that page for use.                                   *)

procedure FetchPage(fName : FnString;
                    prNum : PrNumber;
                    var pg : SinglePage);

var
    pgPtr : PagePtr;

    begin
    pgPtr := GetPagePtr(fName,prNum);          (* try to find page in buffer *)
    if pgPtr = NIL then                    (* check to see if page was found *)
        begin                                    (* page not found in buffer *)
        if (pagesInUse <> maxBufferPages) and      (* check for unused pages *)
           (MaxAvail >= SizeOf(PageEntry)) then      (* check for heap space *)
            begin                             (* there is room in the buffer *)
            CreateNewPage(fName,prNum,pgPtr);    (* make new page and use it *)
            end
        else
            begin                                         (* no unused pages *)
            pgPtr := LRUPage;                (* get least recently used page *)
                                                     (* and write it to disk *)
            InsertPgInList(fName,prNum,pgPtr);      (* reuse page and put in
                                                      proper place in buffer *)
            end;
        ReadFromDisk(fName,prNum,pgPtr);             (* read in desired page *)
        end
    else
        begin                                           (* page is in buffer *)
        bufferHits := bufferHits + 1;                 (* update hits counter *)
        end;
    GetTime(pgPtr^.timeUsed);                 (* set time page was requested *)
    pg := pgPtr^.page;       (* return copy of the actual page to the caller *)
    bufferAttempts := bufferAttempts + 1;
    end;                                         (* end of FetchPage routine *)

(*\*)
(* This routine will store a page in the buffer.  It accomplishes this by
   seeing if an old version is in the buffer.  If it is not it creates a new
   page.  The page is stored, the dirty flag is set, and the timeUsed is
   set.

   This can be used to store a page even if the corresponding page does not yet
   exist.  It this case, the record will be created and stored in the buffer.
   It will be physically created in the file when the page is written to
   disk.

   note - This routine will immediately write this page to disk if the user
   has called SetImmediateDiskWrite with a value of true.  Using this feature
   ensure that current info is always on the disk but will greatly reduce
   efficiency                                                                *)

procedure StorePage(fName : FnString;
                    prNum : PrNumber;
                    pg : SinglePage);

var
    pgPtr : PagePtr;

    begin
    pgPtr := GetPagePtr(fName,prNum);
    if pgPtr = NIL then
        begin
        if (pagesInUse <> maxBufferPages) and      (* check for unused pages *)
           (MaxAvail >= SizeOf(PageEntry)) then      (* check for heap space *)
            begin
            CreateNewPage(fName,prNum,pgPtr);
            end
        else
            begin
            pgPtr := LRUPage;
            InsertPgInList(fName,prNum,pgPtr);
            end;
        pgPtr^.fName := fName;
        pgPtr^.prNum := prNum;
        end;
    pgPtr^.page := pg;
    pgPtr^.dirty := TRUE;
    GetTime(pgPtr^.timeUsed);
    if immediateDiskWrite then
        begin
        WriteToDisk(pgPtr);
        end;
    end;                                         (* end of StorePage routine *)

(*\*)
(* Routine to write all dirty pages in buffer to disk.                       *)

procedure WriteEntireBufferToDisk;

var
    pgPtr : PagePtr;
    cnt : PointerArrayRange;

    begin
    for cnt:= 0 to POINTERARRAYSIZE do
        begin
        pgPtr := PointerArray[cnt];
        while pgPtr <> NIL do
            begin
            if pgPtr^.dirty then
                begin
                WriteBufferToDisk(pgPtr^.fName);
                end;
            pgPtr := pgPtr^.nextPage;
            end;
        end;
    end;                           (* end of WriteEntireBufferToDisk routine *)


(* This routine will all pages corresponding to the given file out to disk.
   The routine does not release the pages from the buffer.                   *)

procedure WriteBufferToDisk(fName : FnString);

var
    pgPtr : PagePtr;
    cnt : PointerArrayRange;

    begin
    for cnt := 0 to POINTERARRAYSIZE do
        begin
        pgPtr := PointerArray[cnt];
        while pgPtr <> NIL do
            begin
            if pgPtr^.fName = fName then
                begin
                WriteTodisk(pgPtr);
                end;
            pgPtr := pgPtr^.nextPage;
            end;
        end;;
    end;                                 (* end of WriteBufferToDisk routine *)

(*\*)
(* This routine will release the page in the buffer for a given physical
   record in a given file.  Of course, the routine first checks to see
   if the record is in fact in the buffer.  It is important to realize that
   this page will not be written to disk, but will be lost.                  *)

procedure ReleasePage(fName : FnString;
                      prNum : PrNumber);

var
    pgPtr : PagePtr;

    begin
    pgPtr := GetPagePtr(fName,prNum);
    if pgPtr <> NIL then
        begin
        DeletePgFromList(pgPtr);
        Dispose(pgPtr);
        pagesInUse := pagesInUse - 1;
        end;
    end;                                       (* end of ReleasePage routine *)

(*\*)
(* This routine will release all pages in the buffer for the given file (fName)
   It is extremely important to realize that this DOES NOT write the buffer
   pages to disk prior to releasing them.  This must be done explicitly or they
   will be lost.  This routine is handy for deleting a file to ensure that no
   pages are left roaming around in the buffer.                              *)

procedure ReleaseAllPages(fName : FnString);

var
    pgPtr : PagePtr;
    cnt : PointerArrayRange;

    begin
    for cnt := 0 to POINTERARRAYSIZE do
        begin
        pgPtr := pointerArray[cnt];
        while pgPtr <> NIL do
            begin
            if pgPtr^.fName = fName then
                begin
                ReleasePage(fName,pgPtr^.prNum);
                pgPtr := PointerArray[cnt];     (* reset to a valid location *)
                end
            else
                begin
                pgPtr := pgPtr^.nextPage;
                end;
            end;
        end;
    end;                                   (* end of ReleaseAllPages routine *)


(* This routine will return the number of buffer pages currently in use.     *)

function CheckPagesInUse : BufferSizeType;

    begin
    CheckPagesInUse := pagesInUse;
    end;                                   (* end of CheckPagesInUse routine *)

(* This routine will return the number of maximum buffer pages allowed       *)

function CheckMaxBufferPages : BufferSizeType;

    begin
    CheckMaxBufferPages := maxBufferPages;
    end;                               (* end of CheckMaxBufferPages routine *)

(*\*)
(* This routine will allow the user to set the maximum number of buffer pages
   to be in use at one time.  This routine allows the user to change this while
   the program is running.  The program will check to ensure that the user is
   not setting the maximum number of pages in use to an illegal value.  An
   illegal value is zero or less.  The buffer must contain at least one
   page to function properly.  If the caller has specified a new setting which
   is below the number of pages in use, the routine will release pages
   randomly until the count of pages in use is reduced to n.  There is
   nothing fancy about the algorithm to chose pages to release.  The
   user can alleviate having the wrong pages swapped out by specifying
   certain pages to be swapped out prior to calling this.  For example,
   the user could save and release all pages for a file which won't be used for
   awhile.  Remember, swapping out the wrong pages will not cause errors, but
   it may temporarily affect performance as the pages will have to be read
   back in upon their next use.  As an aside, I did not swap out least
   recently used pages since a large number might be swapped out.  Each
   swap would entail going through the entire buffer to find the least
   recently used page.  This would cause too much overhead.

   note - notice use of Exit for exiting the routine.  The routine will not
   normally fall out the bottom.                                             *)

procedure SetMaxBufferPages(n : BufferSizeType);

var
    pgPtr : PagePtr;
    cnt : PointerArrayRange;

    begin
    if n > 0 then      (* make sure that value is not 0! if it is do nothing *)
        begin
        if pagesInUse <= n then
            begin
            maxBufferPages := n;
            end
        else
            begin
            for cnt := 0 to POINTERARRAYSIZE do
                begin
                while pgPtr <> NIL do
                    begin
                    if pgPtr^.dirty then
                        begin
                        WriteToDisk(pgPtr);
                        end;
                    ReleasePage(pgPtr^.fName,pgPtr^.prNum);
                    if pagesInUse = n then
                        begin
                        Exit;  (* done .. leave the routine *)
                        end
                    else
                        begin
                        pgPtr := pointerArray[cnt];        (* reset pgPtr to
                                                            a valid location *)
                        end;
                    end;
                end;
            end;
        end;
    end;                                 (* end of SetMaxBufferPages routine *)

(*\*)
(* This routine will allow the user to set whether stored pages will be
   immediately  written to disk during StorePage operations.  It will
   set an internal variable which keeps track of whether pages should
   be immediately written to disk or only stored in the buffer.  The
   variable cannot be accessed by the user.  The only way is to set
   it is to call this routine.  The routine is called at initialization
   time with x = FALSE which means that pages will not be written immediately
   to disk.  The user can change this at any time.  Once this is set to
   TRUE all dirty pages in the buffer (ones that have not yet been written
   to disk) will still be dirty (will not be automatically written).  All
   newly stored pages will be immediately written.  To ensure that all
   pages have been written to disk, use WriteEntireBufferToDisk.  Regardless
   of whether this is set to TRUE or FALSE, the page will still be in the
   buffer and will be available for FetchPage operations without going to
   disk.                                                                     *)

procedure SetImmediateDiskWrite(x : Boolean);

    begin
    ImmediateDiskWrite := x;
    end;                             (* end of SetImmediateDiskWrite routine *)


(* This routine will return TRUE if the parameter has been set forcing pages
   to be written to disk immediately on calling StorePage.  This is the only
   to check the variable since it is hidden in the implementation.           *)

function CheckImmediateDiskWrite : Boolean;

    begin
    CheckImmediateDiskWrite := immediateDiskWrite;
    end;                           (* end of CheckImmediateDiskWrite routine *)

(*\*)
(* These routines support debugging of the page buffer routines              *)

procedure PrintPageInfo(pgPtr : PagePtr);

    (* Prints out string equivalent of boolean value *)
    procedure PrintBoolean(x : boolean);

    begin
    case x of
        FALSE : Write(lst,'FALSE');
        TRUE  : Write(lst,'TRUE');
        end;                                        (* end of case statement *)
    end;                                   (* end of PrintPageBuffer routine *)

    (* determines if x is a screen printable non control character *)
    function PrintableChar(x : Char) : boolean;

    begin
    PrintableChar := Integer(x) in [32 .. 127];
    end;                                     (* end of PrintableChar routine *)

const
    LINESIZE = 32;          (* number of bytes output on one line of printer *)

var
    loopByteCnt,            (* used in inner loop to point to bytes *)
    maxLoopByteCnt,         (* used in inner loop to keep from going past
                               end of buffer page  *)
    byteCnt : PageRange;    (* current byte in buffer page *)
    done : boolean;         (* used for inner loop termination *)

    begin
    Writeln(lst,'     fName = ',pgPtr^.fName);
    Writeln(lst,'     prNum = ',pgPtr^.prNum);
    Write(lst,'     dirty = ');
    PrintBoolean(pgPtr^.dirty);
    Writeln(lst);
    Write(lst,'     timeUsed = ');
    Write(lst,pgPtr^.timeUsed[1],'     ');
    Write(lst,pgPtr^.timeUsed[2],'     ');
    Write(lst,pgPtr^.timeUsed[3],'     ');
    Write(lst,pgPtr^.timeUsed[4],'     ');
    Writeln(lst); Writeln(lst);
    byteCnt := 1;
    done := FALSE;
    repeat
        begin
        if ((byteCnt + LINESIZE) - 1) <= PAGESIZE then
            begin
            maxLoopByteCnt := byteCnt + LINESIZE - 1;
            end
        else
            begin
            maxLoopByteCnt := PAGESIZE;
            end;
        (* print column position *)
        for loopByteCnt := byteCnt to maxLoopByteCnt do
            begin
            Write(lst,loopByteCnt : 3,' ');
            end;
        Writeln(lst);
        (* Print HEX value *)
        for loopByteCnt := byteCnt to maxLoopByteCnt do
            begin
            Write(lst,'$',ByteToHex(pgPtr^.page[loopByteCnt]),' ');
            end;
        Writeln(lst);
        (* print integer equivalent *)
        for loopByteCnt := byteCnt to maxLoopByteCnt do
            begin
            Write(lst,pgPtr^.page[loopByteCnt] :3,' ');
            end;
        Writeln(lst);
        (* character equivalent or print '*' if char not printable *)
        for loopByteCnt := byteCnt to maxLoopByteCnt do
            begin
            if PrintableChar(Chr(pgPtr^.page[loopByteCnt])) then
                begin
                Write(lst,' ',Chr(pgPtr^.page[loopByteCnt]),'  ');
                end
            else
                begin
                Write(lst,' *  ');
                end;
            end;
        Writeln(lst); Writeln(lst);
        if byteCnt + LINESIZE > PAGESIZE then
            begin
            done := TRUE;
            end
        else
            begin
            byteCnt := byteCnt + LINESIZE;
            end;
        end;
    until done;
    Writeln(lst); Writeln(lst);
    end;                                     (* end of PrintPageInfo routine *)

(*\*)
(* This routine will print the entire page buffer to the printer *)

procedure PrintPageBuffer;

var
    pgPtr : PagePtr;
    cnt : PointerArrayRange;

    begin
    SetCompressedMode;                 (* sets printer to 132 character mode *)
    for cnt := 0 to POINTERARRAYSIZE do
        begin
        pgPtr := PointerArray[cnt];
        while pgPtr <> NIL do
            begin
            PrintPageInfo(pgPtr);
            pgPtr := pgPtr^.nextPage;
            end;
        end;
    CancelCompressedMode;
    end;                                   (* end of PrintPageBuffer routine *)


(* This routine will initialize the variables used to keep track of buffer
   use statistics.                                                           *)

procedure InitializeBufferStats;

    begin
    bufferAttempts := 0;
    bufferHits := 0;
    end;                             (* end of InitializeBufferStats routine *)


(* This routine will return buffer statistics.  The statistic will be returned
   in a a record of type BufferStats.                                        *)

procedure CreateBufferStats(var stats : BufferStats);

    begin
    stats.pagesInUse := pagesInUse;
    stats.maxPages := maxBufferPages;
    stats.attempts := bufferAttempts;
    stats.hits := bufferHits;
    end;                                 (* end of CreateBufferStats routine *)

(*\*)
(* This routine will print the buffer statistics                             *)

procedure PrintBufferStats;

var
    stats : BufferStats;

    begin
    CreateBufferStats(stats);
    Writeln(lst);
    Writeln(lst,'** Buffer Statistics Follow: **');
    Writeln(lst);
    Writeln(lst,'Buffer Pages In Use = ',stats.pagesInUse);
    Writeln(lst,'Maximum buffer pages available =  ',stats.maxPages);
    Writeln(lst,'Attempts to Fetch Data = ',stats.attempts);
    Writeln(lst,'Number of Hits = ',stats.hits);
    Writeln(lst,'Hit percentage = ',Trunc((stats.hits/stats.attempts)*100),'%');
    end;                                       (* end of PrintBuffer routine *)



begin
InitializePointerArray;
InitializeBufferStats;
SetMaxBufferPages(256);                           (* initially a 128K buffer *)
SetImmediateDiskWrite(FALSE);
end.                                                     (* end of Page unit *)