 |
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.
Syntax
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 17 to FileMaker Pro 21 (2024)
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, numbergFileSpec 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 functions
| TrFile_GetAsPlainText |
| TrFile_SelectFileDialog |
Related topics
Troi File Plug-in online help (overview)
