FileMaker Connectivity

FileMaker Training

FileMaker Connectivity

FileMaker Connectivitypage �

©2006 FileMaker, Inc. All rights reserved. FileMaker is a registered trademark of FileMaker, Inc., in the U.S. and other countries. ScriptMaker and the file folder logo are trademarks of FileMaker, Inc.. DataDirect SequeLink is a registered trademark of Progress Software Corporation in the U.S. and other countries. Microsoft is a registered trademark of Microsoft Corporation. All other trademarks are the property of their respective owners. The example companies, organization, products, domain names, e-mail addresses, logos, people, places and events depicted are purely fictitious, and any resemblance to existing persons and companies is purely coincidental. Product specifications and availability subject to change without notice. All rights reserved.

Special credit to Bob Bowers, Steve Lane, and Scott Love of Soliant Consulting (www.soliantconsulting.com) and Chris Moyer of the Moyer Group (www.moyergroup.com) for assisting FileMaker, Inc. with the development of this document.

This document may not be reproduced or otherwise redistributed without prior consent of FileMaker, Inc.

FileMaker Connectivity page �

Table of Contents

Objectives ..................................................................................................................... 4

Connectivity Standards ............................................................................................... 4

Mechanics of ODBC .................................................................................................... 5

Using FileMaker Pro 8 as an ODBC Host .................................................................. 6

Creating the Data Source Name ..............................................................................10

Using Microsoft Excel as an ODBC Client ..............................................................21

Exercise 1 - Querying FileMaker Data From Excel .................................................24

Using FileMaker Server 8 Advanced as an ODBC/JDBC Host ...........................25

Using FileMaker Pro 8 as an ODBC Client ..............................................................28

Exercise 2 - Querying ODBC Data From FileMaker...............................................33

Exercise 3 - Insert Data into an ODBC Data Source ..............................................34

Review Questions ......................................................................................................35

Review Answers .........................................................................................................37


FileMaker Connectivity

Objectives

By the end of this module, you’ll be able to:

• Describe the components of connectivity.

• Describe how FileMaker® Pro 8 or FileMaker Pro 8 Advanced can be used as an ODBC/JDBC host.

• Describe how FileMaker Server 8 Advanced can be used as an ODBC/JDBC host.

• Describe how FileMaker Pro 8 can act as an ODBC client.

Connectivity Standards

There are a wide variety of relational database management system (RDBMS or DBMS) products that run on a variety of operating systems. Before the advent of a standardized method of communicating between different database products, specific database communication protocols had to be embedded into applications. That meant that an application could usually only communicate with one specific type of database system. It soon became apparent that a common language for communicating with database products was needed.

SQL (Structured Query Language) is that language. The original specification, SQL-89, was created by the American National Standards Institute (ANSI) and the International Standards Organization (ISO). Since then, the specification has evolved, and the current standard is called SQL-2003.

In addition to a standard language, a standard framework for using the language was needed. Microsoft developed the Open Database Connectivity (ODBC) standard, and SQL was designated as its query language. The ODBC specification also defines a set of standard error codes, standard methods for connecting and logging on to a DBMS, and so forth. With the rise of Java, Sun Microsystems developed a Java-based database connectivity API known as JDBC. JDBC is similar to ODBC, but is designed specifically for Java programs, whereas ODBC is language-independent.

This module will focus on ODBC, rather than JDBC, connectivity, though the FileMaker product line offers full support for both.


For latest updates, drivers and documentation, please visit the FileMaker website at: http://www.filemaker.com/developers/resources/odbc.html.

Mechanics of ODBCThere are four components to the ODBC architecture:

HostThe host is the database management system, or DBMS, that is actually running the database that is being queried. FileMaker Server 8 Advanced can act as an ODBC or JDBC host, meaning that it will accept ODBC or JDBC queries from client applications. The term host is also used to refer to the server that the DBMS is running on, and it is sometimes used to refer to the database itself. FileMaker Pro 8 and FileMaker Pro 8 Advanced can also function as ODBC hosts, with certain limitations.

ClientA client is any application that asks for information from the host. Client applications can range from other database programs like FileMaker Pro 8 to a reporting tool like Crystal Reports or Microsoft® Excel.

