File and Directory Functions

The Automation1 controller supports a hierarchical file system with directories and files. This is where the controller’s AeroScript programs and libraries, data collection files, and user files exist. The File and Directory functions supply an easy way to interact with the file system, including the ability to read and write file contents.

WARNING: The File and Directory functions do not execute in real time. The time that it takes for the command to execute is different for different PC configurations. Aerotech recommends that you use these functions only in code that is not time-critical.

In the controller file system, the file and directory paths obey these rules:

File and directory names are case-insensitive.
File system paths must use the forward slash character, ('/'), as the file separator.
Absolute file system paths must start with a forward slash character ('/').
Relative file system paths do not start with a forward slash character ('/'). These paths are relative to the program that is currently executing on the task.

For more information, see Controller File System.

IMPORTANT: When you use a relative path in an immediate command or in the command queue, it is always applied as an absolute path. To make sure that the path points to the correct file, Aerotech recommends that you use only absolute paths in immediate commands and commands in the command queue.

Handles

The handle is a native data type used to interact with an external resource, including files. With a native data type, the AeroScript compiler can supply a well-defined interface for file operations with improved type-checking. For more information, refer to Fundamental Handle Data Type on the Data Types and Variables page.

Open and Close a Handle

You must open a handle before you can use it to communicate with a file. After you open the handle, you can pass it to other file operation functions to do many supported operations.

The controller supports interacting with files in the modes that follow:

Binary mode: Exposes the raw bytes of the file, which lets you do low-level memory operations. For more information, see the Binary Files section on this page.
Text mode: Automatically interprets the file as a sequence of human-readable characters. For more information, see the Text Files section on this page.

Use the enum FileMode to select the file permission mode you want to use.

File Position

After you open a file, it might be necessary to navigate through the file to read information or write new data at a specific location. The functions that follow supply an easy way to navigate using file byte offsets.

Text Files

When a file is in text mode, AeroScript interprets the raw bytes of the file using the UTF-8 encoding. Thus, you can read entire lines from the file until you find a newline character or you find a custom delimiter. And, you can easily write AeroScript strings at the current file location. For information on how to navigate in a file from an AeroScript program, see File Position on this page.

Program Example

// Open a file for writing. If the file already exists, its contents will be overwritten.
var $myTextFileHandle as handle
$myTextFileHandle = FileOpenText("/MyFiles/MyTextFile.txt", FileMode.Overwrite)

// Write text.
FileTextWriteString($myTextFileHandle, "This is the first line.\n")
FileTextWriteString($myTextFileHandle, "This is the second line.\n")


// Close and save the file.
FileClose($myTextFileHandle)


/* Contents of MyTextFile.txt:
This is the first line.
This is the second line.
*/

// Open a file for reading only.
$myTextFileHandle = FileOpenText("MyFiles/MyTextFile.txt", FileMode.Read)

// Read and show the first line.
var $s as string
$s = FileTextReadLine($myTextFileHandle)
AppMessageDisplay($s)
				
// Read and show the second line.
AppMessageDisplay(FileTextReadLine($myTextFileHandle))

// Close the file.

FileClose($myTextFileHandle)

IMPORTANT: When you specify a delimiter to the FileTextReadString() function, you cannot use an empty delimiter or a delimiter that includes the null-terminator.

Binary Files

When you operate on binary files, you must determine how the raw bytes of the file are to be interpreted. AeroScript supplies individual functions to access the current file location based on the specified underlying data type. And, you can use the array-based functions to access contiguous sequences of the file. For more information on file location, see File Position on this page.

Supported data types:

Float32 - IEEE 754 single-precision floating point
Float64 - IEEE 754 double-precision floating point
Int8 - signed 8-bit integer
Int16 - signed 16-bit integer
Int32 - signed 32-bit integer
Int64 - signed 64-bit integer
Uint8 - unsigned 8-bit integer
Uint16 - unsigned 16-bit integer
Uint32 - unsigned 32-bit integer

Program Example

// Open a file for writing. If the file already exists, its contents will be overwritten.
var $myBinaryFileHandle as handle
$myBinaryFileHandle = FileOpenBinary("MyFiles/MyBinaryFile.bin", FileMode.Overwrite)

// Write a 32-bit floating point value.
FileBinaryWriteFloat32($myBinaryFileHandle, 1.234)

// Write an array of 64-bit integrers to the file.
FileBinaryWriteInt64Array($myBinaryFileHandle, [1, 2, 3, 4, 5], 5)

// Close and save the file.
FileClose($myBinaryFileHandle)

/* Contents of MyBinaryFile.txt:
b6f3 9d3f 0100 0000 0000 0000 0200 0000
0000 0000 0300 0000 0000 0000 0400 0000
0000 0000 0500 0000 0000 0000 
*/

// Open a file for reading only.
$myBinaryFileHandle = FileOpenBinary("MyFiles/MyBinaryFile.bin", FileMode.Read)

