F O R M A C I N T O S H A N D W I N D O W S DEVELOPER’S GUIDE ©1996 Claris Corporation. All Rights Reserved. Claris Corporation 5201 Patrick Henry Drive Santa Clara, California 95052 Claris, ClarisImpact, ClarisWorks, FileMaker and ScriptMaker are registered trademarks and KioskMaker is a trademark of Claris Corporation. Apple, AppleScript, AppleTalk, Macintosh, MacTCP, Power Macintosh and QuickTime are registered trademarks and Mac is a trademark of Apple Computer, Inc.
LIMITED WARRANTY AND DISCLAIMER, LIMITATION OF REMEDIES AND DAMAGES YOU ACKNOWLEDGE THAT THE SOFTWARE MAY NOT SATISFY ALL YOUR REQUIREMENTS OR BE FREE FROM DEFECTS. CLARIS WARRANTS THE DISKETTES ON WHICH THE SOFTWARE IS RECORDED TO BE FREE FROM DEFECTS IN MATERIALS AND WORKMANSHIP UNDER NORMAL USE FOR 90 DAYS FROM PURCHASE, BUT THE SOFTWARE AND ACCOMPANYING WRITTEN MATERIALS ARE LICENSED "AS IS.
III Contents Chapter 1: Welcome to FileMaker Pro SDK About FileMaker Pro SDK New features KioskMaker Assigning the three-character extension Changes from FileMaker Pro 2.
IV FileMaker Pro SDK Developer’s Guide Chapter 4: Binding solution files The binding process—an overview What happens during binding Before binding Including solution files Naming the solution file Assigning the three-character extension Assigning the binding key Running your solution in kiosk mode Sharing solution files across platforms Changing or creating solutions 4-1 4-2 4-2 4-2 4-4 4-4 4-6 4-6 4-6 4-7 Chapter 5: Distributing your bundled solution 5-1 Choosing your solution files 5-2 Minimum requir
Chapter 1: Welcome to FileMaker Pro SDK This chapter introduces the FileMaker® Pro Solutions Distribution Kit (SDK). It provides a brief introduction to the terms used in this guide and the requirements for running the FileMaker® Pro Binder application on your system. Note This guide covers both the Apple Mac™ OS computer and Windows versions of the FileMaker Pro Binder application.
1-2 FileMaker Pro SDK Developer’s Guide 1 removing access to the operating system while the runtime application is in use See “Using KioskMaker” on page 3-10 for information and design tips. Assigning the three-character extension While binding, you assign a three-character extension to your solution files and the FileMaker Pro Runtime application. The extension associates your solution files with the FileMaker Pro Runtime application, making your solution files more identifiable.
Welcome to FileMaker Pro SDK 1-3 SDK terminology This guide uses the following terms: Term Refers to FileMaker Pro application The standard version of the FileMaker Pro application FileMaker Pro Binder The application that generates the FileMaker Pro Runtime application and binds it to your solution files FileMaker Pro Runtime application The runtime engine you distribute with your solution files Solution files Your primary file and any auxiliary files Primary file The main database file for you
1-4 FileMaker Pro SDK Developer’s Guide 1 You may not use the Claris® name or logo to market your bundled solution. 1 You must provide an “About” layout that includes your name and the telephone number for your technical support (see “Creating an “About” layout” on page 3-4). Getting customer support To learn about Claris Technical Support and Claris Customer Assistance, their hours of operation, and their telephone numbers, see the Claris® Service Directory included in the product package.
Welcome to FileMaker Pro SDK 1-5 Location Description Use to FMP30SDK folder Contains FMBINDER.EXE and the Runtime folder Bind solution files and distribute Runtime Files folder to enable optional functionality RUNTIME folder Contains the SYSTEM and the Install to enable optional 4WINSYS folders FileMaker Pro functionality, like spell-checking, data and graphics importing, and networking WIN32S1.30C folder Enables FileMaker Pro to run Install on end-user machines on Windows 3.
Chapter 2: Installing FileMaker Pro SDK This chapter provides instructions for installing the FileMaker Pro Binder application on your system. What you need To run FileMaker Pro Binder on the Macintosh, you need the following mimimum equipment and software: 1 any Macintosh, Power Macintosh,® or compatible computer running System 7 or newer (System 7.1 or newer recommended) 1 a hard disk with 4 MB of RAM (8 MB RAM recommended) 1 a CD-ROM drive 1 solution files developed in FileMaker Pro 3.
2-2 FileMaker Pro SDK Developer’s Guide What end-users need To distribute the FileMaker Pro Runtime application on floppy disks, you need to purchase a compression utility or installation program, which stores the runtime application and bound solution files on several disks. Your end-users will need the instructions and software to decompress the files on their hard disks.
Installing FileMaker Pro SDK 2-3 Use the following chart to determine what client networking software your end-users need to use FileMaker Pro Runtime over a network. To use this network On this operating system Networking software necessary AppleTalk® Macintosh Included in operating system IPX/SPX Macintosh MacIPX application program 1.2.1 or later (included on CD-ROM) TCP/IP Macintosh MacTCP® 2.0.6 (included with System 7.5 or later) or Apple Open Transport 1.0.
2-4 FileMaker Pro SDK Developer’s Guide To copy the additional files, drag the Support and/or Tools folder to your hard disk. Copying FMBINDER.EXE on Windows Copy the FMP30SDK folder over to your hard disk. You will move both the binder application and the Runtime folder, which contains networking modules and file filters, to your hard disk. Copying additional files on Windows The Support folder includes cross-platform tips, the TechInfo Sampler, and additional reference information.
Chapter 3: Preparing solution files This chapter describes how to prepare your solution files before binding. It covers what to do after you’ve developed a solution and includes tips for developing a solution using KioskMaker. It also describes how to convert an existing FileMaker Pro 2.x SDK solution file to a FileMaker Pro 3.0 SDK solution. Note This guide assumes you’re familiar with FileMaker Pro and have developed database solutions.
3-2 FileMaker Pro SDK Developer’s Guide 3. Create a Help system to provide help on your solution. The Help files contained in the FileMaker Pro application are not available with the FileMaker Pro Runtime application. Claris recommends you create a Help layout or database integrated in your solution files. There is a sample integrated Help system included in the Sample Solution folder (SAMPLE folder on Windows) inside the Tools folder on the CD-ROM.
Preparing solution files 3-3 1 Do you want your end-users to open and close auxiliary files? In the FileMaker Pro Runtime application, several menu options have been eliminated, including Open and Close. If you want your end-user to open and close auxiliary files, you must provide scripts in your solution to perform these operations. 1 Are you running your files in kiosk mode? If your solution files will be run in kiosk mode, the entire interface must be accessible via buttons on the layouts.
3-4 FileMaker Pro SDK Developer’s Guide Claris recommends You should password protect solution files before binding. This protects the file in case an end-user opens your solution with the FileMaker Pro application. Without password protection, your end-user can print or modify your scripts and field definitions, and make modifications to your solution. See “Using passwords” on page 3-9 for more information.
Preparing solution files 3-5 3. Make sure the “About” layout includes a button that lets your end-user return to the original layout. 4. Do one of the following: 1 Write a script that displays the layout each time the end-user starts the bundled solution. 1 In FileMaker Pro 3.0, select Preferences from the Edit menu. In Document Preferences, set the Switch to layout option for the primary file. Select the “About” layout as the layout that appears first.
3-6 FileMaker Pro SDK Developer’s Guide Selected topic Enter Help for the selected topic in this area 2. Edit the layout so that your logo and solution name appear. 3. Select a Help topic on the left and then enter the Help information on that topic on the right, in the corresponding layout. Make a new layout for each Help topic. 4. Modify the script for the Return button so that it returns your end-user to your solution.
Preparing solution files 3-7 1 what to do in case of a damaged file (see “Recovering damaged files” on page 5-11) 1 how to reach you for technical support You might also want to include the following recommendations: 1 Tell your end-users not to rename any files in your solution folder, or they may be unable to run your solution. 1 Recommend that your end-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.
3-8 FileMaker Pro SDK Developer’s Guide 1 The number of guests using the FileMaker Pro Runtime application as a host is limited to 25. With FileMaker Pro Server, a computer can host a solution that can be accessed by up to 100 guests using FileMaker Pro Runtime or the FileMaker Pro application. FileMaker Pro Runtime is optimized so, when used with FileMaker Pro Server, background tasks associated with managing a database file are handled by FileMaker Pro Server.
Preparing solution files 3-9 Using passwords You should define a password to protect your solution files. If the solution files are unprotected, an end-user can open your bundled solution with the FileMaker Pro 3.0 application. Once your solution is open in the FileMaker Pro application, the end-user has access to your scripts, field definitions, access privileges, and layout mode. If you want to prevent this, you need to set passwords.
3-10 FileMaker Pro SDK Developer’s Guide Using KioskMaker In the Binding Options dialog box, select Run solution in kiosk mode when you want to design a special interface for your solution files. In kiosk mode, your solution files lose the appearance of the operating system and the monitor area around your solution file is black. The following table describes how to emulate interface elements that are not shown when you run your solution files in kiosk mode.
Preparing solution files 3-11 Solution interface in kiosk mode No menu bar Button driven interface Quit button Design considerations 1 Start by planning your database design on paper. Decide what will happen when each button is selected, and give users a way to get back to the beginning. 1 If your solution will be run with a touch screen, use large buttons and allow space between buttons. 1 Try to limit the number of options available on one screen.
3-12 FileMaker Pro SDK Developer’s Guide Testing your solution You should verify the functionality of your solution by testing it thoroughly before and after binding it to FileMaker Pro Runtime. Here are some suggestions for ensuring the quality of your solution: 1 Verify every function and option in your solution. 1 Verify that the scripts and buttons work as expected. This is especially important if you are running your solution in kiosk mode.
Preparing solution files 3-13 Converting and upgrading solution files This section assumes you have developed a solution in the FileMaker Pro 2.1 SDK and want to upgrade your current end-users to FileMaker Pro 3.0 SDK. This lets you take advantage of the many new features in FileMaker Pro 3.0, such as relational capabilities and more robust scripting. To upgrade your solution files: 1. Convert the 2.x solution files to FileMaker Pro 3.0. 2.
3-14 FileMaker Pro SDK Developer’s Guide 1 To upgrade repeating field data to a relational table, you will need to separate repeating fields by importing the data into another database file. For example, to break out the repeating fields from the Invoices database below, create a Sold Items database, and then import the repeating fields into it, choosing to split repeating field values during import.
Preparing solution files 3-15 3. Create scripts that import data from the old filename (Address) to the new filename (Address2). Although you’re working in FileMaker Pro 3.0, the scripts you are creating will work with your end-user’s 2.x solution files. If your end-users only want to import a subset of the records in the 2.x file format, you should create a script that opens the database, goes to Find Mode and pauses. They then search on the criteria they choose.
Chapter 4: Binding solution files This chapter describes how to create the bundled solution you’ll distribute to your end-users. It assumes you have developed and thoroughly tested the solution files.
4-2 FileMaker Pro SDK Developer’s Guide What happens during binding A solution can consist of one primary file, or a primary file and a set of auxiliary files. The primary file is the database that FileMaker Pro Runtime opens first. Auxiliary files are related or external files that the primary file interacts with. During binding, you specify the files that make up your solution. Then you highlight the primary file, name your solution, and provide the binding key and three-character extension.
Binding solution files 4-3 There are three ways to include solution files: 1 The easiest way to include solution files is to drag and drop your solution files on top of FileMaker Pro Binder. Drag solution files onto FileMaker Pro Binder 1 Another way to include solution files is to launch FileMaker Pro Binder, select the primary solution file, and click the Add button. Then, in the Binding Options dialog box, click the Add File button to add other files.
4-4 FileMaker Pro SDK Developer’s Guide Drag solution files into the Binding list or... ... click here to add solution files Cross-platform users If you’re creating a solution to run on both Macintosh and Windows, you should bind the file twice: first using FileMaker Pro Binder for Windows, and then using FileMaker Pro Binder for the Macintosh. Use the same binding key on both platforms. Naming the solution file Type a name for your FileMaker Pro Runtime application in the Solution Name text box.
Binding solution files 4-5 Files are grouped by type Windows solution Assigning the three-character extension on the Macintosh On the Macintosh, these characters become the creator type for the FileMaker Pro Runtime application. The creator type is stored in both the solution files and runtime application, and makes identifying solution files easier by associating files with the appropriate application.
4-6 FileMaker Pro SDK Developer’s Guide Assigning the binding key The binding key internally links the primary file to the FileMaker Pro Runtime application. It is stored in both the runtime application and the solution files to ensure that the bound runtime application will only be able to open the appropriate solution files. The binding key is case-sensitive on the Macintosh, and must be between 6 and 31 characters.
Binding solution files 4-7 3. Bind the solution files on that platform using the same key you used to bind your primary file. 4. Distribute your bundled solution. See “Cross-platform considerations” on page 3-12 and “Running solution files on a network” on page 5-9 for tips. Changing or creating solutions FileMaker Pro SDK entitles you to create or change your solutions.
Chapter 5: Distributing your bundled solution The final step in preparing your bundled solution is creating an installation procedure for your solution.
5-2 FileMaker Pro SDK Developer’s Guide Macintosh solution folder Windows solution folder runtime application runtime application bound solution files bound solution files FileMaker Extensions networking files and data import filters Files for System Folder items are moved into the end-user’s System Folder Claris Folder Spell-checking and file importing software Extensions Spell-checking and MacIPX software 6 DLLs generated during binding System folder networking files, spell-checking files, and dat
Distributing your bundled solution 5-3 Minimum requirements for Macintosh solution On the Macintosh, all you need to distribute is the runtime application and your bound solution files. Runtime Files folder Items in the Runtime Files folder should be distributed along with your bound solution files and the runtime application to enable additional features, such as spell-checking, data and graphic importing, and networking. Drag the contents of this folder into the same folder as the runtime application.
5-4 FileMaker Pro SDK Developer’s Guide To create Win32s diskettes: 1. Format three 1.4 MB diskettes and name them Disk1, Disk2, and Disk3. 2. Drag the contents of the corresponding folders from the CD-ROM onto the floppy disks. Important Disk names, filenames and paths cannot be modified or the Win32s installation will fail. Additional files required for networked solutions If your end-users will be using your bundled solution over a network, you’ll need to distribute additional files from the CD-ROM.
Distributing your bundled solution 5-5 If your end-users are using the MS IPX/SPX network with Windows 95 and Windows NT They should use the IPX/SPX-compatible Protocol to share FileMaker Pro files. On Windows NT, they should use the NWLink IPX/SPX Compatible Transport. You also need to distribute the FMIPX32.NET file inside the FileMaker System folder.
5-6 FileMaker Pro SDK Developer’s Guide Workgroups 3.11: They’ll need to install the TCP/IP-32 (version 3.11b) software, available from Microsoft. You also need to distribute the FMTCP32.NET file inside the FileMaker System folder. Choosing the distribution method After you have chosen the files that comprise your solution and determined where the files will go, you need to decide how your end-users will install them.
Distributing your bundled solution 5-7 Installing your solution You’ll need to provide installation instructions to your end-users. Keep the following in mind: 1 Provide written instructions for copying or installing your solution to your end-user’s hard disk. 1 Include software and instructions specifying how your end-users will decompress your solution files. 1 If your end-users are installing your solution on Windows 3.1 or Windows for Workgroups 3.
5-8 FileMaker Pro SDK Developer’s Guide Change virtual memory type to Permanent Set swap file to at least 20480 KB Enable 32-bit disk access Enable 32-bit file access 4. Install Win32s. Instruct your end-users to insert the Win32s Disk1. In the Program Manager, choose Run from the File menu and type a:\SETUP.EXE from the Program Manager. Follow the Win32s setup instructions. 5. When the Win32s installation is complete, the Freecell Setup dialog box appears.
Distributing your bundled solution 5-9 Installing your solution files for a network If you’re creating a multiuser solution, the runtime application should be installed for each guest on the network, and solution files should be hosted by a dedicated machine. You should distribute the primary file to guests when the primary file can’t be easily found on the local network.
5-10 FileMaker Pro SDK Developer’s Guide Double-clicking the icons for the primary or auxiliary files might result in errors, depending on whether there are other copies of the runtime application on the hard disk.
Distributing your bundled solution 5-11 Updating a solution You will need to update your solution if you want to make feature enhancements, modifications, or if you want to add additional files. You can update a solution by making modifications to the primary file and sending that file to your end-users. If you are adding more files, you need to bind those files with the original key used when you bound the primary file.
5-12 FileMaker Pro SDK Developer’s Guide Adding new or changed auxiliary files To add new or changed files, rebind the solution files and generate a new runtime application. Use the same binding key that you used for the primary file. Remember that the key is case-sensitive on the Macintosh. Recovering damaged files Power failures, hardware problems, or other factors can damage a FileMaker Pro file. If your solution becomes damaged, your end-user needs to recover the damaged file.
Distributing your bundled solution 5-13 In your printed documentation, you should tell your end-users what to do once a file has been recovered.
Appendix A: FileMaker Pro Runtime features FileMaker Pro Runtime is a modified version of the FileMaker Pro application. With FileMaker Pro Runtime, your end-users can’t modify the design of your solution files. In FileMaker Pro Runtime: 1 end-users can use your solution files without having the FileMaker Pro application 1 all the database design features have been removed or hidden 1 some menu items have been removed The following table shows which menu commands are available in FileMaker Pro Runtime.
A-2 FileMaker Pro SDK Developer’s Guide Menu Menu Item FileMaker Pro FileMaker Pro Runtime Edit menu Undo • • Cut • • Copy • • Paste • • Paste As... (on Windows only) • • Clear • • Duplicate • Paste As... (on Windows only) • Mode menu Select menu Select All • • Paste Special • • Object (on Windows only) • • Spelling • • Preferences...
FileMaker Pro Runtime features A-3 Menu Menu Item FileMaker Pro FileMaker Pro Runtime Arrange menu All menu items • Format menu • • Size • • Style • • Align Text • • Line Spacing • • Text Color • • Text... • • Text Ruler • • ScriptMaker...
A-4 FileMaker Pro SDK Developer’s Guide Additional differences Other features have been removed from the FileMaker Pro Runtime application. If your scripts contain any of the following items, FileMaker Pro Runtime skips over them, and may not alert the end-user. These items can be in scripts, but they won’t be executed.
Appendix B: SDK file locations The following sections show the locations for the SDK files and folders. Solution files should be copied to the same folder as the runtime application. The FileMaker Pro Runtime application moves the contents of the Files for System Folder (on the Macintosh) or the 4WINSYS folder (on Windows) to the System folder when it is first opened. Contents of the Runtime folder The following tables show the files and folders inside the Runtime Files folder (RUNTIME on Windows).
B-2 FileMaker Pro SDK Developer’s Guide File or folder Description Location on CD-ROM Preferred location on end-user’s hard disk US English - Spelling Spell-checking dictionary FileMaker Pro 3.0 SDK: Runtime Files: Files for System Folder: Claris Folder Solution folder: Files for System Folder: Claris Folder User Dictionary Stores words added to the user dictionary FileMaker Pro 3.
SDK file locations B-3 Distribute the following files or folders with solution files for Windows. Location on CD-ROM Preferred location on end-user’s hard disk File or folder Description SYSTEM folder Place in same folder as runtime FMP30SDK application to enable data importing and FileMaker networking Solution folder FMBMP32.FLT BMP graphic filter FMP30SDK\SYSTEM Solution folder\SYSTEM FMCGM32.FLT CGM graphic filter FMP30SDK\SYSTEM Solution folder\SYSTEM FMDRW32.
B-4 FileMaker Pro SDK Developer’s Guide File or folder Description Location on CD-ROM Preferred location on end-user’s hard disk 4WINSYS Distribute on Windows 3.1 or Windows for Workgroups 3.11 FMP30SDK\SYSTEM Solution folder\SYSTEM CTRL3D32.DLL Provides Windows 95 dimensional interface FMP30SDK\SYSTEM Solution folder\SYSTEM NWIPXSPX.DLL Netware IPX/SPX network support FMP30SDK\SYSTEM file Solution folder\SYSTEM NWNETAPI.DLL Netware network support file FMP30SDK\SYSTEM Solution folder\SYS
I-1 Index Numerics 4WINSYS folder 5-3 A "About" layout, the 3-1, 3-4 About menu command 3-5 Auxiliary files adding new 5-11 closing 3-3, 3-7 described 1-3 opening 3-3, 3-7 updating 5-11 key for 4-2, 4-6 naming 4-2 planning 3-3 running 5-10 sample 3-1 Cross-platform tips 3-1, 3-3, B-4 CSA Guide folder B-4 Customer assistance. See Claris Customer Assistance Customer support.
I-2 FileMaker Pro SDK Developer’s Guide solution files 4-6 solution files, for 4-2 Kiosk folder B-4 Kiosk mode closing files 3-10 designing for 3-10, 3-11 menu commands 3-11 running solution in 4-6 using 3-10 KioskMaker described 1-3 using 3-10 suppressing 3-9 Passwords, defining 3-9 Planning for networks 3-7 Posters solution 3-4 Primary file binding 4-2 described 1-3 locating 5-9 updating 5-10 Printed documentation 3-6, 3-8 R L Macintosh copying FileMaker Pro Binder 2-3 networks supported 2-2 runtime ap
