php-doc-en/reference/sdo/reference.xml

<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.21 $ -->
<!-- Purpose: database.abstract -->
<!-- Membership: pecl -->
<!-- State: experimental -->

<reference id="ref.sdo">
 <title>SDO Functions</title>
 <titleabbrev>SDO</titleabbrev>

 <partintro>
  <section id="sdo.intro">
   &reftitle.intro;
   <para>
    <!-- This warns that the extension is experimental -->
    &warn.experimental;
   </para>
   
   <para>
    Service Data Objects (SDOs) enable PHP applications to work with
    data from different sources (like a database query, an XML file, 
    and a spreadsheet) using a single interface.
   </para>
   <para>
    Each different kind of data source requires a Data Access Service 
    (DAS) to provide access to the data in the data source.
    In your PHP application, you use a DAS to create an SDO 
    instance that represents some data in the data source.  You can then 
    set and get values in the SDO instance using the standard SDO 
    interface.  Finally, you use a DAS to write the modified data back
    to a data source (typically the same one).
   </para>
   <para>
    See the
    <link linkend="sdo.das.table">list of Data Access Services</link>
    for details on those
    currently available.  In addition to the provided DASs, SDO also
    provides interfaces to enable others to be implemented 
    (see the section on <link linkend="sdo.class.sdo-das-spis">SDO Data
    Access Services Interface</link> for more details).
   </para>
    <para>
    This extension is derived from concepts taken from the
    <ulink url='&url.ibm.sdo;'>
    Service Data Objects specification
    </ulink>
   </para>

   <section id="sdo.intro.structure">
    <title>The Structure of a Service Data Object</title>
    <para>
     A Service Data Object instance is made up of a tree of data objects.
     The tree is defined by containment relationships between the data 
     objects.  For example, a Company data object might consist of a number 
     of Department data objects and therefore the Company would have 
     a containment relationship to the Departments.  
     Deleting a data object which has a containment relationship to another
     data object will also delete the contained data object.  For example, 
     deleting the Company data object will also delete the Departments.
    </para>
    <para>
     An SDO may also have non-containment references between data objects 
     in the tree.  For example, one Employee data object might reference 
     another Employee to identify a career mentor.  Deleting a data object
     which has a non-containment reference to another data object does 
     not delete the referenced data object.
    </para>
    <para>
     As well as data objects referencing each other, they can also have
     primitive properties.  For example, the Company data object might
     have a property called "name" of type string, for holding the name
     of the company (for example, "Acme").
    </para>
   </section>
  </section>

  <section id="sdo.requirements">
   &reftitle.required;
   <para>
    The SDO extension requires PHP 5.1 or higher.
   </para>
   <para>
    SDO <link linkend="ref.sdo-das-xml">XML Data Access Service</link>,
    which is built as part of this extension, requires libxml2
    (Tested with libxml2 2.6.19) which can be downloaded from
    <ulink url='&url.libxml;'>&url.libxml;</ulink>.
   </para>
  </section>

  <section id="sdo.installation">
   &reftitle.install;
   <para>
   There are several options, depending on whether you are installing on
   Windows or Linux, and depending on whether you are installing a released
   version (a .tgz file from the PECL site) or the latest from CVS.
   The Relational DAS also needs special attention as it is written in
   PHP.
   </para>
   <para> The instructions are likely to change as PHP 5.1 progresses in status from beta to
    stable release. The instructions here were correct on 6th October 2005, when PHP
    5.1.0RC1 was the current release candidate for PHP, and 0.5.2 was the current beta
    release of SDO.
   </para>
   <para> 
    The options are summarised in the following table:
    <informaltable>
     <tgroup cols='3'>
      <thead>
       <row>
        <entry>latest/Release</entry>
        <entry>Windows</entry>
        <entry>Linux</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         latest CVS
        </entry>
        <entry>
         <itemizedlist>
          <listitem>
           <para>
            The latest DLLs for the SDO core and the XML DAS can be 
            downloaded from 
           <ulink url='&url.pecl.win.ext;php_sdo.dll'>php_sdo</ulink> and 
           <ulink url='&url.pecl.win.ext;php_sdo_das_xml.dll'>php_sdo_das_xml
           </ulink> respectively.
           </para>
          </listitem>
          <listitem>
           <para>
            Check out the Relational DAS from CVS to somewhere on the
            PHP 
            <link linkend="ini.include-path">include_path</link>.
           </para>
          </listitem>
         </itemizedlist>
        </entry>
        <entry>
         <itemizedlist>
          <listitem>
           <para>
            Check out the SDO core and the XML DAS from CVS 
            and build according to the instructions 
            below for building on Linux.
           </para>
          </listitem>
          <listitem>
           <para>
            Check out the Relational DAS from CVS to somewhere on the
            PHP 
            <link linkend="ini.include-path">include_path</link>.
           </para>
          </listitem>
         </itemizedlist>
        </entry>
       </row>
       <row>
        <entry>
         Release
        </entry>
        <entry>
         <itemizedlist>
          <listitem>
           <para>
            There is currently no way provided for building the release 
            version of the SDO core and XML DAS on a user's machine. 
            You will only be able to pick up the latest DLLs from the 
            snaps site (see previous row of this table).
           </para>
          </listitem>
          <listitem>
           <para>
            The Relational DAS can be downloaded and installed with 
            the command:
           </para>
           <para>
            <command>
            pear install -B &lt;package name and level&gt;
            </command>
           </para>
           <para> 
            Substitute the desired package name and level, for example
            <varname>sdo-0.5.2</varname>, in the command above.
           </para>
          </listitem>
         </itemizedlist>
        </entry>
        <entry>
         <itemizedlist>
          <listitem>
           <para>
            You can download and install all three SDO components - the
            SDO core, the XML DAS and the Relational DAS - with the 
            command:
           </para>
           <para>
            <command>
             pear install &lt;package name and level&gt;
            </command>
           </para>
           <para>
            Substitute the desired package name and level, for example
            <varname>sdo-0.5.2</varname>, in the command above.
           </para>
           <para> 
            This command will build the SDO and XML shared libraries as well 
            as installing the PHP files that make the Relational DAS.
           </para>
          </listitem>
         </itemizedlist>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
   <para>
    Regardless of which platform or which level of the code you have installed
    you will need add the two extension libraries to your &php.ini; file.
    On Windows, add:
    <programlisting role="php" id="sdo.installation.ini.windows">
<![CDATA[
extension=php_sdo.dll
extension=php_sdo_das_xml.dll
]]> 
    </programlisting>
    On Linux, add:
    <programlisting role="php" id="sdo.installation.ini.linux">
<![CDATA[
extension=sdo.so
extension=sdo_das_xml.so
]]>
    </programlisting>
    You may also need to update your 
    <link linkend="ini.extension-dir">extension_dir</link>
    in &php.ini; to point to the location of these libraries.   
   </para>
   
   <para>
    The Relational DAS is written in PHP. You may need to 
    update your 
    <link linkend="ini.include-path">include_path</link>
    in &php.ini; to point to the directory that contains
    <filename>sdo/DAS/Relational</filename>.
   </para>
   <procedure id='sdo.build.linux.steps'>
    <title>Building SDO on Linux</title>
    <para>
     This section describes how to build the SDO core and XML DAS on Linux.
     Currently you would only need to know how to do this if you 
     wish to build a recent version that you have checked out
     of CVS. 
    </para>
    <step>
     <para>
      Change to the main extension directory:
      <command>cd &lt; wherever your sdo code is &gt;</command>
     </para>
    </step>
    <step>
     <para>
      Run <command>phpize</command>, which will set up the environment to
      compile both SDO and the XML Data Access Service.
     </para>
    </step>
    <step>
     <para>
      Next, run <command>./configure; make; make install</command>. Please
      note, you may need to login as root to install the extension.
     </para>
    </step>
    <step>
     <para>
      Make sure that these modules are loaded by PHP, by adding
      <command>extension=sdo.so</command> and
      <command>extension=sdo_das_xml.so</command> to your
      <filename>php.ini</filename> file in the same order. 
     </para>
    </step>
   </procedure>
  </section>

  <section id="sdo.das.table">
   <title>Data Access Services</title>
   <para>
    The table below lists the currently provided SDO Data Access Services:
    <informaltable>
     <tgroup cols='2'>
      <thead>
       <row>
        <entry>DAS Name</entry>
        <entry>Description</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         <link linkend="ref.sdo-das-xml">SDO_DAS_XML</link>
        </entry>
        <entry>
         An XML Data Access Service supporting reading/writing
         SDOs as XML documents or via a Web URL to supporting things like 
         RSS feeds.
        </entry>
       </row>
       <row>
        <entry>
         <link linkend="ref.sdo.das.rel">SDO_DAS_Relational</link>
        </entry>
        <entry>
         A PDO-based Data Access Service supporting reading/writing SDO 
         to relational data sources.  
         Implements an optimistic concurrency policy for updates.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
  </section>

  <section id='sdo.limitations'>
   <title>Limitations</title>
   <procedure id='sdo.limitations.implementation'>
    <title>Implementation Limitations</title>
    <para>
     The following are limitations in the current SDO implementation:
    </para>
    <step>
     <para>
      There is no support for multi-byte character sets.
     </para>
    </step>
   </procedure>
   <procedure id='sdo.limitations.sdo'>
    <title>SDO Limitations</title>
    <para>
     The following SDO 2.0 concepts are not supported in the current 
     PHP implementation.
     It is not necessarily the case that these will all be added over time.
     Their inclusion will depend on community requirements.
    </para>
    <step>
     <para>
      Abstract types and type derivation.
     </para>
    </step>
    <step>
     <para>
      Open types.
     </para>
    </step>
    <step>
     <para>
      Bi-directional relationships.
     </para>
    </step>
    <step>
     <para>
      Type and property alias names.
     </para>
    </step>
    <step>
     <para>
      Read-only properties.
     </para>
    </step>
    <step>
     <para>
      XMLHelper/XSDHelper (the XML DAS provides a lot of this functionality)
     </para>
    </step>
    <step>
     <para>
      TypeHelper (the SDO_DAS_DataFactory provides this functionality)
     </para>
    </step>
   </procedure>
  </section>

  <section id='sdo.examples'>
   &reftitle.examples;
   <para>
    The examples below assume an SDO created with the schema
    and instance information shown below, using the XML Data Access Service.
   </para>
   <para>
    The schema describes a company data object.  
    The company contains department data objects, and
    each department contains employee data objects.
    Each data object has a number of primitive properties to describe things
    like name, serial number, etc.
    Finally, the company data object also has a non-containment reference 
    to one of the employee data objects to identify them as the 
    'employeeOfTheMonth'.
   </para>
   <para>
    <programlisting role="xml">
