TweetFollow Us on Twitter

FileMaker Pro Plug-Ins

Volume Number: 15 (1999)
Issue Number: 1
Column Tag: Plugging In

External Function Plug-ins for FileMaker Pro

by David McKee
Edited by Michael Brian Bentley

An Introduction to Their Nature and Creation.

FileMaker Pro and Plug-ins

FileMaker® Pro software is the database of choice for Mac OS users; part of its success has been due to the very accessible user interface. Much of what you do is point-and-click. Up until recently, the closest to programming you could get is a very complex calculation formula or script. Plug-ins introduce a level of programmability never before available.

A script in FileMaker Pro is not unlike a macro in a word processing application. Scripts are great for automating tasks you can do manually in the user interface such as switching layouts or printing a report, but they must be initiated by the user. Calculations are performed without user input and are adequate for typical usage, since calculations are written in a high level syntax that is interpreted by the FileMaker Pro calculation engine. Creating a formula merely requires that you assemble a series of built-in functions from various categories.

A calculation formula like "fieldA + Sin(fieldB)" can be created entirely by the point-and-click interface.

The problem is, formulas that require recursion or looping are not possible in calculations. Typical kinds of functions are built-in, like trigonometric functions, but industry-specific algorithms, like annuity functions based on payments at the beginning of a period, are not.

Scripts support recursion and looping, but require the user to execute them.

Both calculations and scripts interact with other parts of a FileMaker Pro database. The various parts of FileMaker Pro integrate well, but a database is closed to the outside world of the OS and/or other applications. What if your calculation requires some information from another SDK? What if you wanted to create your solution to present to the user a very specific style of dialog boxes?

With AppleScript and the right scripting addition, you could achieve some sort of integration with another application. With some layout tricks, you could simulate dialogs. However, this just isn't the same as having a programmable feature within the application that would give you direct access to the OS or another SDK.

FileMaker Pro "External Function Plug-ins" can bridge this gap between the application's predefined interface and your need for a custom one. An API/SDK was released for FileMaker Pro 4.0 that allows you to create your own compiled code that can be referenced by a formula in a calculation, as an "External" function. When an External function is referred to, FileMaker Pro passes program control over to the external code you created. Your plug-in can then do what it needs to do and pass the needed information (and program control) back to FileMaker Pro.

By using an External Function Plug-in, you can use calculation formulas that take advantage of things like recursion and looping. Plug-ins can hook into other applications or the Mac OS toolbox. This means things previously impossible with calculations and scripts are now within the database developer's reach.

For brevity and focus, this article assumes you have at least a rudimentary knowledge of FileMaker Pro calculation fields and scripts.

Terms

The following are terms used within this article. They are included for those new to programming plug-ins or modules.

Plug-in
A plug-in is a file separate or external to the application that contains executable code. The application loads the plug-in at runtime and passes information and control to the plug-in whenever needed. The advantages of putting some features in a plug-in include easier revision of the feature, as well as allowing the application author to open up feature creation or modification to the public without exposing sensitive parts of the program. A plug-in is essentially a separate application that is complied as a code resource or library. It inhabits the same application space as the host program that loaded and passed execution to it.
Parameter Block
A Parameter Block is the sole shared data structure that gets passed between the program and the plug-in. This allows data and functions to be passed seamlessly, even though they are basically two separate applications. If a particular function is not supported by the parameter block, then the desired control or communication between the two entities is probably not possible.
API
An API, or Application Programming Interface, is a set of standards that your application must adhere to in order for it to be usable with the host program or standard. Some APIs are header and source code documents that you are required to use when compiling your code, while other APIs are just header files that allow you to link to a provided library. There are no extra libraries needed to create a FileMaker Pro plug-in other than the ones you would normally need to create a code resource or shared library.
SDK
An SDK, or Software Development Kit, is often used interchangeably with API.
External Function
An External function is a new class of calculation functions that can be used in a calculation formula. First introduced in FileMaker Pro 4.0, functions in this class are not built into the application. External functions can be designed and used in two ways. When used from within a calculation field, as part of a formula, the External function behaves as a function. In this case, the External function returns data that will be used as part of the formula. When used from a SetField script step, where an action is involved, the External function behaves as a command. In this case, what the External function returns may only be a result/error code.
External Function Plug-in
An External Function Plug-in is a third-party file that contains External functions. These are loaded by the FileMaker Pro application upon startup. The External functions are then listed in the calculation dialog box interface of FileMaker Pro.
Feature String
A Feature String is a series of flags that inform FileMaker Pro how to utilize the plug-in. Part of the Feature String is the "Feature String ID", which is essentially a Mac OS creator code that uniquely identifies that plug-in. No two plug-ins should have the same Feature String ID.
FileMaker Pro Developer Edition
The FileMaker Pro Developer Edition (DE) is a FileMaker, Inc. product for high-end FileMaker Pro developers. This product includes many developer-oriented products that are of little use to end users. The Developer Edition (DE) is required to obtain the External Function Plug-in API. However, plug-ins created with the API can be used on any FileMaker Pro 4.0 (or greater) based product.

