4.2 FMPXMLRESULT Schema/Grammar

The FMPXMLRESULT is the schema that returns some information about the fields on a layout and the field contents. This grammar is the only format used by FileMaker Pro 6 when importing XML. The example database Contact Management.fp5 will be used with the request to find any record in the database and return the results with the FMPXMLRESULT format. You may make the HTTP request below or export the XML for the fields in Listing 4.5:

<!-- HTTP REQUEST-->
http://localhost/fmpro?-db=Contact%20Management.fp5&-lay=
  Form%20-%20Main%20Address&-format=-fmp_xml&-findany

Listing 4.5: Export FMPXMLRESULT fields

Address Type 1
City 1
Company
Email
First Name
Last Name
Notes
Phone 1
Phone 2
Postal Code 1
State Province 1
Street 1
Title

Note

You can make the HTTP request and get container field information, but you cannot export a container field. The Image Data field will not export. The result for the Image Data field from the HTTP request is shown here:

<!-- FIELD INFORMATION -->
<FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Image Data" TYPE="CONTAINER" />
<!-- DATA -->
<DATA>FMPro?-db=Contact Management.fp5&-RecID=24&Image Data=&-img</DATA>

The root element in this type of XML document is FMPXMLRESULT and has five child elements: ERRORCODE, PRODUCT, DATABASE, METADATA, and RESULTSET. The attribute xmlns is required. The definition for FMPXMLRESULT begins:

<!DOCTYPE FMPXMLRESULT [
<!ELEMENT FMPXMLRESULT (ERRORCODE, PRODUCT, DATABASE, METADATA, RESULTSET)>
      <!ATTLIST FMPXMLRESULT xmlns CDATA #REQUIRED>
      <!ELEMENT ERRORCODE (#PCDATA)>
      <!ELEMENT PRODUCT EMPTY>
            <!ATTLIST PRODUCT
                  NAME CDATA #REQUIRED
                  VERSION CDATA #REQUIRED
                  BUILD CDATA #REQUIRED>

Listing 4.6 shows the beginning of the well-formed XML document. The prolog is the same as the FMPXMLLAYOUT result. The xmlns attribute for the root element FMPXMLRESULT has the value "http://www.filemaker.com/fmpxmlresult" and is a unique identifier for this type of document. The first two child elements, ERRORCODE and PRODUCT, are just like the elements in FMPXMLLAYOUT.

Listing 4.6 : XML results from -format=-fmp_xml or export as FMPXMLRESULT

<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">
      <ERRORCODE>0</ERRORCODE>
      <PRODUCT BUILD="08/09/2002" NAME="FileMaker Pro" VERSION="6.0v3" />

4.21 Database Information

The third child element of the FMPXMLRESULT element is DATABASE. The DATABASE element is empty but has five required attributes: the name of the database, the number of records in the database, the name of the layout used in the request (if any), and the date and time formats of the database. The date format and time format are included because of international variations for these kinds of formats.

<!ELEMENT DATABASE EMPTY>
      <!ATTLIST DATABASE
            NAME CDATA #REQUIRED
            RECORDS CDATA #REQUIRED
            LAYOUT CDATA #REQUIRED
            DATEFORMAT CDATA #REQUIRED
            TIMEFORMAT CDATA #REQUIRED>

The XML result shows how many records are in the database Contact Management.fp5. If you make the HTTP request and specify a layout, it will be listed; otherwise the value for LAYOUT is empty. The date and time formats will be whatever the computer operating system had for the DateTime Control Panel settings when the database was created or cloned. The format of these types of fields on the layout do not change the values.

<DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="" NAME="Contact Management.fp5"
  RECORDS="1" TIMEFORMAT="h:mm:ss a" />

4.22 Metadata Information

Metadata is data, or information, about the data. The FMPXMLRESULT returns the field information in the METADATA element. This element is empty if there are no fields on the layout (HTTP request):

<METADATA />

The definition for METADATA contains one child element and no attributes. The child element FIELD may occur zero or more times in the XML result. Listing 4.7 shows the results for the metadata in the Contact Management.fp5 database for those fields in the export or on the layout in an HTTP request.

<!ELEMENT METADATA (FIELD)*>

The FIELD element is empty and has four required attributes: NAME, TYPE, EMPTYOK, and MAXREPEAT. The type of field is how the field was created in the Define Fields dialog. If the field is a global, calculation, or summary, the field type is the global, calculation, or summary result. The EMPTYOK attribute relates directly to the validation for the named field. The default value for the EMPTYOK attribute is "yes". If the "Not empty" check box is selected under the Validation tab in the Options dialog, this value will be "no". A field defined to be a repeating field will show the maximum number of repetitions as the value for this attribute. MAXREPEAT has a default of "1" for all fields not defined as repeating fields.

<!ELEMENT FIELD EMPTY>
      <!ATTLIST FIELD
            NAME CDATA #REQUIRED
            TYPE (TEXT | NUMBER | DATE | TIME | CONTAINER) #REQUIRED
            EMPTYOK (YES | NO) #REQUIRED
            MAXREPEAT CDATA #REQUIRED>

Listing 4.7: Metadata in the XML results

<METADATA>
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Address Type 1"
        TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="City 1" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Company" TYPE="TEXT" />
<FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Email" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="First Name" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Last Name" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Notes" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Phone 1" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Phone 2" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Postal Code 1"
        TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="State Province 1"
        TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Street 1" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Title" TYPE="TEXT" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="FndCt" TYPE="NUMBER" />
      <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="RecCt" TYPE="NUMBER" />
</METADATA>

The names of the fields are listed in the METADATA because the next element, RESULTSET, does not show the names along with the contents of the fields. The order in which the fields are listed in the METADATA is the same order that the fields are listed in the COL elements, shown in Listing 4.8.

Listing 4.8: Resultset (rows and columns) of data

<RESULTSET FOUND="1">
      <ROW MODID="1" RECORDID="1">
            <COL><DATA>A</DATA></COL>
            <COL><DATA>B</DATA></COL>
            <COL><DATA>C</DATA></COL>
            <COL><DATA>D</DATA></COL>
            <COL><DATA>E</DATA></COL>
            <COL><DATA>F</DATA></COL>
            <COL><DATA>G</DATA></COL>
            <COL><DATA>H</DATA></COL>
            <COL><DATA>I</DATA></COL>
            <COL><DATA>J</DATA></COL>
            <COL><DATA>K</DATA></COL>
            <COL><DATA>L</DATA></COL>
            <COL><DATA>M</DATA></COL>
            <COL><DATA>1</DATA></COL>
            <COL><DATA>1</DATA></COL>
      </ROW>
</RESULTSET>

4.23 The Resultset (Contents of the Fields)

The last child element of FMPXMLRESULT is RESULTSET. This element has one element and one required attribute. The value of the FOUND attribute is the number of records in the found set. The child element ROW may occur zero or more times in the XML results and will be repeated for each record in the found set:

<!ELEMENT RESULTSET (ROW)*>
<!ATTLIST RESULTSET FOUND CDATA #REQUIRED>

The ROW element has one child element, COL, and two required attributes, RECORDID and MODID. The RECORDID is the same as the Status(CurrentRecordID) function and is a unique number created when a new record is created in the database. The number is used when searching for specific records, editing records, and deleting records. The MODID is the same as the Status(CurrentRecordModificationCount) function and changes as the record is modified. The value for the MODID attribute is used to track if a record has changed before submitting data from the web browser. COL is repeated for each field in the METADATA list. The COL element has one child element, DATA, which may be empty if the field is empty. The text between the start and end DATA element markup is the content of each field.

4.24 Completing the FMPXMLRESULT DTD

The FMPXMLRESULT definition ends with "]>". The full DTD is shown in Listing 4.9. The advantage for this type of schema is to return the results of rows and columns (records and fields) without needing to know the names of the fields. The same stylesheets can be used for multiple files if the number of columns is the same. The type of field should also match so that the columns can be formatted as needed.

Listing 4.9: FMPXMLRESULT Document Type Definition

<!DOCTYPE FMPXMLRESULT [
<!ELEMENT FMPXMLRESULT (ERRORCODE, PRODUCT, DATABASE, METADATA, RESULTSET)>
      <!ATTLIST FMPXMLRESULT xmlns CDATA #REQUIRED>
      <!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)>
]>

The content of the records and fields on a layout can be returned as well-formed XML with the FMPXMLRESULT schema/grammar. Any style information will be lost in the data returned. The date and time are returned with the date and time format of the database when created or cloned. Number fields are returned as text and may not be formatted as they are on the layout. Container fields will have a link path to retrieve the image for display. The METADATA could be used to label each COL in a stylesheet. The next schema, FMPDSORESULT, returns the name of each field as an element name. There are similarities to FMPXMLRESULT.