 |
TrFile_AppendToFile |
Append characters to the contents of an existing file
Syntax
TrFile_AppendToFile ( switches; filepath ; text )
Parameters
| switches | these alter the behavior of the function |
| filepath | the path to the file where the text must be appended |
| text | the characters that you want to add at the end of the 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 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 17 to FileMaker Pro 21 (2024)
Considerations
See also the function:
TrFile_SaveFileDialog to ask the user for a filePath.
Note that the maximum size of text to append with TrFile_AppendToFile 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 character 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:
Set Field [ gErrorCode ; TrFile_AppendContentsToFile ( "-Unused" ; 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:
Set Field [ gErrorCode ; TrFile_AppendContents ( "-Encoding=UTF8" ; gLogFilePath ;
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:
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…
Used in example file
CreateFile.fmp12
Related functions
| TrFile_CreateFile |
| TrFile_InsertContents |
| TrFile_SelectFileDialog |
| TrFile_SetContents |
Related script step
| Append to File |
Related topics
Troi File Plug-in online help (overview)
