<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/hw.xml, last change in rev 1.2 -->
  <refentry id="function.hw-modifyobject">
   <refnamediv>
    <refname>hw_Modifyobject</refname>
    <refpurpose>Modifies object record</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>hw_modifyobject</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
      <methodparam><type>int</type><parameter>object_to_change</parameter></methodparam>
      <methodparam><type>array</type><parameter>remove</parameter></methodparam>
      <methodparam><type>array</type><parameter>add</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     This command allows to remove, add, or modify individual attributes
     of an object record.  The object is specified by the Object ID
     <parameter>object_to_change</parameter>. The first array
     <parameter>remove</parameter> is a list of attributes to remove.
     The second array <parameter>add</parameter> is a list of attributes
     to add. In order to modify an attribute one will have to remove
     the old one and add a new one. <function>hw_modifyobject</function>
     will always remove the attributes before it adds attributes unless
     the value of the attribute to remove is not a string or array.
    </para>
    <para>
     The last parameter determines if the modification is performed
     recursively. 1 means recursive modification. If some of the objects
     cannot be modified they will be skipped without notice.
     <function>hw_error</function> may not indicate an error though
     some of the objects could not be modified.
    </para>
    <para>
     The keys of both arrays are the attributes name. The value of each
     array element can either be an array, a string or anything else.
     If it is an array
     each attribute value is constructed by the key of each element plus
     a colon and the value of each element. If it is a string it is taken
     as the attribute value. An empty string will result in a complete
     removal of that attribute. If the value is neither a string nor an
     array but something else, e.g. an integer, no operation at all will
     be performed on the attribute. This is necessary if you want to
     add a completely new attribute not just a new value for an existing
     attribute. If the remove array contained
     an empty string for that attribute, the attribute would be tried to be
     removed which would fail since it doesn't exist. The following addition of
     a new value for that attribute would also fail. Setting the value
     for that attribute to e.g. 0 would not even try to remove it and
     the addition will work.
    </para>
    <para>
     If you would like to change the attribute 'Name' with the current
     value 'books' into 'articles' you will have to create two arrays
     and call <function>hw_modifyobject</function>.
     <example>
      <title>modifying an attribute</title>
      <programlisting role="php">
<![CDATA[
<?php
       // $connect is an existing connection to the Hyperwave server
       // $objid is the ID of the object to modify
       $remarr = array("Name" => "books");
       $addarr = array("Name" => "articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>
]]>
      </programlisting>
     </example>
     In order to delete/add a name=value pair from/to the object record just
     pass the remove/add array and set the last/third parameter to an empty
     array. If the attribute is the first one with that name to add, set
     attribute value in the remove array to an integer.
     <example>
      <title>adding a completely new attribute</title>
      <programlisting role="php">
<![CDATA[
<?php
       // $connect is an existing connection to the Hyperwave server
       // $objid is the ID of the object to modify
       $remarr = array("Name" => 0);
       $addarr = array("Name" => "articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <note>
      <simpara>
       Multilingual attributes, e.g. 'Title', can be modified in two
       ways. Either by providing the attributes value in its native
       form 'language':'title' or by providing an array with elements
       for each language as described above. The above example would
       than be:
      </simpara>
     </note>
     <example>
      <title>modifying Title attribute</title>
      <programlisting role="php">
<![CDATA[
<?php
       $remarr = array("Title" => "en:Books");
       $addarr = array("Title" => "en:Articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>
]]>
      </programlisting>
     </example>
      or
     <example>
      <title>modifying Title attribute</title>
      <programlisting role="php">
<![CDATA[
<?php
       $remarr = array("Title" => array("en" => "Books"));
       $addarr = array("Title" => array("en" => "Articles", "ge"=>"Artikel"));
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>
]]>
      </programlisting>
     </example>
     This removes the English title 'Books' and adds the English title
     'Articles' and the German title 'Artikel'.
     <example>
      <title>removing attribute</title>
      <programlisting role="php">
<![CDATA[
<?php
       $remarr = array("Title" => "");
       $addarr = array("Title" => "en:Articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>
]]>
      </programlisting>
     </example>
     <note>
      <simpara> 
       This will remove all attributes with the name 'Title' and adds
       a new 'Title' attribute. This comes in handy if you want to
       remove attributes recursively.  
      </simpara>
     </note>
     <note>
      <simpara>
       If you need to delete all attributes with a certain name you
       will have to pass an empty string as the attribute value.
      </simpara>
     </note>
     <note>
      <simpara>
       Only the attributes 'Title', 'Description' and 'Keyword' will
       properly handle the language prefix. If those attributes don't carry
       a language prefix, the prefix 'xx' will be assigned.
      </simpara>
     </note>
     <note>
      <simpara>
       The 'Name' attribute is somewhat special. In some cases it cannot 
       be complete removed. You will get an error message 'Change of base
       attribute' (not clear when this happens). Therefore you will always
       have to add a new Name first and than remove the old one.
      </simpara>
     </note>
     <note>
      <simpara>
       You may not surround this function by calls to
       <function>hw_getandlock</function> and <function>hw_unlock</function>.
       <function>hw_modifyobject</function> does this internally.
      </simpara>
     </note>
    </para>
    <para>
     &return.success;
    </para>
   </refsect1>
  </refentry>

<!-- 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
-->