TrFile_GetContents (function reference)

By May 1, 2017 May 22nd, 2019 Online Help, Troi File Plug-in
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

switchesthese alter the behavior of the function
filePaththe 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:

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

$$-50paramErrparameter error
$$-41mFulErrnot enough memory
$$-39eofErrstart is beyond the end of the file
$$-4241start or size parameter too big (> 2 Gb)

Originated in

Troi File Plug-in 3.0

Compatibility

FileMaker Pro 14 to 18

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.

Related functionFunction badge

TrFile_SelectFileDialog

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 14 to 18 –> TrFile_GetContents (filep4223) 2019-0522 16:41:28