<![CDATA[
<xsd:schema  
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:sdo="commonj.sdo"
  xmlns:sdoxml="commonj.sdo/xml"
  xmlns:company="companyNS"
  targetNamespace="companyNS">
  <xsd:element name="company" type="company:CompanyType"/>
  <xsd:complexType name="CompanyType">
    <xsd:sequence>
      <xsd:element name="departments" type="company:DepartmentType" 
       maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" 
sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
  <xsd:complexType name="DepartmentType">
    <xsd:sequence>
      <xsd:element name="employees" type="company:EmployeeType"  
       maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="location" type="xsd:string"/>
    <xsd:attribute name="number" type="xsd:int"/>
  </xsd:complexType>
  <xsd:complexType name="EmployeeType">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="SN" type="xsd:ID"/>
    <xsd:attribute name="manager" type="xsd:boolean"/>
  </xsd:complexType>
</xsd:schema>
]]>
    </programlisting>
   </para>

   <para>
    The instance document below describes a single company, 
    called 'MegaCorp', which contains a single department, 
    called 'Advanced Technologies'.
    The Advanced Technologies department contains three employees.
    The company employeeOfTheMonth is referencing the second employee,
    'Jane Doe'.
   </para>

   <para>
    <programlisting role="xml">
<![CDATA[
<?xml version="1.0" encoding="UTF-8" ?> 
<company xmlns="companyNS" name="MegaCorp" 
 employeeOfTheMonth="#/departments.0/employees.1">
  <departments name="Advanced Technologies" location="NY" number="123">
    <employees name="John Jones" SN="E0001"/>
    <employees name="Jane Doe" SN="E0003"/>
    <employees name="Al Smith" SN="E0004" manager="true"/>
  </departments>
</company>
]]>
    </programlisting>
   </para>

  </section>

  <section id="sdo.sample.getset">
   <title>Setting and Getting Property Values</title>
   <para>
    The following examples assume <command>$company</command> is a data
    object created from the schema and instance document shown above.
   </para>
   <para>
    <example>
     <title>Access via Property names</title>
     <para>
      Data object properties can be accessed using the object property
      access syntax.  The following gets the list of departments 
      (containing a single department), and sets the company name to 'Acme'.
     </para>
     <programlisting role="php" id="sdo.examples.propname">
