9.19 File object
Description
You can read/write files with the File object. Due to security reasons each file access is only possible inside of the game directory. The File object requires an index in the range of 0 to 31. This index is required to specify which file stream shall be used (in other words you can open multiple files at the same time).
List of methods/properties
| Name | Type | Short description |
| Open | Method | Opens a file for reading and/or writing |
| Close | Method | Closes a previously opened file |
| ReadRawData | Method | Reads data from the file |
| WriteRawData | Method | Writes data into the file |
| GetFilePointer | Method | Returns the current read/write position of the file |
| SetFilePointer | Method | Sets the current read/write position of the file |
| Length | Method | Returns the current length of the file |
| Truncate | Method | Truncates the rear part of the file |
Description
With this method you can open a file for reading/writing. If you open a file for writing and it doesn't exist then it will be created automatically. You can specify only a
relative path to the game directory as file name. The parameter file mode specifies either the file shall be opened for reading and/or writing. You can use the
file mode constants for this. After opening and reading/writing all required data you must close the file with the
close method to ensure that the file handles are free again.
Syntax
1
File[Index].Open(Filename, FileMode)
Return value
None
Type
Method
Parameter: Filename
Description
Specifies the filename (including the relative path if necessary) of the file which shall be opened. Files may only be opened inside the game directory (and subdirectories)!
Data type
String
Parameter: FileMode
Description
Specifies whether a file shall be opened for reading/writing. To specify more than one file mode you must use the binary or operator (e. g. FILE_READ | FILE_WRITE). If you open a file for appending it will always be opened with write access. You can use the
file mode constants for this parameter.
Data type
Dword
Range
1 to 7
Example
1
2
$
File[0].Open("Textfile.txt", FILE_WRITE)
At the end a file with the name "Textfile.txt" whould be opened in the game directory for writing. If this file whould not exist then it whould be created.
Description
With this method you can close a previously opened file. The file handle will be free again and each writing operation will be finally done. (On some operating systems it is possible that some write operations are only done after you closed the file! Hence you should close the file if you no longer need it.)
Syntax
Return value
None
Type
Method
Example
At the end the file previously opened with the
open method whould be closed. Hence you can open a file with the File object (using index 0) again.
Description
With this method you can read an amount of bytes from a previously opened file (with read access). The first parameter specifies the data type which is used to return the bytes read. You can use the
data type constants for this. If you read data from a text file then you should only use strings for reading/writing. The second parameter specifies the amount of bytes which is being read. This value may not exceed the maximum size of the data type (e. g. 8 bytes for double, 4 bytes for dword, ...). If this value is smaller than the maximum size of the specified data type then the missing bytes will be filled with zero-bytes to reach the required length. If you specify (for each data type expect string) a length of 0 bytes then the required number of bytes will be read automatically. After reading the bytes the internal file pointer will be increased automatically by the amount of bytes.
Syntax
1
File[Index].ReadRawData(DataType, Length)
Return value
Depends on the parameter DataType.
Type
Method
Parameter: Data type
Description
Data type
Dword
Range
1 to 7
Parameter: Length
Description
Specifies the amount of bytes that will be read. If this value is too small for the specified data type then the data type will be filles with zero-bytes. You can specify a 0 here for each data type expect string to detect automatically which length is required.
Data type
Dword
Example
1
2
$
a[1] = File[0].ReadRawData(TYPE_STRING, File[0].Length()))
At the end the entire content of a previously opened (text-)file whould be read into a[1].
Description
With this method you can write data into a previously opened file (with write access). The first parameter specifies the data source (which contents the bytes to be written). If the target file is a text file then you should only write strings. The second parameter specifies the amount of bytes that shall be written into the file. This value may not exceed the maximum length of the data type used by the data source. You can specify a 0 here to write the entire data source (unlike ReadRawData this works with strings) into the file. After writing the data into the file the internal file pointer will be increased automatically by the amount of bytes written. If you write past the end of file then the file size will increase automatically.
Syntax
1
File[Index].WriteRawData(DataSource, Length)
Return value
None
Type
Method
Parameter: DataSource
Description
Specifies the data source which contains the bytes that shall be written into the file.
Data type
All
Parameter: Length
Description
Specifies the amount of bytes that shall be written into the file. If this value is 0 then the entire content of the data source will be written into the file automatically.
Data type
Dword
Example
1
2
$
File[0].WriteRawData(v[1], 0)
At the end the entire content of the first variable whould be written into a (binary) file.
Description
With this method you can retrieve the position of the internal file pointer.
Syntax
1
File[Index].GetFilePointer()
Return value
Dword
Type
Method
Example
1
2
$
v[1] = File[0].GetFilePointer()
Description
With this method you can set the new position of the internal file pointer.
Syntax
1
File[Index].SetFilePointer(NewFilePointer)
Return value
None
Type
Method
Parameter: NewFilePointer
Description
Specifies the new position of the file pointer. This value may not exceed the current file length.
Data type
Dword
Example
1
2
$
File[0].SetFilePointer(0)
At the end the internal file pointer whould point to the begin (= 0) of the file.
Description
With this method you can retrieve the current length of a file.
Syntax
Return value
Dword
Type
Method
Example
1
2
$
v[1] = File[0].Length()
Description
With this method you can truncate the rear part of a file. The file will be truncated after the position of the internal file pointer. For example you can clear to entire content of a file if the internal file pointer points to the begin of the file (= 0). To truncate a file you must open it with write access.
Syntax
Return value
None
Type
Method
Example
1
2
3
$
File[0].SetFilePointer(0);
File[0].Truncate()
At the end the entire file whould be cleared.