5.2 XML Request Commands for Web Companion

5.1 Setting Up Web Companion for XML Requests

Web Companion is a plug-in or, more specifically, an application programming interface (API) used by FileMaker Pro to web publish your databases. The Web Companion API is designed to be both a web server and a Common Gateway Interface (CGI) application. Web Companion has been available since FileMaker Pro 4.0 under various revisions, but only since FileMaker Pro 5.x have the necessary commands for XML publishing been available. You should always use the most recent version of the Web Companion plug-in. This API file is placed in the FileMaker Extensions folder and is called Web Companion on the Macintosh. The Web Companion icon is shown in Figure 5.1. Web Companion is called WEBCOMPN.FMX or webcmpn.fmx and is installed in the SYSTEMS directory of the FileMaker directory if you are using the Windows operating system. The Web Companion will be loaded, as well as the other extensions, when FileMaker Pro is started and it is configured from the Application Preferences, Plug-Ins tab.

Figure 5.1: Web Companion plug-in icon

5.11 Web Companion as a Web Server

A web server receives requests from a browser when the user types in the location or clicks on a Uniform Resource Locator (URL) link. The web server returns and temporarily transfers formatted text pages, files, movies, graphics, and sounds to your computer. Your browser combines them and translates these into the documents you see on the World Wide Web. There is a two-way communication between the browser and the web server using the platform-independent Hypertext Transfer Protocol (HTTP). Most links you click probably start with "http://." HTTP is the communication and transfer protocol found in the Uniform Resource Locator of the link.

HTTP communication is stateless. A request is made from the browser and sent to the server. After a required file is returned, the connection to the server is broken until another request is made. A typical web page may have multiple requests for text, image, document, or sound files. These connections are sometimes called hits. You can specify in your browser preferences how many multiple simultaneous connections to make (four is the default maximum). After each connection or hit is completed, you are disconnected from the server although you may not think so.

As you design your web-published FileMaker Pro databases, contemplate the statelessness of HTTP. You make a request from the browser that is sent to the web server, in this case, the Web Companion API. The request is processed and a text page and/or images are displayed in the browser and the connection is stopped. You are not connected to Web Companion or FileMaker Pro continuously. You need to plan carefully for the actions of users who will not see changes until the browser window is updated by making a new request or refreshing a web page.

The communication between FileMaker Server hosted files and FileMaker Pro clients is quite different from web-published databases. The only delay in the data exchange from a user's client computer to FileMaker Server is waiting for the user cache (temporary locally stored data) to be written to the server. You can see practically immediately any changes you or another user makes to a database record using a server and clients.

The client-server model has features to prevent more than one user from trying to alter the same piece of information at the same time. This is called record locking and allows all users to see the same record in a multiuser situation but only gives to one user permission to make changes to a record. Because the web is stateless it does not provide this protection. When publishing a FileMaker Pro database on the web, you must carefully analyze that you have not assumed record locking will take place. Fortunately, there are some tricks built into FileMaker Pro and the Web Companion commands to check for ownership of a record whether on a network, an intranet, or the Internet. You will read about these tricks and how to maintain state (associate the web user from the last action to the next action) in this chapter.

5.12 Web Companion as CGI

The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or web servers. Hypertext Markup Language was designed to be a static page display mechanism with embedded images and hyperlinks to interconnect various pages. To perform actions such as form processing, image maps, dynamically produced pages, or database interactivity, gateway interfaces were created as an extension to HTML. CGIs are separate applications or scripts that run on a web server and accept commands the web server cannot understand. This is called server-side processing. If the particular commands are acceptable by a Common Gateway Interface, results, often in the form of HTML pages, are returned to the web server to be passed to the browser. Common CGIs are written in a variety of languages, such as Perl, UNIX shell, AppleScript, Python, TCL (Tool Command Language), C/C++, and Visual Basic.

Overview of the Processing Steps for a Web Server and CGI

1. The user enters a location in the browser, clicks a link, or clicks a form submit button.

2. A request is sent to the web server through Hypertext Transfer Protocol (HTTP). This request can also contain hidden information, such as the page from which the request was initiated, a field to search, or the name of an image to apply in the page.

3. The web server processes the request, translating the commands it understands and passing on to the CGI any information it does not understand. Only if the location of the CGI is included in the request can the web server pass along the request. You specify the location of Web Companion by including "fmpro?" in your links or form actions.

4. The CGI accepts the information it needs from the request and communicates with any resources necessary to process the request, such as a database or file server.

5. If the request is sent to FileMaker Pro, the CGI (Web Companion) tells FileMaker Pro to perform actions as if the user had manually entered them or performed a FileMaker Pro script. These actions will create new records, edit fields, delete records, and find and sort records. CGI requests to FileMaker Pro in CDML or XML can be actions, replacement text, or variables.

