Developer’s Guide

Manuals Brands Claris FileMaker Manuals Applications FileMaker Developer 5.5

Table Of Contents

FileMaker, Inc.

5201 Patrick Henry Drive

Santa Clara, California 95054

www.filemaker.com

FileMaker and ScriptMaker are trademarks of FileMaker, Inc., registered in the U.S. and other countries, and the file folder logo is a

trademark of FileMaker, Inc. All other trademarks are the property of their respective owners. Portions of some screen shots are

of Netscape.

the work of the Independent JPEG group.

All persons and companies listed in the examples are purely fictitious and any resemblance to existing persons and companies is

purely coincidental.

Mention of third party companies and products is for informational purposes only and does not constitute an endorsement. FileMaker

assumes no responsibility with regard to the selection, performance, or use of these products. All understandings, agreements or

warranties, if any, take place directly between the vendor and prospective users.

FileMaker

Developer

5.5

Developer’s Guide

For Windows and Mac

Summary of content (204 pages)

PAGE 1

For Windows and Mac FileMaker Developer 5.5 ® Developer’s Guide © 1998, 2000-2001 FileMaker, Inc. All Rights Reserved. FileMaker, Inc. 5201 Patrick Henry Drive Santa Clara, California 95054 www.filemaker.com FileMaker and ScriptMaker are trademarks of FileMaker, Inc., registered in the U.S. and other countries, and the file folder logo is a trademark of FileMaker, Inc. All other trademarks are the property of their respective owners.
PAGE 2
PAGE 3

Contents Preface Introducing FileMaker Developer 5.5 Ways to use FileMaker Developer 5.5 Create a custom database solution Customize FileMaker database solutions Create custom web sites Take advantage of FileMaker support for open standards Expand your FileMaker Pro calculations and scripts Provide layout themes for your solutions Use design tools and templates for UI design Using FileMaker Developer 5.
PAGE 4

iv Developer’s Guide Using scripts to control your solution Creating startup scripts Centering a database window in the Kiosk screen Emulating menu commands and window controls Creating dynamic buttons Protecting your database solution files Providing user documentation Creating an About layout Creating a custom Help layout or file Providing What’s This? Help (Windows) Including printed documentation Design tips for cross-platform solutions Creating a consistent appearance Simulating outline and shadow te
PAGE 5

Contents Saving your settings in the Developer Tool Using the Solution Options text file Saving a set of options Modifying the Solution Options text file 4-14 4-14 4-14 4-14 Chapter 5 Distributing FileMaker Pro runtime database solutions Organizing your runtime database solution components Generated DLL files for Windows runtime database solutions System files for Windows solutions Solution Extras files for Mac OS solutions FileMaker Extensions files for Mac OS solutions Including a license agreement Cho
PAGE 6

vi Developer’s Guide Chapter 7 Using FileMaker Pro XML to deliver your data Chapter 8 Custom web publishing using CDML About the XML examples 7-1 General process for custom web publishing using XML 7-2 Generating an XML document 7-2 About XML namespaces 7-3 About FileMaker Pro database error codes 7-3 Using the FMPDSORESULT grammar 7-3 Description of elements in the FMPDSORESULT grammar 7-3 Example of XML data in the FMPDSORESULT grammar 7-4 Using the FileMaker Pro Extended XML grammars 7-4 Description
PAGE 7

Contents Specifying driver properties in the URL subname 9-3 SQL supported by the FileMaker JDBC Driver 9-4 Using DbOpen and DbClose pseudo procedures 9-5 Using the RecordID pseudo column 9-6 Using the ModID pseudo column 9-6 SQL statement examples 9-7 Using a character escape 9-7 FileMaker data type mapping to JDBC SQL and Java data types 9-7 FileMaker Pro support for Unicode characters 9-7 About the FileMaker JDBC Driver interfaces and extensions 9-8 Example 1: Looking at the FileMaker Pro Explorer appli
PAGE 8

viii Developer’s Guide Steps for registering your external function plug-in Revising a registered plug-in 10-13 10-14 Appendix A Feature comparison of the runtime application and FileMaker Pro Application and document preferences Toolbar comparison Menu command comparison Ignored script steps Stored registry settings A-1 A-2 A-3 A-5 A-6 Appendix B Valid names used in CGI requests for FileMaker Pro XML data Generating a –find, –findall, or –findany request Examples of –find, –findall, and –findany requ
PAGE 9

Preface Introducing FileMaker Developer 5.5 Welcome to FileMaker® Developer 5.5! The FileMaker Developer 5.5 product provides the software, APIs, and tools to create custom FileMaker Pro database solutions for work groups, web sites, or stand-alone runtime applications. Ways to use FileMaker Developer 5.
PAGE 10

x Developer’s Guide Provide layout themes for your solutions Use custom FileMaker layout themes to create a consistent look for new layouts in your database solutions. Use design tools and templates for UI design Use the sample buttons, interface elements, and database examples provided by FileMaker Developer 5.5 as you develop the user interface to your custom database solutions. FileMaker Pro 5.5 Unlimited includes all of the features of FileMaker Pro 5.
PAGE 11

Preface 1 Chapter 9 describes how to use the FileMaker JDBC Driver to create FileMaker Pro database-aware Java applications and applets. It also includes a section on the proprietary FileMaker Java Class Library from the previous Developer Edition. 1 Chapter 10 provides guidelines for writing FileMaker Pro external function plug-ins to use in FileMaker Pro field calculations and scripts. 1 See Appendix A for a comparison of the features in the runtime application and in FileMaker Developer.
PAGE 12
PAGE 13

Chapter 1 Installing FileMaker Developer 5.5 FileMaker Developer 5.5 enables you to create custom database solutions and distribute your solutions as standalone, executable applications, or host your solutions on a web server. To help you create your custom solution, the FileMaker Developer 5.5 CD includes design tools, sample databases, and examples for using XML, CDML, Java, and JDBC to deliver your data, and external APIs to extend your solution functionality through plug-ins.
PAGE 14

1-2 Developer’s Guide System requirements for FileMaker Developer 5.5 For Windows 1 an Intel-compatible computer with a 486/33 processor 1 a hard disk 1 at least 32 MB of RAM 1 a CD or DVD drive 1 Windows 95, Windows 98, Windows Me, Windows NT 4.0 Networking requirements We recommend using the TCP/IP protocol for networking the FileMaker Developer application on both Windows and Mac OS networks. You must use the TCP/IP protocol to share files on a mixed Windows and Mac OS network.
PAGE 15

Installing FileMaker Developer 5.5 Requirements for advanced features (Windows) Some of the advanced features of FileMaker Pro require additional software. 1-3 Requirements for advanced features (Mac OS) FileMaker Pro advanced feature Minimum software requirement URL support Either Internet Config 1.1 or, for Mac OS 8.5 or later, the Internet Control Panel Perform AppleScript script step AppleScript system software URL.
PAGE 16

1-4 Developer’s Guide Installing FileMaker Developer 5.5 in Windows You must use the installation program to install FileMaker Developer—you can’t install FileMaker Developer by dragging files to your hard disk. For late-breaking information about FileMaker Developer, browse the contents of the CD and view the Readme file or visit www.filemaker.com. To install FileMaker Developer on Windows systems: 1. Insert the FileMaker Developer 5.5 CD into your CD or DVD drive. 2.
PAGE 17

Installing FileMaker Developer 5.5 1-5 6. Click Next. 7. In the Destination Folder panel, choose the folder where you want to install FileMaker Developer 5.5. By default, FileMaker Developer 5.5 will be installed in the C:\Program Files\FileMaker\FileMaker Developer 5.5 folder. If you want to install FileMaker Developer in another folder or on another drive, click the Change button and navigate to the folder where you want to install FileMaker Developer 5.5.
PAGE 18

1-6 Developer’s Guide The default protocol is TCP/IP. You can change the network protocol later without reinstalling the program. If you are not certain which protocol to use, see your network administrator. Note The option “This feature will be installed when required” means that the necessary files are copied to your hard drive, but are not installed until needed. 12. When you have selected the custom installation options for all the features you want to install, click Next. 13.
PAGE 19

Installing FileMaker Developer 5.5 17. Click Next. 1-7 21. When the installation is complete, click Finish. 18. In the Installation Code panel, type the 17-digit installation code that came with the product. Important You must enter the installation code or the software will not install. See “Installation code” on page 1-1 for more information.
PAGE 20

1-8 Developer’s Guide 1 Select Repair to restore missing or corrupted files, shortcuts, or registry entries. 5. Click Next to continue. You may be prompted to enter your installation code. Adjusting the FileMaker Pro cache See chapter 2 of the FileMaker Pro 5.5 Getting Started Guide for details. Adjusting the network software 5. Click Next. 6. In the Remove the Program panel, click Remove.
PAGE 21

Installing FileMaker Developer 5.5 1 If you want to install all the available files, continue with “Easy installation.” 1 If you want to install a subset of the FileMaker Developer files, skip to “Custom installation” on page 1-10. Easy installation Follow these steps to install the complete FileMaker Developer package on your hard disk. 1. If you have not done so already, start the Installer. You see the FileMaker Developer 5.5 Installer dialog box.
PAGE 22

1-10 Developer’s Guide Check your typing carefully. After you click OK, you can’t change the name, company, or installation code unless you reinstall FileMaker Developer. 7. Click OK. The Installer begins copying files. After all the files are installed, a dialog box shows your registration options. After you choose an option, you are given the option to create an alias to FileMaker Developer on the desktop and, if you haven’t registered, to create an alias for registration.
PAGE 23

