File plug-in logo

Troi File Plug-in 8.6.1

Troi File Plug-in is a very powerful tool for getting access to information outside the FileMaker Pro database. Any files stored on the rest of the computer can be accessed through the functions of the plug-in.

Troi File Plug-in FMP8 conversion notes

We have two flavors of File Plug-ins: Troi File Plug-in 2.8.2 which uses the Classic function API (Application Programmers Interface) and Troi File Plug-in 3 (or higher) which uses the FileMaker 7 Native function API introduced with FileMaker 7. Below you find a discussion of both.

NB Below we will discuss Troi File Plug-in 3.0 (the first version to use the new API), but this also applies to versions with a higher number, for example version 5.5 and 4.0.

TIP 1 Troi File Plug-in 3.0 and higher also work with FileMaker 8.x and FileMaker Pro 9, as the share the same plug-in API, so the conversion notes also apply for FileMaker 8.x and 9 databases.

TIP 2 You can use both 2.8.2 and 3.0 together when running FileMaker 7. This way you can still use the old function calls, while you are converting your databases and gradually move to use the new features of Troi File Plug-in 3.0. But be aware that the classic and new plug-in don't communicate settings, like for example the default FileSpec.

Troi File Plug-in 2.8.2 (Classic API) is compatible with FileMaker 7

Troi File Plug-in 2.8.2 in general does work with FileMaker Pro 7, without modification. We have found no other issues with FileMaker 7 than the ones below.

ReferenceToClip

This function does not work with FileMaker Pro 7. Solution: use the native FileMaker 7 way to import as a reference. See the RefPict.fp7 example file in the download of File Plug-in 3

GetPathTo -CurrentFileName

This function does not work with FileMaker Pro 7 when using the "-CurrentFileName" switch. Solution: use the built-in Get(FilePath) function.
The other switches still work. See the GetpathTo.fp7 example file in the download of File Plug-in 3, for an example on how to convert a FileMaker path from Get(FilePath) to a full path in the format the Troi File Plug-in understands.

General issue for all classic plug-ins with higher ASCII's

FileMaker Pro 7 has a new internal architecture, which is using Unicode for the text fields. FileMaker Pro 6 only used ASCII encoding. All plug-ins written for the 'classic' FileMaker 6 architecture do not receive characters that are outside this ASCII range, these characters are replaced with spaces. In general our classic plug-ins should be compatible as long as the text used is lower ASCII text.

The File Plug-in 2.8.2 is using the classic API, so only characters in the ASCII range will work.

Troi File Plug-in 3.0 (Native FileMaker 7 API)

Troi File Plug-in 3.0 and later were created specifically for FileMaker 7. Below are some considerations when converting to Troi File Plug-in 3.0 and later.

New function syntax

The plug-in functions have a different syntax compared to the FileMaker 6 plug-in.

For example the GetContents function has this syntax in the classic API:

External("TrFile-GetContents", "fileSpec| start | size" )

The syntax in the new API looks like this:

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

Note that functions look like a real function call, no longer a call to External(). Also a hyphen "-" is no longer allowed in the function names, so the hyphens have changed to underscores "_" instead. Note too that parameters don't have to be concatenated with a pipe. Instead use a semicolon ";" to separate the parameters. The brackets "{}" indicate optional parameters. Below is an example how this function would appear in ScriptMaker:

Set Field [textField , TrFile_GetContents( "-Unused" ; gFileSpec ; 0 ; 1000 ) ]

TIP Function names are no longer case sensitive, and will change to the correct case after you close the "Specify Calculation" dialog box.

Multiple parameters and new switches

As seen from the syntax, plug-in functions now can have multiple parameters. To make this plug-in more consistent, all functions now have a switches parameter as the first parameter. This makes enhancing the plug-in in the future easier. Finally we renamed a few functions and also removed any spaces in the name. See the specific functions notes below for the specifics.

TIP Switches are not case sensitive.

Omitting optional parameters

When you omit an optional parameter be sure to add an extra semicolon after the last one, otherwise FileMaker will show an alert that there are too few parameters in this function. For example, below we omitted the 3rd parameter at the end (initialfolder). This is the correct way to do this:

Set Field [theFile, TrFile_SelectFileDialog("-Unused" ; "Select a file" ; )]

New parameter limits

The plug-in functions now have a size limit of 1 Gb per parameter (up from the total of 64000 character limit for all parameters in FileMaker 6). The Troi File Plug-in 3.0 can handle those bigger parameters, however, displaying the results in FileMaker 7 can take a long time. For example we read in a 300.000 character text from a file on disk with this script step:

Set Field [textField , TrFile_GetContents( "-Unused" ; gFileSpec ; ) ]

The step itself took less than a second. However, FileMaker then updated the layout, which took about 20 seconds!

Converting the function call