6. Any actions performed will return a result, so the Web Companion CGI passes the results, even errors, back to the web server. This is returned to the web server as HTML, which the web server understands.

7. The Web Companion web server sends the HTML results back to the browser along with any associated files, images, or sound and breaks the connection.

8. The CGI portion of the Web Companion API performs the translation of the unique commands sent to it. These commands are either XML and/or a proprietary set of commands called Claris Dynamic Markup Language (CDML). Some of the commands are actions to create new records or save and return variables like the current database. Some of the CDML commands are replacement text, for example, returning field contents, controlling flow, or providing today's date. The commands for XML publishing are similar and use many of the same names as CDML. You will read more about CDML and FileMaker Pro XML commands in this chapter and in Chapter 6.

Now that you know what Web Companion is and a little about how it works as a web server and a Common Gateway Interface, you are ready to continue the setup of FileMaker Pro for web publishing. If you have not already done so, verify that the Web Companion plug-in is in the proper location of your FileMaker Pro directory: WEBCOMPN.FMX is in the SYSTEM directory for Windows; Web Companion is in the FileMaker Extensions folder for Macintosh.

Web Companion can also be used as an Asynchronous Common Gateway Interface (ACGI). Asynchronous means both connections can communicate without waiting for a reply. Web Companion can communicate asynchronously with another web server. The advantages of "Alias-of-FMP-as-an-acgi" addressed in Appendix B: Resources are speed, caching, control of MIME mappings, use of other CGIs, and security features.

5.13 Static or Persistent Server Address

Web Companion does not require that you be using TCP/IP as the network protocol TCP/IP in FileMaker Pro, but TCP/IP networking must be set up correctly on the machine. This setting is found in Edit, Preferences, Application, General tab. You may need to restart FileMaker Pro if you change this setting. If you cannot choose TCP/IP, verify that the TCP/IP extension is in the same folder as Web Companion. You may also need to install a network card and/or driver and check your network settings for your computer. You can read more about FileMaker Pro networks in the document A Guide to Networking FileMaker Pro Solutions, referenced on p. 166. Section 5.15, "Standalone Considerations", may help you set up some of the settings for network or standalone web publishing.

Figure 5.2: TCP/IP plug-in icon

TCP/IP (Transmission Control Protocol/Internet Protocol) is used for sending data around the Internet and networks as small chunks called packets. Used together, TCP maintains the connection between two systems and tracks the packets so that they are sent and reassembled correctly and IP delivers the data by routing the packets from the computer to a local network and on to the Internet.

The address you assign your computer or server so that other systems may identify it is the IP address. This number must be unique and composed of four segments separated by "." (dot). Each segment is a number from 0 to 255, reflecting the maximum decimal digits that correspond to the hexadecimal numbers 00 to FF or the binary digits (bits) 00000000 to 11111111 in a byte (any single ASCII character).

For another computer to access the data on your server or a web server, it must know the location. As an HTTP request, the location can be formatted in a URL such as: http://192.0.0.10/ or as a name of a particular domain: http://www.mydomain.com/. The domain name is convenient to humans, but the servers and TCP/IP are looking for the number. Domain Name System (DNS), a network of servers with a list of domain names and corresponding IP addresses, will resolve this name to the correct number and pass the information along. It also allows you to change the IP address of http://www.mydomain.com, for example, to work transparently without you having to pass the new IP address to everyone.

Web publishing, including XML publishing, with FileMaker Pro requires that the databases are open on a system with an address that can be found by other computers. FileMaker Pro Help recommends a static IP address. Whether you host databases for a network, a browser accessed intranet, or the Internet, carefully consider the security concerns when these files are available. For security reasons, you may have the files hosted only at times when they can otherwise be regulated. Regardless of when your files are available, you need to provide the location to the user. A unique and static IP address is more convenient for sharing your databases. Your server may also have a domain name that can resolve to an IP address.

Warning 

ISPs (internet service providers) can offer to you a unique and static IP address. However, they may not have the equipment or software necessary to host FileMaker Pro files. You may need to co-locate (provide your own servers at an ISP) or have a persistent connection to the Internet from your own location. You may also find hosting companies that provide this service.

5.14 FileMaker Pro Products for XML Publishing

A single copy of the standard FileMaker Pro application can be used as a small network host or a web publisher. As a web-publishing application, FileMaker Pro 5, 5.5 (FMP5), and FileMaker Pro 6 support connections to Web Companion for ten users' IP addresses in a 12-hour consecutive period. Under no circumstances should this machine also be used as a client while it is hosting databases.