Before Starting

External Function Plug-ins (EFPs) were primarily intended to allow someone to supplement the list of calculation functions. While EFPs can supply many functions, you should consider a plug-in a toolbox of similar features. Try to focus your plug-in project on a certain function or tight group of functions. "Swiss army knife" plug-ins with unrelated functions will confuse end users and not distinguish your plug-in from others.

Non-programmers will use EFPs you create for their databases. Most FileMaker Pro database developers may not understand programming conventions that you take for granted. Design your plug-in and the syntax of the External functions with your audience in mind.

Since the Feature String ID is vital to your plug-in, you'll want to register it with Apple and FileMaker, Inc. Details of plug-in registration are included with the API package in the FileMaker Developer Edition.

If you have ever written a plug-in, a Desk Accessory, or a Driver, you will find that writing a FileMaker Pro plug-in is extremely simple. The details in this article concerning the API itself will probably be enough to get you on your way.

If you have never written a plug-in it is strongly recommended that you re-use the sample plug-in projects that come with the API. Walking a programmer through creating a FileMaker Pro plug-in from scratch is beyond the scope of this article.

The External Function Plug-in API

The External Function Plug-in API package contains many files, and includes two examples. The best way to understand how the individual source and header files relate is to examine the examples. The core of the functionality of this API is actually quite simple.

The API includes a programming overview ("EFP Documentation.pdf") targeted at experienced programmers who also know FileMaker Pro. It outlines details relevant to the differences between a FileMaker Plug-in and other plug-ins. It covers only specifics that wouldn't be part of the creation of a "typical" plug-in. It is not intended to be a "How-to" on writing plug-ins.

The "FMFlags.h" header file contains used compiler directives to control code compilation. Since the API supports both Macintosh and Windows plug-ins on more than one compiler, this file allows you to have one set of source code files that will compile in all cases. Do not alter this file.

The "FMExtern.h" and "FMExtern.c" files define the parameter block and some shared function calls. The function calls are needed to, among other things, manipulate the "parameter" and "result" handles contained in the parameter block that your plug-in will use.

In the FMExtern.h file, you will notice the call-back functions for memory operations are defined. Below that, is the definition of the different kinds of plug-in events sent to the plug-in.

typedef    enum { kFMXT_Init, kFMXT_Idle, kFMXT_Internal1,
                  kFMXT_External, kFMXT_Shutdown, 
                  kFMXT_DoAppPreferences, kFMXT_Internal2 }
FMExternCallSwitch;

There will be an item in the parameter block that will be equal to one of these values. The "Internal" values are reserved items. When your plug-in receives control from the FileMaker Pro host program, it will be under one of the following conditions.

kFMXT_Init
This indicates that your plug-in is being loaded during the initialization of the FileMaker Pro application. This occurs shortly after the user launches the application.
kFMXT_Idle
This indicates that your plug-in is being given some processing time, but is not being explicitly used by the database or user. If the appropriate flag in the Feature String of the plug-in is not set, your plug-in will never receive this event.
kFMXT_External
This indicates that one of the functions of your plug-in is being explicitly used by the database or user, and needs to return a value. If the appropriate flag in the Feature String of the plug-in is not set, the functions of your plug-in will not be accessible to the database or user.
kFMXT_DoAppPreferences
This indicates that the user has just clicked on the "Configure" button in the plug-in management dialog within FileMaker Pro. Your plug-in can now present its own preferences dialog box. If the appropriate flag in the Feature String of the plug-in is not set, the Configure button will be grayed out and your plug-in will never receive this event.
kFMXT_Shutdown
This indicates that the FileMaker Pro application is about to terminate normally. This allows your plug-in to do the appropriate cleanup, if needed.

