Skip to main content

TrFile_GetContents (function reference)

Troi File Plug-in > Functions reference > TrFile_GetContents
Troi File Plug-in for FileMaker Pro

TrFile_GetContents

Returns (a part of) the contents of the file specified by the filePath. You can specify the starting position and the number of characters to get.

SyntaxFunction badge

TrFile_GetContents( switches ; filePath ; { start ; { size } } ) 

Parameters

switches these alter the behavior of the function
filePath the path to the file
start (optional) starting position in the file (with a value of 0 returning the first character)
size (optional) the number of characters to get

Switches

Switches can be empty or 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.

You can also add this switch:

-ConvertToFMPLinebreaks this will convert any line breaks in the data to the line break FileMaker expects: CRLF, LF and CR will all become CR.

Returned Result

Data type returned

Text

Result

The characters of the file specified.

If unsuccessful this function returns an error code starting with $$ and the error code. Returned error codes can be:

$$-50 paramErr parameter error
$$-41 memFulErr not enough memory
$$-39 eofErr start is beyond the end of the file
$$-4241 start or size parameter too big (> 2 Gb)

Other errors may be returned.

Originated in

Troi File Plug-in 3.0

Compatibility

FileMaker Pro 16 to FileMaker Pro 2023

Considerations

The offset of the “start” parameter is from 0. For example a value of 1 will return the contents from the 2nd character.

You can read up to 2 Gb into a field. However more than 500000 characters will slow down FileMaker considerably.

Only use -ConvertToFMPLinebreaks when getting text files, as it might change the data returned. If for example you use it with an image file the imported image might get corrupted.

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 [ MyTextField ; TrFile_GetContents ( "-Unused" ; "HD Mac:Text files:My Letter" ) ]

returns the contents of the file.

Example 2

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

    gContents		Global, text         	   
    gFileSpec		Global, text          	   
    gStart		Global, number
    gLength		Global, number

gFileSpec should contain the path to an existing file, for example “D:\Readme.txt” (Windows) or “Mac HD:Readme.txt” (Mac). In gStart should be the start position and in gLength the number of bytes you want to get. In a script add the following scriptstep:

Set Field [ gContents ; TrFile_GetContents ( "-Unused" ; gFileSpec ; gStart ; gLength ) ]

This will get part of the contents of the file into the gContents field.

Used in example file

DataIn.fmp12

Related functionsFunction badge

TrFile_GetAsPlainText
TrFile_SelectFileDialog

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 16 to 2023 –> TrFile_GetContents (filep4223) 2023-0601 15:23:14