CVS update: php3/doc/functions

Date: Friday April 16, 1999 @ 8:09 Author: steinm Update of /repository/php3/doc/functions In directory asf:/u/temp/cvs-serv5808/doc/functions Modified Files: hw.sgml Log Message: - some code cleanups - replaced sprintf by snprintf to prevent buffer overflow - updated documentation Index: php3/doc/functions/hw.sgml diff -c php3/doc/functions/hw.sgml:1.16 php3/doc/functions/hw.sgml:1.17 *** php3/doc/functions/hw.sgml:1.16 Thu Apr 8 11:08:12 1999 --- php3/doc/functions/hw.sgml Fri Apr 16 08:09:46 1999 *************** *** 12,21 **** the name <acronym>Hyper-G</acronym> and changed to Hyperwave when it was commercialised (If I remember properly it was in 1996). <para> ! Hyperwave is not free software. The current version, 4.0, is available at <ulink url="http://www.hyperwave.com/">www.hyperwave.com</ulink>. A ! time limited version can be downloaded for free (30 days). <para> Hyperwave is an information system similar to a database (<acronym>HIS</acronym>, Hyperwave Information Server). Its focus --- 12,21 ---- the name <acronym>Hyper-G</acronym> and changed to Hyperwave when it was commercialised (If I remember properly it was in 1996). <para> ! Hyperwave is not free software. The current version, 4.1, is available at <ulink url="http://www.hyperwave.com/">www.hyperwave.com</ulink>. A ! time limited version can be ordered for free (30 days). <para> Hyperwave is an information system similar to a database (<acronym>HIS</acronym>, Hyperwave Information Server). Its focus *************** *** 25,31 **** contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by ! the user. <para> Besides the documents, all hyper links contained in a document are stored as object records as well. Hyper links which --- 25,52 ---- contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by ! the user. An attribute is a name/value pair of the form name=value. ! The complete object record contains as many of those pairs as the ! user likes. The name of an attribute does not have to be unique, ! e.g. a title may appear several times within an object record. ! This makes sense if you want to specify a title in several languages. ! In such a case there is a convention, that each title value is ! preceded by the two letter language abbreviation followed by a colon, ! e.g. 'en:Title in English' or 'ge:Titel in deutsch'. Other attributes ! like a description or keywords are potential candidates. You may ! also replace the language abbreviation by any other string as long ! as it separated by colon from the rest of the attribute value. ! <para> ! Each object record has native a string representation with each ! name/value ! pair separated by a newline. The PHP3 Hyperwave module also knows ! a second representation which is an associated array with the ! attribute name being the key. Multilingual attribute values itself ! form another associated array with the key being the language ! abbreviation. Actually any multiple attribute forms an associated ! array with the string left to the colon in the attribute value ! being the key. (This is not fully implemented. Only the attributes ! Title, Description and Keyword are treated properly yet.) <para> Besides the documents, all hyper links contained in a document are stored as object records as well. Hyper links which *************** *** 47,75 **** Saying that <function>hw_pipedocument</function> and <function>hw_gettext</function> do the link insertion automatically is not as simple as it sounds. Inserting links implies a certain ! hierachy of the documents. On a web server this is given by the ! file system, but Hyperwave has its own hierachy and names do not ! reflect the position of an object in that hierachy. Therefore creation of links first of all requires a mapping from the Hyperwave ! hierachy and namespace into a web hierachy respective web namespace. The fundamental difference between Hyperwave and the web is the clear ! distingtion between names and hierachy in Hyperwave. The name does ! not contain any information about the objects position in the hierachy. In the web the name also contains the information on where the object is located ! in the hierachy. This leads to two possibles ways of mapping. Either ! the Hyperwave hierachy and name of the Hyperwave object is reflected in the URL or the name only. To make things simple the second approach is used. Hyperwave object with name 'my_object' is mapped to ! 'http://host/my_object' diregarding where it resides in the ! Hyperwave hierachy. An object with name 'parent/my_object' could be the child of ! 'my_object' in the Hyperwave hierachy, though in a web namespace it appears to be just the opposite and the user might get confused. ! This can only be prevented by selecting reasonable obect names. <para> ! Having made this decission a second problem arises. How do you involve php3? The URL http://host/my_object will not call any php3 script unless you tell your web server to rewrite it to e.g. 'http://host/php3_script/my_object' and the script 'php3_script' --- 68,96 ---- Saying that <function>hw_pipedocument</function> and <function>hw_gettext</function> do the link insertion automatically is not as simple as it sounds. Inserting links implies a certain ! hierarchy of the documents. On a web server this is given by the ! file system, but Hyperwave has its own hierarchy and names do not ! reflect the position of an object in that hierarchy. Therefore creation of links first of all requires a mapping from the Hyperwave ! hierarchy and namespace into a web hierarchy respective web namespace. The fundamental difference between Hyperwave and the web is the clear ! distinction between names and hierarchy in Hyperwave. The name does ! not contain any information about the objects position in the hierarchy. In the web the name also contains the information on where the object is located ! in the hierarchy. This leads to two possibles ways of mapping. Either ! the Hyperwave hierarchy and name of the Hyperwave object is reflected in the URL or the name only. To make things simple the second approach is used. Hyperwave object with name 'my_object' is mapped to ! 'http://host/my_object' disregarding where it resides in the ! Hyperwave hierarchy. An object with name 'parent/my_object' could be the child of ! 'my_object' in the Hyperwave hierarchy, though in a web namespace it appears to be just the opposite and the user might get confused. ! This can only be prevented by selecting reasonable object names. <para> ! Having made this decision a second problem arises. How do you involve php3? The URL http://host/my_object will not call any php3 script unless you tell your web server to rewrite it to e.g. 'http://host/php3_script/my_object' and the script 'php3_script' *************** *** 87,95 **** It gets more complicated if php3 is not run as a module/CGI script but as a standalone application e.g. to dump the content of the Hyperwave server on a CD-ROM. In such a case it makes sense to ! retain the Hyperwave hierachy and map in onto the filesystem. This ! conflicts with the object names if they reflect its own hierachy ! (e.g. by chosing names including '/'). Therefore '/' has to be replaced by another character, e.g. '_'. to be continued. <para> The network protocol to communicate with the Hyperwave server is --- 108,116 ---- It gets more complicated if php3 is not run as a module/CGI script but as a standalone application e.g. to dump the content of the Hyperwave server on a CD-ROM. In such a case it makes sense to ! retain the Hyperwave hierarchy and map in onto the file system. This ! conflicts with the object names if they reflect its own hierarchy ! (e.g. by choosing names including '/'). Therefore '/' has to be replaced by another character, e.g. '_'. to be continued. <para> The network protocol to communicate with the Hyperwave server is *************** *** 99,105 **** initiate certain actions, e.g. get object record. In early versions of the Hyperwave Server two native clients (Harmony, Amadeus) were provided for communication with the server. Those ! two disappeared when Hyperwave was commercialized. As a replacement a so called wavemaster was provided. The wavemaster is like a protocol converter from <abbrev>HTTP</abbrev> to <abbrev>HG-CSP</abbrev>. The idea is to do all the --- 120,126 ---- initiate certain actions, e.g. get object record. In early versions of the Hyperwave Server two native clients (Harmony, Amadeus) were provided for communication with the server. Those ! two disappeared when Hyperwave was commercialised. As a replacement a so called wavemaster was provided. The wavemaster is like a protocol converter from <abbrev>HTTP</abbrev> to <abbrev>HG-CSP</abbrev>. The idea is to do all the *************** *** 294,332 **** </sect1> </partintro> ! <refentry id="function.hw-changeobject"> <refnamediv> ! <refname>hw_Changeobject</refname> ! <refpurpose>changes object</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> ! <funcdef>int <function>hw_changeobject</function></funcdef> <paramdef>int <parameter>connection</parameter></paramdef> <paramdef>int <parameter>object_to_change</parameter></paramdef> ! <paramdef>string <parameter>commands</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>; commands ! adhere to the following syntax: ! <literallayout> ! &lt;command> ::= &lt;remcmd&gt; | ! &lt;addcmd&gt; | ! &lt;remcmd&gt; "\" &lt;addcmd&gt; ! ! &lt;remcmd&gt; ::= "rem " &lt;attribute&gt; "=" &lt;value&gt; ! ! &lt;addcmd&gt; ::= "add " &lt;attribute&gt; "=" &lt;value&gt; ! </literallayout> ! ! Note that in order to delete or remove an attribute its old value ! has to be supplied (some attributes are allowed more than ! once). A command like <command>rem attr=value\add ! attr=value</command> allows to modify attributes in one ! operation. <para> Returns TRUE if no error occurs otherwise FALSE. </refsect1> --- 315,371 ---- </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> ! </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. ! <example> ! <title>modifying an attribute</title> ! 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>. ! <programmlisting> ! // $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); ! </programmlisting> ! </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 NULL. ! <para> ! Note: Multilingual attributes, e.g. 'Title', have to be provided in its ! native form 'language':'title'. The above example would than be: ! <example> ! <title>modifying Title attribute</title> ! <programmlisting> ! $remarr = array("Title" => "en:Books"); ! $addarr = array("Title" => "en:Articles"); ! $hw_modifyobject($connect, $objid, $remarr, $addarr); ! </programmlisting> ! </example> ! This removes the english title 'Books' and adds the english title ! 'Articles'. <para> Returns TRUE if no error occurs otherwise FALSE. </refsect1> *************** *** 1383,1388 **** --- 1422,1432 ---- </funcsynopsis> <para> Converts an <parameter>object_record</parameter> into an object array. + The keys of the resulting array are the attributes names. + Multiple attributes like 'Title' in different languages form its own + array. The keys of this array are the left part to the colon of the + attribute value. Currently only the attributes 'Title', 'Description' + and 'Keyword' are treated properly. </refsect1> </refentry> -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net