When converting FileMaker does not change the plug-in call. So after conversion you need to do this manually. Here are the global steps:

remove the External(" at the beginning
in the function name: change - to _ and remove spaces, add a ( at the end.
change the name of the function (in some cases)
add as first parameter: "-Unused" ( if no switch parameter is there)
split the remaining parameters: separate each with a ;

Let's for example take this File Plug-in 2.8.2 call:

External("TrFile-Get FileSpec Dialog", "Please select a file|" & gInitialFolder)

This needs to be changed to this File Plug-in 3.0 call:

TrFile_SelectFileDialog( "-Unused" ; "Please select a file" ; gInitialFolder )

TIP Just copy script or steps from the example files, they are all in the File Plug-in 3.0 format!

Renamed functions

The table below will help you figure out the new names for changed function names:

Old function name	New function name	Notes
TrFile-FileSpec To FullPath	TrFile_FileSpecToFullPath	Only removed spaces
TrFile-FullPath To FileSpec	TrFile_FullPathToFileSpec	Only removed spaces
TrFile-Get FileSpec Dialog	TrFile_SelectFileDialog
TrFile-GetDateTimeCreated	TrFile_GetTimestampCreated
TrFile-GetDateTimeModified	TrFile_GetTimestampModified
TrFile-Save FileSpec Dialog	TrFile_SaveFileDialog
TrFile-ThumnailToClip	TrFile_CreateThumbnail	Now returns the thumbnail as a container

Specific functions notes

The table below lists conversion issues with specific functions:

Function name	Notes
TrFile_DeleteFolder	A folder may contain an invisible .DS_Store or Icon file on Mac OS X, there is currently no easy way to delete it when only those 2 files are there.
TrFile_FileSpecToFullPath	Renamed from "TrFile-FileSpec To FullPath" (removed spaces).
TrFile_FindFolder	By default now returns a full path, for example: "Mac HD:System:". See the "-ReturnFSSpec" switch to change this.
TrFile_FullPathToFileSpec	Renamed from "TrFile-FullPath To FileSpec" (removed spaces).
TrFile_GetContents	Updated: The offset of the optional 'start' parameter is from 0, contrary to the classic version 2.8.2 and earlier which had 1 as offset. For example: TrFile_GetContents( "-Unused" ; filepath ; 2 ; 5) with "abcdefgh" as contents will now returns "cdefgh".
TrFile_GetTimestampCreated	Renamed from "TrFile-GetDateTimeCreated". It now returns a timestamp.
TrFile_GetTimestampModified	Renamed from "TrFile-GetDateTimeModified". It now returns a timestamp.
TrFile_GetFileAttribute	Mac OS X: finder comment does not work.
TrFile_GetPathTo	By default now returns a full path, for example: "Mac HD:text.txt". See the "-ReturnFSSpec" switch to change this.
TrFile_Launch	Mac OS X: also opens folders.
TrFile_ListDisks	The result no longer has a return at the end of the last line. Add the -ReturnAtEnd switch if you want the last item to be followed by a return.
TrFile_ListFolder	Higher Unicode characters in disk names don't work for short filenames. Use the -Longnames switch. The result no longer has a return at the end of the last line. Add the -ReturnAtEnd switch if you want the last item to be followed by a return.
TrFile_ReferenceToClip	Obsolete See below.
TrFile_SaveFileDialog	Renamed from "TrFile-Save FileSpec Dialog". By default now returns a full path, for example: "Mac HD:text.txt". See the "-ReturnFSSpec" switch to change this.
TrFile_Search	Higher Unicode characters in the search parameter don't yet work as expected. The result no longer has a return at the end of the last line. Add the -ReturnAtEnd switch if you want the last item to be followed by a return.
TrFile_SelectFileDialog	Renamed from "TrFile-Get FileSpec Dialog". By default now returns a full path, for example: "Mac HD:text.txt". See the "-ReturnFSSpec" switch to change this.
TrFile_SelectFolderDialog	By default now returns a full path, for example: "Mac HD:System:". See the "-ReturnFSSpec" switch to change this.
TrFile_CreateThumbnail	No longer uses the clipboard, but now returns the thumbnail as a container. See the Thumbnail.fp7 example file for the implementation details.

Obsolete functions

Function name	Notes
TrFile_ReferenceToClip	This function is not implemented, and will return $$-4221. Use this script step instead: `Set Field [ container, "image:/DISKNAME/foldername/filename.jpg" ]` See the RefPict.fp7 example file for a way to do this.
Troi-Set Default Separator	No longer needed. API allows multiple parameters.
Troi-Set Separator Once	No longer needed. API allows multiple parameters.

Please report problems and bugs

If you find any other problems or bugs, not mentioned above, please send an email to us. Please do NOT send attachments unless specifically requested. Please include the FileMaker version, your platform and operating system in your comments.

Back to details File Plug-in page