Blitz:File.include.ab3

The file.include.ab3 include provides many functions for easily accessing and manipulating files.

Opening and Closing Files

Opening Files

Files must be opened before they can be read from or written to. This is normally done using the file_Open{} function. Two arguments are required, the name of the file as a string, which can include a full or relative path also if required, and the mode in which to open the file. The mode should be one of the following constants:

Constant	Mode Description	Exclusive?
#file_read	Opens file for reading and writing if it exists, fails if the file doesn't exist. Use this for reading files.	No
#file_open	Opens the file for reading and writing if it exists, or creates a new empty file if the given filename doesn't exist. Use this for modifying existing files.	No
#file_write	Opens the file for writing. If it already exists, a requester will open asking whether to overwrite the existing file or cancel. If the user cancels, the function will return a failure (-1).	Yes
#file_forcewrite	As for #file_write, except it does not ask permission before overwriting the file. Use this along with the dos_Exist{} function from dos.include.ab3 if you would prefer to handle your own "Are you sure?" requesters, or don't need to check (e.g. saving config files).	Yes

The function returns a (long) File ID number if successful, or -1 if it fails for any reason. This File ID is used by other procedures in file.include.ab3 so you need to store it for later use. Note that the File ID could be 0, so ensure you take this into account when you check for success: fid.l = file_Open{"Ram:Test.txt", #file_read} If fid >= 0

 ; Do all your file reading here and close the file again

Else

 NPrint "Unable to open file for reading!"

End If Reasons file_Open{} could fail include:

• Trying to read a file that doesn't exist
• Trying to read a file that is read protected (i.e. doesn't have the r flag set)
• Trying to write to a file that is write protected (i.e. doesn't have the w flag set)
• Trying to write to a file that is on a read-only volume (e.g. a CD-ROM or write-protected floppy)
• Trying to create a file with the same name as a directory in the same path

It is very important not to access a file that you haven't successfully opened! Always check for success and make sure your file access code will only be executed if you successfully open the file.

Closing Files

Closing files that were previously opened is simple using the file_Close{} statement. The only argument it requires is the File ID from the file_Open{} function of the file you want to close: file_Close{fid} It is important to close files when you're finished as sometimes the information written to the file might only be in the filesystem's cache, and will only actually saved when the file is closed. This can lose the information saved, and with the Fast File System it can be especially dangerous if the Amiga is powered off, crashes or resets while files are held open. Closing files also frees the file for access by other programs should they need it.

Reading and Writing

Once a file is successfully opened, you're ready to read and write information. This can be done in a number of ways, depending on your needs.

Reading and Writing Text

Lines of text are very simple to read and write with the file_ReadLine{} and file_WriteLine{} functions. Both require the File ID of a currently open file. the file_ReadLine{} function returns a string containing the next line to be read in the file, up to either the next line break or the end of the file, whichever comes first: myline$ = file_ReadLine{fid} NPrint "Line read: ", myline$ The file_WriteLine{} function writes the given string to the file, returning True (-1) if successful or False (0) if not: succ = file_WriteLine{fid, "Line of Text!"} If succ = False Then NPrint "Error writing to file!"

Reading and Writing Binary

In a similar way, individual byte, word, longword and float values can be read and written easily. The functions used for these operations are: