5.3 Performing Scripts on Web-Published Databases

5.2 XML Request Commands for Web Companion

A request is sent to FileMaker and Web Companion from the browser as an HTTP request. HTTP has many methods for a request. Post and get are the most common and the get method of a hyperlink is used in this section. The post method is more common with form submission and will be discussed in section 6.5, "Using the Form Element to Make HTTP Requests." A request made to Web Companion must be formatted as other HTTP requests. The location of the server may be included in a hyperlink, followed by a port number (if any) and the location of the CGI. The initial query is to Web Companion itself. It asks the web server to find the CGI with "fmpro?". All other information after the question mark (?) is the request commands processed by the Web Companion CGI. Each additional piece of the request is separated with the ampersand character (&) and name-value pairs or other CGI commands. These calls to Web Companion are shown here:

 fmpro? fmpro?doThis&doThat&anotherRequest&action 

You should remember that the request must be URL-encoded (ready for HTTP request). If you have any database names or layout names with spaces, for example, they must be converted or they may cause errors. The space character may be changed to "+" or "%20." You can use the External("Web-ToHTTP", parameter) function in a script or calculation to make the conversion for you. An example script step is included:

 Set Field [ myfilename, [External("Web-ToHTTP", Status(CurrentFileName) ]

5.21 Database and Layout

A request is placed to a specific database and layout. Example requests are shown in Listing 5.1. When you make a web request for a layout, FileMaker Pro navigates to an open file and to a particular layout, as with a Go to Layout[] Script step. Any fields residing on the named layout in that database are accessible to the request. FileMaker Pro does not need to physically open the layout but has access to just those fields. The command for specifying the correct database is the parameter -db, and the command for layout is the parameter-lay.

Listing 5.1: Database and layout requests

 -db=Xtests.fp5 -lay=web -db=Xtests.fp5&-lay=web fmpro?-db=Xtests.fp5&-lay=web& ... 

Naming Suggestions

Web Companion will produce well-formed and valid XML from your database. Well-formed XML does not like spaces in element names. Web Companion will convert these to an underscore (_). If your database is named Invoice Items.FP5, it will be converted to Invoice_ Items.FP5. The same will apply to layout names, field names, script names, value list names, and relationship names. The FileMaker Pro Help topic, "Designing cross-platform databases", suggests that filenames should not contain these characters: quotation mark ("), slash (/), backslash (<), colon (:), asterisk (∗), question mark (?), greater than or less than (> or <), or vertical bar, also called a pipe character (|). XML uses greater than, less than, and slash symbols (>, < and /) for tags, so these should not be used in any names in your database.

5.22 Actions

Every request needs an action to be fulfilled by Web Companion. These perform the equivalent of menu commands or script steps in FileMaker Pro databases. Common actions on the web or in the database are Create a New Record, Find a Record, Edit a Record, and Delete a Record. Privileges for any of these actions depend upon the permission set for them in the Password dialog of the database or through the Web Security files.

"Name=value" pairs are often appended to the request to create and edit records or used as search criteria to find a record. The name is the name of the field in the database, and the value is whatever will appear in the field upon action completion. At least one name=value is required for a new or edit action. In addition, deleting or editing a record requires a special parameter, -recid (RecordID), to verify that the action is performed upon the correct record. The following are some examples:

 firstname=Joe&lastname=Brown&-recid=5846 company=Procter+&+Gamble&date=03/05/97 

Create New Records

-new—This creates a new record in the database. Any fields specified in the request are populated and your defined auto-enter fields are triggered. The RecordID (-recid) and any field data are returned by this action and can be used in the next action. Equivalent to the New Record/Request script step or menu command, it creates the new record and places all your named fields with the values supplied in the request. The result is a well-formed and valid XML document containing the fields on the layout, the contents, and the RecordID. If you do not specify a -format, no record will be created and you may get a browser error.

Listing 5.2: New Record requests and result

 fmpro?-db=Xtests.fp5&firstname=Joe&lastname=Brown&-new fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-format=   -dso_xml&-new <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>Xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>     <firstname>Joe</firstname>     <lastname>Brown</lastname>     <RecordID>36488</RecordID> </ROW> </FMPDSORESULT> 

It is important to note that the fields on the layout are what drives the response from WC. If you add or delete fields to the layout or change layouts, you can get different records back from FileMaker. As an exercise, duplicate the layout "web", name it "dweb", change the fields that appear on it, and then modify your request to call dweb instead of web. For extra credit, change the format parameter to use the fmpxmlresult DTD. (Hint: It's called fmp_xml.)

Duplicate Records

-dup—Duplicating a record is similar to creating a new record. A new RecordID is created for this record and auto-enter fields are populated, but all other data is copied from the specified record you are duplicating. Supply a -recid for the record you want to duplicate. The results returned will be for the new record. If you supply field values, these will not be entered into the new record. Duplicate creates the new record with the same data but changes the internal RecordID. Use this step to return a new record, which may be edited.

 fmpro?-db=Xtests.fp5&-lay=web&-recid=234&-format=-dso_xml&-dup 

Edit Records

-edit—Requires the parameter -recid to know which record to update. You can get the -recid from a -new or -find. Just like -new, any fields specified in the request are updated. All other fields retain their original data. Any field that would auto-enter upon modification will do so unless you supply a value. A sample request to edit is shown in Listing 5.3. There is no specific equivalent in the database, as any record is updated by entering new information in any field and exiting the record. The XML returned by this action is the record designated by the -recid, with all the fields on the specified layout. Like the -new action, this returned record can be used in the next action.

Listing 5.3: Edit requests and result

 fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&firstname=Jane&lastname=   Doe&-recid=36488&-edit <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>Xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>     <firstname>Jane</firstname>     <lastname>Doe</lastname>     <RecordID>36488</RecordID> </ROW> </FMPDSORESULT> 

Delete Records

-delete—Requires the parameter -recid to delete the correct record. This is equivalent to the Delete Record script step or menu command. Listing 5.4 shows some -delete requests. If you do not specify a layout in this request, you will get all the field data back from the default layout. XML is not returned with this action, and the record is removed from the database. Perform another action after -delete to return to the record or records needed. If you specify a layout, you will get back the current record as it was before deleting with only those fields on that layout. Consider this distinction and the possibilities. You could save the record even as you delete it. This may be advantageous if you need to log the delete action or provide a "rollback" if the transaction should not be completed.

Listing 5.4: Delete requests and results

 fmpro?-db=Xtests.fp5&-format=-dso_xml&-recid=36488&-delete fmpro?-db=Xtests.fp5&-format=-dso_xml&-lay=web&-recid=36488&-delete <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>Xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>     <firstname>Jane</firstname>     <lastname>Doe</lastname>     <RecordID>36486</RecordID> </ROW> </FMPDSORESULT> 

Find Records

-find—Like the database, you place the search criteria into appropriate fields. This is accomplished through Web Companion by appending name=value pairs to the request or using the -recid. The internal record ID is returned along with any found records and can be used for subsequent actions. The attribute <RECORDID> is in every <ROW> element regardless of the action. The -find action performs the combined script steps as Enter Find Mode[], Set Field [name, value], and Perform Find [].

You can also find all records by using -findall. This action does not require any name=value pairs or record IDs. It simply returns all records in the named database and is equivalent to Show All Records.

Another option is -findany. It will randomly return a record from the current database. While this does not have a direct command or single script step equivalent, random records could be used to supply a parameter result, such as a dynamic picture for a catalog "special."

These find requests return the results depending on the type of request and the number of records that match the criteria. -find with the parameter -recid or the -findany request will return only one record (or none). If no records are found, you get an error code of 401 just as you would in the database. Listing 5.5 shows some example find requests and example results of requests.

Listing 5.5: Find Records requests and results

 <!-- requests --> fmpro?-db=Xtests.fp5&-lay=web&-recid=36488&-find fmpro?-db=people.fp5&-lay=web&-findall fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-find fmpro?-db=Xtests.fp5&-lay=web&-findany <!-- nothing found (ERROR= 401) result --> <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>401</ERRORCODE> <DATABASE>Xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> </FMPDSORESULT> <!-- all records returned --> <?xml version="1.0"?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>people.fp5</DATABASE> <LAYOUT>cgi</LAYOUT> <ROW MOD RECORD>     <Name>Dave Samud</Name>     <Title>Web Administrator</Title>     <Phone>555 555-1212</Phone>     <Picture>FMPro?-DB=people.fp5&amp;-RecID=1&amp;         Picture=&amp;-Img</Picture> </ROW> <ROW MOD RECORD>     <Name>Robert Siwel</Name>     <Title>Web Designer</Title>     <Phone>555 555-1212</Phone>     <Picture>FMPro?-DB=people.fp5&amp;-RecID=2&amp;         Picture=&amp;-Img</Picture> </ROW> </FMPDSORESULT> 

The following actions are for accessing other information about or controlling your database other than record and field contents. All data is returned in well-formed and valid XML and could be used with your stylesheets or as a report of the database information.

Layout Request

-view—This command is used by Web Companion and the -format parameter to return the layout information. An example request for layout information is shown in Listing 5.6. You can use this layout information to format your results. For example, if the database and layout has a field formatted as a check box, this is returned in the request using -view. -db, -lay, and -format are required with this action.

Listing 5.6: View Layout Information request and result

 fmpro?-db=Xtests.fp5&-lay=web&-format=-fmp_xml&-view <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLLAYOUT xmlns="http://www.filemaker.com/fmpxmllayout"> <ERRORCODE>0</ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion"       VERSION="6.0v1" /> <LAYOUT DATABASE="xtests.fp5" NAME="web">       <FIELD NAME="firstname">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="lastname">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="RecordID">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD> </LAYOUT> <VALUELISTS /> </FMPXMLLAYOUT> 

Database Names Request

-dbnames—To return a list of all open databases with Web Companion enabled, use this command. Listing 5.7 shows the results of the request for the open databases. This is equivalent to the design function request DatabaseNames, but only databases shared by Web Companion are returned in this XML list. The parameter -format is required with this action. The XML data returned gives you a lot of information about the open databases.

Listing 5.7: Request for database names and result

 fmpro?-format=-fmp_xml&-dbnames <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult"> <ERRORCODE>0</ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=   "6.0v1" /> <DATABASE DATEFORMAT="" LAYOUT="" NAME="DBNAMES" RECORDS="1"   TIMEFORMAT="" /> <METADATA>       <FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="DATABASE_NAME" TYPE="TEXT" /> </METADATA> <RESULTSET FOUND="1"> <ROW MOD RECORD>       <COL><DATA>Xtests.FP5</DATA> </COL> </ROW> </RESULTSET> </FMPXMLRESULT> 

Layout Names Request

-layoutnames—When you specify a particular database in this request, all the layouts for that database are returned. This is equivalent to the design function LayoutNames (dbname). The database name and -format needs to be specified with this action. Listing 5.8 shows the XML returned by a request for the layout name in the Xtests database.

Listing 5.8: Request for layout names and result

 fmpro?-db=Xtests.fp5&-format=-fmp_xml&-layoutnames <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult"> <ERRORCODE>0</ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=   "6.0v1" /> <DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="" NAME="xtests.fp5" RECORDS="23"   TIMEFORMAT="h:mm:ss a" /> <METADATA>       <FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="LAYOUT_NAME" TYPE="TEXT" /> </METADATA> <RESULTSET FOUND="23"> <ROW MOD RECORD>       <COL>       <DATA>About</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>Form View</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>             <DATA>web</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>webForm</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>webList</DATA>       </COL> </ROW> </RESULTSET> </FMPXMLRESULT> 

Script Names Request

-scriptnames—Equivalent to the design function ScriptNames (dbname), this command will return the list of all the scripts in the named database. Listing 5.9 shows that only the database name, result format, and the action need to be specified in this request.

Listing 5.9: Request for script names and result

 fmpro?-db=Xtests.fp5&-format=-fmp_xml&-scriptnames <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult"> <ERRORCODE>0</ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=   "6.0v1" /> <DATABASE DATEFORMAT="" LAYOUT="" NAME="SCRIPTNAMES" RECORDS="48"   TIMEFORMAT="" /> <METADATA>       <FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="SCRIPT_NAME" TYPE="TEXT" /> </METADATA> <RESULTSET FOUND="48"> <ROW MOD RECORD>       <COL>       <DATA>New Request</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>openURL</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>Edit Request</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>Delete Request</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>Find Request by ID</DATA>       </COL> </ROW> <ROW MOD RECORD>       <COL>       <DATA>Find Request by Field</DATA>       </COL> </ROW> </RESULTSET> </FMPXMLRESULT> 

Open or Close Databases Command

-dbopen and -dbclose—These two commands are used to control which databases are available to the web users. Any file opened or closed by these commands must reside in the Web folder of the FileMaker Pro folder and have the Web Companion enabled. Specify Remote Administration in the Web Companion Configuration dialog for FileMaker Pro. The parameter -password is optional but advisable for remote administration. These two commands are shown below:

 fmpro?-db=Xtests.fp5&-format=-fmp_xml&-dbopen fmpro?-db=Xtests.fp5&-format=-dso_xml&password=master&-dbopen fmpro?-db=Xtests.fp5&-format=-fmp_xml&-dbclose 

Warning 

Placing any file in the Web folder may have security implications. If you must use this feature, provide a password for your database. Do not enable the Try default password option in the Edit, Preferences, Document Preferences dialog.

Request for Image in a Container Field

-img—This command is used specifically with images placed in a container field in the database. FileMaker Pro will produce a link pattern to the image and provide the -img action for you. Images may be in a container field or stored with a field referencing the path to the images. The -img action is used only with stored images.

The XML created for the container field Picture is shown in the following code. Using this information and one of the stylesheet methods, you can web publish the container field to a web page. The text created has to be converted to HTML encoding, so that the "&" shows as "&amp;", but the character is converted back if this field is used as a link to display the graphic.

 <Picture>FMPro?-DB=people.fp5&amp;-RecID=1&amp;Picture=&amp;-Img</Picture> <Picture>FMPro?-DB=people.fp5&amp;-RecID=2&amp;Picture=&amp;-Img</Picture> 

Actions are used singly and not together. One action at a time can be performed. Careful design may be needed to produce desired results from web-published FileMaker Pro and XML. Actions equate to simple steps on the databases themselves. Using scripts we can perform multiple steps, but these may not be appealing for the web-published data. Using these actions, you can manipulate the information in your database through a web page interface. The actions rarely perform alone and require different parameters to act upon.

5.23 Parameters

Parameters are similar to actions because they begin with the "-" sign. However, they use the name=value notation, requiring a value. These parameters could also be called variables. The value of the parameter depends on how it is used. The first two parameters, -db and -lay, have already been discussed.

Database Parameter

-db—This parameter is required by all actions except -dbnames. The full name of the database file (including extension) needs to be provided. Case may or may not matter, so use the exact name of the file. You can determine the current database name with the function Status(CurrentFileName). You can also use the Design functions to determine all open database names. If the -db is not set up for sharing with Web Companion, you will get results with the error number 973. See section 5.5, "Error Codes for XML", for more errors you may get with XML publishing.

Layout Parameter

-lay—The layout name is optional with -find, -findall, and -findany but required to return the list of fields when used with the -view action. -lay also is required for -edit and -new requests if you need to access related fields.

A default layout named "Layout 0" (zero) is similar to the Define Fields dialog. It contains all the fields in the current database and will be used if no layout is specified. To use related data, you must specify the layout where these related fields are displayed or create calculated fields based on the relationship. On the layout, you can place related fields in or out of a portal. Single related fields are treated as if they were the first record in the related file. For all the related records, a portal should be displayed on the layout with those fields required by the request.

XML Format Parameter

-format—When using Web Companion and CDML, -format is used to designate a particular HTML-formatted page used to display the results of the HTTP request. New in FileMaker Pro, this parameter is used to specify which well-formed and valid XML document to return. How it is used depends upon the results you want. There are four format types, and they are combined with the actions to return five different types of XML: FMPDSORESULT, FMPDSORESULT with DTD, FMPXMLRESULT, with DTD, FMPXMLRESULT, and FMPXMLLAYOUT. The DTD formats were discussed more fully in Chapter 4.

-dso_xml is used to return the field names as the tag names and is the easiest to work with for specific data reading and writing:

<fieldname>field contents</fieldname>. The root of the XML document is <FMPDSORESULT></FMPDSORESULT>. DSO is the acronym for Data Source Object. A sample request to FileMaker Pro is shown in Listing 5.10. -dso_xml differs from -fmp_xml by using the field names as the names of the element tags.

Listing 5.10: Request for FMPDSORESULT

 fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&-recid=36489&-find <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>       <firstname>Sue</firstname>       <lastname>Smythe</lastname> </ROW> </FMPDSORESULT> 

-fmp_xml is more generic and perhaps allows greater flexibility for formatting the results. The root element of the XML results returned is <FMPXMLRESULT></FMPXMLRESULT>. The field names are returned near the beginning of the document and found in the element <METADATA></METADATA>. By including the METADATA, some of the layout information for each field is also returned. Listing 5.11 shows a request for the data in Xtest.fp5 with fmp_xml results.

Listing 5.11: Request for FMPXMLRESULT

 fmpro?-db=Xtests.FP5&-lay=web&-format=-fmp_xml&-recid=36489&-find <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult"> <ERRORCODE>0</ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=   "6.0v1" /> <DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="web" NAME="xtests.fp5" RECORDS="4"   TIMEFORMAT="h:mm:ss a" /> <METADATA>       <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="firstname" TYPE="TEXT" />       <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="lastname" TYPE="TEXT" />       <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="RecordID" TYPE="NUMBER" /> </METADATA> <RESULTSET FOUND="1"> <ROW MOD RECORD>       <COL>       <DATA>Sue</DATA>       </COL>       <COL>       <DATA>Smythe</DATA>       </COL>       <COL>       <DATA>36489</DATA>       </COL> </ROW> </RESULTSET> </FMPXMLRESULT> 

-dso_xml_dtd is used to return the DTD for this format. If you do not specify a layout or find any particular record, all the fields on the default layout will be returned. The same request as Listing 5.11 is issued but this time asking for the Document Type Definition to be returned.

Notice the new line added to the XML returned, "<!DOCTYPE FMPDSORESULT (View Source for full doctype…)>." Showing the browser source code reveals the full doctype for the request in Listing 5.12. The DTD in Listing 5.13 tells the document what elements and attributes it can contain and is why the document is valid XML. The element names are specific to the fields on the named layout.

Listing 5.12: Request for FMPDSORESULT with DTD

 fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml_dtd&-recid=36489&-find <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE FMPDSORESULT (View Source for full doctype...)> <FMPDSORESULT> <ERRORCODE>0</ERRORCODE> <DATABASE>xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>       <firstname>Sue</firstname>       <lastname>Smythe</lastname>       <RecordID>36489</RecordID> </ROW> </FMPDSORESULT> 

Listing 5.13: DTD for FMPDSORESULT request

 <!DOCTYPE FMPDSORESULT [ <!ELEMENT FMPDSORESULT (ERRORCODE, DATABASE, LAYOUT, ROW*)>       <!ELEMENT ERRORCODE (#PCDATA)>       <!ELEMENT DATABASE (#PCDATA)>       <!ELEMENT LAYOUT (#PCDATA)>       <!ELEMENT ROW (firstname,lastname,RecordID)>             <!ATTLIST ROW RECORDID CDATA #REQUIRED MODID CDATA #REQUIRED>             <!ELEMENT firstname (#PCDATA)>             <!ELEMENT lastname (#PCDATA)>             <!ELEMENT RecordID (#PCDATA)> ]>

-fmp_xml_dtd includes the DTD for the particular XML document returned when an action is performed. Similar to the DTD for FMPDSORESULT, Listing 5.14 shows the Document Type Definition for an FMPXMLRESULT request.

Listing 5.14: DTD for FMPXMLRESULT request

 <!DOCTYPE FMPXMLRESULT [ <!ELEMENT FMPXMLRESULT (ERRORCODE,PRODUCT,DATABASE,METADATA,RESULTSET)>       <!ELEMENT ERRORCODE (#PCDATA)>       <!ELEMENT PRODUCT EMPTY>             <!ATTLIST PRODUCT NAME CDATA #REQUIRED VERSION CDATA #REQUIRED             BUILD CDATA #REQUIRED>       <!ELEMENT DATABASE EMPTY>             <!ATTLIST DATABASE NAME CDATA #REQUIRED RECORDS CDATA #REQUIRED             DATEFORMAT CDATA #REQUIRED TIMEFORMAT CDATA #REQUIRED LAYOUT             CDATA #REQUIRED>       <!ELEMENT METADATA (FIELD)*>       <!ELEMENT FIELD EMPTY>             <!ATTLIST FIELD NAME CDATA #REQUIRED TYPE (TEXT|NUMBER|DATE|             TIME|CONTAINER) #REQUIRED EMPTYOK (YES|NO) #REQUIRED             MAXREPEAT CDATA #REQUIRED>       <!ELEMENT RESULTSET (ROW)*>             <!ATTLIST RESULTSET FOUND CDATA #REQUIRED>             <!ELEMENT ROW (COL)*>                   <!ATTLIST ROW RECORDID CDATA #REQUIRED MODID CDATA                     #REQUIRED>                   <!ELEMENT COL (DATA)*>                         <!ELEMENT DATA (#PCDATA)> ]> 

-fmp_xml when used with the action -view will produce another kind of document containing the layout information. The database name, layout name -format=-fmp_xml is needed to return the document type. The root of this document is <FMPXMLLAYOUT></FMPXMLLAYOUT>. Listing 5.15 shows the request and results for the layout information of the "web" layout in the Xtests.fp5 database. Just changing the action to -view results in the FMPXMLLAYOUT.

Listing 5.15: Request for FMPXMLLAYOUT and result

 fmpro?-db=Xtests.fp5&-lay=web&-format=-fmp_xml&-view <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLLAYOUT xmlns="http://www.filemaker.com/fmpxmllayout"> <ERRORCODE>0 </ERRORCODE> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion"   VERSION="6.0v1" /> <LAYOUT DATABASE="xtests.fp5" NAME="web">       <FIELD NAME="firstname">       <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="lastname">       <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="RecordID">       <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD> </LAYOUT> <VALUELISTS /> </FMPXMLLAYOUT> 

RecordID Parameter

-recid—This parameter is required with -edit and -delete actions to act upon a specific record. When used with the -find action, it will return a specific record if it exists in the named database. FileMaker Pro automatically assigns this ID to each record as it is created. It is always unique in any given database. The number assigned is not sequential, so it is rarely used for an invoice number or relationship key. In the database this can be determined by creating an unstored calculation: RecordID=Status(CurrentRecordID). The value of this parameter is returned in the XML results in the record element: <ROW RECORDID= "'MODID='">. Here are some sample requests using -recid:

 fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&firstname=   Jane&lastname=Doe&-recid=36488&-edit fmpro?-db=Xtests.fp5&-format=-dso_xml&-lay=web&-recid=36488&-delete fmpro?-db=Xtests.fp5&-lay=web&-recid=36488&-find 

Record Modification Count Parameter

-modid—Introduced in FileMaker Pro 5, the count status of a particular record is updated every time the record is modified. This function in the database is Status (CurrentRecordModificationCount). When a record is returned to the browser, the value of the parameter is in the record element: <ROW RECORDID= "MODlast-para">This function is most important when using the web for record editing. When using peer-to-peer or client-server networking, the database only allows one user in a record with edit privileges. This is called record locking. Other users can view the record but cannot modify it until the "owner" exits that record. In contrast, the stateless HTTP protocol used by Web Companion for editing the database sends the request for a record and disconnects from the database. By noting the MODID when a record is returned to the browser, you can determine if another user has modified it and decide whether to continue or notify the web user of the new state.

Parameters for Using Stylesheets

-styletype and -stylehref—These two parameters are used together to point to the type and name (or location) of the stylesheet used to format the results of the XML request. FileMaker Pro uses XSL and CSS stylesheets with this parameter. While other means can be used to format your XML results, these files placed in the Web folder are read by the parameter. Depending on your browser capabilities, the stylesheet will display the data with formatting, such as font and location on the browser window. XSL stylesheets and Cascading Style Sheets (CSS+) are discussed in Chapter 7. The two parameters for a stylesheet are as follows:

 -styletype=text/xsl&stylehref=Xtests.xsl -styletype=text/css&stylehref=Xtests.css 

Password Parameter for -dbopen Request

-password—This optional parameter is used with the -dbopen action. If the database has a password, you can use the parameter to specify which password to use when opening the database.

 fmpro?-db=Xtests.fp5&-password=a1b2c3&-dbopen 

Find Request Parameters

The following parameters work with the -find action to alter the found set with operators, number of records, sorting, and scripts to perform.

Logical Operator for Multiple Find Requests

-lop—This logical operator is used when making multiple find requests. The choices are AND (find this and that) and OR (find this or that), with the default value of AND if you do not specify this parameter. AND finds will combine the name=value pairs to match all of the values in their associated fields. OR will search for the values in any record and return any of the matches, much like using multiple find requests. The following examples show the requests for XML and equivalent scripted finds in the database.

In the examples, Listing 5.16 shows an AND request to two different fields. Listing 5.17 shows an equivalent scripted AND request to the database. The logical operator (-lop) is used in Listing 5.18 to find two values in the same field. The scripted equivalent is shown in Listing 5.19. And finally, the OR request is shown in Listing 5.20, with a scripted version in Listing 5.21.

Listing 5.16: AND request with XML results

 fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-find <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>       <firstname>Joe</firstname>       <lastname>Brown</lastname>       <RecordID>36490</RecordID> </ROW> </FMPDSORESULT> 

Listing 5.17: Scripted AND find for multiple fields

 Enter Find Mode [] Set Field [ firstname, "Joe" ] Set Field [ lastname, "Brown" ] Perform Find [] 

Listing 5.18: AND request using LOP with XML results

 fmpro?-db=Xtests.fp5&-lay=web&customer=Joe&-lop=and&customer=Brown&-find <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>       <customer>Joe Brown</customer> </ROW> <ROW MOD RECORD>       <customer>Brownly, Joel</customer> </ROW> </FMPDSORESULT> 

Listing 5.19: Scripted AND find for single field

 Enter Find Mode [] Set Field [ customer, "Joe Brown" ] Perform Find [] 

Listing 5.20: OR request with XML results

 fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&-lop=or&lastname=Brown&-find <?xml version="1.0" encoding="UTF-8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>xtests.fp5</DATABASE> <LAYOUT>web</LAYOUT> <ROW MOD RECORD>       <firstname>Joe</firstname>       <lastname>Jones</lastname>       <RecordID>36490</RecordID> </ROW> <ROW MOD RECORD> <firstname>Elmer</firstname>       <lastname>Brown</lastname>       <RecordID>36532</RecordID> </ROW> </FMPDSORESULT> 

Listing 5.21: Scripted OR finds

 Enter Find Mode [] Set Field [ firstname, "Joe" ] New Record/Request Set Field [ lastname, "Brown" ] Perform Find [] 

Comparison Operator for Each Find Request

-op—The comparison operator is similar to the symbols used by FileMaker Pro when making a find request. The default search operator is "begins with." FileMaker will select words that begin with the pattern of the search criteria. For the multiple words in the search criteria, the -op parameter is applied to the beginning of the search phrase, but all words are used in the search. The default operator for the remaining words is "begins with." This parameter is appended to the first word of the search string (before, after, or both).

Table 5.1: FileMaker Pro symbols and comparison operators

Symbol	-op (Operator)	Searches
(none–default)	(none–begins with)	search
(wildcard, zero or more characters)	bw (begins with)	search∗
	ew (ends with)	∗search
∗	(no equivalent -op)	sear∗ch
"" (literal)	cn (contains)	"search"
@ (wildcard, one character)	(no equivalent -op)	se@r@ch
? (invalid date or time)	(no equivalent -op)	?
! (duplicates)	(no equivalent -op)	!
// (today's date)	(no equivalent -op)	//
… (ranges)	(no equivalent -op)	a…g
.. (same as …)		a..g
= (exact match)	eq (equals)	=search
= (with omit)	neq (not equals)	= (omit)
< > (same as = with omit)
≠ (same as = with omit)
= = (field content match)	(no equivalent -op)	==search
< (less than)	lt (less than)	<search
<= (less than or equal)	lte (less than or equal)	<=search
≤ (same as <=)		<=search
> (greater than)	gt (greater than)	>search
>= (greater than or equal)	gte (great than or equal)	>=search
≥ (same as >=)		>=search

All of these searches can be performed over the web if the user enters the symbols. The -op is a convenient way to present the user of those operators with an equivalent without using the symbols, which may not encode properly in the request. When a request is made with the -op and the find criteria, Web Companion converts the appropriate symbol after the request is submitted. Several requests are listed below, followed by an example of a pop-up menu for specifying the -op for the field myField.

Request for first name, but not Joe:

 -op=neq&firstname=Joe

Request for cost below $5,000:

 -op=lt&cost=5000 

Request for literal (full phrase) "scraped knee":

 -op=cn&injury=scraped+knee 

Listing 5.22: Creating an options request in HTML

 <select name='-op'>       <option value="bw" selected> begins with </option>       <option value="eq"> equals </option>       <option value="cn"> contains </option>       <option value="ew"> ends with </option>       <option value="gt"> greater than </option>       <option value="gte"> greater than or equal </option>       <option value="lt"> less than </option>       <option value="lte"> less than or equal </option>       <option value="neq"> does not equal <option>       </select> <input type="text" name="myField" value="" /> 

You can use the select method before every field to which you want to apply a comparison operator. Web Companion will perform the appropriate conversion when the data is submitted. Not every value needs to be used in a selection process. For example, if your field searched is a number field, such as the cost request above, you may only wish to provide the number comparison operators: =, <, <=, >, >=, and <>. An example of this is found in Listing 5.23.

Listing 5.23: The cost request

 <select name='-op'>       <option value="eq"> = </option>       <option value="gt"> &gt; </option>       <option value="gte"> &gt;= </option>       <option value="lt"> &lt; </option>       <option value="lte"> &lt;= </option>       <option value="neq"> &lt;&gt; <option>       </select> <input type="text" name="cost" value="" /> 

You can specify some of the other find options that may not be available by direct -op equivalent. A form field used to submit the find request will combine all the values if a particular field name is used more than once. When the input type is hidden, you can effectively control what is submitted. This method is useful for a login request for user name and password or other situations where you need an exact field content match and not merely a "begins with" search. Listing 5.24 shows how to use these hidden fields with the input fields.

Listing 5.24: Sample login request

 <form method="post" action="fmpro">       <input type="hidden" name="-op" value="bw" />       <input type="hidden" name="user" value="==" />       User Name: <input type="text" name="user" value="" size="30" /><br />       <input type="hidden" name="-op" value="bw" />       <input type="hidden" name="pass" value="==" />       Password: <input type="password" name="pass" value="" size="30" /> </form> 

Tip 

You can see any search if you submit a request on the web and then perform a manual or scripted Modify Last Find. This is probably not wise to do with "live data" but you can test this with samples.

Parameter for Returning a Maximum Number of Records

-max—The default maximum number of records returned by Web Companion in any find request is 25. This number probably has significance because displaying a list of more than 25 items on a web page can take some time. Depending on the layout of the data records, the perceived time to the user may be too long. If you do not include the -max parameter, up to the default number will be returned. You can set this parameter to include a limited number of records or use the keyword all to return all records. Any number, 1 to 2,147,483,647, can be used as the value of this parameter. The -max parameter is often used with the -skip parameter. The examples below and Listing 5.25 show how to provide for a limited set of values for the -max parameter.

 -max=all -max=1 -max=10 

Listing 5.25: Giving the user a choice for -max

 <select name="-max">       <option value="5">5</option>       <option value="10">10</option>       <option value="15">15</option>       <option value="25">35</option>       <option value="all">All</option> </select> 

Starting Record Number Parameter

-skip—This parameter is set with the number of records to skip before displaying and is used with the -max parameter. Together, these parameters allow the user to see all the records a small amount at a time. If this parameter is not specified, the default record is the first record of the found set. The skip value is often used in a next or previous link. Examples with -max and -skip are shown below.

 -max=5&-skip=5 -max=5&-skip=10 -max=5&-skip=15 -max=5&-skip=20 

Sorting Parameters

-sortfield—You can use more than one field for a sort and they will be equivalent to specifying the same fields in the Sort Records dialog. The last -sortfield is sorted first, followed by the next and so on, until the sort is complete. The sort is performed after the action (usually -find). -sortorder—The default sort order is Ascending, but you can specify Ascend (or Ascending), Descend (or Descending), or Custom. The custom sort uses the value list of the field being sorted if it is displayed as a value list on the layout. This parameter and value must follow the -sortfield to which it applies and multiple sorts can be requested. Example find actions with the sorting parameters are shown here:

 -sortfield=lastname&-sortfield=firstname&-findall -sortfield=date&-sortorder=descend&-findall -sortfield=company&-sortorder=ascend&-sortfield=date&-sortorder=   descend&-findall -lay=web&-sortfield=sizes&-sortorder=custom&-findall 

Script Parameters

Scripts are triggered by specifying the -script parameter and the name of the script as the value of the parameter. An action is required and usually a script is performed with the -find action. However, -new, -edit, and -delete actions can also use a -script parameter. The actual script should not conflict with the action just performed, although it might depend on your script steps. Any script requiring user interaction (clicking a button, entering data, or dismissing a dialog) may not function correctly when called through the Web Companion.

-script—You can specify a script to be performed after the -find action and sort of the found set.

-script.prefind—If you wish a script to run before the -find action, use this parameter and specify the name of the script.

-script.presort—A script normally runs after the find and the sort, but you may specify a script to run before the sort and after the find.

Any sort specified with the action -find is performed after the find. Any -script specified is performed after the find and sort. The two special -script options -script.prefind and -script.presort are performed just as their names say, before the find or before the sort, respectively. The following list will help you remember the precedence of these actions and parameters:

• -script.prefind

• find

• -script.presort

• sort

• -script

5.24 Creating the XML Requests

These request actions and parameters will be used throughout this chapter and in section 6.5. You can create these requests by typing them into a browser. Any database referenced will need to be web enabled (sharing with Web Companion). Instructions for this are included above in section 5.1, "Setting Up Web Companion for XML Requests." Rather than creating these requests manually, you may choose to do the exercise below. The file shown in Figure 5.11 will create your requests.

Figure 5.11: XQUERY.FP5

Exercise 5.1: Creating XML Requests

You can download the database XQUERY.FP5 from the companion web sites: http://www.wordware.com/fmxml and http://www.moonbow.com/xml. This file uses the design functions to determine open databases and retrieve the layout, script, and field names for creating XML queries. The queries are properly formatted HTTP requests for the get method.

When performing any of the actions, use only backup copies of your files, as they will be changed! You must also have password privileges for full access to open the file and get the information.

Web Companion must be enabled in the XQUERY.FP5 file for the scripts that convert field contents with the External("Web-ToHTTP") function. In addition, launching the request that you create requires Web Companion sharing on any database referenced.

1. Open the file XQUERY.FP5 with FileMaker Pro.

2. Open copies of any file for which you want to create a query. If a password is required, enter a password that allows export privileges.

3. Verify that the FileMaker Pro application has Web Companion enabled with Edit, Preferences, Application, Plug-Ins. Instant Web publishing need not be enabled, but take notice of the port used in the Configuration dialog.

4. Verify that all open files (including XQUERY.FP5) have Web Companion enabled with File, Sharing.

5. Create your requests by entering data into the fields provided in XQUERY.FP5. The instructions on the following page explain how the fields and buttons can be used to create the HTTP request. Some fields are buttons to trigger the design function scripts. These buttons over the fields populate the value list of the field. You may need to click a field twice to trigger the update script.

6. Complete the calculation for the request by clicking on the Calc button. Any changes to Database or Layout will clear this calculation field so that the correct information will be included in the calculated request.

7. Copy the resulting text and paste it into your browser or click the launch button to perform the Open URL script. If you have your browser set to automatically launch with the Open URL script step, you will see the results of the request.

8. Any error message will be displayed in the tags <ERRORCODE>0 </ERRORCODE> of the resulting XML. Any error other than 0 (zero) will equate to FileMaker Pro's error codes.

9. Internet Explorer should display a tree-like structure of the well-formed and valid XML results. Netscape 6 will display the contents, but viewing the source will reveal the XML.

If your browser does not launch, check the FileMaker Pro Help for the topic "Open URL script step." Try setting the maximum number of records to a low number (5) so that your browser does not take a long time to show the results. Also, pick a layout with few fields for the initial tests.

Along with clearing the cache and history in the browser, the author usually includes a random number at the end of any action. Actions such as -view=1298, -find=510, and -edit=9 ensure that the request will be unique each time and trick the browser into loading the new results.

The XQUERY.FP5 database (see the following Note) will assist you in creating HTTP hyperlink requests for XML results. You can also use it to create HTTP hyperlink requests for CDML. Context help is available by clicking the [?] buttons.

Note 

"XQUERY.FP5" is not to be confused with "Xquery", the XML language used to make SQL-like queries to XML documents and sources. See http://www.w3.org/ for more information about the proposals for the XML Query Language.

Instructions

1. Create a NEW query. Use the button on the layout, rather than manually duplicating or creating a new record.

2. Choose a HOST. This is the IP address or domain where the databases to be web published are located. You can try "localhost" or the default loopback "127.0.0.1" if you are testing the databases and browser on the same machine. You may need to specify the IP address of your local machine rather than using "localhost" or the loopback IP.

3. Choose a PORT (optional). If you have set up Web Companion to use a port other than the default of 80, you must set this field.

4. Refresh the list of open databases by clicking the "refresh" icon (circular arrows). This will populate a value list for choosing a database for the query. This will also clear the layouts, scripts, and fields when you refresh. All databases for web publishing should already be set to Sharing with Web Companion.

5. Choose a DATABASE name.

6. Refresh the LAYOUTS to select one that is in the chosen database. (optional) A layout that is not specified will give you all of the fields in the chosen database. If you want to use related fields, you must specify a layout with these fields upon it.

7. Choose a FORMAT. If you want to make an HTTP request for CDML, you can enter an HTML/CDML page name. All CDML pages must be in the Web folder or, beginning with 6.0, the cdml_format_files folder. If you want to make an HTTP request for XML results, choose one of the predefined values in the pop-up. "-format=-fmp_xml" will give you layout information if your action is "-view", for example.

8. Choose an ACTION.

   1. Some actions require a "-recid" to be set and some are optional. The label will appear when this field is to be used. The find action can specify a record ID for searching for a specific record. You can use "-recid" as a search field in the Add a Search Field dialog.

Tip 

Create a calculated field in all your databases with RecID=Status(CurrentRecordID) to use this value in an HTTP request.

9. Chose a script type, refresh the scripts, and choose a SCRIPT name (optional).

   1. Script types are: -script, -script.prefind, and -script.presort.

   2. Use scripts very carefully with web-enabled databases! If you can, try to perform the same results with multiple HTTP requests.

10. Choose a STYLE TYPE and STYLE HREF (XML only).

    1. The style type can be XSL (XML Stylesheet Language) or CSS (Cascading Style Sheet).

    2. The "href" is the hypertext link to the location of the stylesheet. The link can be an absolute path to another server or a relative link. Stylesheets should be placed in the Web folder.

11. Choose the MAXimum number of records to return in a find request. By default, 25 records will be returned if you do not specify a value.

12. Choose the SKIP # if you do not want to start the result on the first record. The [INCREMENT] button will add the MAX to SKIP each time it is clicked (optional, but only works with MAX).

13. To ADD SORT FIELDS or ADD SEARCH FIELDS, click on those buttons. If a chosen layout has no fields, clear the layout field or chose a layout with fields.

    1. After you choose a SORT FIELD, you can choose a SORT ORDER (optional). Add or remove sort fields in the order you want them to sort.

    2. Choose a FIELD NAME and enter the VALUE (optional) for that field. New or edit actions will enter this value and the find action will search for it. You can also choose an OPERATOR and LOGICAL OPERATOR.

    3. Go back to the main query screen by clicking the [BACK] button or clicking anywhere above the list of fields.

14. Click the [CALC] button to refresh the HTTP request. A random value will be appended to the action. This is used to force a unique request to browsers that may be caching pages.

15. LAUNCH will open your primary browser and send the HTTP request. You may select the request and paste into any browser or use the request with any application that can use it.

16. You can LIST ALL the requests to see what they look like.

5.25 Creating or Editing Related Records

To create a related record, you use the relationship name, a double colon (::), and the field name. A new related record must have ".0" appended to each field name in the related record. You can add a new related record to an existing parent record, one at a time. Rather than use the action -new, you are adding new related records but not new records, so we use the action -edit. To edit the parent record, you must specify the record ID parameter (-recid). Listing 5.26 shows the results of the request to add a related record on the webForm layout. The file Company.FP5 from Chapter 2 is used for these examples. The entire record with the added related record is returned in the request.

 http://localhost/fmpro?-db=COMPANY.FP5&-lay=webForm&-format=-dso_ xml&-recID=5&-edit=1675&CoID::Department.0=department&CoID:: EmployeeID.0=6&CoID::EmployeeName.0=name 

Listing 5.26: Result of adding a new related record

 <?xml version="1.0" encoding="UTF8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>COMPANY.FP5</DATABASE> <LAYOUT>webForm</LAYOUT> <ROW MOD RECORD> <CompanyID>2</CompanyID> <CompanyName>Herbson's Pices</CompanyName> <CoID.EmployeeID>       <DATA>5</DATA>       <DATA>6</DATA>       <DATA>7</DATA>       <DATA>6</DATA> </CoID.EmployeeID> <CoID.EmployeeName>       <DATA>Rosemary Thyme</DATA>       <DATA>Elvis Parsley</DATA>       <DATA />       <DATA>name?</DATA> </CoID.EmployeeName> <CoID.EmployeePhXt>       <DATA>3256</DATA>       <DATA />       <DATA />       <DATA /> </CoID.EmployeePhXt> <CoID.Department>       <DATA>Seasons</DATA>       <DATA>Pickles</DATA>       <DATA>Chutney</DATA>       <DATA>department</DATA>       </CoID.Department> </ROW> </FMPDSORESULT> 

To edit an existing related record, use the same format except that the .n extension is the related record number. This related record number is the portal row of a sorted relationship. You can edit multiple rows by specifying the correct portal row number with the fields to be edited. This request edits the related record, created in Listing 5.26, to add the employee's phone extension and edit the name.

 http://localhost/fmpro?-db=COMPANY.FP5&-lay=webForm&-format=-dso_xml&   -recID=5&-edit=4852&CoID::EmployeePhXt.4=9874&CoID::EmployeeName.4=   Hot%20Pepper 

Listing 5.27: Result of editing a portal row

 <?xml version="1.0" encoding="UTF8" ?> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult"> <ERRORCODE>0</ERRORCODE> <DATABASE>COMPANY.FP5</DATABASE> <LAYOUT>webForm</LAYOUT> <ROW MOD RECORD> <CompanyID>2</CompanyID> <CompanyName>Herbson's Pices</CompanyName> <CoID.EmployeeID>       <DATA>5</DATA>       <DATA>6</DATA>       <DATA>7</DATA>       <DATA>6</DATA> </CoID.EmployeeID> <CoID.EmployeeName>       <DATA>Rosemary Thyme</DATA>       <DATA>Elvis Parsley</DATA>       <DATA />       <DATA>Hot Pepper</DATA> </CoID.EmployeeName> <CoID.EmployeePhXt>       <DATA>3256</DATA>       <DATA />       <DATA />       <DATA>9874</DATA> </CoID.EmployeePhXt> <CoID.Department>       <DATA>Seasons</DATA>       <DATA>Pickles</DATA>       <DATA>Chutney</DATA>       <DATA>department</DATA> </CoID.Department> </ROW> </FMPDSORESULT> 

Deleting Related Records

Related records can be created or edited from a parent record by appending the correct extension to the end of the field name. ".0" will create a new related record and ".n" (the number of the portal row) will edit the related record. The correct action for creating or editing related records is -edit. The use of the -delete action on related records is different. If you allow the deletion of related records in the Define Relationship dialog, all related records will be deleted along with the parent record. The check box When deleting a record in this file, also delete related records must be selected. The -delete action on a parent file requires the Record ID of the parent record:

 http://localhost/fmpro?-db=COMPANIES.FP5&-recid=5&-delete=457 

You can also create, edit, or delete the related records directly by calling the related database directly and specifying the key field CompanyID, for example. If the record is a new record, the correct action is -new:

 http://localhost/fmpro?-db=EMPLOYEES.FP5&-lay=webForm&-format=   -dso_xml&-new=1675&CompanyID=2&Department=department&   EmployeeID&EmployeeName=name 

The results will be the EMPLOYEES.FP5 database and the one new record you created. You can use the key field CompanyID to perform another action and return you to the COMPANY.FP5 database. This is an additional step, so the editing of related records from the parent record may be preferable. Use the same methods to edit or delete a record.

5.26 Repeating Field Data

Repeating fields use the same format as related fields. This means that creating and editing repeating fields uses the ".n" extension on the field name. The command to edit data in a repeat could be: "&repeat1.1=this%20is%20line%20one". This is similar to the script step to change data in a particular repeat number: Set Field ["repeat1"-1, "this is line one". Clearing a single repeat would use this extension, too, but clearing the field with no extension, such as "&repeat1=", clears all of the repeats in that field. The code below shows some of these requests:

 http://localhost/fmpro?-db=MAIN.FP5&-lay=web&-format=-fmp_xml&-findall http://localhost/fmpro?-db=MAIN.FP5&-format=-dso_xml&repeat1.1=   this%20is%20line%20one&-edit http://localhost/fmpro?-db=MAIN.FP5&-format=-fmp_xml&-op=cn&-repeat2=   one&find http://localhost/fmpro?-db=MAIN.FP5&-format=-dso_xml&repeat1=&-edit 

The results of an HTTP request to a web-published FileMaker Pro database is similar to the export of repeating fields. The results of the above requests are not included here. The request for -format=-fmp_ xml and -format=-fmp_dso will produce different results for repeating fields. The result is similar for either request and uses the DATA element around each repeat, whether there is data or not. See Chapters 2 and 4 for more information about repeating fields and XML.