cem             Fri Mar 24 15:46:38 2006 UTC

  Modified files:              
    /phpdoc/en/reference/sdo    reference.xml 
  Log:
  Updates for 1.0 release
  
http://cvs.php.net/viewcvs.cgi/phpdoc/en/reference/sdo/reference.xml?r1=1.21&r2=1.22&diff_format=u
Index: phpdoc/en/reference/sdo/reference.xml
diff -u phpdoc/en/reference/sdo/reference.xml:1.21 
phpdoc/en/reference/sdo/reference.xml:1.22
--- phpdoc/en/reference/sdo/reference.xml:1.21  Fri Feb 24 18:36:41 2006
+++ phpdoc/en/reference/sdo/reference.xml       Fri Mar 24 15:46:38 2006
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.21 $ -->
+<!-- $Revision: 1.22 $ -->
 <!-- Purpose: database.abstract -->
 <!-- Membership: pecl -->
 <!-- State: experimental -->
@@ -10,12 +10,7 @@
 
  <partintro>
   <section id="sdo.intro">
-   &reftitle.intro;
-   <para>
-    <!-- This warns that the extension is experimental -->
-    &warn.experimental;
-   </para>
-   
+   &reftitle.intro;   
    <para>
     Service Data Objects (SDOs) enable PHP applications to work with
     data from different sources (like a database query, an XML file, 
@@ -28,7 +23,7 @@
     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).
+    to a data source, typically the same one.
    </para>
    <para>
     See the
@@ -40,10 +35,10 @@
     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>
+     This extension is derived from concepts taken from the
+     <ulink url="&url.ibm.sdo;">Service Data Objects specification</ulink>.
+     It includes a version of the
+     <ulink url="&url.apache.tuscany;">Apache Tuscany</ulink> SDO 2.0 for C++ 
project.
    </para>
 
    <section id="sdo.intro.structure">
@@ -54,16 +49,10 @@
      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> 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. 
     </para>
     <para>
      As well as data objects referencing each other, they can also have
@@ -71,187 +60,115 @@
      have a property called "name" of type string, for holding the name
      of the company (for example, "Acme").
     </para>
