Read Files Functions

The following functions allow reading a file in the predefined folder. The file system location allowed to read files is the folder shared\scripting of the current project. For example, [Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting.

Such functions can be run synchronously or asynchronously, and in the last case, it is necessary to provide a callback method that will be executed when the read operation is completed.

fileReadSync

The fileReadSync function allows reading the content of the file specified by <relativePath> in the predefined folder, with the given <encoding>.

fileRead

The fileRead function allows reading asynchronously the content of the file specified by <relativePath> in the predefined folder, with the given <encoding>.

Then it calls the <callback> with the operation result.

Syntax

 

(Synchronous read)

var result = fileReadSync(<relativePath>, <encoding>)

 

(Asynchronous read. The result is provided in the callback method.)

fileRead(<relativePath>, <callback>, <encoding>)

Parameters Usage

Parameter

Type

Default

Use

Annotation

relativePath

String

-

Mandatory

Relative path of the file to access in the shared\scripting folder of the current project.

callback

Function

-

Mandatory for asynchronous calls

Object that identifies the callback function invoked to provide the result of the operation.

encoding

String

"utf8"

Optional

File encoding. Allowed values are "utf8", "ascii", "Unicode", "utf32", "utf7".

The callback function is declared as follows:

 

function fileReadCallback(<FileReadResult>)

{

    //... Do callback stuff here ...

}

 

Where <FileReadResult> is the result object.

Result

The functions fileReadSync and fileReadCallback return the FileReadResult object.

Error Handling

Errors can occur in case:

  • The specified <relativePath>:
    • Is missing, null, empty or white space
    • Is not a string
    • Is invalid (such as, path containing a root directory, wrong absolute path, path outside of the predefined folder, path or file name containing invalid characters, files or directories that have too long path). Note that invalid characters and the path length depend on the operating system.
    • Does not exist. For example:
      If the file does not exist, the error message is: 'File '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\xyz.txt not found.'
      Data = ''
      If the folder does not exist, the error message is: 'Directory '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\FolderAbc not found.'
      Data = ''
    • Does not represent a file

Note that path errors that occur when the fileRead method is called produce a specific error message returned in result.error.

  • The callback is missing, invalid, null, or empty (for asynchronous function only).
    • The related error is logged only in the Trace Viewer.
  • <encoding> is invalid.

Examples of Use

 

How to read the content of a read-only file

Create a read-only file named "readonlyFile.txt" that contains the following text:

"this file contains

my read-only text"

Here follows the code example:

var result = fileReadSync("readonlyFile.txt")

console("Error = '{0}'", result.error)

console("Data = \n'{0}'", result.data)

 

The following is printed to the Console expander:

 

Error = ''

Data =

'this file contains

my read-only text'

 

How to read the content of a file asynchronously and write the read data to another file

Create a file named "FileToRead.txt" that contains the text "hello world", and then execute the following code:

fileRead("FileToRead.txt", readCallback)

 

function readCallback(readResult)

{

    console("Read Error = '{0}'", readResult.error)

 

    if (!readResult.error)

    {

        fileWrite("FileToWrite.txt", readResult.data, writeCallback)

    }

}

 

function writeCallback(writeResult)

{

    console("Write Error = '{0}'", writeResult.error)

}

 

The following is printed to the Console expander:

Read Error = ''

Write Error = ''

 

A file named "FileToWrite.txt" is created in the "shared\scripting" folder of the current project that contains the text "hello world".