Installing FileMaker Developer 5.5 1-11 The installation code is a seventeen-digit number located on a multipart sticker on a separate paper sheet within the box. FileMaker Pro 5.5 and Mac OS X Important You must enter the installation code or the software will not install. See “Installation code” on page 1-1 for more information. For information about FileMaker Pro 5.5 in Mac OS X, see the FMP 5.5 and Mac OSX.PDF file in the Electronic Documentation folder on the CD. Check your typing carefully.
PAGE 24

1-12 Developer’s Guide Read Me file Developer Extras Folder Contents Description In the FileMaker Developer 5.5 folder, the Read Me file is a text document that contains last-minute information about FileMaker Developer 5.5.
PAGE 25

Installing FileMaker Developer 5.5 1 You must distribute a license agreement with your bundled solution. A sample license agreement is included in the Developer Extras folder on the FileMaker Developer 5.5 CD: FileMaker Developer 5.5\Developer Extras\FileMaker, Inc\Examples\ Runtime Solution\Sample Solutions License.txt 1 You must provide an “About” layout that includes your name, address, and the telephone number for your technical support.
PAGE 26
PAGE 27

Chapter 2 Creating a database solution You use FileMaker Pro to design and build your database solution, and FileMaker Developer Tool to bind the Kiosk-mode or customized stand-alone runtime application. Before you begin to build your database solution, you need to decide how users will interact with it.
PAGE 28

2-2 Developer’s Guide Note FileMaker Developer 5.5 includes Database Design Report and Debug Script menu commands to assist you in designing your database solution. With the Database Design Report feature, you can create schema reports of all your databases, in either a FileMaker Pro database format or in an XML format. With the Debug Script feature, you can easily set and clear break points, single-step through your scripts, and run subscripts.
PAGE 29

Creating a database solution In the runtime application, several FileMaker Pro menu options are not available to the user, including File menu > Open and File menu > Close. If you want users to open and close auxiliary files, you must provide scripts in your solution to perform these operations. Then, place a button or startup script in each auxiliary file that returns to the main layout of the primary file. The \Developer Extras\FileMaker, Inc\Examples\Creating Dynamic Buttons\ folder on the FileMaker Dev
PAGE 30

2-4 Developer’s Guide To decide how users will navigate your Kiosk database solution, start by planning your navigation design on paper. Decide what will happen when each button is clicked, and give users a way to get back to the beginning of your system from each layout. To further control what users see, create startup scripts that display a specific layout when a file is opened. 1 If your Kiosk solution will be run with a touch screen, use large buttons and allow space between buttons.
PAGE 31

Creating a database solution 2-5 To create a startup script: 1. In FileMaker Pro, open the file that will contain the script, such as the primary file. 2. Choose Scripts menu > ScriptMaker and create a script to perform the desired actions. 3. Choose Edit menu > Preferences > Document. 4. In the When opening “document.fp5” area, select Perform script and choose the script you created from the pop-up menu.
PAGE 32

2-6 Developer’s Guide Centering a database window in the Kiosk screen To center your databases in the middle of a Kiosk screen, create a startup script that uses the Toggle Window and Set Zoom Level script steps. When a file is opened in Kiosk mode, two things will happen: 1 The database window snaps to fit layout objects at the right and bottom edges of the layout. 1 If the window is smaller than the available screen area, it is centered in the middle of the screen.
PAGE 33

Creating a database solution Protecting your database solution files If passwords have not been defined, your solution files can be opened in FileMaker Pro, and users can access and modify scripts, field and relationship definitions, access privileges, and layouts. You may want to set a master password that gives you access to the entire file and another password that gives users limited access. To create a master password and a limited password for users: 1.
PAGE 34

2-8 Developer’s Guide You can permanently remove access to the Access Privileges menu command after you’ve defined the passwords, as well as access to other menu commands, by selecting the Permanently prevent modification of database structure option in the Developer Tool. See “Removing design access to your databases” on page 4-10 for information.
PAGE 35

Creating a database solution To create an About layout: 1. Create a blank layout in the primary file of your database solution and include the word “About” in the layout name. (In FileMaker Pro, choose View menu > Layout Mode, choose Layouts menu > New Layout/Report, type About in the Layout Name box, select Blank Layout and then click Finish to create the layout.) Note For runtime database solutions, you must include the word “About” in the layout name.
PAGE 36

2-10 Developer’s Guide The Kiosk Solution Example contains a single Help layout The Runtime Solution Example contains a separate Help file, available by clicking a Help button or choosing Posters Help from the Help menu In addition to an online Help system, you should include printed documentation that explains how to install your database solution and briefly how to use it in case users are not able to open your solution files.
PAGE 37

Creating a database solution 2-11 1 Recommend that users back up their data regularly. You might want to automate some of the process by including scripts that save copies of the solution files. For more information on automating a backup procedure, see the FileMaker Pro Help. Select an option in the dialog box and press Shift+F1 to display What’s this? Help for that option See chapter 5, “Distributing FileMaker Pro runtime database solutions” for more information.
PAGE 38

2-12 Developer’s Guide When you move a file from one platform to another, if the font used to create the file isn’t available, another font will be substituted. In FileMaker Pro for Windows, you can specify how fonts are substituted in the Microsoft Windows Registry Editor. You can add more fonts to the Registry Editor to include more font substitutions. If there is no match and no substitute is defined, FileMaker Pro changes the font to Arial.
PAGE 39

Creating a database solution 1 Avoid mixing text and fields because character spacing may vary. If necessary, use merge fields—for example, to place a field in the middle of a sentence. Mac OS-only characters: 1 1 1 1 ≠ (not equal) ≥ (greater than or equal to) ≤ (less than or equal to) Using a common color palette √ (square root/check mark) When 256 or more colors are available, FileMaker Pro will offer an 88-color palette that is virtually identical across platforms.
PAGE 40

2-14 Developer’s Guide Graphics with gradients that are imported and stored as bitmaps will redraw faster on the screen than graphics imported and stored as PICT images. Additionally, PICT images containing gradients may have some quality degradation when displayed on Windows machines. If your layouts are designed to take up most of the available screen space, users can deselect this option in FileMaker Pro or in your runtime application to make more room.
PAGE 41

Creating a database solution 4. In Layout mode, choose Layouts menu > Layout Setup, select Fixed Page Margins, and specify margins for Top, Bottom, Left, and Right. Using the Status (CurrentPlatform) function 1 1 2-15 Perform AppleScript Speak FileMaker Pro includes a status function that lets you determine the platform on which the database solution is being run. This allows you to perform different script actions such as changing to a different layout or performing a platform-specific script step.
PAGE 42

2-16 Developer’s Guide 1 Solution Name 1 Your company information: company name, address, city, state, postal code, country, and phone number 1 Your support policy (for example, how and when you are available for technical support) 5. If your databases contain passwords, and you do not want FileMaker, Inc.
PAGE 43