+    <para> Each of these properties of a data object - containment 
relationships,
+     non-containment references, or primitive properties - may be many-valued 
or
+     single-valued. In the above examples, Departments is many-valued and
+    the Company name is single-valued.
+    </para>
+    <para> In PHP, each SDO data object is represented as a PHP object. The 
properties of the
+     data object can be accessed using either object syntax or associative 
array syntax.
+     We'll see some examples of this later.
+    </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
+   <para> The SDO extension requires PHP 5.1 or higher. It also requires the 
libxml2 library.
+    Normally libxml2 will already be installed, but if not, it 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">
+   <procedure id='sdo.install.unix'>
+     <title>Unix systems</title>
+     <step>
+      <para> You can download and install the latest stable release of all 
three SDO
+       components - the SDO core, the XML DAS and the Relational DAS - with 
the command:
+       <screen> <![CDATA[
+pear install sdo
+]]>
+       </screen>
+      </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>
+      <para>
+       If you want to use the latest beta version, then instead run:
+       <screen> 
 <![CDATA[
+pear install sdo-beta
+]]>
+       </screen>
+     </para>
+    </step>
+    <step>
+     <para> The
+      <command>pear</command> command automatically installs the SDO and 
SDO_DAS_XML
+      modules into your PHP extensions directory. To enable the SDO extensions 
you must add
+      the following lines to &php.ini;:
+      <screen> <![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>
+      </screen>
+     </para>
+     <para> For more information about building PECL packages, consult the
+      <link linkend="install.pecl">PECL installation</link> section of the 
manual.
+     </para>
+    </step>
+    </procedure>
+   
+   <procedure id='sdo.install.win32'>
+    <title>Windows</title>
+    <step>
+     <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.dll</ulink> and 
+      <ulink 
url='&url.pecl.win.ext;php_sdo_das_xml.dll'>php_sdo_das_xml.dll</ulink> 
respectively.
+     </para>
+     <para> 
+      Note that currently the <ulink url='&url.pecl.win;'>pecl4win</ulink> 
site does not provide 
+      these binaries at the current release level; you can only download the 
latest level.
+     </para>
+    </step>    
+    <step>
+     <para> The
+      <command>pear</command> command automatically installs the SDO and 
SDO_DAS_XML
+      modules into your PHP extensions directory. To enable the SDO extensions 
you must add
+      the following lines to &php.ini;:
+      <screen>
+       <![CDATA[
+extension=php_sdo.dll
+extension=php_sdo_das_xml.dll
+]]>
+      </screen>
+     </para>
+    </step>
+    <step>
+     <para> The Relational DAS can be downloaded and installed with the 
command:
+      <screen>
+      <![CDATA[
+pear install -B sdo
+]]>
+      </screen>
+     </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>
+    </step>
+   </procedure>
    
-   <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> This section describes how to build the SDO core and XML DAS on 
Linux. 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>
@@ -267,8 +184,8 @@
     </step>
     <step>
      <para>
-      Next, run <command>./configure; make; make install</command>. Please
-      note, you may need to login as root to install the extension.
+      Next, run <command>./configure; make; make install</command>. 
+      Please note, you may need to login as root to install the extension.
      </para>
     </step>
     <step>
@@ -276,7 +193,7 @@
       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. 
+      &php.ini; file in the same order. 
      </para>
     </step>
    </procedure>
@@ -301,8 +218,7 @@
         </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.
+         SDOs as XML documents.
         </entry>
        </row>
        <row>
@@ -311,7 +227,7 @@
         </entry>
         <entry>
          A PDO-based Data Access Service supporting reading/writing SDO 
-         to relational data sources.  
+         to relational databases.  
          Implements an optimistic concurrency policy for updates.
         </entry>
        </row>
@@ -331,6 +247,9 @@
     <step>
      <para>
       There is no support for multi-byte character sets.
+      This will be considered, depending on community requirements,
+      in the Unicode-enabled version of PHP.
+      See <link linkend="ref.unicode">Unicode Functions</link>.
      </para>
     </step>
    </procedure>
@@ -344,16 +263,6 @@
     </para>
     <step>
      <para>
-      Abstract types and type derivation.
-     </para>
-    </step>
-    <step>
-     <para>
-      Open types.
-     </para>
-    </step>
-    <step>
-     <para>
       Bi-directional relationships.
      </para>
     </step>
@@ -368,13 +277,12 @@
      </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> 
+      The Helper classes defined in SDO 2.0 are not directly implemented. 
+      However equivalent function is provided in a more natural way for PHP. 
+      For example the function of <command>CopyHelper::copy()</command> 
+      is provided by applying the PHP
+      <link linkend='language.oop5.cloning'>clone</link> keyword to a data 
object.
      </para>
     </step>
    </procedure>
@@ -387,14 +295,32 @@
     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'.
+    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="E0003">
+  <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>
+   <para> The root element of the schema is a company. The company contains 
departments, and
+    each department contains employees. Each element has a number of 
attributes to store
+    things like name, serial number, and so on. Finally, the company also has 
an IDREF
+    attribute which identifies one of the employees as the 
'employeeOfTheMonth'.
    </para>
    <para>
     <programlisting role="xml">
@@ -409,15 +335,16 @@
   <xsd:complexType name="CompanyType">
     <xsd:sequence>
       <xsd:element name="departments" type="company:DepartmentType" 
-       maxOccurs="unbounded"/>
+        maxOccurs="unbounded"/>
     </xsd:sequence>
     <xsd:attribute name="name" type="xsd:string"/>
     <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" 
-sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
+      sdoxml:propertyType="company:EmployeeType"/> 
+  </xsd:complexType>
   <xsd:complexType name="DepartmentType">
     <xsd:sequence>
       <xsd:element name="employees" type="company:EmployeeType"  
-       maxOccurs="unbounded"/>
+        maxOccurs="unbounded"/>
     </xsd:sequence>
     <xsd:attribute name="name" type="xsd:string"/>
     <xsd:attribute name="location" type="xsd:string"/>
@@ -432,52 +359,32 @@
 ]]>
     </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>The XML Data Access Service maps the schema to an SDO. Attributes 
