# Troi File Plug-in 10 for FileMaker 17 USER GUIDE March, 2019 Troi Boliviastraat 11 2408 MX Alphen aan den Rijn The Netherlands You can visit the Troi web site at: www.troi.com Troi File Plug-in is copyright 1998-2019 of Troi Automatisering. All rights reserved. # Table of Contents Installing plug-ins If you have problems What can this plug-in do? Software requirements Getting started Using external functions Where to add the external functions? Using script steps About file paths Simple example You can use globals or variables Function and script step reference ## Installing plug-ins Starting with FileMaker Pro 12 a plug-in can be installed directly from a container field. Installation is therefore very easy: just open the "All File Examples.fmp12" example file and the startup script will install the plug-in for you. See also the EasyInstallTroiPlugins.fmp12 example file which contains the actual plug-in and install script. TIP You can check which plug-ins you have loaded by going to the plug-in preferences: choose Preferences from the Edit menu, and then choose Plug-ins. You can now open the file "All File Examples.fmp12" to see how to use the plug-in's functions. There is also a function and script step reference available. ## If you have problems This user guide tries to give you all the information necessary to use this plug-in. So if you have a problem please read this user guide first. You can also visit our support web page: www.troi.com/support This page contains FAQ's (Frequently Asked Questions), help on registration and much more. If that doesn't help you can get free support by email. Send your questions to support@troi.com with a full explanation of the problem. Also give as much relevant information (version of the plug-in, which platform, version of the operating system, version of FileMaker Pro) as possible. Note that due to spam we have to filter incoming email. It might happen that non-spam email is filtered out too. If you have sent an email and you don't get an answer, try to send another email, slightly differently formulated and include the word "FileMaker" in the body text. If you find any mistakes in this manual or have a suggestion please let us know. We appreciate your feedback! TIP You can get more information on returned error codes from the OSErrrs database on our web site. This free FileMaker database lists all error codes for Windows and macOS! ## What can this plug-in do? Troi File Plug-in is a very powerful tool for getting access to information outside the FileMaker database. Any files stored on the rest of the computer can be accessed through the functions of the plug-in. All from within FileMaker you can: get data out of files on the disk of the computer create files anywhere on the hard disk and put data from FileMaker fields into it manipulate files and folders on the disk, like creating/deleting/copying/moving get metadata from images and movies, such as size, resolution, Exif, IPTC etc. and much more... ## Software requirements ### System requirements for macOS Mac OS X 10.8 (Mountain Lion), OS X 10.9 (Mavericks), OS X 10.10 (Yosemite), OS X 10.11 (El Capitan), macOS 10.12 (Sierra), macOS 10.13 (High Sierra), macOS 10.14 (Mojave). ### System requirements for Windows Windows 7 Windows 8, Windows 8.1 Windows 10, including Creators Update, Fall Creators Update, April 2018 Update and October 2018 Update. ### FileMaker Pro requirements FileMaker Pro 13 or FileMaker Pro Advanced 13. FileMaker Pro 14 or FileMaker Pro Advanced 14. FileMaker Pro 15 or FileMaker Pro Advanced 15. FileMaker Pro 16 or FileMaker Pro Advanced 16. FileMaker Pro Advanced 17. ### FileMaker Server requirements FileMaker Server 13 or FileMaker Server Advanced 13. FileMaker Server 14 or FileMaker Server Advanced 14. FileMaker Server 15 or FileMaker Server Advanced 15. FileMaker Server 16 or FileMaker Server Advanced 16. FileMaker Server 17 or FileMaker Server Advanced 17. You can use FileMaker Server to serve databases that use functions of Troi File Plug-in (client-side): you need to have the plug-in installed at the clients that use these functions. Troi File Plug-in can also be used by FileMaker Server as a server-side plug-in or as a plug-in used by the web publishing engine. To use Troi plug-ins as a server-side or web-side plug-in you need to purchase a special Server/Web license. More information can be found in the download or on our web site. ## Getting started ### Using external functions Troi File Plug-in adds new functions to the standard functions that are available in FileMaker Pro. The functions added by a plug-in are called external functions. You can see those extra functions for all plug-ins at the top right of the Specify Calculation box: You use special syntax with external functions: FunctionName ( parameter1 ; parameter 2 ) where FunctionName is the name of an external function. A function can have zero or more parameters. Each parameter is separated by a semi-colon. Plug-ins don't work directly after installation. To access a plug-in's function, you need to add the calls to the function in a calculation, for example in a text calculation in Define Fields or in a script in Script Workspace (formaly called ScriptMaker). ### Where to add the external functions? Most of the external functions for this plug-in are intended to be used in a script step using a calculation, in a Set Field script step. For quite a lot of functions of this plug-in it makes no sense to add them to a define field calculation, as the functions will have side effects. When you are defining fields (choose Define Database from the File menu), only some of the functions will be visible. Those should be safe to use there, but be careful and think about it before adding external functions to a calculation field. ### Using script steps Starting with FileMaker 16 plug-ins can also add script steps. You can select these script steps in the script steps pane in Script Workspace, or you can begin typing the script step name, then choose the script step from the list that appears. The script steps significantly expand the possible actions you can perform with FileMaker Pro. NOTE only steps that perform an action have been added as a script step. Functions that just return information (like for example TrFile_GetFileSize) are only available as an external function. ### About file paths To be able to specify a file or folder, the plug-in can use a full path or a FileMaker styled path. NOTE Troi File Plug-in 10 no longer supports FSSpecs (see below). On Windows the path is always a full path like this for a file: C:\Data Files\Database\Test.Txt and similar to this for a folder: C:\My Files\Main\ If you use the FileMaker style paths this becomes: filewin:/C:/Data Files/Database/Test.Txt and similar to this for a folder: filewin:/C:/My Files/Main/ On macOS a file path can be a full path or a FileMaker styled path. A full path on Mac looks like this: Mac HD:Data Files:Database:testfile and similar to this for a folder: Mac HD:My Files:Main: If you use the FileMaker style paths on macOS this becomes for a file: filemac:/Mac HD/Data Files/Database/Test.Txt and similar to this for a folder: filemac:/Archive CD/My Files/Main/ Older versions of Troi File Plug-in also supported an FSSpec, which has the following format: :volumeID:directoryID:fileName An example would be: :-1:300:testfile NOTE 1 With macOS FSSpec's are no longer supported. Therefore all plug-in functions now return a full path. NOTE 2 On macOS a volume name and therefore a full path need not be unique. Be careful with this. ### Simple example Say you want to get the contents of a report file that contains text. The file resides on a known place on the harddisk. Say you want the text to be put in the text field "myTextField". Create a script "Get Report Text". Add the following script step to this script: Set Field [ myTextField ; TrFile_GetContents ( "-Unused" ; "C:\DataFiles\Report.txt" ) ] If you run this script the contents of the file is put in the field "myTextField". NOTE Function names, like TrFile_GetContents are not case sensitive. As you can see the path "C:\DataFiles\Report.txt" in the script above makes it clear that this script only works on Windows. If you want to remove this platform dependency you can use a variable or global text field, which holds the path to the folder. Say the full path on macOS would be "Disk:DataFiles:Report.txt". Also assume you have defined a global text field "gPathToFolder". The script would then become like this:
      If [ Abs(Status(CurrentPlatform ) ) = 1 ]
           # ...on Mac OS...
           Set Field [ gPathToFolder ; "Disk:DataFiles:" ) ]
      Else
           # ...on Windows...
           Set Field [ gPathToFolder ; "C:\DataFiles\" ) ]
      End If
      Set Field [ myTextField ; TrFile_GetContents ( "-Unused" ; gPathToFolder & "Report.txt" ) ]
Of course the global gPathToFolder could be set earlier in a separate script, as part of the preferences. Please take a close look at the included example files, as they provide a great starting point. From there you can move on, using the more than 70 functions of the plug-in as building blocks. Together they are a powerful tool set for working with files on the disk. ### You can use globals or variables With the release of FileMaker Pro 8 and later it is possible to use variables in calculations. Our example files in the download now both use global fields and variables to pass parameters and store the results of a plug-in function. As this release of Troi File is intended for FileMaker Pro 13 and higher, we continue to move the scripts to use variables wherever possible. Note that not all examples are using variables yet. All plug-in functions work with variables just fine. For example if you have these script steps:
      Set Field [ this::gPath ; "your path here" ]
      Set Field [ this::gImageDesc ; TrFile_MetaData ( "-GetImageDescription" ; this::gPath ) ]
With variables you can alternative use:
      Set Variable [ $Path ; "your path here" ]
      Set Variable [ $ImageDesc ; TrFile_MetaData ( "-GetImageDescription" ; $Path ) ]
The main advantage of variables is that you don't need to define global fields that clutter your database definitions. The variables can stay local to the script. See for example the ManageMedia.fmp12 example file, which uses variables in its scripts. Note that this example file also depends on global fields, as the scripts have been copied from an older example file. ## Function and script step reference For a description of all External Functions and External Script Steps added by Troi File Plug-in please see the separate Reference.fmp12 file. For each function and script step you will find: the correct syntax the parameters/options to be used the returned result special considerations an example usage The same information is also available as online help on Troi's web site. You can easily consult the online help directly from FileMaker, by clicking the Help button (the small question mark button) next to the function description in the functions pane or the script step description in the script steps pane.