 |
TrFile_SetContentsOfFile |
Sets the contents of a file.
Syntax
TrFile_SetContentsOfFile ( switches ; filePath ; text )
Parameters
| switches | these alter the behavior of the function |
| filePath | |
| text | the characters that you want to write in 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 text to be written.
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 written in the file |
| $$-1 | genericErr | The file could not be opened for writing (You may 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 functions:
“TrFile_SaveFileDialog” to get a FilePath for the file
Note that the maximum size of SetContentsOfFile is currently 150 million characters which 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.
Use the TrFile_AppendContents function if you need to append more characters.
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 UTF-8.
Example
Assume your C disk already contains a file “Testtext.txt” which is empty. We assume that a global number field gErrorCode is defined. Create the following script:
Set Field [ gErrorCode ; TrFile_SetContentsOfFile ( "-unused" ; "C:\Testtext.txt" ; "Hello there." ) ]This script will set the contents of the file “C:\Testtext.txt” to the text “Hello there.”.
Related functions
| TrFile_AppendContents |
| TrFile_CreateFile |
| TrFile_SaveFileDialog |
| TrFile_SelectFileDialog |
Related topics
Troi File Plug-in online help (overview)