// Read the first 4 bytes and interpet the data as a 32-bit floating point value.
AppMessageDisplay(RealToString(FileBinaryReadFloat32($myBinaryFileHandle))) // Displays "1.234"

// Read the next 40 bytes of data and interpet the data as an array of 5 64-bit integers.
var $array[5] as integer
FileBinaryReadInt64Array($myBinaryFileHandle, $array, 5)
AppMessageDisplay(IntegerToString($array[0] + $array[1] + $array[2] + $array[3] + $array[4]) ) // Displays "15"

// Close the file.
FileClose($myBinaryFileHandle)

Reading Binary Files

To determine if the floating-point values returned by some of the functions that follow are valid, specify the values to the RealIsInfinity() or the RealIsNan() functions. The value that you give for the $numElements argument must be at least 1 and less than or equal to the length of the ref $values array argument. If the $numElements argument is less than 1 or greater than the length of the ref $values array argument, then a task error will occur.

Writing Binary Files

The value that you give for the $numElements argument in the FileBinaryWrite*() functions must be at least 1 and less than or equal to the length of the $values array argument. If the $numElements argument is less than 1 or greater than the length of the $values array argument, then a task error will occur.

Directories

Use the Directory*() functions to make changes to the controller file system. This includes the ability to copy, delete, and move files. These are the other ways you can get access to the controller file system:

In Automation1 Studio, in the Configure workspace under Controller, select Controller Files.
In Automation1 Console, use the file command.

INI Files

INI files contain values that correspond to a specific key. You can put these keys into sections for organization. Use the FileIni functions to do work with INI files in UTF-8 encoding. This includes the ability to read a value, modify or create a new value, search to see if a section exists, and delete a section or key.

When you use File INI, make sure that you know the important information that follows:

Sections and keys are case-insensitive.
Sections and keys cannot include whitespace.
You cannot have duplicate sections, but you can have nested sections.
You cannot have duplicate keys. You can have two or more of the same key if each one belongs to a different section.
You cannot have multi-line values.
Each time the INI file is modified with a FileIni function, the file will try to adjust itself to maintain two new lines of space between sections.

IMPORTANT: FileIniWriteValue() will make a new INI file if one does not exist. Make sure that the INI file name is correct. You can also use DirectoryFileExists() to determine if an INI file exists on your controller file system before you write a new value.

If you want to read to or write from a key that does not belong to a section, specify an empty string for that section.

// Make a new key that does not belong to a section.
FileIniWriteValue("Example.ini", "", "Key1", "Value1")

// Read from the newly created key.
$sglobal[0] = FileIniReadValue("Example.ini", "", "Key1", "Key was not found.")

When you directly edit an INI file, you can put comment lines in the file. Comments must be standalone lines that start with a number sign (#) or a semicolon (;). Do not put a comment on the same line as a section or key-value pair. If you do this, the comment will be automatically removed the next time you use a FileIni function to do work with an INI file.

Example INI File

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Example.ini
#
# If the first non-whitespace line is a comment, the comment is viewed as
# an overview comment by File INI and will maintain two newlines
# between the end of this line and the next comment, section, or key.


; A key without a section. For keys without sections, specify
; them before sections.
;
; Notice that you can use a different comment character.
key1 = value1


; A non-nested section.
[section1]
key1 = value2


; A nested section.
[section1.nested1]
key1 = value3
key2 = 2

; You can have comments for keys too. File INI will try to maintain a 
; single newline to separate a comment from a key. In this case, a newline 
was automatically inserted to separate key2 from this comment.
; Note: This key and all others that follow without a section are still 
associated with section1.nested1.
key3 = 3.3
key4 = “444”

Program Example: Reading from an INI File

// This program shows you the information that is read from the Example INI File: Example.ini.

// Shows value1
AppMessageDisplay(FileIniReadValue("Example.ini", "", "key1", "key1 was not found!"))

// Shows value2
AppMessageDisplay(FileIniReadValue("Example.ini", "section1", "key1", "section1 key1 was not found!"))

// Shows value3
AppMessageDisplay(FileIniReadValue("Example.ini", "section1.nested1", "key1", "section1.nested1 key1 was not found!"))

// Shows 2
AppMessageDisplay(FileIniReadValue("Example.ini", "section1.nested1", "key2", "section1.nested1 key2 was not found!"))

// Shows 3.3
AppMessageDisplay(FileIniReadValue("Example.ini", "section1.nested1", "key3", "section1.nested1 key3 was not found!"))

// Shows 444
AppMessageDisplay(FileIniReadValue("Example.ini", "section1.nested1", "key4", "section1.nested1 key4 was not found!"))

For more information about how to use FileIni functions, see the INI Files Example Program.

For information about how to edit INI files in the Programming module of the Develop workspace, see Working with INI Files.

Related Help Pages

Controller File System

Files Example Program

INI Files Example Program