For development and testing or only a very small number of users, you will be able to web publish well-formed and valid XML documents with standard FileMaker Pro 6. For more efficient web publishing, place your files on FileMaker Server and open with the Host dialog. The databases are enabled for web sharing before being placed on a networked computer with FileMaker Server. Any FileMaker Pro application, except runtime versions, enabled for web publishing can produce XML from an HTTP request, even if it is part of the network. The XML export and import work with FileMaker Pro and not FileMaker Server. This gives each person the ability to work with XML.

FileMaker Developer (FMD) installs an expanded version of FileMaker Pro that includes script debugging and Database Design Report. It also contains additional items that may assist you in web-enabling your databases. You get the FileMaker Developer Tool, Design Tools sample files, External FileMaker API files, and the Developer's Guide. These additional items assist you with renaming files and maintaining relationships across multiple related files. Examples and usage of JDBC and XML is included with FileMaker Developer. Other features of FMD are beneficial to developers working with network or web publishing of files and include: creating a Kiosk mode so that the user does not see some of the standard operating system and application elements or interface, ODBC support, renaming files while maintaining the relationships in multiple files, examples, and artwork. The new Database Design Report gives you a listing of the fields, scripts, layouts, relationships, value lists, and passwords. The report options are used to create a new database, add to an existing database, or create an XML/XSL report summary or full report. These options were explored in Chapter 4.

FileMaker Pro Unlimited (FMU) is a special version of the standard FileMaker Pro application that allows an unlimited number of IP connections for web publishing from FileMaker Pro. The FileMaker Pro Unlimited install also includes the Web Server Connector (WSC). The WSC is a Java servlet that extends the functionality of Web Companion by working with some existing web servers. If you are using a middleware application, CGI, or application server, FMU can be used to facilitate the integration of your applications and web servers with FileMaker Pro. Web Companion does not have built-in support for Secure Socket Layer (SSL) and server-side includes (SSI), so the Web Server Connector can be used as a plug-in by your web server and take advantage of these features.

Using multiple FileMaker Pro Unlimited sets, you can set up a Redundant Array of Inexpensive Computers (RAIC) and the Web Server Connector to process requests and distribute the load. If you are serving the same databases on each computer in the RAIC and one goes down, the WSC will forward the request to another. See the FileMaker Pro Unlimited Administrator's Guide for more information about FileMaker Pro Unlimited and about using the Web Server Connector Java servlet. FileMaker Pro Unlimited will also be used with middleware with FileMaker Pro for web publishing.

Using Middleware with FileMaker Pro Unlimited

Any application that can make an HTTP request to FileMaker Pro can be used to create, edit, and delete records. For example, the web application server ColdFusion, by Macromedia, can make a request and create a new record. The first example that follows shows the hypertext link, followed by the equivalent FORM request. You can see in the last example how ColdFusion <cfhttp> can send the same information to FileMaker Pro:

1. HTTP request:

    fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-format=   -dso_xml&-new 

2. FORM request:

    <form action="fmpro" method="post">     <input name="-db" type="hidden" value="Xtest.fp5" />     <input name="-lay" type="FormField" value="web" />     <input name="firstname" type="hidden" value="Joe" />     <input name="lastname" type="hidden" value="Brown" />     <input name="-format" type="hidden" value="-dso_xml" />     <input name="-new" type="submit" value="" /> </form> 

3. ColdFusion request to create a new record in FileMaker:

    <cfhttp url="hostname/fmpro" method="post">     <cfhttpparam name="-db" type="FormField" value="Xtest.fp5">     <cfhttpparam name="-lay" type="FormField" value="web">     <cfhttpparam name="firstname" type="FormField" value="Joe">     <cfhttpparam name="lastname" type="FormField" value="Brown">     <cfhttpparam name="-format" type="FormField" value="-dso_xml">     <cfhttpparam name="-new" type="FormField" value=""> </cfhttp> 

FileMaker Server (FMS) is a special database engine application that is optimized for serving FileMaker Pro files over a network. It cannot directly create, open, or edit FileMaker Pro files, but it shares them as a host and takes care of some of the housekeeping necessary to rotate client users in and out of the files. FMS increases the speed of operations and allows up to 250 users to access the files.

FileMaker Server cannot web publish files directly, as this function is performed by the Web Companion. The FileMaker Pro Web Companion plug-in works with FileMaker Pro, FileMaker Pro Unlimited, and FileMaker Developer only. However, I strongly recommend that all databases to be web published be placed on a computer and hosted with FileMaker Server. FileMaker Server can greatly stabilize the workload.

Database files can be enabled for Web Companion sharing and set to Multi-User (see "Sharing Databases for Web Companion" in section 5.17) before being opened by FileMaker Server. FileMaker Pro or FileMaker Pro Unlimited then opens them remotely. The Web Companion, as a part of these client applications, becomes the web publisher. Using FileMaker Server is not required but strongly recommended for production systems. This arrangement is not a requirement but can improve the web/network experience.

Figure 5.3: Setting network protocol for FileMaker Pro

For additional information about setting up a FileMaker Pro network, consult the document A Guide to Networking FileMaker Pro Solutions by Wim Decorte and Anne Verrinder. This guide is a thorough explanation of how to set up TCP/IP as your network on both the Windows and Macintosh OS. The document covers:

• IP addresses and subnet masks

• Finding and pinging your IP address

• Sharing databases on a network

• Memory considerations

• A tutorial on opening hosted databases and creating an opener database file

• A review of the products and how peer-to-peer and client-server models differ

• How to monitor with server administration and server event logs

• The techniques and need for backups of your databases

This document is available for download from http://www.wordware.com/fmxml, the book's web site, http://www.moonbow.com/xml, and from Kim Jordan at http://www.pair.com/kjordan/NetworkingGuide.pdf.

Another useful guide is the TechInfo document from FileMaker, Inc., http://www.filemaker.com/support/techinfo.html, TechInfo #101295, "Optimizing Network Performance for Shared Databases." Among this document's recommendations:

• Use a fast network connection

• Use TCP/IP protocol

• Locate your databases on the host computer

• Host the databases on a computer running only FileMaker Pro

• Host your databases with FileMaker Pro Server (a.k.a. FileMaker Server)

• Optimize the host computer

• Optimize the guest computers

• Optimize connecting as a guest

• Optimize the databases

In summary, Web Companion is used for XML publishing, and FileMaker Server cannot directly perform this task. The Web Companion API is only available in FileMaker Pro, FileMaker Developer, and FileMaker Unlimited. Files set to Multi-User and sharing for Web Companion and hosted on the FileMaker Server are available for web serving, too. Files for web publishing must be placed on the same machine with FileMaker Server and opened through Hosts on a client machine with FileMaker Pro or FileMaker Pro Unlimited. There are several options for hosting files over a network and web publishing the same databases. See "FileMaker Pro Unlimited", section 5.18.

5.15 Standalone Considerations for Testing

You can set up your computer to test web publishing from FileMaker Pro without being connected to the Internet or a network. Standalone testing allows you to be the web publisher and the client (browser) all on the same computer. If you already have TCP/IP set up on your computer, you do not need to change it. Review the final paragraphs of this section, "Finish TCP/IP Setup for All Systems", for hints on how to use this method. The following recommendations are from the FileMaker Pro Help topic, "Testing the Web Companion without a network connection", with minor revisions.

Macintosh OS 8.x, 9.x Open Transport TCP/IP Configuration

Important: Follow the instructions and duplicate an existing configuration, make the changes, and save them. You can safely return to your current settings when needed.

1. Open the TCP/IP control panel. This dialog is shown in Figure 5.4.

   
   Figure 5.4: TCP/IP control panel (Macintosh OS 9.1)

2. Under the File menu, select Configurations.

3. Click on any configuration to highlight it and then click on the Duplicate button.

4. Give this new configuration a name, such as Web Companion Testing.

5. If prompted to make these new settings active, click the Make Active button.

6. Enter the following values in the new configuration:

   • Connect via: AppleTalk (MacIP)

   • Configure: Using MacIP Manually

   • MacIP server zone: <current AppleTalk zone>

   • IP Address: 192.0.0.10

   • Router address: (leave blank)

   • Name server addr: (leave blank)

   • Implicit Search Path: Starting domain name: (leave blank)

   • Ending domain name: (leave blank)

   • Additional Search domains: (leave blank)

7. Close the TCP/IP control panel. If asked to save your settings, click Yes.

8. To revert to your previous settings, open the TCP/IP control panel, press command+K, or choose File, Configurations, and make the original TCP/IP configuration active.

Setting TCP/IP on Windows 95, 98, NT, Me, and 2000

Important: Following these instructions will remove any network connection currently in place on your Windows PC. If your PC is already connected to a network or to an ISP, please make a careful note of how your Windows PC was originally configured before making these changes.

1. Open the Network control panel (in the Control Panel directory). The dialog for setting TCP/IP on NT is shown in Figure 5.4.

2. If you have any network adapter, network clients, or network protocols installed, remove them.

3. Click the Add button. Then, double-click on the Adapter item in the menu.

4. Select Microsoft from the list of manufacturers. From the right-hand menu, select Dial-Up Adapter, and click OK.

5. In the Network control panel again, click the Add button. Then, double-click on the Protocol item in the menu.

6. Scroll down the list of manufacturers until you reach Microsoft. Select it. Then, from the right-hand menu, select TCP/IP, and click OK.

