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

iFFmpeg 6.4.0 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more
Thunderbird 52.2.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Airfoil 5.6.1 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Apple Remote Desktop Client 3.9.3 - Clie...
Apple Remote Desktop Client is the best way to manage the Mac computers on your network. Distribute software, provide real-time online help to end users, create detailed software and hardware reports... Read more
jAlbum Pro 14.0 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly... Read more
jAlbum 14.0 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results - Simply drag and drop photos into groups, choose a design... Read more
Vitamin-R 2.48 - 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
Beamer 3.3 - Stream any movie file from...
Beamer streams to your Apple TV.... Plays any movie file - Just like the popular desktop movie players, Beamer accepts all common formats, codecs and resolutions. AVI, MKV, MOV, MP4, WMV, FLV. To... Read more
Shredo 1.2.2 - $9.99
Shredo is a beautiful, functional file-shredding and privacy scan utility. It permanently shreds files, folders, and external volumes' contents to keep information secure and impossible for anyone to... Read more
Final Draft 10.0.3 - Industry-leading sc...
Final Draft allows you to use your creative energy to focus on the content; let Final Draft take care of the style. Final Draft is the number-one selling application specifically designed for writing... Read more

Latest Forum Discussions

See All

The House of da Vinci (Games)
The House of da Vinci 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Enter The House of Da Vinci, a new must-try 3D puzzle adventure game. Solve mechanical puzzles, discover hidden... | Read more »
Solve the disappearance of history’s gre...
Blue Brain Games invites you to indulge in an immersive hands-on 3D puzzle adventure in similar vein to The Room series, with its debut release The House of Da Vinci. Set during the historic period of the Italian Renaissance (when Leonardo himself... | Read more »
Age of Rivals (Games)
Age of Rivals 3.3 Device: iOS Universal Category: Games Price: $.99, Version: 3.3 (iTunes) Description: Deep civilization-building strategy in a fast-paced card game! | Read more »
Panthera Frontier (Games)
Panthera Frontier 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Angry Birds Evolution beginner's gu...
Angry Birds changes things up a fair bit in its latest iteration, Angry Birds Evolution. The familiar sling-shot physics mechanics are still there, but the game now features team-based gameplay, RPG elements, and a new top-down view. With all of... | Read more »
Sega Forever is for the retro game fans
Sega is launching a new retro games service titled Sega Forever, in a move that's sure to delight games enthusiasts with a bit of nostalgia. Sega's releasing five classic games for free. The titles include Sonic the Hedgehog, Phantasy Star II,... | Read more »
The Little Acre (Games)
The Little Acre 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Lovely adventure game 'The Little A...
The Little Acre makes its way from PC to iOS today and it's a real charmer. It's a lovely little adventure game set in 1950's Ireland, gorgeously animated in a style slightly reminiscent of old Disney films. The game won a lot of praise for its... | Read more »
Futurama: Worlds of Tomorrow officially...
Futurama: Worlds of Tomorrow arrives next Thursday, and it features . . . Stephen Hawking? Turns out a few of your favorite science super stars, including Bill Nye, Neil DeGrasse Tyson, and George Takei will be making an appearance alongside the... | Read more »
MU Origin’s new update offers exciting c...
MU Origin is kicking off the summer with style. Its latest update is a real doozy, offering up plenty of fresh content. New challenges, some extra help for newcomers, and new costumes are just a few of the things you will find in the new patch. | Read more »

Price Scanner via MacPrices.net

Clearance 2016 MacBook Pros available for up...
B&H Photo has clearance 2016 13″ and 15″ MacBook Pros in stock today and on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 15″ 2.7GHz... Read more
Apple Ranks 9th In comScore Top 50 U.S. Digit...
comScore, Inc. has released its monthly ranking of U.S. online activity at the top digital media properties for May 2017 based on data from comScore Media Metrix Multi-Platform. * Entity has... Read more
10.5-inch iPad Pros available for up to $20 o...
B&H Photo has the new 2017 10.5″ iPad Pros available for up to $20 off MSRP including free shipping plus NY & NJ sales tax only: - 64GB iPad Pro WiFi: $649 - 256GB iPad Pro WiFi: $749 - 512GB... Read more
Three Off-The-Beaten-Track iOS Apps That Dese...
One of the great things about using iPads and iPhones is the vast selection of apps available for most anything you want or need to do. The three outlined in this article have been in my core app... Read more
Apple No. 1 Spot In Gartner Top 100 Vendors i...
Gartner, Inc. has unveiled the top global 100 vendors in IT in 2016 based on their revenue across IT (excluding communication services) and component market segments. In the Gartner Global Top 100:... Read more
Clearance iMacs available for up to $300 off...
B&H Photo has clearance 21″ and 27″ Apple iMacs available starting at $949, each including free shipping plus NY & NJ sales tax only: - 27″ 3.3GHz iMac 5K: $1999 $300 off original MSRP - 27″... Read more
1.4GHz Mac mini, refurbished, available for $...
The Apple Store has Apple Certified Refurbished 1.4GHz Mac minis available for $419. Apple’s one-year warranty is included, and shipping is free. Their price is $80 off MSRP, and it’s the lowest... Read more
Free Mixoo iOS Photo Editing App Gets Major U...
Button Software Technology has announced Mixoo 3.0, an important feature update to the company’s photo editor for iOS devices. Mixoo offers amazing ways to edit as well as decorate personal photo... Read more
FNable 2.0 Function Key Enabling Software Get...
Briksoftware has released FNable 2.0 With Touch Bar Support, a major new version of the function key enabling software now compatible with Touch Bar keyboards. FNable’s simplicity that allows users... Read more
Clearance 2016 12-inch Retina MacBooks, Apple...
Apple recently dropped prices on Certified Refurbished 2016 12″ Retina MacBooks, with models now available starting at $1019. Apple will include a standard one-year warranty with each MacBook, and... Read more

Jobs Board

Lead *Apple* Solutions Consultant - Apple I...
…integrity, and trust.Success Metrics/Key Performance Indicators:Quantitative* Year over Year growth in Apple Product and Beyond the Box sales in the assigned Point of Read more
*Apple* Solutions Consultant till v%u00E5r...
…ethics, integrity, and trust.Success Metrics/Key Performance Indicators:QuantitativeYear over Year growth in Apple Product and Beyond the Box sales in the assigned Point Read more
Sr. Software Engineer, *Apple* Retail - App...
Apple Retail is looking for a Software Engineer…You'll work on projects that touch all aspects of Apple Retail Point-of-Sale system, and will leverage your strong Read more
*Apple* Solutions Consultant (Asc) - PT - Cu...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include:* Promoting Apple products and solutions Read more
Product Metrics Manager - *Apple* Media Pro...
- Identify blind spots in existing product metrics- Presenting on how Apple Media Products are used and perceived by our customers- Work with data science and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.