Difference between revisions of "Blitz:File.include.ab3"

From Amiga Coding
Jump to: navigation, search
(Created page with "The file.include.ab3 include provides many functions for accessing and manipulating files. Blitz [[Category:Advancing With Blitz|Advancing...")
 
Line 1: Line 1:
The file.include.ab3 include provides many functions for accessing and manipulating files.
+
The file.include.ab3 include provides many functions for easily accessing and manipulating files.
 +
 
 +
==Opening and Closing 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:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Constant
 +
! Mode Description
 +
|-
 +
| #file_read
 +
| Opens file for reading and writing if it exists, fails if the file doesn't exist. Use this for reading files.
 +
|-
 +
| #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.
 +
|-
 +
| #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).
 +
|-
 +
| #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).
 +
|}
 +
 
 +
The function returns a (long) File ID number if successful, or -1 if it fails for any reason. Note that the File ID could be 0, so ensure you take this into account when you check for success:
 +
<code>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</code>
 +
 
  
 
[[Category:Blitz Basic / AmiBlitz|Blitz]]
 
[[Category:Blitz Basic / AmiBlitz|Blitz]]
 
[[Category:Advancing With Blitz|Advancing With Blitz]]
 
[[Category:Advancing With Blitz|Advancing With Blitz]]
 
[[Category:AmiBlitz Includes|AmiBlitz Includes]]
 
[[Category:AmiBlitz Includes|AmiBlitz Includes]]

Revision as of 18:18, 23 February 2016

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

Opening and Closing 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
#file_read Opens file for reading and writing if it exists, fails if the file doesn't exist. Use this for reading files.
#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.
#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).
#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).

The function returns a (long) File ID number if successful, or -1 if it fails for any reason. 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