7. In the list displayed in the Network control panel, you should see both a Dial-Up Adapter and the TCP/IP protocol. If you see anything else, such as an IPX/SPX or NetBEUI protocol, remove it.

8. Double-click the TCP/IP protocol to edit its properties. Enter 10.10.10.10 as the IP address, disable WINS and DNS services, and enter 10.10.10.1 as the gateway. Click OK.

9. Click OK and restart your computer.

Figure 5.5: TCP/IP control panel (Windows NT)

Setting TCP/IP on Macintosh OS X

1. Choose System Preferences, Network. The dialog for Macintosh OS X is shown in Figure 5.6.

   
   Figure 5.6: TCP/IP control panel (Macintosh OS X)

2. From the Location: pop-up, select New Location.

3. In the Name your new Location dialog, enter Web Companion Testing.

4. Select Built-in Ethernet from the Configure pop-up (this may vary depending on your network).

5. Select the TCP/IP tab and enter the following information:

Finish TCP/IP Setup for All Systems

You are now ready to use your computer to test FileMaker Pro web publishing without an Internet or Ethernet connection. If you changed your TCP/IP settings, you may interrupt your current Internet or Ethernet connections (including email). Remember to change your TCP/IP settings back when needed. Only set up a new TCP/IP configuration if you do not have a network to test your files. A simple network of two computers using an Ethernet crossover cable may be preferable to disrupting your existing network access or Internet configurations.

You must choose TCP/IP as your network protocol in FileMaker Pro under the General tab in the Edit, Preferences, Application dialog.

After you restart FileMaker Pro, you can use the Web Companion for instant web publishing, custom web publishing, JDBC publishing, or XML publishing. You access the web server by entering the IP address you created as your "domain" in the URL: http://192.0.0.10/ or http://10.10.10.10/. You may also access the Web Companion with the default loopback IP address of http://127.0.0.1/. The loopback address may be called with the default server name: http://localhost/. If the defaults do not work, try the IP address of your machine.

5.16 Web Companion Setup

After you have TCP/IP set correctly on your computer through a network or for standalone testing, you are ready to configure the Web Companion plug-in for publishing. The important items of which to be mindful are the TCP/IP extension, the Web Companion plug-in, the Web folder (located in the FileMaker Pro folder), and the Web Security folder. The Web Security folder contains the Web Fields_.fp5, Web Users_.fp5, and Web Security_.fp5 databases, along with sample web pages for remote administration and the guide, "Web Security.pdf." Another step to web publishing is enabling particular databases. The next section in this chapter, "Sharing Databases for Web Companion", covers where to place your files (databases and web files). Web security is discussed in section 5.41, "Security with Web Companion."

Open a FileMaker Pro application and choose Edit, Preferences, Application and then the Plug-Ins tab. In Windows FileMaker, Figure 5.7 is the Application Preferences dialog for selecting plug-ins. Enable the Web Companion plug-in if it is not already checked. You can enable the Web Companion plug-in without any databases open. If you launch the application and cancel the Open File dialog or the New Database dialog, you have access to the plug-ins and can configure the Web Companion.

Figure 5.7: Application Preferences Plug-Ins tab

The menus have been changed slightly for Macintosh OS X. The Preferences are now listed under the second menu, FileMaker Pro (File is the third menu). Choose FileMaker Pro, Preferences, Application and then the Plug-Ins tab. The configuration is the same, only the location of the menu has changed.

Look at the Web Companion Configuration dialog in Figure 5.8. It may be beneficial for you to understand what it does as it will be used for XML publishing. If you have left the Application Preferences Plug-Ins dialog, return there by choosing Edit, Preferences, Application and the Plug-Ins tab. Highlight the Web Companion plug-in; if it is enabled (checked) you will see information in the Description box and the Configure button. Click the Configure button to view the Web Companion Configuration dialog.

Figure 5.8: Web Companion Configuration dialog

The Web Companion user interface is available for setting up Instant Web Publishing (IWP) and is used by custom web publishing. You can use IWP as a test to see if your setup is working correctly, so leave Enable Instant Web Publishing checked for now. Also, you can select a default home page to be viewed in your web browser if a particular database is web published. Built-in is the default home page for Instant Web Publishing and available only if Enable Instant Web Publishing is checked. If you do not have a database open for web sharing and Enable Instant Web Publishing is unchecked, the home page pop-up will be blank. A list of web pages in the top level of the Web folder will be listed here if you have a database open and shared using Web Companion.

