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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adobe Illustrator 24.0.3 - Professional...
You can download Adobe Illustrator for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have also purchased an earlier software version). Adobe Illustrator for Mac is the... Read more
Adobe Dreamweaver CC 2020 20.1 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more
Adobe Audition 13.0.3 - Professional pos...
Audition is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition empowers you to create and deliver... Read more
Adobe After Effects 17.0.3 - Create prof...
After Effects is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects can make the impossible possible. Get... Read more
Audio Hijack 3.6.4 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
Eye Candy 7.2.3.96 - 30 professional Pho...
Eye Candy renders realistic effects that are difficult or impossible to achieve in Photoshop alone, such as Fire, Chrome, and the new Lightning. Effects like Animal Fur, Smoke, and Reptile Skin are... Read more
Notability 4.2.2 - Note-taking and annot...
Notability is a powerful note-taker to annotate documents, sketch ideas, record lectures, take notes and more. It combines, typing, handwriting, audio recording, and photos so you can create notes... Read more
Adobe Acrobat Reader 20.006.20034 - View...
Adobe Acrobat Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
Adobe Acrobat DC 20.006.20034 - Powerful...
Acrobat DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat DC with Adobe Document Cloud services is... Read more
Day One 4.8 - Maintain a daily journal.
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more

Latest Forum Discussions

See All

Marvel Strike Force introduces new brawl...
FoxNext's squad-based RPG Marvel Strike Force is set to receive some fresh characters from the X-Men and Iron Man series. They'll arrive as part of the game's latest update, which follows a sizable spending boycott on the title due to complaints... | Read more »
Speed Dating for Ghosts is a narrative a...
Speed Dating for Ghosts originally released on Steam back 2018, since then it has received honourable mentions for narrative during the Independent Games Festival. Now it's made its way over to iOS devices where it's available as a premium title... | Read more »
Fast-paced multiplayer title Tennis Star...
Tennis Stars: Ultimate Clash is the latest free-to-play tennis title to hit iOS and Android. It's said to be a fairly casual experience, offering easy-to-learn controls and fast-paced, mobile-friendly matches. [Read more] | Read more »
Super Mecha Champions' latest updat...
Super Mecha Champions' latest update sees the addition of a brand new character called R.E.D. Alongside that, there's news about the current season and a series of Emojis that have been added to the game. [Read more] | Read more »
Isle Escape: The House is an upcoming pu...
Isle Escape: The House is an upcoming puzzle game from Simeon Angelov that's intended to serve as an introduction to a saga they're planning on releasing in an episodic fashion. The first chapter is set to release for both iOS and Android on 29th... | Read more »
Company of Heroes, the classic RTS, is n...
Feral Interactive has finally released their highly anticipated iOS version of the strategy classic Company of Heroes. It's available now for iPad as a premium title and has had various tweaks to ensure that it's optimised for touch controls. [... | Read more »
Mario Kart Tour's Vancouver Tour ha...
With Mario Kart Tour's Valentine's Tour now at an end (suspiciously before Valentine's Day has even arrived), it's now time to move on to the all-new and exciting Vancouver Tour. This time around, the featured drivers are Hiker Wario and Aurora... | Read more »
A new PictoQuest update makes it a much...
PictoQuest is a charming little puzzle game, but it left us a little disappointed. The game just didn’t seem to use screen space effectively, to the point that using the touch controls (as opposed to the default virtual d-pad) could lead to errant... | Read more »
Alley is an atmospheric adventure game a...
Alley is an atmospheric adventure game that sees you playing as a young girl trapped in an inescapable nightmare. Surrounded by her worst fears, every step forward for her is a huge challenge that you'll help guide her through using some simple... | Read more »
Fight monsters and collect heroes in Cry...
From Final Fantasy to Chaos Rings, Japanese roleplaying games have found a large and loyal fanbase on mobile devices. If you’re seeking a more under-the-radar JRPG to escape into, Lionsfilm’s Cryptract could be the one. The game has been around... | Read more »

Price Scanner via MacPrices.net

Apple AirPods are on sale for $30 off today
Amazon has new 2019 Apple AirPods (non-Pro models) on sale today for $30 off MSRP, starting at $129. Shipping is free: – AirPods with Wireless Charging Case: $169 $30 off MSRP – AirPods with Charging... Read more
27″ 3.7GHz 6-Core 5K iMac on sale for $2099,...
B&H Photo has the 2019 27″ 3.7GHz 6-Core 5K iMac in stock today and on sale for $200 off Apple’s MSRP. Overnight shipping is free to many locations in the US: – 27″ 3.7GHz 6-Core 5K iMac: $2099 $... Read more
Save up to $250 on a 12.9″ iPad Pros with the...
Apple has Certified Refurbished 12.9″ iPad Pros available on their online store for up to $250 off the cost of new models. Prices start at $849. Each iPad comes with a standard Apple one-year... Read more
Save up to $220 on 11″ iPad Pros with these r...
Apple has Certified Refurbished 11″ iPad Pros available on their online store for up to $220 off the cost of new models. Prices start at $679. Each iPad comes with a standard Apple one-year warranty... Read more
8-Core 27″ iMac Pro available for $4249, Cert...
Apple has Certified Refurbished 27″ 3.2GHz 8-Core iMac Pros available for $4249 including free shipping. Their price is $750 off the cost of new models. A standard Apple one-year warranty is included... Read more
$749 MacBook Airs continue to be available on...
Amazon has the 2017 13″ 1.8GHz/128GB MacBook Air on sale today for only $749 shipped. That’s $250 off Apple’s original MSRP for this model and the cheapest new MacBook available from any Apple... Read more
HomePods on sale for $204 at Other World Comp...
Other World Computing has discounted, new, Apple HomePods on sale for up to $95 off Apple’s MSRP: – HomePod Space Gray: $207.99 $92 off MSRP – HomePod White: $204.99 $95 off MSRP These are the same... Read more
Get a Certified Refurbished iMac at Apple for...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
A Look Back At The Top 5 Most Read Stories Of...
FEATURE: 02.21.20 The best of the best are now history and we’re not talking about Super Bowl LIV from earlier this month but rather, coverage from the past year (its second and first full one at... Read more
Apple offers wide range of discounted custom...
Save up to $610 on a custom-configured 21″ or 27″ iMac with these Certified Refurbished models available at Apple. Each iMac features a new outer case, free shipping, and includes Apple’s standard 1-... Read more

Jobs Board

Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Geek Squad *Apple* Consultation Professiona...
**762475BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 001423-San Jose-Store **Job Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Geek Squad *Apple* Consultation Professiona...
**756636BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 001053-Arundel Mills-Store Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.