such as "name"
+    become primitive properties, the sequence of employees becomes a 
many-valued
+    containment relationship, and so on. Note that the containment 
relationships are
+    expressed as one complex type within another, whereas non-containment 
references are
+    expressed in terms of ID and IDREF, with a special
+    <command>sdoxml:propertyType</command> attribute specifying the type of the
+    non-containment reference.
    </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> The following examples assume
+    <command>$company</command> is the root of a tree of data objects created 
from the
+    schema and instance document shown above.
    </para>
    <para>
     <example>
-     <title>Access via Property names</title>
+     <title>Access via property name</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'.
+      access syntax.  The following sets the company name to 'Acme'.
      </para>
      <programlisting role="php" id="sdo.examples.propname">
 <![CDATA[
 <?php
-  $departments = $company->departments;
   $company->name = 'Acme';
 ?>
 ]]>
@@ -487,24 +394,16 @@
 
    <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'.
+     <title>Access via property name as array index</title>
+     <para>We can also access properties using associative array syntax. The 
simplest
+      form of this uses the property name as the array index. For example, the 
following sets
+      the company name and gets the employeeOfTheMonth.
      </para>
-     <programlisting role="php" id="sdo.examples.propindex">
+     <programlisting role="php" id="sdo.examples.simplexpath">
 <![CDATA[
 <?php
-  $departments = $company[0];
-  $company[1] = 'Acme';
+  $company['name'] = 'UltraCorp';
+  $eotm = $company['employeeOfTheMonth'];
 ?>
 ]]>
      </programlisting>
@@ -513,59 +412,55 @@
 
    <para>
     <example>
