Skip to main content

TrFile_Substitute (function reference)

By June 1, 2024June 4th, 2024Online Help, Troi File Plug-in
Troi File Plug-in > Functions reference > TrFile_Substitute
Troi File Plug-in for FileMaker Pro

TrFile_Substitute

Substitutes every occurrence of a specified set of characters in a (text) file with another set of characters you specify, and writes the revised file. The Substitute function is case sensitive.

SyntaxFunction badge

TrFile_Substitute ( switches ; sourceFile ; destinationFile ;
                    search string ; replace string )

Parameters

switches these determine how the function works. At the moment you can specify how the function handles case differences
sourceFile the path to the file which is the source for the substitution
destinationFile the path where the resulting file must be written to
search string any text expression or field containing text
replace string any text expression or field containing text

Switches

switches can be one of the following:

-CaseSensitive substitute strings only if the case of the source string is the same
-IgnoreCase substitute strings even if the case differs

Switches can also be one of this:

-Encoding=Native (default)
-Encoding=UTF8
-Encoding=ASCII_DOS
-Encoding=ASCII_Windows
-Encoding=ASCII_Mac

This determines the character encoding of the text to be read.

Returned Result

Data type returned

Error code

Result

The returned result is an error code. An error always starts with two dollars, followed by the error code. You should always check for errors. Returned error codes can be:

0 no error The destination file with the substitutions was created
$$-43 fnfErr Source file not found, or destination directory does not exist
$$-48 dupFNErr Destination file already exists
$$-1 genericErr The substitution could not be made

Other errors may be returned.

Originated in

Troi File Plug-in 2.0

Compatibility

FileMaker Pro 17 to FileMaker Pro 21 (2024)

Considerations

If the destination parameter is empty the substitution result will be saved in the source file itself. This happens also when you specify the same source file and destination file (this possibility was added in version 2.5). Note that the plug-in uses a temporary file to implement this feature, which can require the same amount of disk space as the source file. The plug-in can fail if there is not enough space on the disk.

NOTE The length of the search and replace string can be up to 1 GB.

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.

Example

Set Field [ result ; TrFile_Substitute ( 
                                "-IgnoreCase" ; "C:\Data\temp.tab" ; "C:\Main.tab" ; "country" ; "world" ) ]

This will create the file “C:\Main.TAB” where all occurences of “country” are replaced with the string “world”. The case is ignored, so that also a string “Country” will be substituted.

Example 2

We assume that in your FileMaker file the following fields are defined:

    gErrorCode		Global, number			
    gSourceFilePath	Global, text			
    gDestFilePath	Global, text
    gSearchStr		Global, text
    gReplaceStr		Global, text

gSourceFilePath should contain the path to an existing file, for example “D:\TempLogs\Log01.TXT” (Windows) or “Mac HD:TempLogs:Log 1” (Mac).
gDestFilePath should contain the path to the destination and should not exist, for example “D:\Output\L2000_01.TXT” (Windows) or “Mac HD:Output:Log 2000_01” (Mac). In a script add the following scriptstep:

Set Field [ gErrorCode ; TrFile_Substitute ( "-CaseSensitive" ; gSourceFilePath ; gDestFilePath ; 
			gSearchStr ; gReplaceStr ) ]

This will create a new file gDestFilePath where all occurences of gSearchStr are replaced with the contents of gReplaceStr.

Used in example file

Substitute.fmp12

Related functionFunction badge

TrFile_InsertContents

Related script stepScript step badge

Substitute In File

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 17 to 2024 –> TrFile_Substitute (filep4283) 2024-0604 19:40:07