troi.com – Append to File (script step reference)

Troi File Plug-in > Script steps reference > Append to File

Append to File

Append characters to the contents of an existing file

Syntax

Append to File [ Select ; Result (error) ; FilePath ; Text to append ;
                 Encoding ; Line endings ]

Options

Select entire contents	replaces the contents of a field with the result. If not checked the result replaces the currently selected portion of the field
Result (error)	an error code
Filepath	the path to the file where the text must be appended
Text to append	the characters that you want to add at the end of the file
Encoding	the desired character encoding like UTF-8
Line endings	choose "Don’t change" or "CR to CRLF (Windows)" to change return characters in the text to CRLF (Carriage Return followed by a Line Feed) in the written file

Returned Result

Data type returned

Error code

Result

The returned result is an error code. An error always starts with 2 dollars, followed by the error code. You should always check for errors. Returned error codes can be:

0	no error	The string of characters was added to the file
$$-1	genericErr	The file could not be opened for appending (You might need to create the file first).
$$-2	genericErr	The file could not be opened for appending (You might need to create the file first).

Other errors may be returned.

Originated in

Troi File Plug-in 9.0

Compatibility

FileMaker Pro 16 to FileMaker Pro 2023

Considerations

See also the script step: Show Save File Dialog to ask the user for a filePath.

Note that the maximum size of text to append with Append to File is currently 150 million characters (per call to the script step). This equals to about max. 600 million characters written. This depends on the encoding, for example one Unicode character encoded as UTF-8 can require up to 4 characters in the written file.

Example

Assume your C disk already contains a file “Testtext.txt”, which contains the text “Hello”. We assume that a global number field gErrorCode is defined. Create the following script:

Append to File [ Select ; gErrorCode ; "C:\Testtext.txt" ; " there." ]

This script will add the text ” there.” to the end of the file. After running the script once the file will contain “Hello there.”. If you run the script again the file will contain “Hello there. there.”

Example 2

This shows how to write to a log file. We assume that in your FileMaker file the following fields are defined:

gErrorCode		Global, number
gXplatformReturn	Global, text
gLogFilePath		Global, text	  	
gLogtext		Global, text

gLogFilePath should contain the path to an existing log file, for example “D:\Logs\L2017_01.TXT” (Windows) or “Mac HD:Logs:Log 2017_01” (Mac). gXplatformReturn should contain a return on Mac and a return and a linefeed on Windows. gLogtext is the text you want to log.

Whenever you need to write a line to the log fill the field gLogtext and perform this script step:

Append to File [ Select ; gErrorCode ; 
		gLogFilePath ; DateToText ( Get (CurrentDate ) ) & " " &
		TimeToText (Get (CurrentTime ) ) & " text: " & gLogtext & gXplatformReturn ;
		Encoding: UTF-8 ]

This script step will add a line every time this script is performed. The log file might look like this:

04/12/2017 10:23:56 text: user Peter logged in
04/12/2017 14:31:02 text: user Peter logged out
04/12/2017 14:31:02 text: closed file “Invoices”
etc…