TrFile_InsertContents (function reference)

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

TrFile_InsertContents

Inserts text into a file, at the specified position.

SyntaxFunction badge

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 19

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 functionsFunction badge

TrFile_AppendContents
TrFile_SelectFileDialog
TrFile_SetContents

Related script stepScript step badge

Insert in File

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 16 to 19 –> TrFile_InsertContents (filep4302) 2021-0126 11:26:38