TrFile_AppendContents (function reference)

By January 1, 2021January 26th, 2021Online Help, Troi File Plug-in
Troi File Plug-in > Functions reference > TrFile_AppendContents
Troi File Plug-in for FileMaker Pro

TrFile_AppendContents

Append characters to the contents of an existing file indicated by the SetDefaultFileSpec function.

SyntaxFunction badge

TrFile_AppendContents ( switches ; text )

Parameters

switches these alter the behavior of the function
text the characters that you want to add at the end of the default file

Switches

Switches can be empty or one of this:

-Encoding=Native (default)
-Encoding=UTF8
-Encoding=ASCII_DOS
-Encoding=ASCII_Windows
-Encoding=ASCII_Mac
-Encoding=ISO_8859_1 (Windows Latin-1)
-Encoding=BytesOnly only characters in the range 0-255 are written, others are skipped

This determines the character encoding of the appended data.

You can also add this switch:

-CRtoCRLF Use Windows line endings. Returns in the text parameter are substituted with CRLF (Carriage Return followed by a Line Feed) in the written file.

Returned Result

Data type returned

Error code

Result

The returned result is zero or 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 1.1

Compatibility

FileMaker Pro 16 to 19

Considerations

Use the function TrFile_SetDefaultFileSpec first to set the default file. See also the functions:
TrFile_SaveFileDialog to ask the user for a FileSpec, TrFile_SetDefaultFileSpec to indicate the file to affect.

Note that the maximum size of TrFile_AppendContents is currently 150 million characters (per call to the function). 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.

Up to v5.0 there was an error in the documentation: it was incorrectly stated that UTF-8 was the default encoding. The default is -Encoding=Native, which is the current encoding as set in the system preference, for example on western Windows systems it usually is ISO_8859_1 or ASCII_Windows. On macOS the default will be ASCII_Mac.
To be able to export all possible characters (like chinese characters) it is best to export with encoding UTF8.

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:

Set Field [ gErrorCode ; TrFile_SetDefaultFileSpec ( "-Unused" ; "C:\Testtext.txt" ) ]
If [ gErrorCode = 0 ]
    Set Field [ gErrorCode ; TrFile_AppendContents ( "-Unused" ; " there." ) ]
End If 

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 2000_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. Add the following scriptstep to your startup script:

Set Field [ gErrorCode ; TrFile_SetDefaultFileSpec ( "-Unused" ; gLogFilePath ) ]

This will set the default file to your log file. Then whenever you need to write a line to the log fill the field gLogtext and perform this script step:

Set Field [ gErrorCode ; TrFile_AppendContents ( "-Encoding=UTF8" ; 
    DateToText ( Get ( CurrentDate ) ) & " " &
    TimeToText ( Get ( CurrentTime ) ) & " text: " & gLogtext & gXplatformReturn ) ) ]

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

12/31/2016 10:23:56 text: user Peter logged in
12/31/2016 14:31:02 text: user Peter logged out
12/31/2016 14:31:02 text: closed file “Invoices.fmp12”
and so on…..

Used in example file

CreateFile.fmp12

Related functionsFunction badge

TrFile_AppendToFile
TrFile_CreateFile
TrFile_InsertContents
TrFile_SelectFileDialog
TrFile_SetContents

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 16 to 19 –> TrFile_AppendContents (filep4201) 2021-0125 20:56:08