Blitz:File Access

Blitz Basic / AmiBlitz provides numerous commands giving you full control over the reading or writing of files. It's generally a simple process, but you should be careful that you're not overwriting something important by accident (such as your own program's source code!), and that you close your files after use or they could remain inaccessible to other programs until you reboot, and could become corrupted in certain circumstances.

The overall process looks like this:

• Open a file
• Check if it was opened successfully
• Direct input from open file or output to open file
• Read or write information as required
• Close the file
• Return input or output to their previous state

Opening Files

Files need to be opened before reading or writing. There are three commands for opening files; which one you use will depend on what you want to do with the file. To open a file you need to provide an ID number which is used to identify the file for later use. Multiple files can be opened at once if you use a unique file ID number for each.

ReadFile

The ReadFile function opens a file for reading. It is a function taking a file ID number and a filename, and will return True (-1) if the file was successfully opened or False (0) if opening the file failed. Possible reasons for failure include the file not existing, the filename being a directory, the file being read protected, file already in use by another program, etc.

Example of use:

succ.l = ReadFile(0, "Work:Files/Test.txt")

WriteFile

WriteFile opens a file for writing. If the file exists it will be overwritten without warning! If the file doesn't exist, it will be created as an empty file. Like ReadFile, WriteFile is a function and will return True or False depending on whether it succeeded in opening the file or not. Possible reasons for failure include the volume being write protected, file protected from writing, volume full etc.

Usage is the same as for ReadFile above.

OpenFile

OpenFile opens a file for both reading and writing. Again, if the file doesn't exist, it will be created. Existing files won't be overwritten until you write information to them. This command allows full random access of a file, i.e. seeking to a specified point and reading or writing from that point, and appending files by seeking to the end before writing.

Again, usage is the same as for ReadFile above.

Reading Data

Once a file is open, you can redirect the input stream from that file, and that lets you use the standard Edit() or Edit$() functions to read information as if it was input by the user in the shell. To redirect the input stream, use the FileInput command with the ID number assigned to the opened file:

FileInput 0

This is best suited to ASCII files as opposed to binary files, as the Edit() and Edit$() functions look for an end of line character to finish the data input. The DefaultInput command switches the input stream back to the shell. It's always a good idea to set the input stream to the default input.

For non-ASCII files, or where speed is of importance, the entire contents of a file can be read into memory using ReadMem():

ReadMem file_number,memory_address,number_of_bytes

The address may be a variable. To retrieve the address of a variable, prepend the variable name with an ampersand. The size of a variable is retrieved using SizeOf.type.

ReadMem 0,&variable,SizeOf.variabletype

Writing Data

Writing to ASCII files is almost identical to reading from them. The output stream is redirected to an open file, and then the Print and NPrint commands can be used to write data to the file:

FileOutput 0

The output stream is redirected to the shell using the DefaultOutput command. Again, this is always a good idea.

Closing Files

Closing files is done with the CloseFile command. Its usage is simply:

CloseFile 0

Where 0 is the previously opened file. Always close files after you're finished with them, and remember to redirect your input and output streams elsewhere if necessary (using PopInput or DefaultInput).

Complete Example

The following example code uses the code segments above to read two lines from a file and write them to a new file.

; Read the first two lines from the file

If ReadFile(0, "Ram:Test.txt")
  FileInput 0
  firstline$ = Edit$(100)
  secondline$ = Edit$(100)
  CloseFile 0
  DefaultInput
Else
  NPrint "Unable to open file for reading!"
End If

; Now write the lines to a new file

If WriteFile(0, "Ram:NewTest.txt")
  FileOutput 0
  NPrint firstline$
  NPrint secondline$
  CloseFile 0
  DefaultOutput
Else
  NPrint "Unable to open file for writing!"
End If

AmiBlitz Include

Note that file access is also provided by the include file.include.ab3, which provides all the procedures you will need for reading and writing files. It uses the OS calls directly for maximum compatibility with the modern iterations of the OS, and allows for more advanced file handling. Please consider using the file include if possible!