Immediately below the FMExternCallSwitch definition is the type definition for "FMExternCallStruct". The FMExternCallStruct is the structure of the parameter block for the External function API. "FMExternCallPtr" is defined as a pointer to that struct. A global variable "gFMExternCallPtr" is then defined as a FMExternCallPtr.

These structures are the "meat and potatoes" of the communication between your plug-in and FileMaker Pro. Nestled within this structure are two innocent looking variables of type long. They are "param3" and "result". The variable "param3" is actually the parameter data that was passed to the External function from the calculation formula in FileMaker Pro. It is referred to as "parameter" in some of the functions.

Variables you will coerce to "FHandle" variables in your plug-in code. A Fhandle is simply a handle to unsigned character data. There is no need for a length byte or null terminator for this string as the size of the handle is the size of the string. Since External functions can only return text/string data, the data you read from "param3" (or "parameter") and the data you put into "result" must be text, or a textual representation of a number.

The "FMTemplate.c" or "FMExample.c" files are examples of what the main file should look like. Note that they both define the main/entry point function for the various environments (PPC, 68k, or x86) a plug-in can be compiled for.

Inside the Main entry point, there is a switch statement that allows the plug-in to determine the condition under which control is passed to it, so that it may act appropriately.

switch (pb->whichCall) {

The variable "pb" is simply a local variable that was assigned to be equal to gFMExternCallPtr. Everything else within these files is non-essential to the API and specific to your plug-in.

Since the API is considered proprietary information, you cannot republish any information in any of the files other than the "FMTemplate.c" and "FMExample.c" files.

The Full Example Plug-in

Provided with the API are a "Template" plug-in and a "Full Example" plug-in. The "Template" is a shell project with two functions typically used only by programmers.

The "Full Example" plug-in was designed as an example of what a "full blown" plug-in would look like. While it doesn't illustrate every possible use of a plug-in, it does have many subroutines that are well suited as External functions, or in designing them. It also demonstrates a rudimentary preferences dialog.

Let's say the FileMaker Pro user has installed the compiled Full Example plug-in and created a calculation field that refers to one of the functions, Xpl-BigPi. The reference to the External function would appear in the calculation formula as something like "...External("Xpl-BigPi","")...".

"External" signals FileMaker Pro that it must locate the function "Xpl-BigPi" in one of the loaded External Function Plug-ins. Once located, the External function passes the contents of the second parameter as a handle. In this case, the handle will have a size of zero. The contents of this parameter are stored in the contents of "param3" for the plug-in.

Within the main/entry point, the plug-in will be notified that one of its External functions is being used, and that it must call the appropriate function. The sample plug-ins use a handler named "Do_External".

case kFMXT_External:
     Do_External(pb->parm2, (FHandle)(pb->parm3),
                               (FHandle)(pb->result));
     break;

Note that the handler has three parameters (obtained from the parameter block). The first parameter is the index number of the plug-in. The first function is index number zero. Xpl-BigPi is the second function, so the index number will be one.

Going to the source code, the "Do_External" handler looks something like this:

// Received a message that some calc depends on one of the
// External functions in this plugin, so perform the appropriate
// function and return the results back to FileMaker Pro (FMP).

static void Do_External(long functionId, FHandle parameter,
     FHandle result) {

    switch (functionId) {

        #if DEBUG_VERSION
        case 0:
            // Since we're debugging, let's have a debug function
            // to access from FMP in place of ThisVersion.
            // In FMP, we'll still have to "pretend" we're using 
            // the version function "ThisVersion", but we're actually
            // calling a different function in our plugin.
            DebugPlugin(parameter, result); // not PluginVersion
            break;
        #else        
        case 0:
            // This is the "shipping" version of our plug-in, so
            // let's disable the debug funct and use the proper
            // ThisVersion function -> PluginVersion
            PluginVersion(parameter, result);
            break;
        #endif

        case 1: // pi =  Xpl-BigPI
            funct_PI(result);
            break;

        case 2: // format a number =  Xpl-Format
            funct_Format(parameter, result);
            break;

        case 3: // number to words =  Xpl-NumericalWords
            funct_Num2Words(parameter, result);
            break;

        default:
                // Beep. -This plugin is being sent a message to execute
                // a function that doesn't exist in this plug-in. (This
                // could be due to a plug-in installed with the same name
                // as ours, with a bigger number of functions.)
            #if FM_CPU_X86
                MessageBeep(0);
            #else
                SysBeep(1);
            #endif

    }; /* switch */
} /* Do_External */

The function with the index of one that is executed by this function is "funct_PI(result)". We pass on the result handle that this handler function received from the main/entry point. Remember that the parameter was "" in the original calculation formula.

The pi function doesn't need a parameter, so even if the handler passed on the parameter handle, it wouldn't use it. However, funct_PI does change the result handle to k_PI ("3!14159265358979\0"). It is defined as a null-terminated string in case the programmer will use it elsewhere. k_PILength represents the length of the string we will actually return to FileMaker Pro (i.e. 16).

The exclamation point is a placeholder that will be replaced with whatever decimal point character is appropriate for the country the plug-in is being used in.

// Returns pi to the 14th digit (past decimal), as hardcoded in the
// defines file "FMExample.h"

static void funct_PI(FHandle result) {

    FMX_SetHandleSize(result, k_PILength);
    
    if (FMX_MemoryError() == 0) {
        #if FM_CPU_X86
        lstrcpy((LPTSTR)*result, k_PI);
        #else
        BlockMoveData(k_PI, *result, k_PILength);
        #endif

(*result)[1] = decimalSepCH;    
                  // Make sure to substitute that '!' in our pi value to the
                  // acceptable decimal separator for numbers in this 
                  // country.
        } // end if
} // funct_PI

When control is passed back to FileMaker Pro, the result handle in the parameter block is the value of "External("Xpl-BigPi","")".

Although the other functions do much more complicated things, this is essentially how all External functions will behave. The rest is up to your imagination!

Considerations

Debugging code resources or shared libraries is not a simple task. However, if you use DebugStr() and the "DisplayMessage" function, you can do rudimentary debugging very easily. DebugStr() is a function defined in the Universal Headers, which allows you to display a Pascal-style string in a low-level debugger. "Display Message" is a function that is defined in the sample plug-in projects.

If you are having trouble, you might want to consider pasting your plug-in functions into a console project and debug it as an application.

The API is provided only in a C/C++ format. If you plan on using another programming language, you will have to convert the API from C to the other language.

The API is designed to be cross-platform (both Mac OS and Windows). If your plug-in is going to be Mac OS only, you can feel free to strip out all the compiler directives for readability. It is recommended to keep them in, however. Many FileMaker Pro database solutions are cross-platform.

In addition to having cross-platform compiler directives, the Full Example plug-in takes into consideration international users. If you are manipulating numbers, dates or monetary amounts, it is strongly recommended that you also take international users into consideration. The Internet has significantly increased the market for products that are friendly to international users.

Some advanced plug-ins will rely on resources. Make sure to set and restore the current resource file to avoid getting a resource from another plug-in. Also, use resource IDs only in the range between 23,000 and 24,999.

While you own the code you create, you should be careful not to release or publish any files that include code from the External Function Plug-in API. You should also treat your plug-in as a separate software product with its own user license agreement and provisions for technical support. FileMaker, Inc. does not warrant the usability of third-party plug-ins, nor provide technical support for using them.

David McKee is the author of many FileMaker Pro plug-ins, including the "Full Example" plug-in for the FileMaker Pro Developer Edition. He presented a seminar on writing plug-ins at the 1998 FileMaker Developer Conference and works in the Engineering department of FileMaker, Inc.

 
AAPL
$98.38
Apple Inc.
-0.64
MSFT
$43.89
Microsoft Corpora
-0.09
GOOG
$585.61
Google Inc.
-4.99

MacTech Search:
Community Search:

Software Updates via MacUpdate

Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more
Vitamin-R 2.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Toast Titanium 12.0 - The ultimate media...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more
TotalFinder 1.6.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more
Vienna 3.0.0 RC 2 :be5265e: - RSS and At...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
VLC Media Player 2.1.5 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Default Folder X 4.6.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more

Latest Forum Discussions

See All

Note Review
Note Review By Jennifer Allen on July 29th, 2014 Our Rating: :: TOO SIMPLEiPhone App - Designed for the iPhone, compatible with the iPad Note is a note taking app that’s a little too short on features to be worth its asking price... | Read more »
Chainsaw Warrior Goes on Sale & Ther...
Chainsaw Warrior Goes on Sale & There’s a Chance to Win a Copy of the Original Board Game Posted by Jennifer Allen on July 29th, 2014 [ permalink | Read more »
It Came From Canada: Tiny Tower Vegas
If you go to a casino, you might make a lot of money. If you run a casino, you’re guaranteed to make a lot of money. The choice seems pretty obvious. So while waiting for your shady real estate deals to move forward, get prepared with Tiny Tower... | Read more »
Z Hunter Review
Z Hunter Review By Lee Hamlet on July 29th, 2014 Our Rating: :: RIGHT ON TARGETUniversal App - Designed for iPhone and iPad While it might not necessarily break new ground, Z Hunter has enough tricks up its sleeve to ensure that... | Read more »
Huge Update Comes To Duet, Adding 48 New...
Huge Update Comes To Duet, Adding 48 New Stages Posted by Jennifer Allen on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Sharknado: The Video Game Available Now....
Sharknado: The Video Game Available Now. Seriously. Posted by Rob Rich on July 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Frog Orbs 2 Review
Frog Orbs 2 Review By Nadia Oxford on July 29th, 2014 Our Rating: :: THIS MAGIC IS A TAD MONOTONOUS Universal App - Designed for iPhone and iPad Frog Orbs 2 is repetitive, but younger players should enjoy it nonetheless.   | Read more »
Puzzix Review
Puzzix Review By Jennifer Allen on July 29th, 2014 Our Rating: :: NICE IDEAUniversal App - Designed for iPhone and iPad A little like Tetris, Puzzix is all about piecing together blocks and watching them vanish. It could do with... | Read more »
Cannonball eMail is Now Live – Works Wit...
Cannonball eMail is Now Live – Works With Gmail, Yahoo, Outlook, Hotmail, and AOL Posted by Jessica Fisher on July 29th, 2014 [ permalink ] | Read more »
To The End Review
To The End Review By Lee Hamlet on July 29th, 2014 Our Rating: :: A VICIOUS CYCLEUniversal App - Designed for iPhone and iPad To The End will test players’ patience, timing, and dedication as they try to navigate all 13 levels in... | Read more »

Price Scanner via MacPrices.net

The lowest prices on leftover Retina MacBook...
Best Buy has dropped prices on leftover 13″ and 15″ Retina MacBook Pros by up to $300 off original MSRP on their online store for a limited time. Choose free local store pickup (if available) or free... Read more
Apple Updates MacBook Pro with Retina Display...
Apple today updated its MacBook Pro with Retina display with faster processors and double the amount of memory in both entry-level configurations. MacBook Pro with Retina display features a Retina... Read more
Up to $250 price drop on leftover 15-inch Mac...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by as much as $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2349... Read more
Updated MacBook Pro Price Trackers
We’ve updated our MacBook Pro Price Trackers with the latest information on prices, bundles, and availability on the new 2014 models from Apple’s authorized internet/catalog resellers as well as... Read more
Apple updates MacBook Pros with slightly fast...
Apple updated 13″ and 15″ Retina MacBook Pros today with slightly faster Haswell processors. 13″ models now ship with 8GB of RAM standard, while 15″ MacBook Pros ship with 16GB across the board. Most... Read more
Apple drops price on 13″ 2.5GHz MacBook Pro b...
The Apple Store has dropped their price for the 13″ 2.5GHz MacBook Pro by $100 to $1099 including free shipping. Read more
Apple drops prices on refurbished 2013 MacBoo...
The Apple Store has dropped prices on Apple Certified Refurbished 13″ and 15″ 2013 MacBook Pros, with model now available starting at $929. Apple’s one-year warranty is standard, and shipping is free... Read more
iOS 8 and OS X 10.10 To Support DuckDuckGo As...
Writing for Quartz, Dan Frommer reports that Apple’s forthcoming iOS 8 and OS X 10.10 operating systems version updates will allow users to select DuckDuckGo as their default search engine. He notes... Read more
U.K. Hospital Using iPods and iPads To Record...
British news journal GazetteLive’s. Ian McNeal notes that the old “an apple a day keeps the doctor away” proverb is being turned on its head at http://southtees.nhs.uk/hospitals/james-cook/ James... Read more
13-inch 2.5GHz MacBook Pro on sale for $1099,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $1099.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.