The Language pop-up is also available here. It is quite unique, as it changes the interface elements and onscreen help of the instant web published database according to the language selected. Your choices for language are Dutch, English, French, German, Italian, Spanish, and Swedish. The Display parameter is used by the CDML tags [FMPCurrentAction], [FMP-FindOpItem], and [FMP-SortOrderItem]. It can be a source of confusion and possible errors if the language is accidentally changed. If you get unpredictable results, you might want to check this setting. It has no apparent effect on XML publishing and does not change the language of your field names and field contents.

Logging gives you three check boxes to select. The Access log file option, if checked, records every request to Web Companion from a web browser by creating and maintaining the file access.log in your FileMaker Pro folder.

For each request, this access log file lists:

• The remote IP address or hostname

• The rfc931 required by UNIX systems for determining the identity of a user of a particular TCP connection with the Authentication Server Protocol

• The authenticated user name

• The date and time of the request

• The request from the user as sent by clicking a link or submitting a form

• The HTTP status of the request. For example, if you go to a web site and the page is moved or no longer exists, you may receive a notice stating "404 Not found." This is the HTTP status for that request. This is also called the Server Response Code.

• The size of the document (web page, graphic image, or other type of file) returned to the browser

The error log file (error.log) is also created and stored in the FileMaker Pro folder if you have selected this option. This file lists the date and time with the error number and description of any unusual errors. Common errors are not reported to this file. There is no definitive list of errors considered common by Web Companion. You should remember this does not list all errors encountered. The access.log (above) provides all information, including errors.

The information log file (info.log) is placed in the FileMaker Pro folder and accepts any information you have specifically placed there with a custom CDML request [FMP-Log: _your text here_]. The date and time of the request is logged.

Remote Administration is used to access the Web folder from another location. Your options are Disabled, Requires no password, and Requires password with a field to specify the password. The Web folder is located in the FileMaker Pro folder of the machine, which is used for web publishing. External files, such as images, can be placed in the Web folder. You can use HTTP Put and Get to exchange files, and you do not need direct access to the machine. Remote Administration access also allows you to administer the Web Security databases remotely. If you will be using the Web folder for any reason, it is advisable to set the configuration to Requires password and specify a password or to disable remote access.

Security gives you some options to allow or deny access to your web-published databases. Web Companion security is not the only precaution you should implement. If you already have passwords enabled in your databases and different groups and access features (browse, create, and edit), you use the same access for your web published databases. Any permission not granted by password is denied to the user through web published files. Your current passwords and groups are used if you select FileMaker Pro Access Privileges. If you have the Web Security databases open, you will see the option Web Security Database; otherwise, this option is disabled. The "Security with Web Companion" section later in this chapter will explain where these files should go and how to use them.

Another security option is Restrict access to IP address(es). Here you can specify a single IP address, a list of addresses separated by commas, or a range of addresses. The range is really a single address with an asterisk replacing one segment of the four-part IP address (123.456.78.∗). See section 5.13, "Static or Persistent Server Address", for IP address information. Only those IP addresses listed are allowed to access your databases. This feature can be especially beneficial to databases hosted on an intranet (internal network), but it can be used for any web publishing where this needs to be restricted.

The default TCP/IP port number is 80. Port number 80 is a specific designation for the Hypertext Transfer Protocol (HTTP). Assigning a port allows TCP to know the endpoint of a connection. The port number may be registered or generally reserved for common usage. Port 80 is used by HTTP and may be used by your web server if you are using one. You may specify any port number in the Web Companion Configuration dialog, but if it is not 80, you must use it in the URL (Internet address) when accessing your web-published database. If you assign port 123, for example, you would use http://mydomain.com:123/the/rest/. Since the default port number is 80, you need not specify it in the URL: http://mydomain.com/the/rest/.

If you must use a port other than 80, FileMaker Pro Help suggests, "FileMaker, Inc. has registered port number 591 with the Internet Assigned Numbers Authority (IANA) for use with FileMaker Pro Web Companion."

Warning 

If you just pick some other port, especially ports below 1023, some part of your computer may stop working and/or FileMaker may act strange when you try to give it mail or FTP traffic.

The first time you select the Web Companion plug-in after you install FileMaker Pro on Macintosh OS X, you will be instructed to specify a port number. Mac OS X reserves all ports 0 to 1023 for security reasons. You may use port 80 or port 591 for Web Companion on Mac OS X, but you must set this up. If you do not change this when you first install, you must reinstall FileMaker Pro to reset the port. If you choose to use port 1024 or higher, specify this in the Web Companion Configuration dialog and use it in your URL.

IP Guest Limit is the number of IP addresses allowed access to your web-published databases in a concurrent 12-hour period. If you have FileMaker Pro 5, 5.5, or 6, this will be set automatically to 10. If you have FileMaker Pro Unlimited, this is automatically set to Unlimited. If you have installed FileMaker Pro Unlimited and see 10 in this location, try reinstalling. The IP Guest Limit does not affect the number of connections you may have set up if you use FileMaker Server 5. This setting only affects web publishing.