-     <title>Data Object Iteration</title>
+     <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.
+      The following iterates over the properties of the employee of the month.
      </para>
      <programlisting role="php" id="sdo.examples.doiter">
 <![CDATA[
 <?php
-  foreach ($company as $name => $value) {
-    // ...
+  $eotm = $company->employeeOfTheMonth;
+  foreach ($eotm as $name => $value) {
+      echo "$name: $value\n";
   }
 ?>
 ]]>
      </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> 
+      which will output:
+     </para>     
+     <programlisting id="sdo.examples.doiter-output">
+<![CDATA[
+name: Jane Doe
+SN: E0003
+]]>
+     </programlisting>
+     <para> 
+      The 'manager' property is not output, because it has not been set.
      </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.
+     <title>Access many-valued property by name</title>
+     <para> Many-valued data object properties can also be accessed using the 
object
+      property name syntax. The following gets the list of departments.
      </para>
-     <programlisting role="php" id="sdo.examples.mvpiter">
+     <programlisting role="php" id="sdo.examples.mvpname">
 <![CDATA[
 <?php
-  foreach ($company->departments as $department) {
-    // ...
-  }
+  $departments = $company->departments;
 ?>
 ]]>
      </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>
+     <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.
@@ -582,98 +477,101 @@
 
    <para>
     <example>
-     <title>Nested Property Access</title>
+     <title>Many-valued property iteration</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.
+      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.nestedprop">
+     <programlisting role="php" id="sdo.examples.mvpiter">
 <![CDATA[
 <?php
-  $dept_name = $company->departments[0]->name;
-  $company->departments[0]->name = 'Emerging Technologies';
+  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>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.
+     <title>Chained property access</title>
+     <para> We can chain property references on a single line. 
+      The following sets and gets the name of the first department.
      </para>
-     <programlisting role="php" id="sdo.examples.simplexpath">
+     <programlisting role="php" id="sdo.examples.nestedprop">
 <![CDATA[
 <?php
-  $company['name'] = 'UltraCorp';
-  $eotm = $company['employeeOfTheMonth'];
+  $company->departments[0]->name = 'Emerging Technologies';
+  $dept_name = $company->departments[0]->name;
 ?>
 ]]>
      </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>
+     <para>Using the associative array syntax, this is equivalent to</para>
      <programlisting role="php" id="sdo.examples.chainarray">
 <![CDATA[
 <?php
-  $dept_name = $company['departments'][0]['name'];
   $company['departments'][0]['name'] = 'Emerging Technologies';
+  $dept_name = $company['departments'][0]['name'];
 ?>
 ]]>
      </programlisting>
+     <para> In either case, the dept_name variable is set to 'Emerging 
Technologies'.
+     </para>
     </example>
    </para>
 
    <para>
     <example>
-     <title>XPath Navigation</title>
+     <title>XPath navigation</title>    
+     <para> The associative array index can be an XPath-like expression. Valid
+      expressions are defined by an augmented sub-set of XPath.
+     </para>
      <para>
-      We can use XPath expressions to navigate the data object
-      instance structure.  Two forms of indexing into many-valued 
-      properties are supported.  
+      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.
+      starting at zero.  The standard syntax is:
      </para>
-     <programlisting role="php" id="sdo.examples.xpathnav">
+     <programlisting role="php" id="sdo.examples.xpath1nav">
 <![CDATA[
 <?php
   $jane_doe = $company["departments[1]/employees[2]"];
+?>
+]]>
+     </programlisting>    
+     <para>and the SDO XPath extension syntax is:</para> 
+     <programlisting role="php" id="sdo.examples.xpath0nav">
+<![CDATA[
+<?php
   $jane_doe = $company["departments.0/employees.1"];
 ?>
 ]]>
      </programlisting>
+     <para>
+      Both these examples get the second employee from the first department.
+     </para>
     </example>
    </para>
 
    <para>
     <example>
-     <title>XPath Querying</title>
+     <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[
+      <![CDATA[
 <?php
  $ad_tech_mgr = 
-  $company["departments[name=\"Advanced 
Technologies\"]/employees[manager=\"true\"]"];
+  $company["departments[name='Advanced 
Technologies']/employees[manager=true]"];
 ?>
 ]]>
      </programlisting>
@@ -682,7 +580,7 @@
 
    <para>
     <example>
-     <title>Creating child data object</title>
+     <title>Creating child data objects</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.  
@@ -692,7 +590,7 @@
      <programlisting role="php" id="sdo.examples.create">
 <![CDATA[
 <?php
-  $ad_tech_dept = $company["departments[name=\"Advanced Technologies\"]"];
+  $ad_tech_dept = $company["departments[name='Advanced Technologies']"];
   $new_hire = $ad_tech_dept->createDataObject('employees');
   $new_hire->name = 'John Johnson';
   $new_hire->SN = 'E0005';
@@ -705,13 +603,46 @@
 
    <para>
     <example>
-     <title>Unset referenced data object</title>
+     <title>Unset a primitive property</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 clears the name of the first department.
+     </para>
+     <programlisting role="php" id="sdo.examples.unsetprim">
+<![CDATA[ 
+<?php
+  unset($company->departments[0]->name);
+?>
+]]>
+     </programlisting>
+    </example>
+   </para>
+      
+   <para>
+    <example>
+     <title>Unset a data object</title>
+     <para>
+      unset can also be used to remove a data object from the tree.
+      The following example shows John Jones leaving the company. 
+     </para>
+     <programlisting role="php" id="sdo.examples.unsetdo">
+<![CDATA[ 
+<?php
+  unset($company->departments[0]->employees[0]);
+?>
+]]>
+     </programlisting>
+    </example>
+   </para>
+   
+   <para>
+    <example>
+     <title>Unset a referenced data object</title>
+     <para>
       The following removes the 'employeeOfTheMonth' from the company.
       If this were a containment relationship then the
       employee would be removed from the company 
@@ -732,6 +663,32 @@
      </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 company name attribute is the second company property 
(the SDO
+      interface makes no distinction between XML attributes and elements). The 
following
+      sets the company name to 'Acme', with the same result as
+      <link linkend="sdo.examples.propname">Access via property name</link>
+     </para>
+     <programlisting role="php" id="sdo.examples.propindex">
+<![CDATA[
+<?php
+  $company[1] = 'Acme';
+?>
+]]>
+     </programlisting>
+     <para> Using the index directly in this way is likely to be fragile. 
Normally the
+      property name syntax should be preferred, but the property index may be 
required
+     in special cases.
+     </para>
+    </example>
+   </para>
+
   </section>
 
   <section id="sdo.sample.sequence">

Reply via email to