File Handling

File handling support allows you to manipulate your own files directly using scripts. You should already be an expert at writing Aliases, Popups, and Scripts before attempting to use the commands below.

File handles are a limited resource so it is important that you understand how these commands work before trying to use them. Files should always be closed after they have been used to make them available to other applications.

File Handling Commands

/fopen [-nox] <name> <filename>

Opens the specified file and assigns a name to it for later reference. The open fails if the file does not exist. The -n switch creates the file if it does not already exist, fails if the file does exist. The -o switch creates a new file, overwrites if it exists. The -x switch opens the file for exclusive access, preventing other applications from accessing the file.

Note: If this command fails, the script will continue to run. See $ferr and $feof below.

/fclose <name | wildcard>

Closes the file associated with this name. If you specify a wildcard, all matching names are closed.

/flist [name | wildcard]

Lists all open files, or those matching the specified name.

/fseek <name> <position>

Sets the read/write pointer to the specified position in the file. The following switches may also be used to move the file pointer:

-l <name> <line number>

-n <name>

-p <name>

-w <name> <wildcard>

-r <name> <regex>

The -n switch moves the pointer to the start of the next line.

The -p switch moves the pointer to the start of the current line. If the pointer is already at the start of a line, it is moved to the start of the previous line.

/fwrite [-bn] <name> <text | &binvar>

Writes text or the specified binary variable to the file. The -b switch indicates that a &binvar is being specified. The -n switch appends a $crlf to the line being written.

File Handling Identifiers

$fopen(name | N)

Returns information about an open file.

Properties: fname, pos, eof, err

Note: the .eof and .err properties must be checked after each file access command or identifier, since file access errors will not halt a script.

$fread(name | N)

Returns the next $crlf delimited line.

$fread(name | N, M, &binvar)

Returns the number of bytes read into the specified binary variable, where M is the number of bytes to read.

$fgetc(name | N)

Returns the next character.

$feof and $ferr

Return the results of the last file access attempt in any script, where $feof indicates the end of file was reached, and $ferr indicates there was a file error of some kind.