TrFile_SetContents (function reference)

By May 1, 2017May 20th, 2020Online Help, Troi File Plug-in
Troi File Plug-in > Functions reference > TrFile_SetContents
Troi File Plug-in for FileMaker Pro

TrFile_SetContents

Sets the contents of an existing file indicated by the “SetDefaultFileSpec” function.

SyntaxFunction badge

TrFile_SetContents ( switches ; text )

Parameters

switchesthese alter the behavior of the function
textthe 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=BytesOnlyonly 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:

-CRtoCRLFuse 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:

0no errorThe string of characters was written in the file
$$-1genericErrThe 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 1.0

Compatibility

FileMaker Pro 15 to 19

Considerations

See also the functions:
“TrFile_SaveFileDialog” to get a FileSpec for the file and “TrFile_SetDefaultFileSpec” to indicate the file to affect.

Note that the maximum size of SetContents 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_SetDefaultFileSpec ( "C:\Testtext.txt" ) ]
Set Field [ gErrorCode ; TrFile_SetContents ( "-unused" ; "Hello there." ) ]

This script will set the contents of the file “C:\Testtext.txt” to the text “Hello there.”.

Example 2

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

  gErrorCode		Global, number
  gFilePath		Global, text
  textField		text

gFilePath should contain the path to an existing file, for example “D:\Hello.TXT” (Windows) or “Disk1:Hello” (Mac). TextField contains the text you want to write. In a script add the following scriptstep:

Set Field [ gErrorCode ; TrFile_SetDefaultFileSpec ( gFilePath ) ]
Set Field [ gErrorCode ; TrFile_SetContents ( "-Encoding=ASCII_Windows" ; textField ) ]

This will set the default file to your file. Then the text is written to the file.

Related functionsFunction badge

TrFile_AppendContents
TrFile_CreateFile
TrFile_SaveFileDialog
TrFile_SelectFileDialog
TrFile_SetDefaultCreator
TrFile_SetDefaultFileSpec
TrFile_SetDefaultType

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 15 to 19 –> TrFile_SetContents (filep4273) 2020-0520 18:07:34