Append to File (script step reference)

Troi File Plug-in for FileMaker Pro

Append to File

Append characters to the contents of an existing file

SyntaxScript step badge

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

Options

Select entire contentsreplaces 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
Filepaththe path to the file where the text must be appended
Text to appendthe characters that you want to add at the end of the file
Encodingthe desired character encoding like UTF-8
Line endingschoose "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:

0no errorThe string of characters was added to the file
$$-1genericErrThe file could not be opened for appending (You might need to create the file first).
$$-2genericErrThe 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 17

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…

Related script stepsScript step badge

Create File
Insert in File
Set Contents of File
Show Save File Dialog

Related functionsFunction badge

TrFile_AppendToFile
TrFile_AsciiValueToText

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 13 to 17 –> Append to File (filep7308) 2018-0515 15:30:11