FILE Object
Updated: July 19, 2009

Files may be opened, read and/or written and closed.  Read and write methods
get/put data from the current file .Position and when complete, set the
.Position to the first byte after the data transferred.

Large files:  Properties and methods applicable only to files less than
or equal to 2^32 - 2 bytes are marked with "32-bit .Position/.Size only". 

hotfiles.bas, hotmem.bas and hotlist.bas in HotTrial show example code.


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
Position   Current position for next read/write file I/O
           MyFile.Position = 0  'reset position for reading


PROPERTIES (Read Only String):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
ReadBinStr (bytes) Same as .ReadStr.  MyString = MyFile.ReadBinStr(32)

ReadLine   Reads line at current position.  MyString = MyFile.ReadLine

ReadStr    (bytes) Reads bytes number of bytes

  Note: bytes may be a variable, expression or immediate value.


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
EOF        EOF test; 1 = true, 0 = false
           IF NOT MyFile.EOF THEN line$ = MyFile.Readline ELSE Goto TheEnd

Handle     File handle

LineCount  File line count

Mode       Mode used to open file.  Please see .Open

Size       File size (similar to .Length property)

ReadNum    (bytes) Reads bytes number of bytes
           MyInteger = MyFile.ReadNum(4)

  Note: Bytes read are assigned to number which can be any numerical data type.
  Bytes should generally agree with the destination value length.


METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Close      Closes open file

CopyFrom   (stream, bytes) Copies bytes from stream

  Note: Stream may be a STRING, MEMORY, ARRAY, LIST or another FILE.  Data
  copied starts at the .Position property of the source stream.

Decrypt    Decrypts data.  MyFile.Decrypt

Encrypt    Encrypts data.  MyFile.Encrypt

  Note: an optional key argument -- any numeric expression -- may be used with
  .Encrypt and .Decrypt.

  MyFile.Encrypt key
  'code
  MyFile.Decrypt key  'same key value as used with .Encrypt

ExtractRes (resource) Extracts resource to .Position in write-enabled file

  Note: resource may be (1) Resource(n) where n is an immediate integer or
  (2) a quoted string for the resource descriptor used in $RESOURCE.
 
LoadArray  (array) Read array from file

Open       (filename$, mode) Opens file; mode = 0 (read only),
           1 (write only), 2 (read/write), 65535 (create/write).
 
           MyFile.Open filename$, 2  'open for read/write

           filename$ may also be a device name like "com1" or "lpt1".

  Note: .Open indicates to the OS to use "sequential access" buffering.  But
  mode 2 opens files with "random access" buffering, guessing that read/write
  might perform best.  Regardless, the OS "guarantees" proper buffering with
  either type of access [win32.hlp].

  Note: "MyVar = RETFUNC" gets .Open return value (file handle or error).
  If error, use GETLASTERROR for detail.

Read       (var) Reads var from file

ReadUDT    (UDT) Reads UDT from file

SaveArray  (array) Writes array to file

Seek       (position) Sets .Position; Same as .Position =

Write      (var) Writes var.  MyFile.Write(MyVar)

WriteBinStr
           (string$, bytes) Writes bytes from string$

WriteLine  (string$) Writes string$ appending CRLF.  MyFile.WriteLine(MyStr$)

WriteNum   (var, bytes) Writes var as bytes of data
           MyFile.WriteNum(MyDouble, 8)

WriteStr   (string$, bytes) Writes bytes from string$

WriteUDT   (UDT) Writes UDT to file


###########

File Mapping:
============
The Windows OS has file mapping services; however, as with many OS services re
"atoms", "safearrays", numerous string and numeric functions, etc, HotBasic
implements its own code with the goal of producing best executables.

Here is how the present version of file mapping works.

At present, .Decrypt, .Encrypt, and .LineCount cause the file to be "mapped"
to RAM, which simply means it is entirely loaded into memory.  This procedure
may result in faster access in the majority of cases, or cause problems in
other cases where the file size is large relative to RAM installed.

Probably, a .MapToMemory ON or OFF method should be created to provide specific
explicit control of HotBasic's mapping code.

When a file is "mapped to memory" in HotBasic applications, and the file is
closed, the application knows that it needs to write the current file contents
in the application buffer associated with the dimensioned file.  If a
particular file has not been "mapped" since its .Open, then the OS has managed
the buffering of any alterations to the file.  In any case, .Close completes
the file I/O and frees the file handle.


Copyright 2003-2009 James J Keene PhD
Original Publication: Oct 9, 2003