DriverA driver is an intermediate component, bridging the gap between a specific host and a specific client. Drivers are generally specific to both the host and the client: that is, a driver that works with Oracle will not work with PostgreSQL. Within the class of Oracle drivers, there are separate drivers for Mac and Windows clients. The driver’s function is to take a query using SQL and translate it into query instructions that the host can use. Once the host has returned the results of the SQL instructions, the driver returns those to the querying application.

Driver ManagerA driver manager is a client-side user interface that allows users to configure drivers. For example, a user might have the DataDirect driver on their computer. In order to use that driver to communicate with a FileMaker host on another machine, the driver needs to be configured with the host’s network address, the name of the database to be queried, the account name and the password information. The driver manager takes the configuration information that the user enters and writes it to a configuration file. This file could be edited by hand, but it’s easier if the driver manager is used. The driver manager also loads the designated driver for the client application.

There are other components that are required as well, such as network connections and the network protocol, but those aren’t required for local ODBC connections. A specific client-side


configuration of a driver is called a Data Source Name, or DSN. A DSN is used by the ODBC client application to talk to the host.

Using FileMaker Pro 8 as an ODBC/JDBC HostFileMaker Pro 8 can act as an ODBC client (meaning that it can request data from ODBC-aware databases) and as an ODBC/JDBC host (meaning that it can furnish data to ODBC-aware client applications). In this section, we’ll cover the steps required to set up and use FileMaker Pro 8 as an ODBC/JDBC host. FileMaker Pro 8 can only act as an ODBC host for client applications running on the same computer. If you need to have remote ODBC access to a FileMaker database, you need to use FileMaker Server 8 Advanced.

As a first exercise, you are going to set up a FileMaker file called Sales.fp7 for xDBC access. The required steps are:

• Create a privilege set that can be used for xDBC access

• Create an account and assign the privilege set to it

• Enable the file for xDBC sharing

Create a Privilege Set for ODBC/JDBC AccessOpen the file Sales.fp7. Select File>Define>Accounts & Privileges to open the Accounts & Privileges dialog. Select the Privilege Sets tab and click New to open the Edit Privilege Set dialog, as shown in Figure 1.


Figure 1

Name the Privilege Set ‘ODBC Access.’ In the Extended Privileges area, enable Access via ODBC/JDBC.

xDBC clients need to be able to create and edit records, but they can’t access layouts, value lists, or scripts. Therefore, privileges in the Data Design section need to be modified accordingly. As shown in Figure 1 record privileges should be set to Create, edit, and delete in all tables, layouts need to be set to All view only, Value Lists need to be set to All no access, and Scripts need to be set to All no access. Once these changes have been made, you can click OK to return to the Define Accounts & Privileges dialog.

Create an AccountClick the Accounts tab and click New to open the Edit Account dialog, as shown in Figure 2. Leave the authentication method in its default state so that the account is authenticated via FileMaker. Enter ODBC for both the Account Name and Password. For the Privilege Set, select ODBC Access from the pop-up list. Click OK to save the account and click OK to close accounts & privileges. Administrator username is: Admin with no password.


Figure 2

Enable ODBC/JDBC Sharing for the ApplicationSelect Edit>Sharing>ODBC/JDBC to open the ODBC/JDBC Sharing Settings dialog, shown in Figure 3.


Figure 3

In the ODBC/JDBC Sharing Settings dialog set the Turn on ODBC/JDBC Sharing to publish all shared open files using this protocol to On. This allows FileMaker Pro to accept ODBC/JDBC queries. At the file level you have the choice of allowing ODBC/JDBC access to: all users, no users, or only users who are logged in with specific privilege sets. In this case, you want to make use of the ODBC Access privilege set that we created. Select Specify users by privilege set to open the Specify users by privilege set dialog shown in Figure 4.

FileMaker Connectivitypage 10

Figure 4

Check On option for ODBC Access and click OK to exit the Specify users by privilege set dialog. Click OK again to exit the ODBC/JDBC Sharing Settings dialog. The file is now accessible to local ODBC/JDBC clients.

Note that these steps are exactly the equivalent of adding the xDBC extended privilege to one or more privilege sets using the Define Accounts and Privileges dialog, as you did earlier. This is just a convenient alternate interface to accomplish exactly the same task.

