Page tree
Skip to end of metadata
Go to start of metadata

Introduction

Allows direct access to OS-level files, to be created, read, written, etc.

The plugin has to be called via the pluginFunction command, with one of the available functions as an argument. e.g.

_status = pluginFunction ["VBSPluginFileAccess","Exists(one.txt)"]


General

filename/foldername: Default directory is the application folder VBS2 was installed into. If there are multiple installations (others, which were only copied into their destination folder), the plugin will still use the folder that was written to the registry during the installation (and which is returned by "getDirectory 2").

Subfolders or absolute paths can be specified (e.g. "config\vbsEntity.config" or "c:\logs\data.txt").
Specified folders must exist, or the file cannot be created. (Use getDirectory to retrieve VBS-specific paths, or ListFiles to check which files are available in a folder.)

Any return value is sent as a single-element array (e.g. [true]).

In general, the VBS2PluginFileAccess function should not be used to read or write to a mission folder. The getDirectory command will return only temporary folder names (which are different, depending on whether the mission was started from the editor, or as a compiled training scenario), and it is also impossible to execute FileAccess commands on a compiled mission folder (use loadFile to read content of mission files instead).

Example mission available here: VBSPluginFileAccess.zip


Functions

Append

Append(fileName)@data

Adds (data) to the last line in file (no carriage return).

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","Append(one.txt)@100"]

AppendLine

AppendLine(fileName)@data

Adds (data) to the last line in file, followed by a carriage return.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","AppendLine(one.txt)@LineOne"]

CloseFile

CloseFile(fileName) (V1.34+)

Closes file opened for reading via ReadFile. Causes the file pointer to be reset to the beginning of the file.
Closing a file that is already closed will cause an error to be returned.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","CloseFile(one.txt)"]

CreateDir

CreateDir(folderName) (V1.40+)

Creates a folder.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","CreateDir(tmp)"]

Delete

Delete(fileName)

Deletes file.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","Delete(one.txt)"]

Exists

Exists(fileName)

Checks if the specified file exists.

Returns: Boolean (true if the file exists).

Example:
_status = pluginFunction ["VBSPluginFileAccess","Exists(one.txt)"]

Lookup

Lookup(fileName,lookupString)

Browses file, finds the first line that contains (lookupString), and reads 7 (space separated) numbers that follow the string.

Returns: String, containing the 7 read numbers, delimited with commas.

  • If (fileName) or (lookupString) is not found, an empty array is returned.
  • Returns 0 for number entries that aren't filled.
  • Will only read numbers, not strings.
Example:
_status = pluginFunction ["VBSPluginFileAccess","Lookup(one.txt,LineOne)"]

If file contained "LineOne 1 22 333", _status would be "1,22,333,0,0,0,0"

ReadFile

ReadFile(fileName) (V1.34+)

Reads the current line from the specified file. After each read, the file pointer will be moved to the next line. So, in order to read a whole file, the command has to be executed repeatedly, until an empty array is returned (EOF).
The ReadFile command is able to read lines that have single quotes in them ('), but lines with double quotes (") will generate an error.
In older versions of VBS (1.x, 2.x) reading files is very slow, and should only be used for smaller files or in very controlled situations (e.g. about 10 seconds to read 100 lines).

Returns: The line read. Or nothing at the end of file (EOF). Or an error message.

Example (reads the whole contents of file 'one.txt' and then closes the file):
waitUntil {
  _line = pluginFunction ["VBSPluginFileAccess","ReadFile(one.txt)"];
  (count _line==0)
};
pluginFunction ["VBSPluginFileAccess","CloseFile(one.txt)"];

Note: The file should be closed using CloseFile once you are done reading it.

RemoveDir

RemoveDir(folderName) (V1.40+)

Removes a folder. Only empty folders can be removed.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","RemoveDir(c:\bi\tmp)"]

Write

Write(fileName)@data

Creates (or opens) file for writing.
  • If the file already exists, existing content will be overwritten.

Returns: Nothing if successful. Otherwise an error message.

Example:
_status = pluginFunction ["VBSPluginFileAccess","Write(one.txt)@header"]

Note: If first entry should have a line carriage, write an empty string, and then add the data via AppendLine