4.3 FMPDSORESULT Schema/Grammar

The final Document Type Definition for FileMaker Pro XML results is FMPDSORESULT. DSO is the abbreviation for Data Source Object. This format is used by many XML documents and shows the field or column name with the contents. The same database, Contact Management.fp5, is used for the DSO results. The HTTP request is shown here:

http://localhost/fmpro?-db=Contact%20Management.fp5&-lay=Form%20-
  %20Main%20Address&-format=-dso_xml&-findany

The FMPDSORESULT definition begins:

<!DOCTYPE FMPDSORESULT [
<!ELEMENT FMPDSORESULT (ERRORCODE, DATABASE, LAYOUT, ROW*)>
      <!ATTLIST FMPDSORESULT xmlns CDATA #REQUIRED>
      <!ELEMENT ERRORCODE (#PCDATA)>
      <!ELEMENT DATABASE (#PCDATA)>

The root element FMPDSORESULT has four child elements: ERRORCODE, DATABASE, LAYOUT, and ROW, which may be repeated in the XML result zero or more times. The attribute for FMPDSORESULT, xmlns, has the value of "http://www.filemaker.com/fmpdsoresult" in the XML result. The first child element of the root element, ERRORCODE, is the same as in the FMPXMLLAYOUT and FMPXMLRESULT. The element PRODUCT is not used in the DSO results. The DATABASE element is never empty and contains the name of the database between the start and end markup in the XML result. The well-formed XML result has the same prolog and returns:

<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
      <ERRORCODE>0</ERRORCODE>
      <DATABASE>Contact Management.fp5</DATABASE>
      <LAYOUT></LAYOUT>

4.31 Records (ROWS) and Fields

The last child element of the FMPDSORESULT element is where the records are returned as the ROW element. The field names are the child elements of the ROW. If no layout is specified, all fields are returned. If the layout has no fields on it, the ROW element is empty:

<ROW MODID="1" RECORDID="1">

The definition for the ROW element lists the fields on the layout as child elements, and the element has two required attributes, RECORDID and MODID. These attributes serve the same function as the attributes for the ROW in FMPXMLRESULT.

<!ELEMENT ROW (FIELD1, FIELD2, ...)>
      <!ATTLIST ROW
                  RECORDID CDATA #REQUIRED
                  MODID CDATA #REQUIRED>

The element names in FMPDSORESULT are the field names in the database, with the following exceptions: spaces ( ) are converted to underscores (_), and the double colons (::) between a relationship name and a related field are converted to a single period (.).

Listing 4.10 shows the results in DSO format for one record in the Contact Management.fp5 database. Container fields return the link path to the image in the database if you use the HTTP request.

Listing 4.10: DSO results for records/rows

<ROW MODID="1" RECORDID="1">
      <Address_Type_1>A</Address_Type_1>
      <City_1>B</City_1>
      <Company>C</Company>
      <Email>D</Email>
      <First_Name>E</First_Name>
      <Last_Name>F</Last_Name>
      <Notes>G</Notes>
      <Phone_1>H</Phone_1>
      <Phone_2>I</Phone_2>
      <Postal_Code_1>J</Postal_Code_1>
      <State_Province_1>K</State_Province_1>
      <Street_1>L</Street_1>
      <Title>M</Title>
      <Image_Data>FMPro?-db=Contact Management.fp5&-RecID=
        24&Image Data=&-img</Image_Data>
      <FndCt>1</FndCt>
      <RecCt>1</RecCt>
</ROW>

4.32 Related and Repeating Fields

Special considerations are given for repeating fields and related fields (whether in portal or not). See the results with repeating fields in Chapter 2, section 2.23, "Repeating Field Data", and for related fields in Chapter 2, section 2.22, "XML from FileMaker Pro Related Fields". The name of the field is used as the element name, and the element DATA is used for each repeat or related record in the FMPDSORESULT schema:

<!ELEMENT FIELD2 (DATA*)>
<!ELEMENT DATA (#PCDATA)>

4.33 Completing the FMPDSORESULT DTD

The FMPDSORESULT definition ends with "]>". Listing 4.11 shows the full definition.

Listing 4.11 : FMPDSORESULT Document Type Definition

<!DOCTYPE FMPDSORESULT [
<!ELEMENT FMPDSORESULT (ERRORCODE, DATABASE, LAYOUT, ROW*)>
      <!ATTLIST FMPDSORESULT xmlns CDATA #REQUIRED>
      <!ELEMENT ERRORCODE (#PCDATA)>
      <!ELEMENT DATABASE (#PCDATA)>
      <!ELEMENT LAYOUT (#PCDATA)>
      <!ELEMENT ROW (FIELD1, FIELD2, ...)>
            <!ATTLIST ROW
                  RECORDID CDATA #REQUIRED
                  MODID CDATA #REQUIRED>
<!-- grammar for a regular field -->
      <!ELEMENT FIELD1 (#PCDATA)>
<!-- grammar for a repeating or related field -->
      <!ELEMENT FIELD2 (DATA*)>
      <!ELEMENT DATA (#PCDATA)>
]>

If the names for the fields are needed, the FMPDSORESULT is the schema to use in the XML request. This is the most flexible design for data exchange in which the name is required. The names of these elements (fields) may be needed for processing the data with stylesheets. The DSO result can be used for parsing XML data into the FileMaker Pro database. The next section presents two parsing methods of extracting the DSO formatted XML data.