Creating the Data Source Name (DSN)Remember, when you set up ODBC/JDBC sharing for files that are hosted by FileMaker Pro 8 or FileMaker Pro 8 Advanced, ODBC or JDBC access is only possible on the local machine. If you have a remote ODBC or JDBC client that needs to access data over the network, then you need to use FileMaker Server 8 Advanced (not FileMaker Server 8). FileMaker Server 8 Advanced is the only FileMaker host that will allow remote access for ODBC/JDBC clients.

When using FileMaker Pro 8 as a data source, you need to create a Data Source Name (DSN) on the same machine that FileMaker Pro 8 is running on.

FileMaker Connectivity page 11

On Windows, the setup is as follows. Open the Control Panel, and double-click Administrative Tools to open the Administrative Tools window shown in Figure 5.

Figure 5

FileMaker Connectivitypage 1�

Double-click Data Sources (ODBC) to open the ODBC Data Source Administrator shown in Figure 6.

Figure 6

A User DSN can only be used by the currently logged in user. A System DSN can be used by any user of the system. For the purposes of this exercise, you will create a User DSN. Click Add to open the Create New Data Source dialog shown in Figure 7.

FileMaker Connectivity page 1�

Figure 7

The ODBC driver that works with FileMaker Pro 8, FileMaker Pro 8 Advanced, or FileMaker Server 8 Advanced is called DataDirect 32-BIT SequeLink® 5.4. If you don’t see that driver in your list of drivers you’ll need to install the driver from your FileMaker Pro 8 installation CD. Once the driver is available in the Create New Data Source dialog select it and click Finish to open the DataDirect SequeLink for ODBC Setup dialog shown in Figure 8. (Please read the FileMaker Knowledge Base article #357 regarding ‘Recently Installed FileMaker ODBC Driver Is Not Listed In Drivers Tab Of ODBC Data Source Administrator” located in the Support section of the FileMaker website.)


Figure 8

For the Data Source Name entry box you can enter any name that is meaningful to you. If you’re on a computer that has several DSN’s, it might be a good idea to include FMP8 as a prefix or suffix so that you’ll know that the DSN is a FileMaker DSN and not a PostgreSQL or some other kind of DSN. For this exercise, enter the name FMP8_Sales, since the DSN will be for a Sales database.

You can enter anything you like in the Description entry box: it’s optional. Do not enable LDAP. Since the host machine is the same machine you’re already on, you want to specify the SequeLink Server Host as localhost. The SequeLink Server Port must be set to 2399. Once this information is all entered correctly you can select a Server Data Source by clicking the button to the right of the entry box, shown in Figure 8. Clicking that button will open the Server Data Sources dialog shown in Figure 9.


Figure 9

The Server Data Sources dialog will present you with a list of currently-open FileMaker files that have been enabled for ODBC access. For this exercise select the Sales file. Click OK to exit the Server Data Sources dialog and return to the DataDirect SequeLink for ODBC Setup dialog shown in Figure 10.


Figure 10

Notice that the Server Data Source does not include the .fp7 extension. The contents of this entry box will always be a file’s name, minus the extension. You could have just typed Sales into the box.

Note, by the way, that this DSN is file-specific. It’s necessary to establish a new DSN for each FileMaker file you intend to access. Please also note that the FileMaker file must be open in order for ODBC to work in this exercise.

The next step is to test the ODBC connection and make sure that everything is working properly. Click the Test Connect button to open the Logon to SequeLink Service dialog shown in Figure 11.


Figure 11

Enter the Account Name and Password for the ODBC account that you set up earlier. Both the user name and password are ODBC.

If everything was configured correctly you’ll see a SequeLink ODBC Driver dialog that states that the Connection test was successful. If everything wasn’t configured correctly, you might get a TCP/IP parse error. That error usually means that the file isn’t available for ODBC access. If you get an error message, review the earlier steps in this exercise to make sure that all settings are correct.

Once you have a successful test click OK to return to the ODBC Data Source Administrator dialog shown in Figure 12.


Figure 12

Your new DSN should now appear in the list of User Data Sources.

The process for creating a DSN on the Mac OS is similar, but involves a little more work. Assuming the driver has been installed, you’ll need to open the ODBC Administrator utility, located in /Applications/Utilities. (You might also have installed the OpenLink ODBC Administrator utility, located in the same place. The OpenLink utility will work in a similar fashion to the stock Apple utility).

Unlike Windows, the Mac OS will not automatically register the driver upon installation. In order to make the driver available for use in DSNs, it’s necessary to register the driver by hand. To do this, open the ODBC Administrator, switch to the Drivers tab, and click Add. You’ll need to give


the driver a descriptive name of your own choosing, and also specify the path to the driver file itself. The path depends on whether you installed the driver in a system or a user directory: see the installation instructions furnished with the driver for more information.

Assuming the driver was installed in a system location (the file path would be /Library/ODBC/SequeLink.bundle/Contents/MacOS/ivslk18.dylib), the configuration choices for the driver might look like this:

Figure 13

Once the driver is installed and configured, it’s possible to proceed to creating a DSN. Flip to the User DSN or System DSN tab of the ODBC Administrator, depending on which type of DSN you wish to create. Choose Add, then specify the FileMaker driver configured earlier. There’s a bit more work to do here than on Windows. You’ll see the Generic ODBC Driver Setup dialog, where you’ll need to enter a number of keywords and corresponding values. The following diagram shows the necessary settings. For ServerDataSource, use the name of whichever FileMaker file you intend to access.

FileMaker Connectivitypage �0

Figure 14

If you’re doing much ODBC work on the Mac OS, you may want to consider downloading and installing the free OpenLink ODBC Administrator. (See the FileMaker Knowledge Base article #5505 - www.filemaker.com, under Support tab - for more information on this.) It functions similarly to the default Apple tool, but has a few nice additional conveniences, such as the ability to test a DSN, as shown in the following figure.

FileMaker Connectivity page �1

Figure 15

Using Microsoft Excel as an ODBC ClientNow that you have a DSN that can connect to the Sales file you need to use an ODBC client to try it out. Microsoft Excel can work in conjunction with the Microsoft Query Tool, which is an ODBC client. Launch Microsoft Excel to open a blank spreadsheet. Select Data>Import(Get) External Data>New Database Query, which will open the Choose Data Source dialog shown in Figure 16.

Note: FileMaker Pro cannot use ODBC data shared by FileMaker Pro on the same machine.

FileMaker Connectivitypage ��

Figure 16

Select the FMP� Sales DSN and click OK to open the Logon to SequeLink Service dialog shown in Figure 17.

Figure 17

Enter ODBC for both the User Name and Password, and then click OK to open the Query Wizard dialog shown in Figure 18.

FileMaker Connectivity page ��

Figure 18

All of the table occurrences in the host file will be listed in the Query Wizard. Note again that these are table occurrences, not actual tables. All ODBC/JDBC queries are executed against table occurrences, rather than directly against the underlying source tables. Select the Customer table. This will display the Customer fields. You could select one or more of those fields and click the > button to move them into the query pane. For this exercise, select the Customer table itself and click the > button to move all columns into the query, as shown in Figure 18. Click Next through the next few windows until you get to the Query Wizard – Finish dialog shown in Figure 19.


Figure 19

If this were the type of query that you could re-use on a regular basis, it would be worthwhile to click Save Query and store it for future use. For this exercise, just make sure the Return Data to Microsoft Excel is selected, and then click Finish to return the results of your query to Microsoft Excel. Click OK to accept the query.

Exercise 1 – Querying FileMaker Data From Excel

Enable the Sales.fp7 file for local ODBC/JDBC access. Create a DSN using the FileMaker ODBC Sequelink driver. Use this DSN to query the FileMaker data from Microsoft Excel.

If you have extra time and some SQL experience, experiment with using some different SQL statements to fetch different data sets into Excel.


Using FileMaker Server 8 Advanced as an ODBC/JDBC Host

Once a file, such as the Sales file, is configured for ODBC/JDBC access with FileMaker Pro 8, it only takes a few more steps to share the file using FileMaker Server 8 Advanced. Again, FileMaker Server 8 will not host files for ODBC/JDBC access – only FileMaker Server 8 Advanced has this capability.

The benefits of using FileMaker Server 8 Advanced instead of FileMaker Pro 8 or FileMaker Pro 8 Advanced are:

• FileMaker Server 8 Advanced can host up to 50 ODBC/JDBC connections while FileMaker Pro 8 can only host 5.

• FileMaker Server 8 Advanced can host ODBC/JDBC clients over the network while FileMaker Pro 8 can only host ODBC/JDBC clients that reside on the same computer.

Hosting the Sales.fp� FileIn order to host the Sales file for ODBC/JDBC remote access, you’ll need to host the file under FileMaker Server Advanced. The details of hosting a file under FileMaker Server are covered in the FileMaker Server module. Here we’ll concentrate on how to configure FileMaker Server Advanced to allow ODBC/JDBC access.

Configuring FileMaker Server � Advanced for ODBC Access on WindowsOnce the Sales.fp7 file is hosted you need to use the FileMaker Server Administration tool to enable ODBC access. Assuming the tool is open and connected to FileMaker Server 8 Advanced, select the server name in the left-hand pane and then select Action>Properties to open the FileMaker Server Properties dialog shown in Figure 20.


Figure 20

Select the Clients tab and make sure that FileMaker Pro 8 and ODBC/JDBC connections are set appropriately. Remember that all FileMaker clients and ODBC connections count against the total, so the number needs to be high enough to accommodate all FileMaker Pro 8 and ODBC clients. Click Server Advanced Settings to open the dialog shown in Figure 21.


Figure 21

Check Allow ODBC and JDBC connections and click OK to return to the FileMaker Server Properties dialog. At this point, the Server has been configured to respond to ODBC queries, and the file is now available for ODBC access. Use the ODBC control panel to test the connection. (Note: if your FileMaker Server is on a different computer than your ODBC client, you’ll have to change the DNS host parameter to point to the IP address or the host name of the FileMaker Server machine).

Had the Sales file not already been configured for ODBC access, you would have needed to go through the steps in the first exercise in order to enable ODBC/JDBC access for the file. This can be done while the file is being hosted by FileMaker Pro 8 or by FileMaker Server 8 Advanced.


Using FileMaker Pro 8 as an ODBC ClientSo far you’ve learned how to use FileMaker as a data source (host). FileMaker databases can also draw data from ODBC-enabled databases, thus acting as an ODBC client. Since it’s impractical to set up an Oracle server in class, this module will walk through an example that treats a set of comma-separated text files as a kind of data source.

As with any ODBC transaction, there needs to be a DSN set up using the appropriate driver. For this example, you’ll use the Microsoft Text File driver; a driver that can treat text files as an ODBC data source. To do this, create a new DSN, using the Microsoft Text File driver. Configure it as shown in Figure 22. You’ll want to configure it so as to look for text files in the appropriate demo files directory.

Figure 22

The example uses two text files, representing a database of salespeople and a database of transactions. The two datasets share a common field, the Salesperson ID. It’s possible to bring data from both files into a single FileMaker file.

Once the directory is set, you’ll want to choose Options > Define Format. For each file you’ll be querying, make sure to specify that it have a header of column information, and use the Guess button to force the driver to guess the names of the individual columns in the data source. Make sure to designate the file as tab-delimited. Figure 23 shows what this will look like.


Figure 23

Once the DSN is configured for both text files, launch FileMaker Pro 8 and select the option to open an existing file. When the Open File dialog opens, select ODBC Data Source from the Files of type pop-up, as shown in Figure 24.

FileMaker Connectivitypage �0

Figure 24

Once ODBC Data Source has been selected, the Select ODBC Data Source dialog opens, as shown in Figure 25.

FileMaker Connectivity page �1

Figure 25

Select the Sales_Text DSN that was created previously and click Continue to open the Enter Password dialog. There’s no password associated with these text files, so leave the user name and password blank and click OK to open the SQL Query Builder dialog shown in Figure 26.


Figure 26

In this example, you’ll bring data from two separate text data sources into a single FileMaker file. This will require two operations. Begin by choosing all the columns from Salespeople.txt, or entering by hand the SQL query “SELECT * FROM Salespeople.txt”, and choosing Execute,


as shown in Figure 26. This will create a new FileMaker file with a single table. Next, from the new file, perform an Import Records. Choose ODBC Data Source, and, as in the previous step, choose the Sales_Text DSN. This time choose all columns from Sales_Data.txt, or enter the SQL query “SELECT * from Sales_Data.txt”. Make sure to choose the option to Import As New Table. This will create a second table in the file, with sales data. You could now build a relationship between the two tables based on Salesperson_ID.

Exercise 2 – Querying ODBC Data From FileMaker

(This exercise is intended for use on Windows. As of this writing there was no widely available text driver for ODBC on the Mac OS).

Using the Sale_Data.txt and Salespeople.txt text files provided, first create a DSN that references those files. Make sure to configure the DSN for each file so that the file format (tab-delimited) and the individual columns are correctly recognized.

Create a new FileMaker table from one of the data tables using the Open command and choosing ODBC Data Source. Then bring the other table into the new file using the Import as New Table command and again choosing ODBC Data Source.

If you have a little extra time you may want to create a relationship between the two tables. You may also want to create scripts to automatically drop the existing data in each table and re-import it from the source.

Altering Data in an ODBC Data SourceThe previous examples have all dealt with queries. Using the Import or Open command from within FileMaker, it’s possible to create a new file, or add data to an existing file, based on a query against an ODBC data source. So far, none of these examples has had any affect on data in the original ODBC data source itself.

Using FileMaker Pro’s Execute SQL command, it’s also possible to add, edit and delete data in the original data source. For example, an SQL command such as:

INSERT INTO customer VALUES (3, ‘Sharyn, ‘Kellermann, ‘Active’, ‘Midwest’)

would create a new record in a table called “customer”, with the specified values inserted into the fields of the record. It would be possible to execute this SQL command using the Execute SQL script step from within FileMaker, as shown in Figure 27.


Figure 27

In the case of the sales data from the previous example, a command such as:

INSERT INTO Salespeople.txt VALUES (‘SP-8’, ‘Saul Phillipott’, ‘Jason Blasz’, ‘Eastern’)

could be used to create a new record in the Salespeople table. Interestingly, since the example uses a text-based data source, this will actually add a line to the text file. (Note that due to limitations in the Microsoft ODBC text driver, a number of SQL commands don’t work against text sources, including UPDATE and DELETE).

Exercise 3 – Insert Data into an ODBC Data Source

In a new FileMaker file, create a script that inserts data into the Salespeople.txt data source file using the Execute SQL script step.

Once you have this working using a static SQL command, create another script that assembles the SQL statement based on user input fields, so that the user can supply their own data.


Review Questions:

1. What is SQL?

2. What is ODBC?

3. What is JDBC?

4. What are the four components of ODBC?

5. What are the steps you need to go through to enable a file for ODBC hosting?

6. What are the steps you need to go through to enable FileMaker Server 8 Advanced for ODBC hosting?

7. What’s the difference between using FileMaker Pro 8 and FileMaker Server 8 Advanced as an ODBC host?

8. How many ODBC connections can you have to FileMaker Server 8 Advanced?

9. What information do you need to properly configure a DSN that references a file being hosted by FileMaker Server 8 Advanced?


Review Answers:

1. SQL is the language used by ODBC and SQL to perform database queries.

2. ODBC was created by Microsoft, and it stands for Open Database Connectivity.

3. JDBC stands for Java Database Connectivity. JDBC is similar to ODBC, but is designed specifically for Java programs, whereas ODBC is language-independent.

4. The four components of ODBC are the host, the client, the driver, and the driver manager.

5. To enable ODBC hosting for a FileMaker file, you need to enable at least one privilege set for ODBC access, and you need to enable ODBC sharing. You also need to choose whether you want to host ODBC connections for specific privilege sets or for all users.

6. To enable FileMaker Server 8 Advanced for ODBC hosting, you need to use the Server Administration tool to enable ODBC and JDBC sharing in the Client Properties dialog. You also need to make sure that the ODBC Server plug-in is installed and enabled.

7. FileMaker Pro 8 can only host ODBC connections to a client application that’s running on the same machine. FileMaker Server 8 Advanced can host remote ODBC clients. FileMaker Server 8 Advanced can also host more ODBC client connections.

8. 50.

9. To configure a DSN, you need to know the address of the server, the port number (2399), and the name of the database file that you want to query (without the .fp7 extension).

FileMaker Connectivity

Documents

Transcript of FileMaker Connectivity