Append Data to Files Functions

The following functions allow appending data to specific files in a predefined folder of the current project directory. The file system location allowed to append data 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 append operation is completed.

`fileAppendSync`

The fileAppendSync function behaves as the fileWriteSync function. The only difference is that, when a file already exists, the given <data> is appended to the end of file (instead of replacing the file content like with the fileWriteSync call).

`fileAppend`

The fileAppend function behaves as the fileWrite function. The only difference is that, when a file already exists, the given <data> is appended to the end of file (instead of replacing the file content like with the fileWrite call).

Syntax

(Synchronous append)

var result = fileAppendSync(<relativePath>, <data>, <encoding>)

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

fileAppend(<relativePath>, <data>, <callback>, <encoding>)

Parameters Usage

Parameter	Type	Default	Use	Annotation
relativePath	String	-	Mandatory	Relative path of the file to write in the shared\scripting folder of the current project.
data	String Object	-	Mandatory	Data to write. It can be a string or any object to which it makes sense to apply the `ToString` method (for example, simple data as integer, real or boolean values, or objects as `BrowserObject` or `PropertyValue`, and so on). In case of arrays, the elements are printed as comma-separated values enclosed in square brackets.
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 fileAppendCallback(<fileAppendResult>)

{

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

}

Where <fileAppendResult> is the result object.

Result

The functions fileAppendSync and fileAppendCallback return the FileWriteResult 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 represent a file
Represents a read-only file. For example, the content of result.error can be "Access to the path '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\readonlyFile.txt' is denied."

Data to write is not specified or is null.

The error message is: "The data to write is invalid."

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.

Generic error.

Any other errors will result in a result.error message like: "Unable to write to file '<relativePath>'."In this case, check the Trace Viewer for a detailed explanation about the occurred exception.

Examples of Use

The examples of use of fileAppendSync and fileAppend are quite similar to the ones of fileWriteSync and fileWrite. The only difference is that in fileAppendSync and fileAppend the file content is not replaced at each call.

How to append simple data or arrays with ASCII encoding

To avoid replacing the file content at each call as happens in the first example of fileWriteSync, use the fileAppendSync function.

Note the new line between fileAppendSync calls.

var filename = "Data.txt"

var encoding = "ascii"

fileAppendSync(filename, "hello world", encoding)