MPL Training
Lesson 8
Black Panther

Let's check out Text files.

-=-=-=-=-=-=-=-=-

It seems there are some people who want to learn how to read files. I think it
might be a little further in the lesson plan, but let's just jump in take a 
look at how you can work with files.

We'll take a look at some of the functions needed first, then we'll get into
some examples of how they are used.

fAssign(Fptr:File,Mask:String,Attr:Integer)

Before you can work with any type of file, you must first tell the compiler the
name you want to call it (file pointer), and what the files name is. You will 
also need to tell the compiler the file attributes this file has.

If you've looked as some MPL code, you have probably seen something similar to
the following:

Var
  fptr  : File
  Data  : String='textfile.txt'
Begin
  fAssign(fptr,Data,66)
  
In this code, we are telling the compiler that 'fptr' will be the name we will
be calling the file. The 'Data' variable is holding the name of the physical 
file.

When we assign the file, we tell it our name for the file, the name of the 
actual file, and then give it the attributes of the file.

The following are the different attributes that can be used. These need to be
set correctly, or you will not be able to open the file.

01  ReadOnly   Files marked as "Read only"
02  Hidden     Files marked as "Hidden"
04  SysFile    Files marked as "System files"
08  VolumeID   Files marked as "Volume ID"
16  Directory  Files marked as "Directory"
32  Archive    Files marked as "Archive"
66  AnyFile    Any and All files

If you try opening a text file, and have the attributes set as 16, your program
will not be able to open the text file, as it will be looking for a directory
with that name. The most common attribute that you will probably use, will be
66, as it tells the compiler to look at all files to find the one it needs.

-=-=-=-=-=-=-=-=-

Once the file is assigned, you need to tell the compiler what to do with that 
file. There are two functions that you will probably use the most. One is 
fReset and the other is fReWrite.

fReset(File)

This is usually used right after the fAssign, and tells the compiler to open
the file, and set the internal file pointer to the beginning. This way, when
you are either reading or writing, you will be starting from the beginning of
the file.

fReWrite(File)

Use this one with caution, as this will erase an existing file, and recreate
it. Also, if the file does not exist, this function will create it. It is very
handy when working with information you wish to write to a file, as it does
create it for you.

-=-=-=-=-=-=-=-=-

There is one more very important function that *MUST* be used whenever you are
working with files. If your program opens any file, it must close it again. On
systems such as Windows, this isn't as big of a problem, but on Linux/Mac 
systems, if the file is not closed, a lock will exist on that file. This will
make it next to impossible to open the file next time you run your program.

This function is pretty straightforward, just like fReset and fReWrite.

fClose(File)

-=-=-=-=-=-=-=-=-

Now, let's take our example code from above, and put this all together for you.

Var
  fptr  : File                     //Set your file pointer
  Data  : String='textfile.txt'    //Set the string with the filename
Begin
  fAssign(fptr,Data,66)            //Assign (open) the file
  fReset(fptr)                     //Set the internal pointer to the beginning
  If IoResult = 0 Then             //Check to make sure it was successful
  Begin
    //this would be your code to read/write to the file
  End
  fClose(fptr)                     //Close your file
End

-=-=-=-=-=-=-=-=-

Now that you have your text file opened, you will probably want to read the 
information contained within the file, right? :)

fReadLn(File,String)

This function will read a single line within the text file. Keep in mind, a 
line of text is from the beginning of the line, until it reaches '\n', which
is a newline character.

So, in your code, you could have a variable set up called, 'Text'. You can read
the line from the text file, and copy it into your string variable, 'Text' like
this:

fReadLn(fptr,Text)

Always keep in mind where your internal pointer is within the file. After 
reading the first line, the internal pointer is now at the beginning of the
second line. So, if you were to run this command again, your string variable
'Text' would now contain the second line from the file.

fWriteLn(File,String)

This function does the exact opposite as fReadLn, as this one will write a line
of text to the file you have open. The String in the parameters for this 
function, does not have to be a string variable, as you can pass straight text
to the function as well. 

If we had a textfile in the working directory called 'textfile.txt', that had
the contents of:

-=>snip<=-

This is a sample text file

-=>snip<=-

Var
  fptr  : File                     //Set your file pointer
  Data  : String='textfile.txt'    //Set the string with the filename
  Text  : String
  Text1 : String='How about a third line of text.'
Begin
  fAssign(fptr,Data,66)            //Assign (open) the file
  fReset(fptr)                     //Set the internal pointer to the beginning
  If IoResult = 0 Then             //Check to make sure it was successful
  Begin
    fReadLn(fptr,Text)             //Read the line from file into 'Text'
    fWriteLn(fptr,'This is the second line of text for the file.')
    fWriteLn(fptr,Text1)
  End
  fClose(fptr)                     //Close your file
End

After compiling and running this, our 'textfile.txt' contents would be:

-=>snip<=-

This is a sample text file
This is the second line of text for the file.
How about a third line of text.

-=>snip<=-

The next lesson will probably be a bit longer, as we'll go over the basics of
how to work with binary files. A lot of this information is used with binary
files, but slightly different, and we have other options/obstacles to work 
with. :)

Overall, working with binary files is faster for the compiler, and the system,
as they are in a specific order. You will have the option to tell the program
exactly where the information is that you wish to read. With a text file, it
must start at the beginning, and read each line, one at a time, to get to the
information you're looking for. This is the reason why I prefer to work with
binary files, over text files.

Just as a side note, I had written a program called MTAFile, which would read
the .TIC files of incoming files, and generate a report that could be posted
in the messages echos. Each of the .TIC files is plain text, but I needed the
program to read each line, and look for specific keywords, so it could grab the
information needed. 

In my testing, I would run the program with a total of 500 .TIC files to 
process. The program was taking roughly 15 minutes to read all of them, grab
the information, and then sort it to generate the report. Granted most of that
processing time was in the sort process. However, by grabbing the information,
and saving it into a binary file, and then processing it from there, actually 
sped up the program a *LOT*!. I can now process 500 .TIC files within 3 
minutes, instead of 15.