<![CDATA[
<?php
  $departments = $company->departments;
  $company->name = 'Acme';
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Access via Property index</title>
     <para>
      Data object properties can be accessed via their property index
      using array syntax.  The property index is the position at which the
      property's definition appears in the model (in this case the xml
      schema).
      We can see from the schema listing above that the departments element
      is the first company property defined and the company name attribute 
      is the second company property (the SDO interface makes no distinction
      between XML attributes and elements).
      The following gets the list of departments (containing a single
      department), and sets the company name to 'Acme'.
     </para>
     <programlisting role="php" id="sdo.examples.propindex">
<![CDATA[
<?php
  $departments = $company[0];
  $company[1] = 'Acme';
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Data Object Iteration</title>
     <para>
      We can iterate over the properties of a data object using foreach.
      The following iterates over the company properties; name, 
      departments and employeeOfTheMonth.
     </para>
     <programlisting role="php" id="sdo.examples.doiter">
<![CDATA[
<?php
  foreach ($company as $name => $value) {
    // ...
  }
?>
]]>
     </programlisting>
     <para>
      For the first iteration, $name will be 'name' and $value
      will be 'Acme'.  For the second iteration, $name will be
      'departments' and $value will be an SDO_List (because departments is a
      many-valued property (stated <command>maxOccurs="unbouded"</command>
      in the schema)) containing a single data object of type DepartmentType.
      For the third iteration, $name will be 'employeeOfTheMonth' and $value
      will be a data object of type EmployeeType.
     </para>
    </example>
   </para>

   <para>
    <example>
     <title>Many-valued Property Iteration</title>
     <para>
      Many-valued properties can also be iterated over using
      foreach.  The following iterates over the company's departments.
     </para>
     <programlisting role="php" id="sdo.examples.mvpiter">
<![CDATA[
<?php
  foreach ($company->departments as $department) {
    // ...
  }
?>
]]>
     </programlisting>
     <para>
      Each iteration will assign the next department in the
      list to the variable <command>$department</command>.
     </para>
    </example>
   </para>

   <para>
    <example>
     <title>Many-valued Element Access</title>
     <para>
      We can access individual elements of many-valued properties using array
      syntax. The following accesses the first department in the company.
     </para>
     <programlisting role="php" id="sdo.examples.mvaccess">
<![CDATA[
<?php
  $ad_tech_dept = $company->departments[0];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Nested Property Access</title>
     <para>
      We can use nested property access to navigate the data object
      instance structure.  The following gets and sets the name of the first
      department.
     </para>
     <programlisting role="php" id="sdo.examples.nestedprop">
<![CDATA[
<?php
  $dept_name = $company->departments[0]->name;
  $company->departments[0]->name = 'Emerging Technologies';
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Simple XPath support</title>
     <para>
      We can access properties using XPath-like (an augmented
      sub-set of XPath) expressions, the simplest form of which is the 
      property name.  
      The following sets the company name and gets the employeeOfTheMonth.
     </para>
     <programlisting role="php" id="sdo.examples.simplexpath">
<![CDATA[
<?php
  $company['name'] = 'UltraCorp';
  $eotm = $company['employeeOfTheMonth'];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Simple XPath support</title>
     <para>
      We can use chained array access calls to navigate the data
      object instance structure.  The following gets and sets the name of the
      first department.
     </para>
     <programlisting role="php" id="sdo.examples.chainarray">
<![CDATA[
<?php
  $dept_name = $company['departments'][0]['name'];
  $company['departments'][0]['name'] = 'Emerging Technologies';
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>XPath Navigation</title>
     <para>
      We can use XPath expressions to navigate the data object
      instance structure.  Two forms of indexing into many-valued 
      properties are supported.  
      The first is the standard XPath array syntax with the indexing
      starting at one, the second is an SDO extension to XPath with an index
      starting at zero.  The following both get the second employee from the
      first department.
     </para>
     <programlisting role="php" id="sdo.examples.xpathnav">
<![CDATA[
<?php
  $jane_doe = $company["departments[1]/employees[2]"];
  $jane_doe = $company["departments.0/employees.1"];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>XPath Querying</title>
     <para>
      We can use XPath to query and identify parts of a data object based
      on instance data.  The following retrieves the manager from the
      'Advanced Technologies' department.
     </para>
     <programlisting role="php" id="sdo.examples.xpathquery">
<![CDATA[
<?php
 $ad_tech_mgr = 
  $company["departments[name=\"Advanced Technologies\"]/employees[manager=\"true\"]"];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Creating child data object</title>
     <para>
      A data object can be a factory for its child data objects.  
      A child data object is automatically part of the data graph.  
      The following add a new employee to the 'Advanced Technologies' 
      department.
     </para>
     <programlisting role="php" id="sdo.examples.create">
<![CDATA[
<?php
  $ad_tech_dept = $company["departments[name=\"Advanced Technologies\"]"];
  $new_hire = $ad_tech_dept->createDataObject('employees');
  $new_hire->name = 'John Johnson';
  $new_hire->SN = 'E0005';
  $new_hire->manager = false;
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Unset referenced data object</title>
     <para>
      We can use the <function>isset</function> and
      <function>unset</function> functions to test and remove items
      from the data object.
     </para>
     <para>
      The following removes the 'employeeOfTheMonth' from the company.
      If this were a containment relationship then the
      employee would be removed from the company 
      (probably not a good idea to sack your best employee each month!), 
      but since this is a non-containment reference, 
      the employee being referenced will remain in the 
      department in the company,
      but will no longer be accessible via the employeeOfTheMonth property.
     </para>
     <programlisting role="php" id="sdo.examples.unsetrefdo">
<![CDATA[ 
<?php
  if (isset($company->employeeOfTheMonth)) {
    unset($company->employeeOfTheMonth);
  }
?>
]]>
     </programlisting>
    </example>
   </para>
  </section>

  <section id="sdo.sample.sequence">
   <title>Working with Sequenced Data Objects</title>
   <para>
    Sequenced data objects are SDOs which can track property
    ordering across the properties of a data object. They can also
    contain unstructured text elements (text element which do not
    belong to any of the SDO's properties).  Sequenced data objects are
    useful for working with XML documents which allow unstructured text (i.e.
    mixed=true) or if the elements can be interleaved (
    <![CDATA[<A/><B/><A/>]]>).  This can occur for example when
    the schema defines maxOccurs>1 on a
    element which is a complexType with a choice order indicator.
   </para>
   <para>
    The examples below assume an SDO created with the following schema
    and instance information, using the XML Data Access Service.
   </para>
   <para>
    The schema below describes the format of a letter.  The letter can
    optionally contain three properties; date, firstName, and lastName.
    The schema states <command>mixed="true"</command> which means that
    unstructured text can be interspersed between the three properties.
   </para>
   <para>
    <programlisting role="xml">
<![CDATA[
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:letter="http://letterSchema"
  targetNamespace="http://letterSchema">
  <xsd:element name="letters" type="letter:FormLetter"/>
  <xsd:complexType name="FormLetter" mixed="true">
    <xsd:sequence>
      <xsd:element name="date" minOccurs="0" type="xsd:string"/>
      <xsd:element name="firstName" minOccurs="0" type="xsd:string"/>
      <xsd:element name="lastName" minOccurs="0" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>
          ]]>
    </programlisting>
   </para>

   <para>
    The following is an instance letter document.  It contains the
    three letter properties; date, firstName and lastName, and has
    unstructured text elements for the address and letter body.
   </para>
   <para>
    <programlisting role="xml">
<![CDATA[
<letter:letters xmlns:letter="http://letterSchema">
  <date>March 1, 2005</date>
  Mutual of Omaha
  Wild Kingdom, USA
  Dear
  <firstName>Casy</firstName>
  <lastName>Crocodile</lastName>
  Please buy more shark repellent.
  Your premium is past due.
</letter:letters>
          ]]>
    </programlisting>
   </para>
   <para>
    When loaded, the letter data object will have the sequence and
    property indices shown in the table below:
    <informaltable>
     <tgroup cols='3'>
      <thead>
       <row>
        <entry>Sequence Index</entry>
        <entry>Property Index:Name</entry>
        <entry>Value</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>0</entry>
        <entry>0:date</entry>
        <entry>March 1, 2005</entry>
       </row>
       <row>
        <entry>1</entry>
        <entry>-</entry>
        <entry>Mutual of Omaha</entry>
       </row>
       <row>
        <entry>2</entry>
        <entry>-</entry>
        <entry>Wild Kingdom, USA</entry>
       </row>
       <row>
        <entry>3</entry>
        <entry>-</entry>
        <entry>Dear</entry>
       </row>
       <row>
        <entry>4</entry>
        <entry>1:firstName</entry>
        <entry>Casy</entry>
       </row>
       <row>
        <entry>5</entry>
        <entry>2:lastName</entry>
        <entry>Crocodile</entry>
       </row>
       <row>
        <entry>6</entry>
        <entry>-</entry>
        <entry>Please buy more shark repellent.</entry>
       </row>
       <row>
        <entry>7</entry>
        <entry>-</entry>
        <entry>Your premium is past due.</entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>

   <para>
    To ensure sequence indices are maintained, sequenced data objects
    should be manipulated through the SDO_Sequence interface.  
    This allows the data object's instance data to be manipulated 
    in terms of the sequence index as opposed to the property index 
    (shown in the table above).  
    The following examples assume the letter instance has been 
    loaded into a data object referenced by the variable
    <command>$letter</command>.
    <example>
     <title>Getting the SDO_Sequence interface</title>
     <para>
      We obtain a data object's sequence using the
      <function>getSequence</function>
      method. The follow gets the
      sequence for the letter data object.
     </para>
     <programlisting role="php" id="sdo.examples.seqinterface">
<![CDATA[ 
<?php
  $letter_seq = $letter->getSequence();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    All subsequent examples assume that the
    <command>$letter_seq</command>
    variable has been assigned the sequence for the letter data object.
   </para>

   <para>
    <example>
     <title>Get/set sequence values</title>
     <para>
      We can get and set individual values (including unstructured text)
      using the sequence index.  
      The following sets the firstName to 'Snappy' and gets the last 
      sequence values (the unstructured text, 'Your premium is past due.').
     </para>
     <programlisting role="php" id="sdo.examples.getsetseq">
<![CDATA[ 
<?php
  $letter_seq[4] = 'Snappy';
  $text = $letter_seq[count($letter_seq) - 1];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Sequence iteration</title>
     <para>
      We can iterate through the individual sequence values using foreach.
      The following runs through the individual values in sequence order.
     </para>
     <programlisting role="php" id="sdo.examples.seqiter">
<![CDATA[ 
<?php
  foreach ($letter->getSequence() as $value) {
    // ...
  }
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Sequence versus Data Object</title>
     <para>
      Setting values through the data object interface may result in the
      value not being part of the sequence.  A value set through the data
      object will only be accessible through the sequence if the property was
      already part of the sequence. The following example sets the
      lastName through the data object and gets it through the sequence.
      This is fine because lastName already exists in the sequence.  If
      it had not previously been set, then lastName would be set to
      'Smith', but would not be part of the sequence.
     </para>
     <programlisting role="php" id="sdo.examples.seqvsdo">
<![CDATA[ 
<?php
  $letter[2] = 'Smith';
  $last_name = $letter_seq[5];
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Adding to a sequence</title>
     <para>
      We can add new values to a sequence using the
      <link linkend='function.SDO-Sequence-insert'><function>SDO_Sequence::insert</function></link>
      method.  The following examples assume that the 'firstName' and 
      'lastName' properties are initially unset.
     </para>
     <programlisting role="php" id="sdo.examples.seqadd">
<![CDATA[ 
<?php
  // Append a firstName value to the sequence
  // value: 'Smith'
  // sequence index: NULL (append)
  // propertyIdentifier: 1 (firtName property index)
  $letter_seq->insert('Smith', NULL, 1);

  // Append a lastName value to the sequence
  // value: 'Jones'
  // sequence index: NULL (append)
  // propertyIdentifier: 'lastName' (lastName property name)
  $letter_seq->insert('Jones', NULL, 'lastName');

  // Append unstructured text
  // value: 'Cancel Subscription.'
  // sequence index: absent (append)
  // propertyIdentifier: absent (unstructured text)
  $letter_seq->insert('Cancel Subscription.');

  // Insert new unstructured text.  Subsequent sequence values
  // are shifted up.                                       
  // value: 'Care of:'
  // sequence index: 1 (insert as second element)
  // propertyIdentifier: absent (unstructured text)
  $letter_seq->insert('Care of:', 1);
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Removing from a sequence</title>
     <para>
      We can use the <function>isset</function>  and
      <function>unset</function> functions to test and remove items
      from the sequence (Note: <function>unset</function> currently
      leaves the values in the data object, but this behaviour is
      likely to change to also remove the data from the data object).
      A sequence behaves like a contiguous list; therefore, removing
      items from the middle will shift entries at higher indices
      down. The following example tests to see if the first sequence
      element is set and unsets it if is.
     </para>
     <programlisting role="php" id="sdo.examples.seqremove">
<![CDATA[ 
<?php
  if (isset($letter_seq[0])) {
    unset($letter_seq[0]);
  }
?>
]]>
     </programlisting>
    </example>
   </para>

  </section>


  <section id="sdo.sample.reflection">
   <title>Reflecting on Service Data Objects</title>
   <para>
    SDOs have a knowledge of the structure they have been created to 
    represent (the model).  For example, a Company SDO created using 
    <link linkend="sdo.examples">the Company XML schema</link> above
    would only be permitted to contain DepartmentType data objects 
    which in turn could only contain EmployeeType data objects.
   </para>
   <para>
    Sometimes it is useful to be able to access this model information at 
    runtime.  For example, this could be used to automatically generate 
    a user interface for populating a data object.  The model information 
    is accessed using reflection.  
   </para>

   <para>
    <example>
     <title>Reflecting on a Data Object</title>
     <para>
      The following example shows how we can reflect on an empty Employee 
      data object.
     </para>
     <programlisting role="php" id="sdo.examples.reflection">
<![CDATA[ 
<?php
  // Create the employee data object (e.g. from an XML Data Access Service)
  $employee = ...;
  $reflection = new SDO_Model_ReflectionDataObject($employee);
  print($reflection);
?>
]]>
     </programlisting>
     &example.outputs;

     <screen>
<![CDATA[
object(SDO_Model_ReflectionDataObject)#4 { - ROOT OBJECT - Type { 
companyNS:EmployeeType[3] { commonj.sdo:String $name; 
commonj.sdo:String $SN; commonj.sdo:Boolean $manager; } }
]]>
     </screen>
     <para>
      Using print on the SDO_Model_ReflectionDataObject writes out the data 
      object's model.  We can see from the output how the type 
      companyNS:EmployeeType has three properties and we can see the names 
      of the properties along with their types.  Note, the primitive types
      are listed as SDO types (e.g. commonj.sdo namespace, String type).  
      It is worth noting that this is the SDO model and when these are 
      surfaced to an application they can be treated as the PHP equivalent 
      types (e.g. string and boolean).
     </para>
    </example>
   </para>

   <para>
    <example>
     <title>Accessing the type information</title>
     <para>
      We can query the type information of a data object using reflection.  
      The following example checks the type corresponds to a data object
      rather than a primitive and then iterates through the properties of
      the type, writing out the name of each property ($type and $property 
      are SDO_Model_Type and SDO_Model_Property objects, respectively).
     </para>
     <programlisting role="php" id="sdo.examples.reflection.type">
<![CDATA[ 
<?php
    // Create the employee data object (e.g. from an XML Data Access Service)
    $employee = ...;
    $reflection = new SDO_Model_ReflectionDataObject($employee);
    $type = $reflection->getType();
    if (! $type->isDataType()) {
        foreach ($type->getProperties() as $property) {
            print $property->getName() . "\n";
        }
    }
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
name
SN
manager
]]>
     </screen>
    </example>
   </para>

  </section>





  <!-- class definition section -->
  <section id='sdo.classes'>
   &reftitle.classes;
   <para>
    SDO consists of three sets of interfaces.  The first set covers those
    interfaces for use by typical SDO applications.  These are identified 
    by the package prefix 'SDO_'.  The second set is those used to reflect 
    on, and work with, the model of a data object.  These are identified 
    by the package prefix 'SDO_Model_'.  Finally, the third set are those 
    use by Data Access Service implementations and are identified by the 
    package prefix 'SDO_DAS_'.  The majority of SDO users will not need to 
    use or understand the 'SDO_Model_' and 'SDO_DAS_' interfaces.
   </para>

   <section id='sdo.class.sdo-apis'>
    <title>SDO Application Programmer Interface</title>

    <section id='sdo.class.sdo-dataobject'>
     <title>
      <classname>SDO_DataObject</classname>
     </title>
     <para>
      The main interface through which data objects are manipulated.  In
      addition to the methods below, SDO_DataObject extends the
      ArrayAccess, SDO_PropertyAccess (defines <function>__get</function> /
      <function>__set</function> methods for property access overloading),
      Iterator, and Countable interfaces.
     </para>
     <section id='sdo.class.SDO_DataObject.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-getSequence'>getSequence</link>
         - get the sequence for the data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-createDataObject'>createDataObject</link>
         - create a child data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-clear'>clear</link>
         - unset the properties of a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-getContainer'>getContainer</link>
         - get the container (also known as 'parent') of this data object
        </para>
       </listitem>      
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-getTypeName'>getTypeName</link>
         - get the name of the type for this data object
        </para>
       </listitem>     
       <listitem>
        <para>
         <link linkend='function.SDO-DataObject-getTypeNamespaceURI'>getTypeNamespaceURI</link>
         - get the namespace URI of the type for this data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdo-sequence'>
     <title>
      <classname>SDO_Sequence</classname>
     </title>
     <para>
      The interface through which sequenced data objects can be accessed
      to preserve ordering across a data object's properties and 
      to allow unstructured text.  
      SDO_Sequence preserves contiguous indices and therefore inserting 
      or removing elements may shift other elements up or
      down. In addition to the methods below, SDO_Sequence extends the
      ArrayAccess, Iterator and Countable interface.
     </para>
     <section id='sdo.class.SDO_Sequence.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-Sequence-getProperty'>getProperty</link> 
         - get the property for a given sequence index
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Sequence-move'>move</link>
         - move an element from one property index to another
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Sequence-insert'>insert</link>
         - insert a new value into the sequence
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdo-list'>
     <title>
      <classname>SDO_List</classname>
     </title>
     <para>
      The interface through which many-valued properties are manipulated.
      In addition to the method defined below, SDO_List extends ArrayAccess,
      Iterator and Countable.  SDO_List preserves contiguous indices and
      therefore inserting or removing elements may shift other elements
      up or down.
     </para>
     <section id='sdo.class.SDO-List.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-List-insert'>insert</link> 
         - insert a new value into the list
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdo-datafactory'>
     <title>
      <classname>SDO_DataFactory</classname>
     </title>
     <para>
      The interface through which data objects can be created.  
      A Data Access Service is responsible for populating the model 
      (i.e. configuring the data factory with the type and structure 
      information for the data objects it can create.) 
      for the factory and can then optionally return an instance of, 
      or implement, the SDO_DataFactory interface.
     </para>
     <section id='sdo.class.SDO-DataFactory.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DataFactory-create'>create</link> 
         - create a new data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>
        
    <section id='sdo.class.sdo-exception'>
     <title>
      <classname>SDO_Exception</classname>
     </title>
     <para>
      An SDO_Exception is thrown when the caller's request cannot be completed.
      The subclasses of SDO_Exception are:
      <itemizedlist>
       <listitem>
        <para>SDO_PropertyNotSetException -
        the property specified exists but has not been set or does not have a
        default value
        </para>
       </listitem>
       <listitem>
        <para>SDO_PropertyNotFoundException -
        the property specified is not part of the data object's type
        </para>
       </listitem>
       <listitem>
        <para>SDO_TypeNotFoundException -
        the specified namespace URI or type name is unknown
        </para>
       </listitem>
       <listitem>
        <para>SDO_InvalidConversionException -
        conversion between the types of the assignment is not possible 
        </para>
       </listitem>
       <listitem>
        <para>SDO_IndexOutOfBoundsException -
        the numeric index into a data object, sequence or list is not in the
        valid range 
        </para>
       </listitem>
       <listitem>
        <para>SDO_UnsupportedOperationException -
        the request cannot be completed because it is not allowed,
        for example an attempt to set a read-only property.
        </para>
       </listitem>
      </itemizedlist>
     </para>
     <section id='sdo.class.SDO_Exception.methods'> &reftitle.methods;
     <para>One method is added to those inherited from the built in 
     <link linkend='language.exceptions.extending'>Exception</link> class:
     </para>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-Exception-getCause'>getCause</link> 
         - get the cause of this SDO_Exception
        </para>
       </listitem>

      </itemizedlist>
     </section>
    </section>
    
   </section>



   <section id='sdo.class.sdo-model-apis'>
    <title>SDO Reflection Application Programmer Interfaces</title>

    <section id='sdo.class.sdo-reflectiondataobject'>
     <title>
      <classname>SDO_Model_ReflectionDataObject</classname>
     </title>
     <para>
      The main interface used to reflect on a data object instance 
      to obtain its model type and property information.  
      It is designed to follow the reflection pattern introduced in PHP 5.
     </para>
     <section id='sdo.class.SDO_Model_ReflectionDataObject.constructor'> 
       &reftitle.constructor;     
       <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-ReflectionDataObject-construct'>__construct</link>
         - construct a new SDO_Model_ReflectionDataObject.
        </para>
       </listitem>     
      </itemizedlist>
     </section>
     <section id='sdo.class.SDO_Model_ReflectionDataObject.methods'> 
       &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-ReflectionDataObject-export'>export</link>
         - get a string describing the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-ReflectionDataObject-getType'>getType</link>
         - get the SDO_Model_Type for the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend=
          'function.SDO-Model-ReflectionDataObject-getInstanceProperties'>getInstanceProperties</link>
         - get the instance properties of the data object.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend=
          'function.SDO-Model-ReflectionDataObject-getContainmentProperty'>getContainmentProperty</link>
         - get the property which defines the containment relationship to the data object.
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdo-type'>
     <title>
      <classname>SDO_Model_Type</classname>
     </title>
     <para>
      The interface through which a data object's type information can be 
      retrieved.  This interface can be used to find out the type name and 
      namespace URI of the type, whether the type allow open content, and so 
      on.
     </para>
     <section id='sdo.class.SDO_Model_Type.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-getName'>getName</link>
          - get the name of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-getNamespaceURI'>getNamespaceURI</link>
         - get the namespace URI of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-isInstance'>isInstance</link>
         - test for a data object being an instance of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-getProperties'>getProperties</link>
         - get the properties of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-getProperty'>getProperty</link>
         - get a property of the type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-isDataType'>isDataType</link>
         - test to see if this type is a primitive scalar type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-isSequencedType'>isSequencedType</link>
         - test to see if this is a sequenced type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-isOpenType'>isOpenType</link>
         - test to see if this is an open type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-isAbstractType'>isAbstractType</link>
         - test to see if this is an abstract type.
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-Model-Type-getBaseType'>getBaseType</link>
         - get the base type of this type (if one exists).
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdo-property'>
     <title>
      <classname>SDO_Model_Property</classname>
     </title>
     <para>
      The interface through which a data object's property information can 
      be retrieved.  This interface can be used to find out the type of a 
      property, whether a property has a default value, whether the 
      property is contained or reference by its parent, its cardinality, 
      and so on.
     </para>
     <section id='sdo.class.SDO_Model_Property.methods'> &reftitle.methods;
      <itemizedlist>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-getName'>getName</link>
          - get the name of the property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-getType'>getType</link>
          - get the type of the property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-isMany'>isMany</link>
          - test to see if the property is many-valued.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-isContainment'>isContainment</link>
          - test to see if the property describes a containment relationship.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-getContainingType'>getContainingType</link>
          - get the type which contains this property.
         </para>
        </listitem>
        <listitem>
         <para>
          <link linkend='function.SDO-Model-Property-getDefault'>getDefault</link>
          - get the default value for a property.
         </para>
        </listitem>
      </itemizedlist>
     </section>
    </section>



   </section>

   <section id='sdo.class.sdo-das-spis'>
    <title>
     SDO Data Access Service Developer Interfaces
    </title>

    <section id='sdo.class.sdodas-dataobject'>
     <title>
      <classname>SDO_DAS_DataObject</classname>
     </title>
     <para>
      The interface through which a Data Access Service can access 
      a data object's 
      <link linkend='sdo.class.sdodas-changesummary'>SDO_DAS_ChangeSummary</link>.
      The change summary is used by the Data Access Service to check for 
      conflicts when applying changes back to a data source.
     </para>
     <section id='sdo.class.SDO_DAS_DataObject.methods'> &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-DataObject-getChangeSummary'>getChangeSummary</link> 
         - get the change summary for a data object
        </para>
       </listitem>

      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdodas-changesummary'>
     <title>
      <classname>SDO_DAS_ChangeSummary</classname>
     </title>
     <para>
      The interface through which the change history of a data
      object is accessed.  The change summary holds information for any
      modifications on a data object which occurred since logging
      was activated.  In the case of deletions and modifications, the old
      values are also held in the change summary.
     </para>
     <para>
      If logging is no longer active
      then the change summary only holds changes made up to the point when
      logging was deactivated.  
      Reactivating logging clears the change summary.
      This is useful when a set of changes have been written out by a
      DAS and the data object is to be reused.
     </para>
     <section id='sdo.class.SDO_DAS_ChangeSummary.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-beginLogging'>beginLogging</link> 
         - begin logging changes made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-endLogging'>endLogging</link> 
         - end logging changes made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-isLogging'>isLogging</link> 
         - test to see if change logging is on
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-getChangedDataObjects'>getChangedDataObjects</link> 
         - get a list of the data objects which have been changed
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-getChangeType'>getChangeType</link> 
         - get the type of change which has been made to a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>getOldValues</link> 
         - get a list of old values for a data object
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-ChangeSummary-getOldContainer'>getOldContainer</link> 
         - get the old container data object for a deleted data object
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdodas-setting'>
     <title>
      <classname>SDO_DAS_Setting</classname>
     </title>
     <para>
      The interface through which the old value for a property is
      accessed. A list of settings is returned by the change summary method
      <link linkend='function.SDO-DAS-ChangeSummary-getOldValues'>
       <function>getOldValues</function>
      </link>.
     </para>
     <section id='sdo.class.SDO_DAS_Setting.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-Setting-getPropertyIndex'>getPropertyIndex</link> 
         - get the property index for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-Setting-getPropertyName'>getPropertyName</link> 
         - get the property name for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-Setting-getValue'>getValue</link> 
         - get the old value for the changed property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-Setting-getListIndex'>getListIndex</link> 
         - get the list index for the old value if it was part of a 
         many-valued property
        </para>
       </listitem>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-Setting-isSet'>isSet</link>
         - test to see if the property was set prior to being modified
         </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section id='sdo.class.sdodas-datafactory'>
     <title>
      <classname>SDO_DAS_DataFactory</classname>
     </title>
     <para>
      The interface for constructing the model for an SDO_DataObject.
      The SDO_DAS_DataFactory is an abstract class providing a static
      method which returns a concrete data factory implementation.
      The implementation is used by Data Access Services to create an 
      SDO model from their model.
      For example, a Relational Data Access Service might create and populate
      an SDO_DAS_DataFactory model based on a schema for a relational
      database.
     </para>
     <section id='sdo.class.SDO_DAS_DataFactory.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-DataFactory-getDataFactory'>getDataFactory</link> 
         - static methods for getting a concrete data factory instance
        </para>
       </listitem>
      </itemizedlist>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-DataFactory-addType'>addType</link> 
         - add a new type to the SDO model
        </para>
       </listitem>
      </itemizedlist>
      <itemizedlist>
       <listitem>
        <para>
         <link linkend='function.SDO-DAS-DataFactory-addPropertyToType'>addPropertyToType</link> 
         - add a new property to a type definition in the SDO model
        </para>
       </listitem>
      </itemizedlist>
     </section>
    </section>
   </section>
  </section>

  &reference.sdo.constants;

 </partintro>

 &reference.sdo.functions;

</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->