static File* File.Open(string filename, FileMode)Opens a disk file for reading or writing. These disk I/O functions are only intended for simple tasks like the way the QFG series export the character when you complete it.
MODE is either eFileRead, eFileWrite or eFileAppend, depending on whether you want to write to or read from the file. If you pass eFileWrite and a file called FILENAME already exists, it will be overwritten.
eFileAppend opens an existing file for writing and starts adding information at the end (ie. the existing contents are not deleted).
This function returns a File object, which you use to perform operations on the file. null is returned if there was a problem (eg. file not existing when MODE is eFileRead).
NOTE: You MUST close the file with the Close function when you have finished using it. There are only a limited number of file handles, and forgetting to close the file can lead to problems later on.
IMPORTANT: If you open the file for writing, then you can ONLY work with files in the game directory. You CANNOT use a path, so any filename with "\" or "/" in it will automatically be rejected, for security reasons.
NOTE: Open file pointers are not persisted across save games. That is, if you open a file, then save the game; then when you restore the game, the File will not be usable and you'll have to open it again to continue any I/O. The safest practice is not to declare any global File variables.
Example:
File *output = File.Open("temp.tmp", eFileWrite);
if (output == null)
Display("Error opening file.");
else {
output.WriteString("test string");
output.Close();
}
will open the file temp.tmp for writing. An error message is displayed if the file could not be created.
Otherwise, it will write the string "test string" to the file and close it.See Also: File.Close, File.ReadString, File.WriteString
File.Close()Closes the file, and commits all changes to disk. You must call this function when you have finished reading/writing the file.
Example:
File *output = File.Open("test.dat", eFileWrite);
output.WriteString("test string");
output.Close();
will open the file test.dat, write the string "test string", and close it.See Also: File.Open
File.ReadString(string buffer)Reads a string into BUFFER, from a file previously opened with File.Open. You should only use this with files which you previously wrote out with File.WriteString. Do NOT use this function with any other files, even text files.
Example:
string buffer;
File *input = File.Open("test.dat", eFileRead);
input.ReadString(buffer);
input.Close();
will open the file test.dat (which you have previously written with File.WriteString) and
read a string into the buffer. Then close the file.See Also: File.Open, File.WriteString
File.ReadInt()Reads an integer from the file, and returns it to the script. Only integers written with File.WriteInt can be read back.
Example:
int number;
File *input = File.Open("stats.dat", eFileRead);
number = input.ReadInt();
input.Close();
will open the file stats.dat, read an integer into number and then close the file.See Also: File.ReadString, File.WriteInt
File.ReadRawChar()Reads a raw character from the input file and returns it. This function allows you to read from files that weren't created by your game, however it is recommended for expert users only.
Example:
string buffer;
File *input = File.Open("stats.txt", eFileRead);
StrFormat(buffer, "%c", input.ReadRawChar());
input.Close();
will read a raw character from file stats.txt and writes it to the string 'buffer'.See Also: File.ReadString, File.ReadRawInt, File.WriteRawChar
File.ReadRawInt()Reads a raw 32-bit integer from the input file and returns it to the script. This allows you to read from files created by other programs - however, it should only be used by experts as no error-checking is performed.
Example:
int number;
File *input = File.Open("stats.txt", eFileRead);
number = input.ReadRawInt();
input.Close();
will read a raw integer from file stats.txt and put it into the integer number.See Also: File.ReadString, File.ReadRawChar
File.ReadRawLine(string buffer)Reads a line of text from the file into buffer. This enables you to read in lines from text files and use them in your game.
NOTE: this command can only read back plain text lines from text files. If you attempt to use it with binary files or files written with commands like WriteString, WriteInt, etc then the results are unpredictable.
Example:
File *input = File.Open("error.log", eFileRead);
if (input != null) {
while (!input.EOF) {
string buffer;
input.ReadRawLine(buffer);
Display("%s", buffer);
}
input.Close();
}
will display the contents of the 'error.log' file, if it existsSee Also: File.WriteRawLine
File.WriteString(string text)Writes TEXT to the file, which must have been previously opened with File.Open for writing. The string is written using a custom format to the file, which can only be read back by using File.ReadString.
Example:
File *output = File.Open("temp.tmp", eFileWrite);
if (output == null) Display("Error opening file.");
else {
output.WriteString("test string");
output.Close();
}
will open the file temp.tmp for writing. If it cannot create the file, it will display
an error message. Otherwise, it will write the string "test string" and close it.See Also: File.ReadString, File.Open, File.WriteRawLine
File.WriteInt(int value)Writes VALUE to the file. This allows you to save the contents of variables to disk. The file must have been previously opened with File.Open, and you can read the value back later with File.ReadInt.
Example:
int number = 6;
File *output = File.Open("stats.dat", eFileWrite);
output.WriteInt(number);
output.Close();
will open the file stats.dat and write the integer number in it.See Also: File.ReadInt, File.WriteString
File.WriteRawChar(int value)Writes a single character to the specified file, in raw mode so that other applications can read it back. If you are just creating a file for your game to read back in, use File.WriteInt instead because it offers additional protection. Only use this function if you need other applications to be able to read the file in.
This command writes a single byte to the output file - therefore, VALUE can contain any value from 0 to 255.
Example:
File *output = File.Open("output.txt", eFileWrite);
output.WriteRawChar('A');
output.WriteRawChar('B');
output.WriteRawChar(13);
output.Close();
will write the text "AB", followed by a carriage return character, to the file.See Also: File.ReadRawChar, File.WriteInt
File.WriteRawLine(string text)Writes a string of text to the file in plain text format. This enables you to read it back in Notepad or any text editor. This is useful for generating logs and such like.
The TEXT will be printed to the file, followed by the standard newline characters.
Example:
File *output = File.Open("error.log", eFileAppend);
output.WriteRawLine("There was an error playing sound1.wav");
output.Close();
will write an error line in the file error.log.See Also: File.ReadRawLine, File.WriteString
readonly bool File.EOFChecks whether the specified file has had all its data read. This is only useful with files opened for reading. It returns 1 if the entire contents of the file has now been read, or 0 if not.
Example:
File *output = File.Open("test.dat", eFileRead);
while (!output.EOF) {
int temp = output.ReadRawChar();
Display("%c", temp);
}
output.Close();
will display every character in the file test.dat, one by one, to the screen.See Also: File.Error, File.Open, File.ReadString
readonly bool File.ErrorChecks whether an error has occured reading from or writing to the specified file.
An error can occur if, for example, you run out of disk space or the user removes the disk that is being read from.
This function only checks for errors while actually reading/writing data. The File.Open function will return null if there was an error actually opening or creating the file.
To find out whether all data has been read from a file, use EOF instead.
Example:
File *output = File.Open("test.dat", eFileWrite);
output.WriteInt(51);
if (output.Error) {
Display("Error writing the data!");
}
output.Close();
will write a number to the file 'test.dat', and display a message if there was a problem.See Also: File.EOF, File.ReadString
| Browser Based Help. Published by chm2web software. |