Developer’s Guide

Requirements for writing an external
function plug-in
FileMaker Pro plug-ins are most useful when they contain a single
function or a set of functions with similar features. When you design
your plug-in, keep in mind that most database developers who use
your plug-in may not understand programming conventions that you
take for granted — the format of each function’s parameter should
be understandable to the typical user.
Required code files
There are three API code files that you must use without alteration
with your external function plug-ins: FMFlags.h, FMExtern.h, and
FMExtern.c. These files are FileMaker Proprietary API files and
cannot be distributed in source form without written consent from
FileMaker, Inc.
FMFlags.h
The FMFlags.h header file contains compiler directives to control
code compilation. This file allows you to have one set of source code
files that will compile on Windows and Mac OS machines. Do not
alter this file.
FMExtern.h and FMExtern.c
The FMExtern.h is the header file for the FMExtern.c file. Together,
these files define the parameter block (the shared data structure used
by your plug-in and FileMaker Pro) and some shared function calls.
The function calls are used to manipulate the parameter and result
handles in the parameter block.
The FMExtern.h file defines the call-back functions for memory
operations and the different kinds of plug-in events (FileMaker Pro
messages) sent to the plug-in in a FMExternCallSwitch definition.
The FMExtern.c file contains a 68K callback mechanism to handle
Power PC applications. Do not alter these files.
Understanding external function plug-ins 12-7
typedef enum { kFMXT_Init, kFMXT_Idle, kFMXT_Internal1,
kFMXT_External, kFMXT_Shutdown,
kFMXT_DoAppPreferences, kFMXT_Internal2 }
FMExternCallSwitch;
The kFMXT_Internal1 and kFMXT_Internal2 values are reserved
by FileMaker, Inc. For information about the other values, see
“FileMaker Pro messages sent to the plug-in” on page 12-10.
FMExternCallStruct defines the structure of the parameter block.
FMExternCallPtr is a pointer to that structure and gFMExternCallPtr
is a global variable that is defined as an FMExternCallPtr pointer.
Within the FMExternCallStruct definition are three variables of type
long: param2, param3 and result. The param2 variable contains the ID
(0, 1, 2, etc.) for the external function referenced from the Specify
Calculation dialog box in FileMaker Pro.
The param3 variable contains the value of the expression that
replaces the external function’s parameter passed to the plug-in from
the calculation formula in FileMaker Pro. Since external functions
can only return text/string data, the data in the param3 variable and
the data you put into the result variable must be text or a textual
representation of a number.
Note Param3 is a pointer (type long integer) to a text variable.
Required resource files
Two resource files are provided, that define the string resources
required by FileMaker Pro. The resource files are FMExample.rc for
Windows, and FMExample.r for Mac OS. For Windows, the string
resources start at string ID 128 in the resource file. For Mac OS,
they’re in a STR# resource with ID 128 in the resource file.
These four string resources are required for a FileMaker Pro plug-in:
• The first string (ID 128) is the plug-in’s name as it appears in the
FileMaker Pro Application Preferences dialog box.