CVS update: php3/doc/functions

Date: Wednesday August 12, 1998 @ 10:01 Author: ssb Update of /repository/php3/doc/functions In directory asf:/tmp/cvs-serv15800/functions Modified Files: hw.sgml Log Message: some fixes Index: php3/doc/functions/hw.sgml diff -c php3/doc/functions/hw.sgml:1.2 php3/doc/functions/hw.sgml:1.3 *** php3/doc/functions/hw.sgml:1.2 Wed Aug 12 08:05:30 1998 --- php3/doc/functions/hw.sgml Wed Aug 12 10:01:33 1998 *************** *** 5,199 **** <partintro> <sect1> ! <title>Introduction</title> ! <para> ! Hyperwave has been developed at ! <ulink url="http://www.iicm.edu">IICM</ulink> in Graz. It started ! with the ! name Hyper-G and changed to Hyperwave when it was commercialised ! (If I remember properly it was in 1996). ! <para> ! Hyperwave is a non 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 ! (HIS, Hyperwave Information Server). Its focus ! is the storage and management of documents. A document can be any ! possible piece of data that may as well be stored in file. Each ! document is accompanied by its object record. The object record ! 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 ! are in a document will be removed from it and stored as individual ! objects, when the document is inserted into the database. ! The object record of the link contains information ! about where it starts and where it ends. ! In order to gain the original document you will have ! to retrieve the plain document without the links and the list ! of links and reinsert them (The functions ! <function>hw_pipedocument</function> and <function>hw_gettext</function> ! do this for you. The advantage of separating links ! from the document is obvious. Once a document to which a link ! is pointing to changes its name, the link can easily be modified ! accordingly. The document containing the link is not affected ! at all. You may even add a link to a document without modifying ! the document itself. ! <para> ! The network protocol to communicate with the Hyperwave server ! is called <ulink url="http://www.hyperwave.de/hg-csp-0xc31b08d4">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, 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 HTTP to HG-CSP. ! The idea is to do all the administration of the database ! and visualisation of documents by a web interface. ! The wavemaster implements a set of placeholders for certain ! actions to customise the interface. This set of placeholders ! is called the PLACE Language. PLACE lacks a lot of features ! of a real programming language and any extension to it only ! enlarges the list of placeholders. This has led to the use ! of JavaScript which IMO does not make live easier. ! <para>Adding Hyperwave support to PHP3 should fill in the gap ! of a missing programming language for interface customisation. ! It implements all the messages as defined by the HG-CSP but ! also provides more powerful commands to e.g. retrieve complete ! documents. ! <para>Hyperwave has its own terminology to name certain pieces ! of information. This has widely been taken over and extended. ! Almost all functions operate on one of the following data types. ! <itemizedlist> ! <listitem><simpara>object ID: An unique integer value for each object ! in the Hyperwave server. It is also one of the attributes ! of the object record (ObjectID). Object ids are often ! used as an input parameter to specify an object.</simpara></listitem> ! <listitem><simpara>object record: A string with attribute-value pairs of ! the form attribute=value. The pairs are separated by ! a carriage return from each other. An object record ! can easily be converted into an object array with ! <function>hw_object2array</function>. ! Several functions return object records. ! The names of those functions end with obj. ! </simpara></listitem> ! <listitem><simpara>object array: An associated array with all attributes of ! an object. The key is the attribute name. If an attribute ! occurs more than once in an object record it will result ! in another indexed or associated array. Attributes which ! are language depended (like the title, keyword, description) ! will form an associated array with the key set to the ! language abbreviation. All other multiple attributes will ! form an indexed array. php3 functions never return object arrays. ! </simpara></listitem> ! <listitem><simpara>hw_document: This is a complete new data type ! which holds the actual ! document, e.g. HTML, PDF etc. It is somewhat optimised for ! HTML documents but may be used for any format. ! </simpara></listitem> ! </itemizedlist> ! ! <para>Several functions which return an array of object records do also return ! an associated array with statistical information about them. The array is the ! last element of the object record array. The statistical array contains the ! following entries: <itemizedlist> ! <listitem><simpara>Hidden: Number of object records with attribute PresentationHints ! set to Hidden.</simpara></listitem> ! <listitem><simpara>CollectionHead: Number of object records with attribute PresentationHints ! set to CollectionHead.</simpara></listitem> ! <listitem><simpara>FullCollectionHead: Number of object records with attribute PresentationHints ! set to FullCollectionHead.</simpara></listitem> ! <listitem><simpara>CollectionHeadNr: Index in array of object records with attribute ! PresentationHints set to CollectionHead.</simpara></listitem> ! <listitem><simpara>FullCollectionHeadNr: Index in array of object records with attribute ! PresentationHints set to FullCollectionHead.</simpara></listitem> ! <listitem><simpara>Total: Number of object records.</simpara></listitem> </itemizedlist> </sect1> <sect1> ! <title>Integration with Apache</title> ! <para> The Hyperwave module is best used when PHP3 is compiled as an ! apache module. In such a case the underlying Hyperwave server ! can be hidden from users almost completely if apache uses its rewriting engine. The following instructions will explain this. ! <para> Since PHP3 with Hyperwave support build into apache is intended to replace the native Hyperwave solution based on wavemaster I will assume that the apache server will only serve as a Hyperwave ! web interface. This is not necessary but it simplifies the configuration. ! The concept is quite simple. First of all you need a PHP3 script which ! evaluates the PATH_INFO variable and treats its value as the name of ! a Hyperwave object. Let's call this script 'Hyperwave'. ! The URL http:/your.hostname/Hyperwave/name_of_object would than return ! the Hyperwave object with the name 'name_of_object'. Depending on ! the type of the object the script has to react accordingly. If it ! is a collection, it will probably return a list of children. If it ! is a document it will return the mime type and the content. A slight ! improvement can be achieved if the apache rewriting engine is used. ! From the users point of view it would be more straight forward if ! the URL http:/your.hostname/name_of_object would return the object. ! The rewriting rule is quite easy: ! <programlisting> ! RewriteRule ^/(.*) /usr/local/apache/htdocs/HyperWave/$1 [L] ! </programlisting> Now every URL relates to an object in the Hyperwave server. This causes a simple to solve problem. There is no way to execute a ! different script, e.g. for searching, than the 'Hyperwave' script. ! This can be fixed with another rewriting rule like the following: ! <programlisting> ! RewriteRule ^/hw/(.*) /usr/local/apache/htdocs/hw/$1 [L] ! </programlisting> ! This will reserve the directory /usr/local/apache/htdocs/hw for additional scripts and other files. Just make sure this rule is ! evaluated before ! the one above. There is just a little drawback: all Hyperwave objects ! whose name starts with 'hw/' will be shadowed. So, make sure ! you don't use such names. If you need more directories, e.g. for ! images just add more rules or place them all in one directory. ! Finaly, don't forget to turn on the rewriting engine with ! <programlisting> ! RewriteEngine on ! </programlisting> ! My experiences have shown that you will need ! the following scripts: <itemizedlist> ! <listitem><simpara>to return the object itself</simpara></listitem> ! <listitem><simpara>to allow searching</simpara></listitem> ! <listitem><simpara>to identify yourself</simpara></listitem> ! <listitem><simpara>to set your profile</simpara></listitem> ! <listitem><simpara>one for each additional function like to show ! the object attributes, to show information about users, ! to show the status of the server, etc.</simpara></listitem> </itemizedlist> ! </sect1> ! <sect1> ! <title>Todo</title> ! <para> There are still some things todo: <itemizedlist> ! <listitem><simpara>The hw_InsertDocument has to be split into ! <function>hw_InsertObject</function> and ! <function>hw_PutDocument</function>.</simpara></listitem> ! <listitem><simpara>The names of several functions are not fixed, yet. ! </simpara></listitem> ! <listitem><simpara>Most functions require the current connection ! as its first parameter. This leads to a lot of typing, which ! is quite often not necessary if there is just one open ! connection. A default connection will ! improve this.</simpara></listitem> </itemizedlist> ! </sect1> </partintro> <refentry id="function.hw-changeobject"> --- 5,249 ---- <partintro> <sect1> ! <title>Introduction</title> ! <para> ! <productname>Hyperwave</productname> has been developed at <ulink ! url="http://www.iicm.edu">IICM</ulink> in Graz. It started with ! 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 ! is the storage and management of documents. A document can be any ! possible piece of data that may as well be stored in file. Each ! document is accompanied by its object record. The object record ! 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 ! are in a document will be removed from it and stored as individual ! objects, when the document is inserted into the database. ! The object record of the link contains information ! about where it starts and where it ends. ! In order to gain the original document you will have ! to retrieve the plain document without the links and the list ! of links and reinsert them (The functions ! <function>hw_pipedocument</function> and <function>hw_gettext</function> ! do this for you. The advantage of separating links ! from the document is obvious. Once a document to which a link ! is pointing to changes its name, the link can easily be modified ! accordingly. The document containing the link is not affected ! at all. You may even add a link to a document without modifying ! the document itself. ! <para> ! The network protocol to communicate with the Hyperwave server is ! called <ulink ! url="http://www.hyperwave.de/hg-csp-0xc31b08d4">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, ! 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 ! administration of the database and visualisation of documents by ! a web interface. The wavemaster implements a set of placeholders ! for certain actions to customise the interface. This set of ! placeholders is called the <abbrev>PLACE</abbrev> Language. ! <abbrev>PLACE</abbrev> lacks a lot of features of a real ! programming language and any extension to it only enlarges the ! list of placeholders. This has led to the use of JavaScript which ! IMO does not make life easier. ! ! <para> ! Adding Hyperwave support to PHP3 should fill in the gap of a ! missing programming language for interface customisation. It ! implements all the messages as defined by the ! <abbrev>HG-CSP</abbrev> but also provides more powerful commands ! to e.g. retrieve complete documents. ! ! <para> ! Hyperwave has its own terminology to name certain pieces of ! information. This has widely been taken over and extended. ! Almost all functions operate on one of the following data types. ! <itemizedlist> ! <listitem><simpara> ! object ID: An unique integer value for each object in the ! Hyperwave server. It is also one of the attributes of the ! object record (ObjectID). Object ids are often used as an ! input parameter to specify an object. ! </simpara></listitem> ! <listitem><simpara> ! object record: A string with attribute-value pairs of the form ! attribute=value. The pairs are separated by a carriage return ! from each other. An object record can easily be converted into ! an object array with <function>hw_object2array</function>. ! Several functions return object records. The names of those ! functions end with obj. ! </simpara></listitem> ! <listitem><simpara> ! object array: An associated array with all attributes of an ! object. The key is the attribute name. If an attribute occurs ! more than once in an object record it will result in another ! indexed or associated array. Attributes which are language ! depended (like the title, keyword, description) will form an ! associated array with the key set to the language ! abbreviation. All other multiple attributes will form an ! indexed array. php3 functions never return object arrays. ! </simpara></listitem> ! <listitem><simpara> ! hw_document: This is a complete new data type which holds the ! actual document, e.g. HTML, PDF etc. It is somewhat optimised ! for HTML documents but may be used for any format. ! </simpara></listitem> </itemizedlist> + + <para> + Several functions which return an array of object records do also + return an associated array with statistical information about + them. The array is the last element of the object record + array. The statistical array contains the following entries: + <variablelist> + <varlistentry> + <term>Hidden</term> + <listitem><simpara> + Number of object records with attribute PresentationHints + set to Hidden. + </varlistentry> + <varlistentry> + <term>CollectionHead</term> + <listitem><simpara> + Number of object records with attribute + PresentationHints set to CollectionHead. + </varlistentry> + <varlistentry> + <term>FullCollectionHead</term> + <listitem><simpara> + Number of object records with attribute + PresentationHints set to FullCollectionHead. + </varlistentry> + <varlistentry> + <term>CollectionHeadNr</term> + <listitem><simpara> + Index in array of object records with + attribute PresentationHints set to CollectionHead. + </varlistentry> + <varlistentry> + <term>FullCollectionHeadNr</term> + <listitem><simpara> + Index in array of object records with + attribute PresentationHints set to FullCollectionHead. + </varlistentry> + <varlistentry> + <term>Total</term> + <listitem><simpara> + Total: Number of object records. + </varlistentry> + </variablelist> </sect1> <sect1> ! <title>Integration with Apache</title> ! <para> The Hyperwave module is best used when PHP3 is compiled as an ! apache module. In such a case the underlying Hyperwave server can ! be hidden from users almost completely if apache uses its rewriting engine. The following instructions will explain this. ! <para> Since PHP3 with Hyperwave support build into apache is intended to replace the native Hyperwave solution based on wavemaster I will assume that the apache server will only serve as a Hyperwave ! web interface. This is not necessary but it simplifies the ! configuration. The concept is quite simple. First of all you ! need a PHP3 script which evaluates the <envar>PATH_INFO</envar> ! variable and treats its value as the name of a Hyperwave ! object. Let's call this script 'Hyperwave'. The URL <systemitem ! role="url">http://your.hostname/Hyperwave/name_of_object</systemitem> ! would than return the Hyperwave object with the name ! 'name_of_object'. Depending on the type of the object the script ! has to react accordingly. If it is a collection, it will probably ! return a list of children. If it is a document it will return the ! mime type and the content. A slight improvement can be achieved ! if the apache rewriting engine is used. From the users point of ! view it would be more straight forward if the URL <systemitem ! role=url>http://your.hostname/name_of_object</systemitem> would ! return the object. The rewriting rule is quite easy: ! ! <informalexample><programlisting role="apache-conf"> ! RewriteRule ^/(.*) /usr/local/apache/htdocs/HyperWave/$1 [L] ! </programlisting></informalexample> ! Now every URL relates to an object in the Hyperwave server. This causes a simple to solve problem. There is no way to execute a ! different script, e.g. for searching, than the 'Hyperwave' ! script. This can be fixed with another rewriting rule like the ! following: ! ! <informalexample><programlisting role="apache-conf"> ! RewriteRule ^/hw/(.*) /usr/local/apache/htdocs/hw/$1 [L] ! </programlisting></informalexample> ! ! This will reserve the directory <filename ! class="directory">/usr/local/apache/htdocs/hw</filename> for additional scripts and other files. Just make sure this rule is ! evaluated before the one above. There is just a little drawback: ! all Hyperwave objects whose name starts with 'hw/' will be ! shadowed. So, make sure you don't use such names. If you need ! more directories, e.g. for images just add more rules or place ! them all in one directory. Finally, don't forget to turn on the ! rewriting engine with ! ! <informalexample><programlisting role="apache-conf"> ! RewriteEngine on ! </programlisting></informalexample> ! ! My experiences have shown that you will need the following ! scripts: ! <itemizedlist> ! <listitem><simpara> ! to return the object itself ! <listitem><simpara> ! to allow searching ! <listitem><simpara> ! to identify yourself ! <listitem><simpara> ! to set your profile ! <listitem><simpara> ! one for each additional function like to show ! the object attributes, to show information about users, ! to show the status of the server, etc. </itemizedlist> ! </sect1> ! <sect1> ! <title>Todo</title> ! <para> There are still some things todo: <itemizedlist> ! <listitem><simpara>The hw_InsertDocument has to be split into ! <function>hw_InsertObject</function> and ! <function>hw_PutDocument</function>.</simpara></listitem> ! <listitem><simpara>The names of several functions are not fixed, yet. ! </simpara></listitem> ! <listitem><simpara>Most functions require the current connection ! as its first parameter. This leads to a lot of typing, which ! is quite often not necessary if there is just one open ! connection. A default connection will ! improve this.</simpara></listitem> </itemizedlist> ! </sect1> </partintro> <refentry id="function.hw-changeobject"> *************** *** 214,235 **** of an object record. The object is specified by the Object ID <parameter>object_to_change</parameter>; commands adhere to the following syntax: ! &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; 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 ! ! rem attr=value\add attr=value ! ! allows to modify attributes in one operation. <para> Returns TRUE if no error occurs otherwise FALSE. </refsect1> --- 264,284 ---- 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> -- 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