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
$102.50
Apple Inc.
+0.25
MSFT
$45.43
Microsoft Corpora
+0.55
GOOG
$571.60
Google Inc.
+2.40

MacTech Search:
Community Search:

Software Updates via MacUpdate

pwSafe 3.1 - Secure password management...
pwSafe provides simple and secure password management across devices and computers. pwSafe uses iCloud to keep your password databases backed-up and synced between Macs and iOS devices. It is... Read more
StatsBar 1.8 - Monitor system processes...
StatsBar gives you a comprehensive and detailed analysis of the following areas of your Mac: CPU usage Memory usage Disk usage Network and bandwidth usage Battery power and health (MacBooks only)... Read more
Path Finder 6.5.5 - Powerful, award-winn...
Path Finder is a file browser that combines the familiar Finder interface with the powerful utilities and innovative features. Just a small selection of the Path Finder 6 feature set: Dual pane... Read more
QuarkXPress 10.2.1 - Desktop publishing...
With QuarkXPress, you can communicate in all the ways you need to -- and always look professional -- in print and digital media, all in a single tool. Features include: Easy to Use -- QuarkXPress is... Read more
Skype 6.19.0.450 - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
VueScan 9.4.41 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Cloud 3.0.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
LibreOffice 4.3.1.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
SlingPlayer Plugin 3.3.20.505 - Browser...
SlingPlayer is the screen interface software that works hand-in-hand with the hardware inside the Slingbox to make your TV viewing experience just like that at home. It features an array of... Read more
Get Lyrical 3.8 - Auto-magically adds ly...
Get Lyrical auto-magically add lyrics to songs in iTunes. You can choose either a selection of tracks, or the current track. Or turn on "Active Tagging" to get lyrics for songs as you play them.... Read more

Latest Forum Discussions

See All

Rhonna Designs Magic (Photography)
Rhonna Designs Magic 1.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0 (iTunes) Description: Want to sprinkle *magic* on your photos? With RD Magic, you can add colors, filters, light leaks, bokeh, edges,... | Read more »
This Week at 148Apps: August 25-29, 2014
Shiny Happy App Reviews   | Read more »
Qube Kingdom – Tips, Tricks, Strategies,...
Qube Kingdom is a tower defense game from DeNA. You rally your troops – magicians, archers, knights, barbarians, and others – and fight against an evil menace looking to dominate your kingdom of tiny squares. Planning a war isn’t easy, so here are a... | Read more »
Qube Kingdom Review
Qube Kingdom Review By Nadia Oxford on August 29th, 2014 Our Rating: :: KIND OF A SQUARE KINGDOMUniversal App - Designed for iPhone and iPad Qube Kingdom has cute visuals, but it’s a pretty basic tower defense game at heart.   | Read more »
Fire in the Hole Review
Fire in the Hole Review By Rob Thomas on August 29th, 2014 Our Rating: :: WALK THE PLANKUniversal App - Designed for iPhone and iPad Seafoam’s Fire in the Hole looks like a bright, 8-bit throwback, but there’s not enough booty to... | Read more »
Alien Creeps TD is Now Available Worldwi...
Alien Creeps TD is Now Available Worldwide Posted by Ellis Spice on August 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Dodo Master Review
Dodo Master Review By Jordan Minor on August 29th, 2014 Our Rating: :: NEST EGGiPad Only App - Designed for the iPad Dodo Master is tough but fair, and that’s what makes it a joy to play.   | Read more »
Motorsport Manager Review
Motorsport Manager Review By Lee Hamlet on August 29th, 2014 Our Rating: :: MARVELOUS MANAGEMENTUniversal App - Designed for iPhone and iPad Despite its depth and sense of tactical freedom, Motorsport Manager is one of the most... | Read more »
Motorsport Manager – Beginner Tips, Tric...
The world of Motorsport management can be an unforgiving and merciless one, so to help with some of the stress that comes with running a successful race team, here are a few hints and tips to leave your opponents in the dust. | Read more »
CalPal Update Brings the App to 2.0, Add...
CalPal Update Brings the App to 2.0, Adds Lots of New Stuff Posted by Ellis Spice on August 29th, 2014 [ permalink ] | Read more »

Price Scanner via MacPrices.net

Are We Now In The Post-Post-PC Era?
A longtime and thoroughgoing laptop aficionado, I was more than a little dismayed by Steve Jobs’s declaration back in 2010 when he sprang the iPad on an unsuspecting world. that we’d entered a “post-... Read more
Apple now offering refurbished 21-inch 1.4GHz...
The Apple Store is now offering Apple Certified Refurbished 21″ 1.4GHz iMacs for $929 including free shipping plus Apple’s standard one-year warranty. Their price is $170 off the cost of new models,... Read more
Save $50 on the 2.5GHz Mac mini, on sale for...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
The Rise of Phablets
Carlisle & Gallagher Consulting Group, a businesses and technology consulting firm focused solely on the financial services industry, has released an infographic depicting the convergence of... Read more
Bad Driver Database App Allows Good Drivers t...
Bad Driver Database 1.4 by Facile Group is a new iOS and Android app that lets users instantly input and see how many times a careless, reckless or just plain stupid driver has been added to the... Read more
Eddy – Cloud Music Player for iPhone/iPad Fre...
Ukraine based CapableBits announces the release of Eddy, its tiny, but smart and powerful cloud music player for iPhone and iPad that allows users to stream or download music directly from cloud... Read more
A&D Medical Launches Its WellnessConnecte...
For consumers and the healthcare providers and loved ones who care for them, A&D Medical, a leader in connected health and biometric measurement devices and services, has launched its... Read more
Anand Lal Shimpi Retires From AnandTech
Anand Lal Shimpi, whose AnandTech Website is famous for its meticulously detailed and thoroughgoing reviews and analysis, is packing it in. Lal Shimpi, who founded the tech site at age 14 in 1997,... Read more
2.5GHz Mac mini, Apple refurbished, in stock...
The Apple Store has Apple Certified Refurbished 2.5GHz Mac minis available for $509, $90 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.