 |
TrFile_InsertContents |
Inserts text into a file, at the specified position.
Syntax
TrFile_InsertContents ( switches ; sourceFilePath ; destFilePath ;
insertText ; { position } )
Parameters
| switches | these alter the behaviour of the function |
| sourceFilePath | the path to the source file |
| destFilePath | (optional) the path to the destination file |
| insertText | text to insert into the file |
| position | (optional) position where to insert the text. This is calculated in number of bytes from the beginning. |
Switches
Switches can be empty or one of this:
| -Encoding=Native | (default) native to the platform |
| -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 inserted, others are skipped |
This determines the character encoding of the inserted 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 written in the file |
| $$-43 | fnfErr | Source file not found |
Other errors may be returned.
Originated in
Troi File Plug-in 7.0
Compatibility
FileMaker Pro 16 to FileMaker Pro 2023
Considerations
If the position parameter is 0 or is empty, the text will be inserted at the beginning of the file.
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.
If the source file is a different encoding it is best to use that encoding.
For most situations it is best to insert with encoding UTF-8.
If the destination parameter is empty, the insertion text will be saved in the source file itself. This happens also when you specify the same source file and destination file.
Example
Set Field [ $ErrorCode ; TrFile_InsertContents ( "-Unused" ; "HD Mac:data:My Letter" ;
"HD Mac:data::My newLetter" ; "my extra text" ; "42" ) ]This will insert the text “my extra text” after the 42nd byte and save the result into the new file “HD Mac:data::My newLetter”.
Used in example file
Insert.fmp12
Related functions
| TrFile_AppendContents |
| TrFile_SelectFileDialog |
| TrFile_SetContents |
Related script step
| Insert in File |
Related topics
Troi File Plug-in online help (overview)
