Category:File Handling

General Explanation

In addition to several high-level file access methods, mIRC offers a low-level way of accessing files, which closely resembles the way that operating systems like Windows or UNIX allow programs to access files. The individual commands and identifiers in this category allow you to open a file, perform a number of (read/write) operations on it, and close it.

First of all you have to open a file using /fopen. When doing this, you have to specify a handle - in subsequent commands you can use this handle to refer to the open file. The handle is just a name that you, the scripter, can choose yourself. This is similar to how socket names work.

Each open file has a file pointer. This file pointer is the current byte position in the file, and the read/write commands will always work from this position. Additionally, those commands will move the file pointer forward with as many bytes as they read/write. For example, if the file pointer is at byte 1055, and you use $fgetc, then you will get the 1055th byte of the file, and the file pointer will move to 1056. When you've just opened the file, the file pointer is set to the start of the file (byte 0); you can manually move the pointer to another position in the file by using /fseek.

mIRC will lock an opened file from being accessed by other programs for as long as the file handle is open. After you've used a file, you have to close it again, using /fclose. That will write any changes you made to disk, and unlock the file.

Note that you should check $ferr after every operation on the file (including opening it!).

Difference to /write and $read

Contrary to this, the "usual" way to access a file (/write and $read that is) work in another way. For example, if you want to echo line number 4 and 5 of a file, you would use:

echo -a $read(my.txt,4) $read(my.txt,5)

Internally, mIRC would do following:

1. open the file (using fopen)
2. read the first line (using $fread - check $read for more details about it)
3. move the pointer to the start of line 4 (using fseek)
4. read this line (using $fread)
5. close the file (using fclose)
6. open the file again (using fopen)
7. move the pointer to the start of line 5 (using fseek)
8. read this line (using $fread)
9. close the file (using fclose) again

That's obviously not efficient, as we don't need to close it after our first read. So using File Handling, we could directly do:

1. open the file (using fopen)
2. jump to line 4 (using fseek)
3. read this line (using fread)
4. read the next line (and the pointer is automatically there after reading line 4 - using fread)
5. close the file (using flose)

If you want to read one or two lines only, there is no need to use this way, as $read is alot easier to handle, but if you have a file of e.g. 40mb and want to read 100 lines, there is a big difference between File Handling and $read (~ factor 10).

Example