5.17 Sharing Databases for Web Companion

This section discusses where to put your FileMaker Pro databases and any web files or documents (including XML or XSL files). It is important to think about security while doing this setup. If you do not password protect the files, anyone on the network can change the files! Any database set to sharing with Web Companion is available for data extraction and possibly data corruption or deletion. Whatever password access you allow or limit in your databases also works for web-published databases.

Databases

If your databases are currently being hosted with FileMaker Server, close them on the server, move them if necessary to a computer with FileMaker Pro 6, and open them off the network. Open your database and set it to Single User to make the changes. Choose Sharing from the File menu, and select the Single User button under FileMaker Network Sharing. Then under Companion Sharing, select Web Companion. If you will be placing this file back on FileMaker Server, you may leave it as Single User if you have FMS set to share single-user files or change it to Multi-User or Multi-User (Hidden). Figure 5.9 shows the sharing dialog and the Multi-User (Hidden) option selected. It may or may not be necessary to set to Single User before sharing with Web Companion. However, I have found this to be helpful. Make your other sharing options after enabling Web Companion.

Figure 5.9: File Sharing dialog

Databases may be placed in the Web folder, but they also are more accessible this way. It is much more secure if you leave databases outside of the Web folder. However, if you will be using Remote Administration in the Web Companion Configuration dialog, files need to be in this folder. You may use an alias or shortcut to the actual file, as long as this is placed in the Web folder.

The FileMaker Pro Developer's Guide, p. 6-18, suggests: "For better security, place your databases in subfolders within the Web folder. This way, unauthorized users will not know the rest of the path even if they gain access to the Web folder."

Do not place your Web Security database in the Web folder. Do not enable the Web Security database sharing with Web Companion. If you have Web Security databases open, Web Companion will use them.

Databases may be placed on a server and opened with FileMaker Server. Access to the databases is via the Hosts button. FileMaker Server does not web publish, as this is a function of the Web Companion plug-in. Launch FileMaker Pro or FileMaker Pro Unlimited with Web Companion enabled and open the databases by selecting File, Open and clicking the Hosts button in FileMaker Pro. New in FileMaker Pro 5.5 and 6 is Open Remote under the File menu. Databases hosted by FileMaker Server will be available for web publishing but not for control through Remote Administration.

Text Pages

FileMaker Pro Web Companion is looking in the Web folder when you specify the URL http://localhost/ or http://127.0.0.1, the IP address, or the domain name of your database web publisher for all files called directly. These text files may be HTML files (.htm or .html), JavaScript files (.js), include files (small reusable code of any type: .inc or .txt), cascading stylesheets (.css), and .xml and .xsl files. XML and XSL files for import and export should not be placed in the Web folder.

All of your web pages can be placed in the Web folder of the FileMaker folder. You can place them there as aliases (Macintosh) or shortcuts (Windows) for greater security. You may place them in subfolders in the Web folder, but remember to include the subfolder name in your path to the file. You can also have text documents on other servers, but each must be called with the full path to the document. Since any file placed in the Web folder is now accessible, secure documents may need to be placed on another server that provides directory security (login with username and password). The new folder, cdml_format_files with FileMaker Pro 6, should be where you place CDML files for added security. See the document folder_info.htm installed in the cdml_format_files folder for more information.

Always provide a default file in every directory to help prevent listing of the files in any directory. This file can be a link back to your main page. The file is a simple HTML file called default.htm, default.html, index.html, or index.htm. The "Security Blankets" section later in this chapter gives some examples of default files that you can use.

Images

Image files can be placed in the Web folder, a subfolder, or multiple subfolders of the Web folder. Images may also be located on another web server. If you will be exchanging images with any frequency, images on an FTP-capable server is advisable. Specifying their location publishes images. This location can be dynamically placed on a web page if the path is a field in the database. Images that change can simply be uploaded to the same location, and the database need not even be revised if the file name is the same. Static images such as a site logo can also be used with a field reference or listed on the page requesting it. Remember to use full paths for images located on another server.

Include the default HTML file, even in Image folders. Your link to images may be http://mydomain.com/images/ and users could enter this in a browser. The default file directs the user back to your main page rather than allowing these files to be listed.

Consider the browser that will be displaying these images. Optimize them for the smallest possible size and provide alternative images for wireless devices. Give all images an "alt" attribute (name of the image) for browsers that do not display images.

Other Files

