Edit

File_Open (path [, mode="r"])

Result Type:  A file handle or NULL

Definition:  Opens an existing file or, if the mode is "w" or "a", creates a new file. On success, a file handle is returned which you can use with the other File_ functions, otherwise a value of NULL is returned. When creating a new file, any existing file at the given path is replaced. File handles may be compared to 0 but are otherwise opaque.

The path may be a fully-qualified path (but see note below), or if it is a simple file name or partial path it will be assumed to be located withing the default script files directory.

If path is the empty string, a file open/save panel is presented to get the file location. If the user cancels this dialog, the return value of the function is 0.

valid modes:

  • "r" Open file for reading (the default)
  • "w" Truncate to zero length or create file for writing.
  • "a" Append; open or create file for writing at end-of-file.
  • "r+" Open file for update (reading and writing).

Example:  

let fd = File_Open("a file in the MoneyWorks Automation dir.txt")
if fd <> NULL
    let content = File_read(fd) // read the entire file
    File_Close(fd)
endif

Default script files directory and safe paths

The default location for files created by scripts (where a fully-qualified path name is not supplied) is a folder named "Automation Files" inside the user's app support folder. This folder will be created automatically if it does not exist.

The user can specify a list of safe directories in their application preferences, the first of which will be used as the default location for partial paths supplied to `File_Open()`. If no directories are specified, the default location (as above) is used.

If you supply a fully-qualified path (beginning at root), it must resolve to a directory that is one of the default "safe" directories, or to a directory that the user has added to the safe script access directory list in their application preferences. Accessing a path that is not designated safe will result in your script receiving a privilege violation error (so you should never attempt to access unsafe paths).

The default "safe" directories are:

  • the `Automation Files` directory in the application support folder (open it with Help -> Support Info -> Automation Files). This is the new default location s of v9.1.3. Otherwise the `MoneyWorks Automation` directory in ~/Desktop (if the automation files folder was created in MoneyWorks 9.1.2 or earlier)
  • the user's system-defined temp directory (this is the default location for creating files via `DoForm()` and `DoReport()`.
  • the custom plugins directory (excluding the `Scripts` subdirectory)
  • the standard plugins directory (excluding the `Scripts` and `Externals` subdirectories)
  • Any path specified by the user in an Open or Save panel.

On Windows, you can't access files with file extensions that denote executable files.

Note:  If you change the safe paths in the app preferences, make sure the first safe path is a writeable directory. Do not make the first path C:\ on Windows because that is not writeable, and many scripts may fail when they try to create files in that location.

Availability:  available within MWScript handlers.

See Also:

AddSafePath: UI to add a safe path to the preferences

CreateFolder: Create a new folder

File_Close: File functions for creating/reading/writing text files

File_GetLength: File length in bytes

File_GetMark: Get current read/write position

File_Move: Rename/move a file

File_Path: Get the full path of an open file

File_Read: Read text from current position

File_ReadLine: Read to end of line from current position

File_SetMark: Set Current read/write position

File_Write: Write text at current position

WriteToTempFile: Create a temp file containing the string

File_Move File_Path