CVS update: phpdoc/functions

Date: Wednesday June 16, 1999 @ 6:29 Author: steinm Update of /repository/phpdoc/functions In directory php:/tmp/cvs-serv23862/functions Modified Files: cpdf.sgml hw.sgml Log Message: - fixed link in hw.sgml - fixed parse errors in cpdf.sgml, some small additions Index: phpdoc/functions/cpdf.sgml diff -u phpdoc/functions/cpdf.sgml:1.3 phpdoc/functions/cpdf.sgml:1.4 --- phpdoc/functions/cpdf.sgml:1.3 Wed Jun 16 02:41:49 1999 +++ phpdoc/functions/cpdf.sgml Wed Jun 16 06:29:53 1999 @@ -19,7 +19,6 @@ show no difference in speed at all. The file size is also similar if compression is turned off. -<<<<<<< cpdf.sgml <simpara> This documentation should be read with the ClibPDF manual in reach since it explains much of the library in much more detail. Once you understand @@ -29,33 +28,15 @@ Many functions in the native ClibPDF and the PHP module as well as in pdflib have the same name. All functions except for cpdf_open() take as a first parameter the -======= - <simpara> - This documentation should be read with the ClibPDF manual in reach since - it explains much of the library in much more detail. - - <simpara> - Many functions in ClibPDF and the php3 module as well as in pdflib - have the same name. - All functions except for cpdf_open() take as a first parameter the ->>>>>>> 1.2 handle for the document on which the function is to be performed. Currently this handle is not used internally since ClibPDF does not support the creation of several pdf documents at the same time and -<<<<<<< cpdf.sgml distinguishing them by a document handle. Actually, you should not even try it, the results are unpredictable. I cannot oversee what the consequences in a multi threaded environment are. According to the author of ClibPDF this will change in one of the next releases (current version when this was written is 1.10). If you need this functionality use the pdflib module. -======= - distinguishing them by a document handle. Actually, you should not - even try it, the results are unpredictable. - According to the author of ClibPDF this will change in one of the - next releases (current version when this was written is 1.10). - If you need this functionality use the pdflib module. ->>>>>>> 1.2 <simpara> One big advantage of ClibPDF over pdflib is the possibility to create @@ -89,8 +70,9 @@ cpdf_close($cpdf); ?> </programlisting> - <para> </example> + + <simpara> The pdflib distribution contains a more complex example which creates a serious of pages with an analog clock. This example converted into php using pdflib 2.0 looks as the following (you @@ -186,7 +168,6 @@ cpdf_close($pdf); ?> </programlisting> - <para> </example> </partintro> Index: phpdoc/functions/hw.sgml diff -u phpdoc/functions/hw.sgml:1.2 phpdoc/functions/hw.sgml:1.3 --- phpdoc/functions/hw.sgml:1.2 Tue Jun 15 16:59:47 1999 +++ phpdoc/functions/hw.sgml Wed Jun 16 06:29:53 1999 @@ -115,7 +115,7 @@ <para> The network protocol to communicate with the Hyperwave server is called <ulink - url="http://www.hyperwave.de/hg-csp-0xc31b08d4">HG-CSP</ulink> + url="http://www.hyperwave.de/7.17-hg-prot">HG-CSP</ulink> (Hyper-G Client/Server Protocol). It is based on messages to initiate certain actions, e.g. get object record. In early versions of the Hyperwave Server two native clients (Harmony, @@ -315,153 +315,6 @@ </sect1> </partintro> - <refentry id="function.hw-modifyobject"> - <refnamediv> - <refname>hw_Modifyobject</refname> - <refpurpose>modifies object record</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcdef>int <function>hw_modifyobject</function></funcdef> - <paramdef>int <parameter>connection</parameter></paramdef> - <paramdef>int <parameter>object_to_change</parameter></paramdef> - <paramdef>array <parameter>remove</parameter></paramdef> - <paramdef>array <parameter>add</parameter></paramdef> - <paramdef>int <parameter>mode</parameter></paramdef> - - </funcsynopsis> - <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> - The last parameter determines if the modification is performed - recursively. 1 means recurive modification. If some of the objects - cannot be modified they will be skiped without notice. - <function>hw_error</function> may not indicate an error though - some of the objects could not be modified. - - <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 neccessary if you want to - 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> - 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"> - // $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"> - // $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> - <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: - </note> - <example> - <title>modifying Title attribute</title> - <programlisting role="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"> - $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"> - $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. - </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 suround this function by calls to - <function>hw_getandlock</function> and <function>hw_unlock</function>. - <function>hw_modifyobject</function> does this internally. - </simpara></note> - <para> - Returns TRUE if no error occurs otherwise FALSE. - </refsect1> - </refentry> - <refentry id="function.hw-children"> <refnamediv> <refname>hw_Children</refname> @@ -1468,6 +1321,153 @@ <function>hw_InsertDocument</function>, <function>hw_InsDoc</function>, <function>hw_InsColl</function>. + </refsect1> + </refentry> + + <refentry id="function.hw-modifyobject"> + <refnamediv> + <refname>hw_Modifyobject</refname> + <refpurpose>modifies object record</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcdef>int <function>hw_modifyobject</function></funcdef> + <paramdef>int <parameter>connection</parameter></paramdef> + <paramdef>int <parameter>object_to_change</parameter></paramdef> + <paramdef>array <parameter>remove</parameter></paramdef> + <paramdef>array <parameter>add</parameter></paramdef> + <paramdef>int <parameter>mode</parameter></paramdef> + + </funcsynopsis> + <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> + The last parameter determines if the modification is performed + recursively. 1 means recurive modification. If some of the objects + cannot be modified they will be skiped without notice. + <function>hw_error</function> may not indicate an error though + some of the objects could not be modified. + + <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 neccessary if you want to + 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> + 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"> + // $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"> + // $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> + <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: + </note> + <example> + <title>modifying Title attribute</title> + <programlisting role="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"> + $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"> + $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. + </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 suround this function by calls to + <function>hw_getandlock</function> and <function>hw_unlock</function>. + <function>hw_modifyobject</function> does this internally. + </simpara></note> + <para> + Returns TRUE if no error occurs otherwise FALSE. </refsect1> </refentry>