You may have other files available for download, such as Adobe's Portable Document Format (PDF). Browser preferences can be set to display these files or download them. If in doubt, compress them for convenient download. Binary files compressed with Aladdin Stuff-it, available at http://www.aladdin-sys.com, WinZip, available at http://www.winzip.com, or similar applications can be placed in the Web folder or any location, as long as the path to the file is available. If you have binary files, provide multiple options for download. Consider platform and browsers by compressing the files for any user.

5.18 FileMaker Pro Unlimited

FileMaker Pro Unlimited and the FileMaker Pro 6 Unlimited Administrator's Guide (included with installation) suggest eight configurations for using Web Server Connector. You can read more details on how to set these up with various servers in the guide. These configurations are:

• FileMaker Pro Unlimited on a single machine

• FileMaker Pro Unlimited, the FileMaker Web Server Connector, and web server software on a single machine

• FileMaker Pro Unlimited on one machine, the FileMaker Web

• Server Connector on another machine

• RAIC with multiple copies of the same database

• RAIC with multiple, different databases

• RAIC using FileMaker Server as a back-end host

• RAIC using FileMaker Pro as a back-end host

• FileMaker Pro Unlimited with middleware

RAIC is defined as a Redundant Array of Inexpensive Computers. Web Server Connector can switch among the servers in an RAIC. Computers running OS X cannot serve as an RAIC machine.

Middleware is defined as another application that can query FileMaker Pro through Web Companion or the Web Server Connector. Some applications that are considered middleware are Lasso, Cold Fusion, Tango/Witango, Perl, PHP, Java, and Flash.

The Web Server Connector (WSC) is a Java servlet. A servlet is a Java component that is a platform-independent method for building web-based applications, without the performance limitations of CGI programs. The FileMaker Pro 6 Unlimited Administrator's Guide, included with FileMaker Pro Unlimited, says, "A servlet is a Java-based web server extension that is an alternative to traditional, platform-specific CGIs."

The minimum requirements for using WSC on Windows 95, 98, NT, or later is with Java Runtime Environment (JRE) 1.1.8. Mac OS Runtime Java (MRJ) 2.1.4 is needed for use with Macintosh OS 8.6 or later. Using Web Server Connector with a version of FileMaker Pro other than Unlimited will produce an error. For all three platforms (Windows, Mac OS X Server, and Red Hat Linux), the version of JDBC driver needs to be JDK/JRE 1.1.8 to 1.3 compliant. The latest Java Runtime Environment software is available on the Sun site, http://www.java.sun.com.

The advantage of using the Web Server Connector is the ability to use FileMaker Pro Unlimited with another web server. FileMaker Pro Web Server Connector works with a wide variety of other web servers. See http://www.filemaker.com/ for the latest versions for web publishing FileMaker Pro.

Web Server Connector works with FileMaker Pro Unlimited and Web Companion to provide additional functions. Some of these functions are a part of the WSC, such as configuring an RAIC to share the load of database serving on the web. It can redirect a request to another machine if the Web Companion is not responding on any machine. Web Companion does not have built-in support for secure web serving. The Web Server Connector can be used to work with any of the supported web servers that have Secure Socket Layer (SSL) or server-side includes (SSI).

Secure Socket Layer is a protocol similar to HTTP. A program is between the HTTP and TCP protocols to send encrypted data. A key is provided on both ends so the data can be sent securely. Links to secure servers often use https:// at the beginning of the link. The browser may change to reflect a secure site. Sometimes a key is displayed and/or there is a blue border around the page on a secure site. Web Companion can send messages to and receive messages from a secure site but does not encrypt the data itself. Encryption is the function of the SSL.

Server-side includes are common on some web servers. A command is sent to the server, interpreted, and returns a value, such as the current date. In the format similar to a comment, <!–#command parameter(s)="argument"–>, the server processes the command. They function more like XML processing instructions than comments. If the web server does not understand the command, however, it is ignored like a comment. Some commands will allow you to include a file, execute an external program, return the date of the server, the document name, or the date the document was last modified, for example.

Chapter 7, "Using the Web Server Connector as host", of The FileMaker Web Server Connector Administrator's Guide, found in FileMaker Pro Unlimited, has details for configuring the WSC. The setup is done through your browser. You can open the configuration file remotely by entering the URL http://yourIPorDomain/ FMPro?config or by pointing to the file FileMaker WSC Admin on your hard drive. You have three options on the first page: Configure by Host, Configure by Database, or Configure Administration Account. This home page is shown in Figure 5.10.

Figure 5.10: FileMaker Web Server Connector Admin

In addition to the log files you can generate with the Web Companion, the Web Server Connector (WSC) produces two other log files, FMWSC.log and FMWSCNative.log. These files contain the date and time of server start and close events for each server and any errors that the servlet encounters. Together, the WSC and WC log files can list problems with the servers or individual files on the servers.