Creating a database solution 2-17 Important You should keep an unbound version of any runtime database solution files, especially if you’ve permanently removed design access. (See “Removing design access to your databases” on page 4-10.) Note There may be a conflict with the icons for the runtime application and database files if your users have an earlier version of your runtime solution on their machines. (Your users will see the old FileMaker 4.0 Developer Edition icons.
PAGE 44

2-18 Developer’s Guide It’s a good idea to use sample data to make sure the records are importing properly and data is going to the correct fields. Test the data on another machine to make sure the external scripts work. 8. Distribute the new solution files that contain the Import scripts. 9. Provide instructions telling users how to import data into the new solution files and set appropriate time expectations. If their solution files are large, the conversion and import process may be lengthy.
PAGE 45

Chapter 3 Creating custom layout themes FileMaker Pro 5.5 uses a variety of layout themes to describe the colors, patterns, fonts, and borders of text, fields, and parts in a new layout. New themes for FileMaker Pro 5.5 include High Contrast, Aqua, and Windows standard. A FileMaker Pro theme is defined in an Extensible Markup Language (XML) document that can be read and edited in text editors (such as Wordpad for Windows or BBEdit for Mac OS) or XML editors (such as XML SPY or XML Pad).
PAGE 46

3-2 Developer’s Guide To modify a theme: 1. Make a duplicate copy of the theme file (for example, Blue_gold.fth) in the Themes folder. FileMaker Developer 5.5\Themes\ or Note If your THEMENAME value contains any upper-ASCII characters, use the HINT attribute to ensure that the theme name will appear on both the Windows and Mac OS platforms. See “Valid values for theme attributes” on page 3-7 for information. 5. Change the values of other elements and attributes as desired. 2.
PAGE 47

Creating custom layout themes 3-3 Minimum required XML elements for themes Every theme file must begin with an XML-document processing instruction that declares it as an XML document using the XML 1.0 specification. In addition, an XML document for a FileMaker Pro layout theme must contain the and start and end tags for the file. This FMTHEMES root element can contain one or more FMTHEME element.
PAGE 48

3-4 Developer’s Guide XML editors expect these characters to be coded as character entities: A single-line element, such as the PEN element, begins with on a single line, and looks like this: Character Coded as ampersand (&) & A multi-line element has start and end tags that look like this: less than (<) < greater than (>) > apostrophe (‘) ' quote (“) " Using the character instead of
PAGE 49

Creating custom layout themes This multi-lined element is used To describe this layout part Leading grand summary — appears at the beginning of a report and displays a summary field for all the records in a found set.
PAGE 50

3-6 Developer’s Guide These multi-line elements May contain these elements These multi-line elements May contain these elements FMTHEME VERSION BASELINE ONOFF (required) THEMENAME (required) (underlining field data) PEN THEMEDEFAULT BORDER PEN Any or all layout part elements (field border) SIDES TITLEHEADERPART FILL HEADERPART FIELD LEADGRANDSUMPART TEXT BODYPART TEXTLABEL BORDER and EFFECT elements share the same pen size—when used together, the pen size value that you set for BOR
PAGE 51

Creating custom layout themes These single-line elements Must contain these attributes ONOFF PARTNUMBER PEN COLOR PATTERN Valid values for theme attributes The following table describes the attribute values supported by FileMaker Pro in a layout theme. Values must be enclosed within quotation marks (“ ”) —if a quotation mark is missing, FileMaker Pro is unable to parse the XML and cannot display the theme in the New Layout/Report assistant.
PAGE 52

3-8 Developer’s Guide This attribute FONT Is used to describe these characteristics And may contain these values The name of the font. More than one font name can be specified, separated by commas. The first font available on a user’s computer will be used in the layout.
PAGE 53

Creating custom layout themes This attribute SIZE (for the PEN element) Is used to describe these characteristics And may contain these values Thickness in pixels for the outline of text blocks, field labels, and field borders. SIZE = “0” SIZE = “-1” SIZE = “1” through The value for NONE is “0” SIZE = “8” and the value for HAIRLINE SIZE = “12” is “-1.
PAGE 54

3-10 Developer’s Guide 1 2 3 4 5 6 7 8 Select a color Then choose Other Color 2. Select the HTML Picker icon on the left side of the dialog box and read the hex value for the selected color in the HTML box on the right side.
PAGE 55

Creating custom layout themes Checking your theme document for errors FileMaker Pro cannot parse an XML theme document that is not well-formed, and it does not validate the XML in your documents. If one required item is missing or wrong, FileMaker Pro will ignore the entire document. Here is a list of things to check for if your new layout themes don’t appear in the New Layout/Report assistant as expected: 1 1 1 The theme filename has the .fth extension. The theme file is in text format.
PAGE 56
PAGE 57

Chapter 4 Using the FileMaker Developer Tool FileMaker Developer 5.5 provides a utility application called the FileMaker Developer Tool that lets you: 1 bind your database files into a stand-alone runtime database solution that does not require FileMaker Pro in order to be used on a computer 1 rename all of your database files and automatically update the internal links to related files and scripts 1 1 These example solutions are on the FileMaker Developer 5.5 CD in the \Developer Extras\FileMaker, Inc\Ex
PAGE 58

4-2 Developer’s Guide 1. Close all of your database files that you are going to customize. What you select determines which screen the Developer Tool displays next. 2. If necessary, install the FileMaker Developer Tool. Select this option (See chapter 1, “Installing FileMaker Developer 5.5.”) Create a stand-alone Create a runtime database solution that includes a runtime solution FileMaker Pro runtime application and the bound database files.
PAGE 59

Using the FileMaker Developer Tool Select this option To create a copy of your database files and do this Add or remove FileMaker Pro extension Add or remove the .fp5 filename extension to associate files with the FileMaker Pro application. The .fp5 extension is useful for database solutions that will be used on Windows machines, and is not necessary for solutions that will only be used on Mac OS machines. 4-3 Note You do not have to type in a filename extension. However, if you want the .
PAGE 60

4-4 Developer’s Guide The primary file stores the custom settings and is the database that users should open first. If you’re binding your files into a runtime database solution, the runtime application will open the primary file first. Use this file for navigation buttons or scripts to other auxiliary files, an About layout, a custom Help layout or file, and to quit the application. 11. If desired, select Use custom About script, and choose the script name from the pop-up menu.
PAGE 61

Using the FileMaker Developer Tool 4-5 Select Filename Extension screen on Windows machines 21. On the Specify Location for Solution Folder screen, click Browse (Windows) or Select (Mac OS) to specify the location for the runtime database solution. The name of the new solution folder is determined by either the name of the primary file or the name of the runtime solution. 22. Select the location and click OK (Windows) or click Choose (Mac OS). 23. Click Finish.
PAGE 62

4-6 Developer’s Guide If an error occurs during the binding, a message displays and the error is logged in the Error Log.txt file: Folder Platform FileMaker Developer 5.5\Developer Tool Windows FileMaker Developer 5.5\FileMaker Developer Tool Mac OS FileMaker Developer 5.5\FileMaker Developer Tool Mac OS X Binding your databases into a runtime database solution Use the FileMaker Developer Tool to bind your database files into a stand-alone runtime database solution that users can access without ru
PAGE 63

Using the FileMaker Developer Tool 4. Specify the database files that you want to bind, rename them if desired, and click Next to go to the next screen in the runtime binding process. 5. Select a primary file. All of the settings for binding are stored in the primary file. The primary file opens automatically when a user double-clicks the runtime application. 6.
PAGE 64

4-8 Developer’s Guide Assigning a three-character filename extension The three-character filename extension associates all of the solution files with the FileMaker Pro runtime application. If a user has more than one runtime database solution on a machine, the filename extension together with the binding key will ensure that the correct runtime application is started when a solution file is double-clicked.
PAGE 65

Using the FileMaker Developer Tool Note No matter what the filename extensions are, runtime database files can still be opened in the FileMaker Pro application. To prevent users from modifying your runtime database solutions, create passwords for specific access privileges or select the Permanently prevent modification of database structure option in the Developer Tool before you bind the files into a runtime database solution.
PAGE 66

4-10 Developer’s Guide 5. Specify the database files that you want to customize, rename them if desired, and click Next. 6. Select a primary file, select other options as desired, and click Next to go through the rest of the screens depending on what other options you selected. 7. Specify the location for the solution files, rename the folder if 7. Specify the location for the files, rename the new solution folder if desired, and click Finish.
PAGE 67

Using the FileMaker Developer Tool 1 1 1 View menu > Layout Mode Scripts menu > ScriptMaker File menu > Access Privileges Important Selecting this option permanently removes access to these menu commands for all database files in the solution, whether they’re opened in a runtime application or in FileMaker Pro. This will help protect your files from password hackers. Structural elements of the files cannot be modified by anyone, including FileMaker, Inc. employees.
PAGE 68

4-12 Developer’s Guide In runtime applications, the custom About menu command replaces the About FileMaker Pro menu command. If you don’t specify an About script when you bind your files into a runtime database solution, an About FileMaker Pro Runtime menu command is added to the Help menu (Windows) or Apple (4) menu (Mac OS) of the runtime application. When users choose this menu command, the FileMaker Pro 5.5 Runtime dialog box appears.
PAGE 69

Using the FileMaker Developer Tool 4-13 Renaming the Scripts menu Custom Help command in a runtime application (Windows) Use the Developer Tool to rename the Scripts menu for your database solution. The setting is stored in the primary file of your solution and the new menu name appears in the menu bar in FileMaker Pro and in a runtime application.
PAGE 70

4-14 Developer’s Guide Adding the FileMaker Pro extension to database filenames To use the Solution Options file: 1. Drag the Solution Options text file onto the Developer Tool application file. Use the FileMaker Developer Tool to quickly add the FileMaker Pro filename extension to your database files. For example, if you created your database files on a Mac OS machine but you now want the database solution to be used on Windows machines, you can add the .
PAGE 71

Using the FileMaker Developer Tool The FileMaker Developer Tool Solutions Options file keeps a record of the solution name and the binding key that you used for that solution 2. Scroll down to the Auto option at the bottom of the list of options. 3. Change the value from 0 to 1. Now, when you drag the text file onto the Developer Tool, the customizing process is performed immediately based on the database files and other settings specified in the text file.
PAGE 72
PAGE 73

Chapter 5 Distributing FileMaker Pro runtime database solutions The final steps in developing your FileMaker Pro runtime database solution are to bundle all of the necessary files together, choose how you will distribute your solution—for example, on a CD-ROM disc, over a network, or on floppy disks—and provide your users with documentation for installing your solution. In addition, your documentation should include instructions for starting the runtime application and what to do if a file is damaged.
PAGE 74

5-2 Developer’s Guide Other solution components that you need to provide include: 1 A license agreement — see “Including a license agreement” on page 5-4. 1 Installation instructions — see “Documenting the installation procedures” on page 5-5. Generated DLL files for Windows runtime database solutions The following table describes the Dynamic Link Libraries (DLLs) that are provided for your runtime database solutions running on Windows machines.
PAGE 75

Distributing FileMaker Pro runtime database solutions System folder and files Description Excel.imp Used to import Excel files Claddon.clr Spelling dictionary that contains computer terminology Ukenglsh.mpr Primary British English dictionary of over 100,000 words that the runtime application uses to check the spelling Usenglsh.mpr User.
PAGE 76

5-4 Developer’s Guide FileMaker Extensions folder and files Description User.upr Spelling dictionary that stores your customized list of spelling exceptions and additions to the User dictionary Usenglsh.mpr Primary US English dictionary of over 100,000 words that the runtime application uses to check the spelling Choosing the distribution method After you have organized the files that comprise your solution, you need to decide how your users will install them.
PAGE 77

Distributing FileMaker Pro runtime database solutions Using a compression utility program If your runtime database solution is small, you might consider a compression utility application rather than a custom installation application. To compress files, use a utility such as: 1 WinZip for Windows (Windows 95, Windows 98, Windows NT, Windows 2000, Windows ME) by WinZip Computing, Inc. (www.winzip.
PAGE 78

5-6 Developer’s Guide 1 Include information about the minimum equipment and software requirements. For suggestions on other information to include with your runtime database solution, see “Including printed documentation” on page 2-11. Starting your runtime database solution The first time users double-click the runtime application icon, the runtime application will auto-register and move appropriate items into the System folder on their machines.
PAGE 79

Distributing FileMaker Pro runtime database solutions 5-7 Distributing updates to your runtime database solution Recovering a runtime database solution file During the recovery process, the FileMaker Pro runtime application: 1 creates a new file 1 renames any damaged file by adding Old to the end of the filenames (for example, Contact Manager is renamed to Contact Manager Old).
PAGE 80

5-8 Developer’s Guide 2. If necessary, create an Import script so users can import their existing data into the new file. (See “Importing data into an upgraded runtime database solution” on page 2-17 for information.) 3. Use the Developer Tool to rebind all of the files in the runtime database solution and include the new or updated auxiliary file. (See “Procedure for binding files” on page 4-6 for information.) Use the same binding key that you used for the primary file.
PAGE 81

Chapter 6 Publishing your database on the Web The FileMaker Pro Web Companion plug-in makes it possible for you to publish your database on the Internet or an intranet in several different ways, giving you more choices and control over the design and functionality of your web pages.
PAGE 82

6-2 Developer’s Guide For a list of JDBC resources, see the product support pages on the FileMaker, Inc. web site at www.filemaker.com. Custom web publishing with CDML The FileMaker Pro Web Companion lets you publish your database with custom web pages using a proprietary markup language called CDML. Included with FileMaker Developer 5.5 are all the tools, templates, and examples you need to create your own custom web pages using CDML. For information, see chapter 8, “Custom web publishing using CDML.
PAGE 83

Publishing your database on the Web In addition, your site folders and web pages must be located inside the Web folder (inside the FileMaker Developer 5.5 application folder) in order for the Web Companion to serve them on the Web. However, your databases do not have to be inside the Web folder. They only need to be open in FileMaker Pro and shared via the Web Companion. For security purposes, it’s a good idea not to have your databases or other sensitive documents in the Web folder. 3.
PAGE 84

6-4 Developer’s Guide 2. In the Web Companion Configuration dialog box, choose an HTML file from the Home Page list so the Web Companion will automatically display it when web users enter the IP address. The [Built-in] option displays the “FileMaker Pro Instant Web Publishing” home page by default. All other HTML files that are located in the root level of the Web folder appear in this list. See “Creating a custom home page” on page 6-5 for more information. 3.
PAGE 85

Publishing your database on the Web 6-5 Sharing the database via the Web Each database that you’re publishing on the Web must be open and shared via the Web Companion. To share a database on the Web: 1. In FileMaker Pro, choose File menu > Open and open the database. 2. Choose File menu > Sharing. 3. Select the Web Companion checkbox. For Instant Web Publishing, choose a web style and layouts for each view (instant web page) 5. Click Done to close the Web Companion View Setup dialog box. 6.
PAGE 86

6-6 Developer’s Guide If you’re hosting multiple sites each with its own home page, you can have each home page named “default.htm” or “index.htm” inside each site folder within the Web folder, and the Web Companion will display them when web users enter the name of the site folder after the IP address. http://17.17.17.17/guest_book If you want, create a link to the IP address of the site folder— otherwise, let users know so they can type it in their web browsers.
PAGE 87

Publishing your database on the Web About the FileMaker WebPortal object With the enhanced Web Companion in FileMaker Pro 5.5, you can now access the elements of the Instant Web Publishing home page (such as database names or the URL to access a Form View of a database) as separate JavaScript objects and extract data from them to build your own custom home page.
PAGE 88

6-8 Developer’s Guide First, you create a startup script to hide the Instant Web Publishing interface. Then you create buttons in the layouts to navigate the web site and perform database functions. To bypass the Instant Web Publishing home page, you use a custom home page that contains a redirect statement for opening the database layout in a particular instant web page.
PAGE 89

Publishing your database on the Web 6-9 Requirements for Instant Web Publishing buttons FileMaker script step CGI request Description A button that you’re using in a layout for Instant Web Publishing may have a single valid script step attached to it or a script containing 1 to 3 valid script steps. Go to Layout [] Go to specified layout This will not affect other current parameters for location.
PAGE 90

6-10 Developer’s Guide FileMaker script step CGI request Description FileMaker script step CGI request Go to Field [ ] Go to Edit Record view Displays the specified field in the Edit Record page (without a blinking insertion point).
PAGE 91

Publishing your database on the Web 6-11 Enter Browse Mode New Record Show All Records Exit Record Perform Find If the first script step in the script is not one of these supported script steps, then it is handled as a single script step. If it is not supported for Instant Web Publishing, then the script is not generated for the button. If a script contains both supported and unsupported steps, then parsing of the script will cease as soon as the first unsupported step is encountered.
PAGE 92

6-12 Developer’s Guide 2. In the Script Definition dialog box, click Clear All, and select Toggle Status Area. Choose Hide from the Specify pop-up menu to add the parameter to the script step. Then click OK. 3. Click Done to close the Define Scripts dialog box. For example, the following redirect statement contains a FileMaker CGI request for layout ID number 3 in the “MyCustomUI.fp5” database to open in the Form View instant web page (formvwcss.htm). 4. Choose Edit > Preferences > Document. 5.
PAGE 93

Publishing your database on the Web Format filenames for instant web pages The following table lists the instant web pages and their format filenames as they apply to those web styles that use cascading style sheets. Instant web page Format filename Form View FormVwCSS.htm Table View TableVwCSS.htm Search SearchCSS.htm New Record NewCSS.htm Edit Record EditCSS.htm Delete Record DeleteCSS.htm Sort SortCSS.htm Error Err.
PAGE 94

6-14 Developer’s Guide Where Means this status The HTTP status code returned to the client (for information, see the World Wide Web Consortium’s web site at www.w3c.org) bytes The content length of the document transferred to the client Using the error.log file The Web Companion records any unusual erros in the error.log file in the FileMaker Developer 5.5 folder. Common errors reported to the web user, such as “Database not open,” are not recorded in the error.log file.
PAGE 95

Publishing your database on the Web To use a Web Companion external function in a calculation field: 6-15 1. Be sure the Web Companion is enabled. (See “Enabling the Web A formula for an external function requires the name of the external function to call and the function’s parameter. Companion” on page 6-3 for information.) 7. Replace the word “parameter” with the required parameter for the 2. Choose File menu > Define Fields. function (0, field name, or text value). 3.
PAGE 96

6-16 Developer’s Guide External function’s name and parameter Web-ToHTTP, field name Web-ToHTTP, text value Description of external function Returns the contents of the specified field or text value encoded in HTTP. This is useful for fields containing data that should be handled as URLs in HREF links by the browser. For example, “Display Art” becomes “Display%20Art.” For more information, see chapter 11, “Using formulas and functions,” in the FileMaker Pro User’s Guide or see FileMaker Pro Help.
PAGE 97

Publishing your database on the Web 5. To export one record that subtotals multiple records, click Summarize by. Then, in the Summarize by dialog box, click to the left of the field you want to use as the break field. A check mark appears to the left of the field. (You must have set up one or more summary fields and sorted by the break field in the database.) Click OK.
PAGE 98

6-18 Developer’s Guide Opening password-protected databases remotely Opening and closing databases using XML You can open and close FileMaker Pro databases from your web browser or other client application by making a –dbopen or –dbclose request to FileMaker Pro. FMPro?–db=secretfolder/employees.fp5&–format=–fmp_xml& –password= dbpassword&–dbopen Note You can also open and close FileMaker Pro databases remotely by using the DbOpen and DbClose pseudo procedures with the FileMaker JDBC Driver.
PAGE 99

Chapter 7 Using FileMaker Pro XML to deliver your data With the enhanced Web Companion, FileMaker Pro 5.5 can deliver data from your database to the Web in Extensible Markup Language (XML) format. In the same way that HTML has become the standard display language for communication on the World Wide Web, XML promises to become the standard language for structured data interchange.
PAGE 100

7-2 Developer’s Guide General process for custom web publishing using XML Here’s a simple overview of the process for publishing your FileMaker Pro database on the Internet or an intranet using XML: 1. You send a FileMaker Pro CGI request (such as to find records in the database) to the Web Companion through an HTML form, an HREF link, or a script on your web page. The request can also be made by typing the URL in the web browser.
PAGE 101

Using FileMaker Pro XML to deliver your data Note XML data generated by the Web Companion is encoded using UTF-8 format (Unicode Transformation Format 8). For information, see “About UTF-8 encoded data” on page 7-7. 7-3 The Web Companion will also generate the document type definition for the grammar if you specify “–dso_xml_dtd” as the format. This is useful if you want an XML parser to validate the XML before your document goes to production.
PAGE 102

7-4 Developer’s Guide Spaces or single colons in field names are converted to underscores in the element names (for example, ). Double colons in portal fields are converted to periods (for example, ). This is done because colons are reserved in XML for specifying namespaces and spaces are not allowed in XML element names. Barbara Jones
PAGE 103

Using FileMaker Pro XML to deliver your data When you specify “–fmp_xml” as the format for a FileMaker Pro CGI request, the Web Companion will generate XML data using either the FMPXMLRESULT or FMPXMLLAYOUT grammar, depending on the request you specify in the CGI command: 1 The Web Companion will generate the FMPXMLRESULT grammar when you specify –edit, –delete, –find, –new, –dbnames, –layoutnames, –scriptnames or –dbopen as the FileMaker CGI request.
PAGE 104

7-6 Developer’s Guide To qualify the XML elements for the FileMaker Pro application, the names of all elements and attributes in this grammar are associated with the unique XML namespace http://www.filemaker.com/ fmpxmlresult. This namespace is declared in the grammar as the default namespace. Engineering The following is an example of XML data generated with the FMPXMLRESULT grammar.
PAGE 105

Using FileMaker Pro XML to deliver your data Description of elements in the FMPXMLLAYOUT grammar In the generated FMPXMLLAYOUT grammar, the LAYOUT element contains the name of the layout, the name of the database, and FIELD elements for each field found in the corresponding layout in the database. Each FIELD element describes the style type of the field, and contains the VALUELIST attribute for any associated value list of the field.
PAGE 106

7-8 Developer’s Guide The UTF-8 encoding format includes the following features: 1 All ASCII characters are one-byte UTF-8 characters. A legal ASCII string is a legal UTF-8 string. For more information and examples, see appendix B, “Valid names used in CGI requests for FileMaker Pro XML data.
PAGE 107

Using FileMaker Pro XML to deliver your data Use these parameter names To go with these requests –modid (modification I.D.) Optional for –edit –lop (logical operator) Optional for –find –op (operator) Optional for –find –max (maximum records) Optional for –find –skip (skip records) Optional for –find –sortorder (sort order) Optional for –find, –findall –sortfield (sort field) Optional for –find, –findall –script (perform script) Optional for –find, –findall –script.
PAGE 108

7-10 Developer’s Guide Note This is an example of XSLT that was written to work with Internet Explorer 5.0 for Windows, not with other browsers using later versions of XSLT.
PAGE 109

Using FileMaker Pro XML to deliver your data 7-11 Comparing CSS, XSLT, and JavaScript The FileMaker Developer 5.
PAGE 110

7-12 Developer’s Guide 3. In your web browser, type localhost (or your computer’s IP address) followed by /simple examples/ and press Enter. http://localhost/simple examples/ http://17.17.17.17/simple examples/ For information on setting up your computer as the localhost, see “Testing your site without a network connection” on page 6-17. The seven fields in the People.fp5 database used for these examples These three examples were designed to be viewed in the Internet Explorer 5.
PAGE 111

Using FileMaker Pro XML to deliver your data A cascading style sheet can only be applied to the existing data in an XML document—it cannot be used to transform the data (such as transforming a URL for a container field into its corresponding image), or to add additional information (such as labels for each field) to the XML document. This example demonstrates the use of a CSS document with an XML document. The following CGI command was used to generate the FMPDSORESULT grammar for the People.
PAGE 112

7-14 Developer’s Guide * The following styles are applied to the actual field data. */ Name { position: absolute; left: 180px; top: 20px; } Title { position: absolute; left: 180px; top: 40px; } Phone { position: absolute; left: 180px; top: 60px; } Extensible Stylesheet Language–Transformations (XSLT) example Extensible Stylesheet Language–Transformations (XSLT) is a language for transforming XML documents into other XML documents.
PAGE 113

Using FileMaker Pro XML to deliver your data PAGE 114
7-16 Developer’s Guide Note The FMP.js JavaScript library was created for the XML Inventory example, described next, which is a more complex and sophisticated example of the use of JavaScript and the W3C Document Object Model with your XML documents. function nextRecord( ) Once the people_form.htm page is loaded in the browser, the onLoad event handler performs the “initialize” function, creating an ActiveXObject and building the FMPFindRequest: } { if (foundSet.
PAGE 115

Using FileMaker Pro XML to deliver your data This example was designed to be viewed in the Internet Explorer 5.0 for Windows web browser. For information on new browsers that can be used to view the example, go to the FileMaker product support pages (www.filemaker.com/support/fm_help.html) in your browser. The example uses an inventory database for office equipment and provides two methods for displaying records from the database—in a list or in a detailed view of each record.
PAGE 116

7-18 Developer’s Guide It is possible to have both the Detail View and Add Record windows open at the same time. The Detail View and Add Record windows will automatically close when a visitor clicks the Back or Forward button in the browser. Detail View of a selected record in the browser 6. To add a record, click the Add button in the List View window. A separate Add Record window opens. Detail View and Add Record windows open at the same time 8.
PAGE 117

Using FileMaker Pro XML to deliver your data 7-19 A detail view of an empty record opens in a separate window with a blinking insertion point in the Item field. When web users click inside the Item, Cost, Date Purchased, Serial Number, or Notes text boxes, a help string appears in the status bar at the bottom of the window. The default operator for a search is “begins with” or web users can type one of the <, <=, >, >=, or = operator symbols in these boxes.
PAGE 118

7-20 Developer’s Guide The scripts and functions are well commented in the source and in the FMP.js library, providing information about each step. It’s useful to arrange the windows so you can switch between the example pages in the browser, the source, and the script library. FMP.js text file containing the JavaScript library for this example 2. In the browser window, choose View menu > Source to see the source markup for the example pages in the Notepad application.
PAGE 119

Chapter 8 Custom web publishing using CDML The FileMaker Pro Web Companion supports CDML, a proprietary markup language that enables your HTML pages to interact with a FileMaker Pro database. The FileMaker Developer 5.5 CD includes: 1 the CDML Tool database and template files to help you insert the CDML tags into your HTML pages (These HTML pages that contain CDML tags are referred to as format files.
PAGE 120

8-2 Developer’s Guide For additional information and examples using CDML to publish FileMaker Pro databases on the Web, see the product support pages on the FileMaker, Inc. web site at www.filemaker.com. 6. In the Web Companion Configuration dialog box, deselect Enable General steps for custom web publishing using CDML See “Setting Web Companion configuration options” on page 6-3 for information.
PAGE 121

Custom web publishing using CDML < INPUT TYPE=“hidden” NAME=“-db” VALUE=“Filename.fp5”> < INPUT TYPE=“hidden” NAME=“-lay” VALUE=“Layout Name”> < INPUT TYPE=“hidden” NAME=“-format” VALUE=“Filename.htm”> 8-3 When a format file is displayed statically in the browser rather than as the result of a FileMaker Pro CGI request, CDML replacement tags will appear on the page. < INPUT TYPE=“hidden” NAME=“-error” VALUE=“Filename.
PAGE 122

8-4 Developer’s Guide For example, to generate a –findall request to display all employees from a database, web users might click on an HREF link containing the following FileMaker Pro CGI command: FMPro?–db=Employees.fp5&–lay=FormView&–format=results.
PAGE 123

Custom web publishing using CDML The following is an example of an –edit request for editing records in a portal, where “Address::” is the name of the relationship, “City.1” is the first row in the portal, and “City.2” is the second row in the portal: FMPro?–db=Employees.fp5&–lay=LayoutOne&recid=11& FirstName=Sam&LastName=Smith&Address::City.1=Seattle &Address::City.2=New York&–format=reply.
PAGE 124

8-6 Developer’s Guide 4. Arrange the windows so you can easily go between the blank page and the CDML Tool. 5. In the CDML Tool, select either the Templates tab or the Tags tab and click the Refresh button. Then choose your database from the Database pop-up menu, and the layout that you want to use from the Layouts pop-up menu. The layout you choose determines which fields will be accessed. Otherwise, it does not affect the layout of the web page. Using the Templates tab 1.
PAGE 125

Custom web publishing using CDML 8-7 You can also click the Tag Description arrow to expand the window and view a description of the tag in another box below. 5. Click the Copy to clipboard button. 6. Paste the tag into your format file. Customizing a format file template The CDML Tool provides nine format file templates for the basic type of actions that web users can perform with your database. These templates are also included in the CDML Templates folder on the FileMaker Developer 5.5 CD.
PAGE 126

8-8 Developer’s Guide This template Contains these CDML tags New_reply.htm [FMP-LinkRecID: Layout=Layout Name, Format=pathto-file/Detail.htm] Results.htm [FMP-RangeStart], [FMP-RangeEnd], [FMP-CurrentFoundCount], [FMP-RangeSize], [FMP-LinkPrevious], [/FMP-LinkPrevious] [FMP-Record] [FMP-Field: Field Name1], [FMP-Field: Field Name2] [FMP-LinkRecID: Layout=layout_name, Format=pathto-file/detail.htm] [/FMP-Record] [FMP-LinkNext], [/FMP-LinkNext] Search.
PAGE 127

Custom web publishing using CDML Use tags in this category For this type of interaction with FileMaker Pro Hidden Do not display this INPUT tag (–db, –lay, –db & –lay, –error, –format, or –token) Links Display a format file based on CDML replacement or action tags within HREF, MAILTO, and SRC (image) links Logical Conditionally display data within the [FMP-If] and [FMP-Else] replacement tags Looping Display multiple lines of data within one of these looping types of replacement tags (Current Find,
PAGE 128

8-10 Developer’s Guide New CDML variable tags –errnum (variable) Specify a range or single error number to be handled by the -error variable tag. You can specify discontinuous ranges, such as -errnum=500-510& -errnum=900-978. If no error numbers are specified, all errors are handled by the –error tag. See appendix B “FileMaker Pro values for error codes” for a list of error numbers.
PAGE 129

Custom web publishing using CDML Modified CDML tag Description [FMP-If:.and.] Use these parameters (conditional operators) with the [FMP-If] tag to specify multiple replacement conditions. [FMP-If:.or.] [FMP-If:.xor.] (new parameters) [FMP-Field: FieldName, Format] and [FMPRepeatingItem: FieldName, Format] (new encoding parameter) If desired, use this modified [FMP-If] tag along with the new [FMP-ElseIf] replacement tag.
PAGE 130

8-12 Developer’s Guide To view the CDML Reference database: 1. In FileMaker Pro, open the CDML_Reference.fp5 file located inside the CDML folder. Developer Extras\FileMaker, Inc\External FileMaker APIs\CDML\ 4. Click the home button to return to the FileMaker Pro CDML Reference screen. From the home screen, you can open the CDML Tool by clicking the tool button. 5. Click the Custom Web Publishing tab to view general information about custom web publishing using CDML. 2.
PAGE 131

Custom web publishing using CDML 6. Click an arrow or a subject title in the table of contents to view a list of underlined topic titles. Then click an underlined title to view the topic. 8-13 1 Use the –error variable tag in the request to specify an error page that contains [FMP-If] and [FMP-Else] replacement tags and FileMaker Pro error codes, which determine certain conditions for displaying an error message.
PAGE 132

8-14 Developer’s Guide For a complete list of error code numbers, see appendix C, “FileMaker Pro values for error codes.” For examples of error pages, see the gb_error.htm file in the Guest Book example, the errors.htm file in the Employee Database example, and the reqfielderror.htm file in the Shopping Cart example. (See “Looking at the three CDML examples” on page 8-15 for more information.
PAGE 133

Custom web publishing using CDML 8-15 Three examples are included with FileMaker Developer 5.5 to give you ideas on how to organize a site. You can also use them as templates and modify them for your own sites. Looking at the three CDML examples The FileMaker Developer 5.5 CD includes three CDML examples that demonstrate ways to publish your databases on the Web using CDML. These examples are located in the CDML folder: Developer Extras\FileMaker, Inc\External FileMaker APIs\CDML\ To examine the three CD
PAGE 134

8-16 1 1 1 Developer’s Guide The second example link contains a FileMaker Pro CGI command for a CDML -view request. (The -view CDML action tag is usually used to display format files containing value lists or CDML replacement tags.) browse the database preselect how many records to view at a time add a record to the database example The CDML replacement tags are replaced with the value lists from the database.
PAGE 135

Custom web publishing using CDML 8-17 Once a guest signs in and sends the information, a summary page is returned notifying the guest that the information has been received. The summary page contains [FMP-Field] replacement tags for the first and last name of the guest that was entered in the new record. Web users add records to the empty Guest_Book.
PAGE 136

8-18 Developer’s Guide The default.htm page in the Shopping Cart Example folder Items that are placed in the Shopping Cart are added to the OrderedItems.fp5 database. Information that the web user enters on the customerid.htm page is added to a new record in the Customers.fp5 database. Items that are finally ordered (when the web user proceeds to Checkout and clicks Continue) are added to the Orders.fp5 database.
PAGE 137

Chapter 9 Using Java and JDBC to deliver your data If you’re a Java programmer, you can use the FileMaker JDBC Driver with any Rapid Application Development (RAD) tool to visually create your FileMaker Pro database-aware Java application or applet. The FileMaker Developer 5.5 CD also includes the proprietary FileMaker Java classes and examples of Java applets that use them. For information, see “Using the FileMaker Java classes” on page 9-17.
PAGE 138

9-2 Developer’s Guide DBMS proprietary protocol Java application JDBC driver Client machine FileMaker Pro Note Although the driver implements the entire JDBC 1.2 API, it cannot be classified as a true JDBC-compliant driver because it supports only a subset of SQL that matches the capabilities of FileMaker Pro, and is therefore not fully SQL-92 Entry Level compliant.
PAGE 139

Using Java and JDBC to deliver your data 9-3 { jdbc:fmpro:https://www.filemaker.com:80 System.out.printIn(“Could not load driver”); Here is an example of registering the FileMaker JDBC Driver with the JDBC driver manager and connecting to FileMaker Pro via the Web Companion —where the open FileMaker Pro database is named Employees.fp5 and the JDBC URL is jdbc:fmpro:http://localhost: } catch(SQLException sqlException) { System.out.printIn(“JDBC Error:” + sqlException.getMessage()); import java.sql.
PAGE 140

9-4 Developer’s Guide Property Description SQL statement Definition escape A string containing the characters to be escaped in table name, field name, and layout name SQL identifiers. The driver will escape all identifiers returned via any method in the DatabaseMetaData class. This will allow RAD tools that don't support spaces and periods in SQL identifiers to work with any FileMaker Pro database. The driver will automatically escape all identifiers for you.
PAGE 141

Using Java and JDBC to deliver your data To update a specific repeating field or field in a portal, add a period and the number of the row to the end of the field name and enclose the field name in double quotation marks. For example, to update the third repetition of the Telephone field for a record in the Employees.fp5 database, specify the following: UPDATE “Employees.fp5” SET “Telephone.
PAGE 142

9-6 Developer’s Guide inventoryStatement.executeQuery("select * from \"inventory.fp5\""); // create a statement for closing the "inventory.fp5" // database CallableStatement closeDbStatement = adminConnection.prepareCall("{call dbclose(\"inventory.fp5\")}"); closeDbStatement.execute(); } Using the ModID pseudo column Each record in a FileMaker Pro database has a corresponding modification ID (ModID) number that increases incrementally every time the record is modified.
PAGE 143

Using Java and JDBC to deliver your data SQL statement examples The following are some examples of SQL statements, some of which use RecordID and ModID pseudo columns, and DbOpen and DbClose pseudo procedures: SELECT recordid, modid, "last name", "first name", department FROM "Employees.fp5" WHERE "last name"='smith' AND "first name" = 'joe' SELECT * FROM "Employees.fp5" WHERE recordid=4 SELECT recordid, modid, * FROM "employees.
PAGE 144

9-8 Developer’s Guide About the FileMaker JDBC Driver interfaces and extensions The FileMaker JDBC Driver implements all of the following JDBC interfaces: 1 1 1 1 1 1 1 1 CallableStatement Connection The API documentation for these standard interfaces and the FileMaker extensions is included in HTML format in the FileMaker JDBC folder on the FileMaker Developer 5.5 CD.
PAGE 145

Using Java and JDBC to deliver your data 9-9 To view the example on Mac OS machines, you need: 1 MRJ 2.2 or equivalent Java virtual machine installed on your computer Install the example and the FileMaker JDBC Driver Replace entire text with the JDBC URL for the computer running the database If necessary, install the FileMaker Explorer example and the FileMaker JDBC Driver. Open and share your databases via the Web 1. In FileMaker Pro, open any FileMaker Pro database, such as the Inventory.
PAGE 146

9-10 Developer’s Guide 7. Select the Form View node to display the fields for that layout on the right side of the window. View the source code of the example 8. Click the Browse tab to display the first five records in the 1. Start your text editor (such as Notepad or SimpleText) or Java development tool. Inventory.fp5 database. 2. Open the main class file, FileMakerExplorer.java, in the The columns correspond to the fields available for the selected layout. FileMaker Explorer folder. 9.
PAGE 147

Using Java and JDBC to deliver your data Example 2: Creating the JBuilder Inventory application This example demonstrates how to build a Java front end to a FileMaker database using the development tool, JBuilder 3.0 Professional for Windows and the FileMaker JDBC Driver. This example uses a modified version of the Asset Management.fp5 database that ships with FileMaker Pro. The following steps are for creating a Java application that accesses the database, renamed Inventory.fp5.
PAGE 148

9-12 Developer’s Guide 7. Click OK to close the Properties dialog box. Create the data module 1. In JBuilder, choose File menu > New. 2. In the New dialog box, select the Data Module icon and click OK. Design the data module 3. In the New Data Module dialog box, make sure that inventory is in 1. In the Data Modeler, choose Database menu > Add Connection URL. the Package text box and that the checkbox for Invoke Data Modeler is selected. 2. In the Driver text box, type com.fmi.jdbc.JdbcDriver. 4.
PAGE 149

Using Java and JDBC to deliver your data 9-13 Test the data module 1. In the Data Modeler, click the Test tab and click Execute Query. The data and all of the images from the Inventory.fp5 database are downloaded into the data module. 2. Choose File menu > Save. JBuilder saves the data module and automatically adds it to your project. 3. Choose File menu > Exit. 4. Click Yes to invoke the Application Generator. Generate the application 1.
PAGE 150

9-14 Developer’s Guide 5. Click Generate. The Application Generator generates the source code and adds the generated files to your project. Field type Field name Text Location Field attribute Value List/Location List (Pop-up menu) Fred’s Office Dirk’s Office Pedro’s Office Anne’s Office Julie’s Office Ruth’s Office Joanna’s Office Business Center 6. Click Close All. 7. Choose Run menu > Run Application to execute the example application.
PAGE 151

Using Java and JDBC to deliver your data 9-15 Install the example and the FileMaker JDBC Driver If necessary, install the Visual Cafe example and the FileMaker JDBC Driver. The Visual Cafe folder contains the modified database file used in this example and all of the completed files generated by the DataBound Project Wizard for the application. Set up Visual Cafe to use the FileMaker JDBC Driver 1. Start Visual Cafe 4.0 Expert Edition for Windows. tab. Then click New for the Classpath Settings. 3.
PAGE 152

9-16 Developer’s Guide 17. Choose Project menu > Execute to run the application. 9. In the DataBound Project Wizard, select com.fmi.jdbc.JdbcDriver in the list of data sources and click Next. 10. In the User Authentication dialog box, click OK. The inventory_db database is not password protected. 11. In the DataBound Project Wizard, select inventory_db in the list of database tables and views, and click Next. 12.
PAGE 153

Using Java and JDBC to deliver your data Field type Field name Text Location Field attribute Value List/Location List (Pop-up menu) Fred’s Office Dirk’s Office Pedro’s Office Anne’s Office Julie’s Office Ruth’s Office Joanna’s Office Business Center Number Cost User defined entry field Date Date Purchased User defined entry field Container Picture Graphic import Text Serial Number User defined entry field Text Information User defined entry field Using the FileMaker Java classes The Fil
PAGE 154

9-18 1 Developer’s Guide the images from FileMaker Pro container fields The FMProResponse class allows you to access the query results.
PAGE 155

Using Java and JDBC to deliver your data 5. In your web browser, type localhost or your computer’s IP address followed by /FMMemoPad.html and press Enter. http://localhost/FMMemoPad.html For information on setting up your computer as a localhost, see “Testing your site without a network connection” on page 6-17. 6. After the applet has loaded, click Open Memo Pad to display the digital memo pad in a separate window. The FMMemoPad applet lets you browse, edit, find, sort, and add records to the FMMemoPad.
PAGE 156
PAGE 157

Chapter 10 Understanding external function plug-ins If you are a C or C++ programmer and familiar with advanced calculations in FileMaker Pro, you can create external function plugins that extend the feature set of FileMaker Pro—including calculation formulas that take advantage of recursion and looping, or that hook into other programming interfaces. Users can enable your plug-ins in FileMaker Pro and use your external functions in their calculation fields and scripts.
PAGE 158

10-2 Developer’s Guide Contents of the FMExample Plugin folder Contents of the Source folder File/Folder Description The Source folder contains the header and source files that make up the example plug-in code. FMExampleCW4.mcp CodeWarrior 4 project file FMExampleCW6.mcp CodeWarrior 6 project file File/Folder Description FMExampleVC.dsp Microsoft Developer Studio project file TargetPrefix.Classic FMExampleVC.
PAGE 159

Understanding external function plug-ins Installing, enabling, and configuring the example plug-in External function plug-in files must be installed in the appropriate folder and enabled in FileMaker Pro before they can be used. Some plug-ins must also be configured by the user. To configure a plug-in: 1. Select the plug-in in the Application Preferences dialog box. 2. Click Configure.
PAGE 160

10-4 Developer’s Guide Function’s name and parameter Xpl-Format, Description of external function This function returns the parameter as a text string formatted as specified in the configuration dialog box. Use this function to format numbers such as telephone numbers, postal codes, and so on. Formatting proceeds from right to left. Each # symbol in the format string is replaced by the next number in the parameter string. All remaining # symbols are replaced with zeros.

PAGE 161

Understanding external function plug-ins 7. Type a name for a new calculation field in the Field Name box. 8. For Type, select Calculation, and click Create. 9. In the Specify Calculation dialog box, choose External Functions from the View pop-up menu. 10-5 All external function calls require the name of the external function to call and the function’s parameter value, even if the value is null ( ). 11. Replace the word “parameter” with the required parameter for the function.
PAGE 162

10-6 1 Developer’s Guide external function coding in FMFunct.c The following tables describe the modifications you must make to the plug-in example files to create a custom external function plugin. Customizing FMExample.r resource kFMEX_RES_CREATOR Specify the creator string value. resource 'vers' resource 'STR#' kFMEX_RES_STRINFOID Customizing FMMain.h #define k_Pref_Registry_Path_Value Place your preferences in the registry under your own software company or product name. Customizing FMFunct..
PAGE 163

Understanding external function plug-ins 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.
PAGE 164

10-8 Developer’s Guide ////////////////////////////////////////////////////////// // // String Table // STRINGTABLE DISCARDABLE BEGIN 128 FMExample /* Name of plugin as shown in calculation dialog */ 129 This is an example plug-in that demonstrates how to write plug-ins. This comes with FileMaker Developer.
PAGE 165

Understanding external function plug-ins The fifth character of the feature string is always “1,” the eighth is always “Y,” and the tenth is always “n.” Other values for these flags are reserved for FileMaker, Inc. use only. Here’s a description of each character in the feature string: Characters in the feature string 1-4 Characters 1-4 are the plug-in ID. (Register the ID on the Apple Developer Support web site at www.filemaker.com/developers/ index.html.) Character 5 is always “1.
PAGE 166

10-10 Developer’s Guide Main entry point for Windows environments External function naming conventions The Windows platform plug-in exists as a 32-bit DLL with one exported, named entry point. The filename extension for the DLL must be “.FMX” and the name of the entry point must be “FMExternCallProc.” The function name prefix for all of the plug-in’s external functions must be a unique value containing 4 or 5 characters and must not begin with the characters “FM” or “Web.
PAGE 167

Understanding external function plug-ins The Initialization message The Initialization message, kFMXT_Init, is sent to the plug-in whenever it is enabled in FileMaker Pro. This may or may not correspond with the startup of the FileMaker Pro application, depending on whether the plug-in is enabled in the Application Preferences dialog box.
PAGE 168

10-12 Developer’s Guide There are two times when this message is called by the FileMaker Pro application: Depending on the value of the param2 variable, the FMExample plug-in (FMFunct.c) will run the following external functions: 1 If the unsafeCalls parameter is non-zero, then the routine has been called at the same time that the FileMaker Pro application’s lowlevel networking code has been called.
PAGE 169

Understanding external function plug-ins 10-13 Debugging your plug-in UseResFile (pb -> resourceID) ; Your plug-in code could include a preprocessor instruction to cause your plug-in to behave differently during the debugging process. For example, the FMExample plug-in will behave in the following ways when the DEBUG_VERSION flag is set to “1”: When FileMaker Pro loads your plug-in, the application gives the resource ID.
PAGE 170

10-14 Developer’s Guide 3. Enter information about you, your company, and others who can be contacted about your plug-in. 4. Enter the required information about your plug-in. The following table describes some of the required fields: Plug-in Name Your plug-in’s name as it will appear in the FileMaker Pro Application Preferences dialog box. The plug-in name “Web Companion” is already registered and any names that begin with the letters “FM” are reserved.
PAGE 171

Understanding external function plug-ins To revise your plug-in registration, provide the following information: 1 The registration ID number that was assigned to you when you first registered your plug-in. 1 1 1 1 Your name. Your full company name. Your daytime phone number. The name of the product with registered information you want to revise. 1 1 Include any changes you want to make. If applicable, send the revised plug-in file. A confirmation of the revision will be sent to you.
PAGE 172
PAGE 173

Appendix A Feature comparison of the runtime application and FileMaker Pro When you double-click the FileMaker Pro application icon to start the application, the New Database dialog box opens automatically, from which you can open a database file. When you start a FileMaker Pro runtime application, the primary bound database file opens automatically. Other key differences between the runtime application and FileMaker Pro 5.
PAGE 174

A-2 Developer’s Guide The Document Preferences dialog box does not have the General tab in the runtime application, only the Spelling tab. General preferences in the runtime application (Windows) Spelling document preferences in the runtime application General preferences in the runtime application (Mac OS) The Layout tab is changed to the Color tab in the Application Preferences dialog box for the runtime application.
PAGE 175

Feature comparison of the runtime application and FileMaker Pro Menu Menu command Export Records Save a Copy As Browse mode in FileMaker Pro Recover Browse mode in the runtime application Menu command comparison The following table shows the menu commands that are available in FileMaker Pro and in the runtime application. Exit or Quit Edit menu Undo Cut Note In the runtime application, the Format menu is unavailable in Preview mode.
PAGE 176

A-4 Developer’s Guide Menu Menu command Status Area Text Ruler Zoom In Zoom Out Insert menu Object (Windows) Picture QuickTime Sound Current Date Current Time Current User Name From Index From Last Record Format menu Font Size Style Align Text Line Spacing Text Color Text Use System Formats Records menu New Record Duplicate Record Delete Record Delete All Records Modify Last Find Show All Records FileMaker Pro 1 1 1 1 1 1 1 1 1 1 1 1 1 1 Runtime application 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
PAGE 177

Feature comparison of the runtime application and FileMaker Pro Menu Menu command Window menu (Mac OS, Mac OS X) Hide Window Minimize Window (Mac OS X only) Help menu (Windows) FileMaker Pro Help FileMaker Pro 1 1 1 What’s This? FileMaker on the Web About FileMaker Pro 1 1 About About Balloon Help Show Balloons FileMaker Pro Help 1 1 Click "?" button in dialog boxes to display Application Menu Mac Os X About FileMaker Pro 1 1 1 Displays if custom
PAGE 178

A-6 Developer’s Guide 1 Open Define Relationships 1 Open Define Value List 1 Open Sharing 1 Open ScriptMaker 1 Open Help (executes custom Help script specified during binding) 1 Set Multi-User 1 New Database 1 Perform External Script (if the specified file has not been bound to the runtime application) 1 Open File (if the specified file has not been bound to the runtime application) Stored registry settings On Windows machines, FileMaker Pro 5.5 stores its registry settings at hkey_current_user\software
PAGE 179

Appendix B Valid names used in CGI requests for FileMaker Pro XML data This appendix describes the valid names of requests and their parameters you can use in a CGI (Common Gateway Interface) command when requesting FileMaker Pro data in XML format. Included are HREF link and HTML form examples of each request. For scripting examples of each request, see the JavaScript library, FMP.js, in the XML Examples folder.
PAGE 180

B-2 Developer’s Guide To find any record using a hypertext link: Find a random record for today’s daily quote To find some records using a form action: Generating a –new request
Name/Value Type: New Record Request PAGE 181
Valid names used in CGI requests for FileMaker Pro XML data B-3 Generating an –edit request Generating a –delete request Name/Value Type: Edit Record Request Name/Value Type: Delete Record Request What it does: Updates the record specified by –recid, populating the fields with the contents of any field name/value pairs. What it does: Deletes the record as specified by –recid parameter. In order to delete a record, the web user must have record deleting privileges for the database.
PAGE 182

B-4 Developer’s Guide Examples of –dbnames requests To retrieve the database names using a hypertext link: PAGE 183
Valid names used in CGI requests for FileMaker Pro XML data What it does: Opens a specified database that’s located in the Web folder with Remote Administration enabled in the Web Companion (web users must enter “Admin” as the user name) Required parameters: –db, –format Optional parameter: –password Examples of –dbclose requests To close a remotely administered database using a link: PAGE 184
B-6 Developer’s Guide Generating an -img request Name/Value Type: Retrieve Image Request What it does: Retrieves the image specified by -img. Required parameters: -db, -format, -recid, image fieldname Examples of -img requests To retrieve the specified image using a link: PAGE 185
Valid names used in CGI requests for FileMaker Pro XML data Required with: All requests Examples: To generate this XML grammar Specify this format FMPDSORESULT FMPro?–db=employees.fp5&–format= "–dso_xml"&–find FMPDSORESULT + document type definition FMPro?–db=employees.fp5&–format= "–dso_xml_dtd"&–find FMPXMLRESULT FMPro?–db=employees.fp5&–format= "–fmp_xml"&–find FMPXMLRESULT + document type definition FMPXMLLAYOUT FMPro?–db=employees.fp5&–format= "–fmp_xml_dtd"&–find FMPro?–db=employees.
PAGE 186

B-8 Developer’s Guide Value is: The operator to use. There are short and long versions of each operator. The default operator is "begins with". Valid operators are as follows: What it does: Specifies the maximum number of records that should be returned. Value is: A number from 1 through 2147483647, or the word "All". The default value is 25. Short Long FileMaker Pro equivalent operator eq equals =word cn contains "word" bw begins with word* Example: FMPro?–db=employees.
PAGE 187

Valid names used in CGI requests for FileMaker Pro XML data Value is: Name of a FileMaker Pro field. Optional with: –find or –findall requests Optional with: –find or –findall requests Example: FMPro?–db=employees.fp5&–format= –fmp_xml& B-9 –script=Omit+Script&–find Example: FMPro?–db=employees.fp5&–format= –fmp_xml& –script.
PAGE 188

B-10 Developer’s Guide Optional with: The –dbopen request What it does: Tells the FileMaker Pro Web Companion to generate an XML-stylesheet processing instruction within the grammar— setting the value of the type attribute (type=text/css or type=text/ xsl)—so you can use cascading style sheets (CSS) or Extensible Stylesheet Language (XSL) documents with your XML document. This parameter is used in conjunction with the –stylehref parameter. Example: FMPro?–db=employees.
PAGE 189

Appendix C FileMaker Pro values for error codes The FileMaker Pro Web Companion generates an error code for databases published in XML, JDBC, or CDML format every time data is requested. The following table describes the value of each error code, which is based on the type of query to the database. Use these values to do error handling on your web pages.
PAGE 190

C-2 Developer’s Guide Error code value Description Error code value Description 405 Number of records specified exceeds number of records that can be omitted 601 Combined header and footer exceed one page 602 Body doesn't fit on a page for current column setup 406 Replace/Reserialize criteria is invalid 603 Print connection lost 407 One or both match fields are missing (invalid relationship) 700 File is of the wrong file type for import 408 Specified field has inappropriate data type fo
PAGE 191

FileMaker Pro values for error codes C-3 Error code value Description Error code value Description 805 File is damaged; use Recover command 973 The database is invalid 806 File cannot be opened with this version of FileMaker Pro 974 Permission Denied 807 File is not a FileMaker Pro file or is severely damaged 975 The field has restricted access 808 Cannot open file because access privileges are damaged 976 Security is disabled 809 Disk/volume is full 977 Invalid client IP address 8
PAGE 192
PAGE 193

Index Numerics 3-character filename extensions for runtime databases (Mac OS) 4-8 for runtime databases (Windows) 4-8 registered by the runtime application 5-6 A About layout adding a custom script 4-2, 4-4, 4-11 creating 2-9 displaying 2-9 example 2-8 license requirements 2-8 password warning 2-16 prevented modification warning 2-16 using 2-8 About FileMaker Pro Runtime, default menu command 4-12 Access Log File option 6-4, 6-14 access privileges record-level access 6-4 settings for Kiosk
PAGE 194

I-2 Developer’s Guide using 8-12 CDML tags disabled in 5.5 8-9 CDML Tool choosing encoding parameters 8-6 described 8-1, 8-5 displaying tag syntax 8-6 parameters and value list options 8-6 tag categories 8-8 Tags tab 8-6 Templates tab 8-5 using 8-5 centering database windows in Kiosk mode 2-6 CGI requests. See FileMaker Pro CGI requests CGM graphic import filter 5-2 character entities, XML 3-4 character escaping 9-4 characters, platform-specific 2-12 Claddon.
PAGE 195

Index default values for layout themes 3-9 default XML namespace declarations 7-2 default.
PAGE 196

I-4 Developer’s Guide Extensible Markup Language (XML). See XML Extensible Stylesheet Language (XSL). See XSL stylesheets Extensible Stylesheet Language– Transformations (XSLT).
PAGE 197

Index registry conflicts (Windows) 4-8 filenames for instant web pages 6-13 files closing in Kiosk mode 2-3 converting to FileMaker Pro 5.5 2-17 cross-platform 2-11 installed in FileMaker Developer 1-11 opening runtime 5-6 preparing 2-1, 2-11 recovering damaged 5-6 renaming 4-10 Find mode in runtime applications A-1 -find requests 7-13, 7-14, B-1 FMBanner applet 9-18 FMBanner.fp5 database 9-18 FMFlags.h header file 10-7 FMMemoPad applet 9-18 FMMemoPad.fp5 database 9-18 FMP.
PAGE 198

I-6 Developer’s Guide I J Idle message 10-11 If script step 2-14 Import script step 2-17 importing records 2-17 index.
PAGE 199

Index for ODBC driver 1-13 for runtime database solutions 1-13 sample file 1-13, 5-4 links HREF 6-2, 6-6, 7-2, 8-4 testing 6-17 to CDML format files 8-2 to IP addresses 6-6 XML example requests B-1 Local Data Access Companion plug-in A-1 localhost networking 6-6, 6-17 log files generated by the Web Companion 6-13 -lop request parameter B-7 Lotus SLD graphic import filter 5-2 lt (less than) character entity 3-4 M Mac OS X and FileMaker Pro 1-11 Help tags 2-8 requirements for FileMaker Developer 1-2 specify
PAGE 200

I-8 Developer’s Guide PARTNUMBER attribute 3-8 password driver property 9-4 passwords decoding and repairing 2-15 default 2-7 master 2-7 protecting files from hackers 4-11 required warning in About layouts 2-16 PATTERN attribute 3-8 pattern palette, FileMaker Pro 3-9 pattern values for layout themes 3-9 PCX graphic import filter 5-2 People.fp5 database 7-11 people_form.css stylesheet 7-13 people_form.htm page 7-16 people_form.
PAGE 201

Index Remote Administration option 6-4 Remote Data Access Companion plug-in A-1 renaming database files 4-10 Scripts menu 4-13, A-1 Solution Options file 4-14 repairing FileMaker Developer (Windows) 1-8 requesting data.
PAGE 202

I-10 Developer’s Guide SELECT SQL statements 9-4, 9-6 Set Multi-User script step A-6 Set Zoom Level script step 2-6 setting document margins for printing 2-3 setting up single-machine networks 6-17 shadow and outline text styles 2-12 sharing databases via the Web Companion 6-5 runtime files over a network 5-5 Shopping Cart CDML example 8-15, 8-17 Shutdown message 10-11 SIDES attribute 3-8 SimpleText 9-10 single-line elements for layout themes 3-4, 3-5 SIZE attribute 3-8 -skip request parameter B-8 Solutio
PAGE 203

Index FileMaker JDBC URL 9-2 for FileMaker Pro CGI requests 7-2 loaded by the FMBanner Java applet 9-18 using to access databases 6-1 Usenglsh.mpr spelling dictionary 5-3, 5-4 user driver property 9-4 User.upr spelling dictionary 5-3, 5-4 UTF-8 (Unicode Transformation 8 Bit) format 7-7 V values for error codes C-1 VBScript 7-3 -view requests B-2 Visual Cafe 4.
PAGE 204