cvs: /phpdoc/appendices debugger.sgml migration.sgml phpdevel.sgml

cslawi Wed Oct 20 18:50:28 1999 EDT Modified files: /phpdoc/appendices debugger.sgml migration.sgml phpdevel.sgml Log: Normalized according to the DocBook 3.1 DTD. This mostly just adds closing tags and attribute quotes, but lets a stock 3.1 install compile the PHP docs. It still compiles with DocBook 3.0, as well. Index: phpdoc/appendices/debugger.sgml diff -u phpdoc/appendices/debugger.sgml:1.2 phpdoc/appendices/debugger.sgml:1.3 --- phpdoc/appendices/debugger.sgml:1.2 Sat Jul 31 20:37:07 1999 +++ phpdoc/appendices/debugger.sgml Wed Oct 20 18:50:26 1999 @@ -1,4 +1,3 @@ - <appendix id="debugger"> <title>The PHP Debugger</title> @@ -11,29 +10,27 @@ for every time PHP starts up. All error messages from that request will be sent to this TCP connection. This information is intended for "debugging server" that can run inside an - <acronym>IDE</acronym> or programmable editor (such as Emacs). + <acronym>IDE</acronym> or programmable editor (such as Emacs).</para> <para> How to set up the debugger: <orderedlist> - <listitem><simpara> Set up a TCP port for the debugger in the <link - linkend="configuration.file">configuration file</link> (<link - linkend="ini.debugger.port">debugger.port</link>) and enable it - (<link linkend="ini.debugger.enabled">debugger.enabled</link>). + <listitem><simpara> Set up a TCP port for the debugger in the <link linkend="configuration.file">configuration file</link> (<link linkend="ini.debugger.port">debugger.port</link>) and enable it + (<link linkend="ini.debugger.enabled">debugger.enabled</link>).</simpara></listitem> <listitem><simpara> Set up a TCP listener on that port somewhere - (for example <command>socket -l -s 1400</command> on UNIX). + (for example <command>socket -l -s 1400</command> on UNIX).</simpara></listitem> <listitem><simpara> In your code, run "debugger_on(<replaceable>host</replaceable>)", where <replaceable>host</replaceable> is the IP number or name of the - host running the <acronym>TCP</acronym> listener. + host running the <acronym>TCP</acronym> listener.</simpara></listitem> </orderedlist> Now, all warnings, notices etc. will show up on that listener socket, <emphasis>even if you them turned off with - <function>error_reporting</function></emphasis>. + <function>error_reporting</function></emphasis>.</para></sect1> <sect1 id="debugger-protocol"> <title>Debugger Protocol</title> @@ -43,7 +40,7 @@ <emphasis>message</emphasis>. Each message starts with a line of the type <literal>start</literal> and terminates with a line of the type <literal>end</literal>. PHP may send lines for different - messages simultaneously. + messages simultaneously.</para> <para> A line has this format: Index: phpdoc/appendices/migration.sgml diff -u phpdoc/appendices/migration.sgml:1.1 phpdoc/appendices/migration.sgml:1.2 --- phpdoc/appendices/migration.sgml:1.1 Sun Jun 6 14:50:31 1999 +++ phpdoc/appendices/migration.sgml Wed Oct 20 18:50:27 1999 @@ -1,4 +1,3 @@ - <appendix id="migration"> <title>Migrating from PHP/FI 2.0 to PHP 3.0</title> @@ -9,26 +8,25 @@ that is much more robust and consistent than 2.0's. 3.0 is also significantly faster, and uses less memory. However, some of these improvements have not been possible without compatibility - changes, both in syntax and functionality. + changes, both in syntax and functionality.</simpara> <simpara> In addition, PHP's developers have tried to clean up both PHP's syntax and semantics in version 3.0, and this has also caused some incompatibilities. In the long run, we believe that these changes - are for the better. + are for the better.</simpara> <simpara> This chapter will try to guide you through the incompatibilities you might run into when going from PHP/FI 2.0 to PHP 3.0 and help you resolve them. New features are not mentioned here unless - necessary. + necessary.</simpara> <simpara> A conversion program that can automatically convert your old - PHP/FI 2.0 scripts exists. It can be found in the <filename - class=directory>convertor</filename> subdirectory of the PHP 3.0 + PHP/FI 2.0 scripts exists. It can be found in the <filename class="directory">convertor</filename> subdirectory of the PHP 3.0 distribution. This program only catches the syntax changes though, - so you should read this chapter carefully anyway. + so you should read this chapter carefully anyway.</simpara></sect1> <sect1 id="migration-startendtags"> <title>Start/end tags</title> @@ -74,7 +72,7 @@ echo "This is PHP 3.0 code!\n"; &lt;/script&gt; -</programlisting></example> +</programlisting></example></para></sect1> <sect1 id="migration-if-endif"> @@ -109,7 +107,7 @@ </programlisting></example> Notice that the semicolons have been replaced by colons in all - statements but the one terminating the expression (endif). + statements but the one terminating the expression (endif).</para></sect1> <sect1 id="migration-while"> <title>while syntax</title> @@ -134,7 +132,7 @@ If you use the old while..endwhile syntax in PHP 3.0, you will get a never-ending loop. </simpara> - </warning> + </warning></sect1> <sect1 id="migration-expr"> <title>Expression types</title> @@ -142,8 +140,8 @@ PHP/FI 2.0 used the left side of expressions to determine what type the result should be. PHP 3.0 takes both sides into account when determining result types, and this may cause 2.0 scripts to behave - unexpectedly in 3.0. - <simpara> + unexpectedly in 3.0.</simpara> + <simpara></simpara> <para> Consider this example: @@ -175,7 +173,7 @@ The fix for this is simple. Replace the while statement with: <informalexample><programlisting> while ((string)$key != "") { -</programlisting></informalexample> +</programlisting></informalexample></para></sect1> <sect1 id="migration-errors"> @@ -185,7 +183,7 @@ but you no longer get to see the code fragment causing the error. You will be supplied with a file name and a line number for the error, though. - </simpara> + </simpara></sect1> <sect1 id="migration-booleval"> @@ -195,11 +193,11 @@ in an expression like <literal>(1 || test_me())</literal>, the function <function>test_me</function> would not be executed since nothing can change the result of the expression after the - <literal>1</literal>. + <literal>1</literal>.</simpara> <simpara> This is a minor compatibility issue, but may cause unexpected - side-effects. + side-effects.</simpara></sect1> <sect1 id="migration-truefalse"> @@ -212,7 +210,7 @@ fail("darn!");</literal>. Because PHP/FI 2.0 had no clear rules for what functions should return when they failed, most such scripts will probably have to be checked manually after using the - 2.0 to 3.0 convertor. + 2.0 to 3.0 convertor.</simpara> <para> <example> <title>Migration from 2.0: return values, old code</title> @@ -228,7 +226,7 @@ <programlisting> $fp = @fopen($file, "r") or print("Could not open $file for reading&lt;br&gt;\n"); </programlisting> - </example> + </example></para></sect1> <sect1 id="migration-other"> @@ -237,38 +235,38 @@ <itemizedlist> <listitem><simpara> The PHP 3.0 Apache module no longer supports Apache versions - prior to 1.2. Apache 1.2 or later is required. + prior to 1.2. Apache 1.2 or later is required.</simpara></listitem> <listitem><simpara> <function>echo</function> no longer supports a format string. Use the - <function>printf</function> function instead. + <function>printf</function> function instead.</simpara></listitem> <listitem><simpara> In PHP/FI 2.0, an implementation side-effect caused <literal>$foo[0]</literal> to have the same effect as - <literal>$foo</literal>. This is not true for PHP 3.0. + <literal>$foo</literal>. This is not true for PHP 3.0.</simpara></listitem> <listitem><simpara> Reading arrays with <literal>$array[]</literal> is no longer - supported + supported</simpara> <simpara> That is, you cannot traverse an array by having a loop that does <literal>$data = $array[]</literal>. Use <function>current</function> and <function>next</function> - instead. + instead.</simpara> <simpara> Also, <literal>$array1[] = $array2</literal> does not append the values of <literal>$array2</literal> to <literal>$array1</literal>, but appends <literal>$array2</literal> as the last entry of <literal>$array1</literal>. See also multidimensional array - support. + support.</simpara></listitem> <listitem> <simpara> <literal>"+"</literal> is no longer overloaded as a concatenation operator for strings, instead it converts it's arguments to numbers and performs numeric addition. Use - <literal>"."</literal> instead. + <literal>"."</literal> instead.</simpara></listitem> </itemizedlist> <example> @@ -289,7 +287,7 @@ $a = 1; $b = 1; echo $a + $b; -</programlisting> +</programlisting></para> <para> This would echo 2 in both PHP 2.0 and 3.0. @@ -299,8 +297,8 @@ $b = 1; echo $a.$b; </programlisting> - This will echo 11 in PHP 3.0. - </example> + This will echo 11 in PHP 3.0.</para> + </example></sect1> </appendix> Index: phpdoc/appendices/phpdevel.sgml diff -u phpdoc/appendices/phpdevel.sgml:1.3 phpdoc/appendices/phpdevel.sgml:1.4 --- phpdoc/appendices/phpdevel.sgml:1.3 Mon Jun 21 17:56:55 1999 +++ phpdoc/appendices/phpdevel.sgml Wed Oct 20 18:50:27 1999 @@ -15,7 +15,7 @@ } </programlisting> Even if your function doesn't take any arguments, this is how it is - called. + called.</para></sect2> <sect2 id="phpdevel-addfunc-args"> <title>Function Arguments</title> @@ -23,7 +23,7 @@ Arguments are always of type pval. This type contains a union which has the actual type of the argument. So, if your function takes two arguments, you would do something like the following at - the top of your function: + the top of your function:</para> <para> <example> @@ -40,27 +40,27 @@ both cases you will need to pass &amp;(pval *) to getParameters. If you want to check if the n'th parameter was sent to you by reference or not, you can use the function, - ParameterPassedByReference(ht,n). It will return either 1 or 0. + ParameterPassedByReference(ht,n). It will return either 1 or 0.</para> <simpara> When you change any of the passed parameters, whether they are sent by reference or by value, you can either start over with the parameter by calling pval_destructor on it, or if it's an ARRAY you want to add to, you can use functions similar to the ones in - internal_functions.h which manipulate return_value as an ARRAY. + internal_functions.h which manipulate return_value as an ARRAY.</simpara> <simpara> Also if you change a parameter to IS_STRING make sure you first assign the new estrdup()'ed string and the string length, and only later change the type to IS_STRING. If you change the string of a parameter which already IS_STRING or IS_ARRAY you should run - pval_destructor on it first. + pval_destructor on it first.</simpara></sect2> <sect2 id="phpdevel-addfunc-varargs"> <title>Variable Function Arguments</title> <para> A function can take a variable number of arguments. If your function can - take either 2 or 3 arguments, use the following: + take either 2 or 3 arguments, use the following:</para> <para> <example> @@ -74,7 +74,7 @@ WRONG_PARAM_COUNT; } </programlisting> - </example> + </example></para></sect2> <sect2 id="phpdevel-addfunc-using-args"> <title>Using the Function Arguments</title> @@ -124,7 +124,7 @@ </row> </tbody> </tgroup> - </table> + </table></para> <para> If you get an argument of one type and would like to use it as @@ -138,18 +138,18 @@ convert_to_string(arg1); convert_to_boolean_long(arg1); /* If the string is "" or "0" it becomes 0, 1 otherwise */ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE depending on string */ - </programlisting> + </programlisting></para> <simpara> - These function all do in-place conversion. They do not return anything. + These function all do in-place conversion. They do not return anything.</simpara> <para> The actual argument is stored in a union; the members are: <itemizedlist> - <listitem><simpara>IS_STRING: arg1-&gt;value.str.val - <listitem><simpara>IS_LONG: arg1-&gt;value.lval - <listitem><simpara>IS_DOUBLE: arg1-&gt;value.dval - </itemizedlist> + <listitem><simpara>IS_STRING: arg1-&gt;value.str.val</simpara></listitem> + <listitem><simpara>IS_LONG: arg1-&gt;value.lval</simpara></listitem> + <listitem><simpara>IS_DOUBLE: arg1-&gt;value.dval</simpara></listitem> + </itemizedlist></para></sect2> <sect2 id="phpdevel-addfunc-memmgmt"> <title>Memory Management in Functions</title> @@ -157,7 +157,7 @@ Any memory needed by a function should be allocated with either emalloc() or estrdup(). These are memory handling abstraction functions that look and smell like the normal malloc() and - strdup() functions. Memory should be freed with efree(). + strdup() functions. Memory should be freed with efree().</simpara> <simpara> There are two kinds of memory in this program: memory which is @@ -167,7 +167,7 @@ make sure you first allocate the memory with either emalloc() or estrdup(). This memory should NEVER be freed by you, unless you later in the same function overwrite your original assignment - (this kind of programming practice is not good though). + (this kind of programming practice is not good though).</simpara> <simpara> For any temporary/permanent memory you need in your @@ -179,12 +179,12 @@ leak. The meaning of "the functions behave exactly like their counterparts" is: if you efree() something which was not emalloc()'ed nor estrdup()'ed you might get a segmentation - fault. So please take care and free all of your wasted memory. + fault. So please take care and free all of your wasted memory.</simpara> <simpara> If you compile with "-DDEBUG", PHP3 will print out a list of all memory that was allocated using emalloc() and estrdup() but never - freed with efree() when it is done running the specified script. + freed with efree() when it is done running the specified script.</simpara></sect2> <sect2 id="phpdevel-addfunc-symtab"> <title>Setting Variables in the Symbol Table</title> @@ -193,31 +193,31 @@ variable in the symbol table: <itemizedlist> - <listitem><simpara>SET_VAR_STRING(name,value) <footnoteref linkend="symtab-1"> - <listitem><simpara>SET_VAR_DOUBLE(name,value) - <listitem><simpara>SET_VAR_LONG(name,value) - </itemizedlist> + <listitem><simpara>SET_VAR_STRING(name,value) <footnoteref linkend="symtab-1"></simpara></listitem> + <listitem><simpara>SET_VAR_DOUBLE(name,value)</simpara></listitem> + <listitem><simpara>SET_VAR_LONG(name,value)</simpara></listitem> + </itemizedlist></para> <para> <footnote id="symtab-1"> <simpara> Be careful here. The value part must be malloc'ed manually because the memory management code will try to free this pointer later. Do - not pass statically allocated memory into a SET_VAR_STRING. - </footnote> + not pass statically allocated memory into a SET_VAR_STRING.</simpara> + </footnote></para> <simpara> Symbol tables in PHP 3.0 are implemented as hash tables. At any given time, &amp;symbol_table is a pointer to the 'main' symbol table, and active_symbol_table points to the currently active symbol table (these may be identical like in startup, or - different, if you're inside a function). + different, if you're inside a function).</simpara> <para> The following examples use 'active_symbol_table'. You should replace it with &amp;symbol_table if you specifically want to work with the 'main' symbol table. Also, the same functions may be - applied to arrays, as explained below. + applied to arrays, as explained below.</para> <para> <example> @@ -238,18 +238,18 @@ Arrays in PHP 3.0 are implemented using the same hashtables as symbol tables. This means the two above functions can also be - used to check variables inside arrays. + used to check variables inside arrays.</para> <simpara> If you want to define a new array in a symbol table, you should do - the following. + the following.</simpara> <simpara> First, you may want to check whether it exists and abort - appropiately, using hash_exists() or hash_find(). + appropiately, using hash_exists() or hash_find().</simpara> <simpara> - Next, initialize the array: + Next, initialize the array:</simpara> <para> <example> @@ -263,10 +263,10 @@ </example> This code declares a new array, named $foo, in the active symbol - table. This array is empty. + table. This array is empty.</para> <simpara> - Here's how to add new entries to it: + Here's how to add new entries to it:</simpara> <para> <example> @@ -295,22 +295,22 @@ you can supply a pval ** to the hash add function, and it'll be updated with the pval * address of the inserted element inside the hash. If that value is NULL (like in all of the above examples) - - that parameter is ignored. + that parameter is ignored.</para> <simpara> hash_next_index_insert() uses more or less the same logic as - "$foo[] = bar;" in PHP 2.0. + "$foo[] = bar;" in PHP 2.0.</simpara> <simpara> If you are building an array to return from a function, you can - initialize the array just like above by doing: + initialize the array just like above by doing:</simpara> <programlisting> if (array_init(return_value) == FAILURE) { failed...; } </programlisting> <simpara> - ...and then adding values with the helper functions: + ...and then adding values with the helper functions:</simpara> <programlisting> add_next_index_long(return_value,long_value); @@ -327,68 +327,68 @@ if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&amp;arr)==FAILURE) { can't find... } else { use arr-&gt;value.ht... } - </programlisting> + </programlisting></para> <simpara> Note that hash_find receives a pointer to a pval pointer, and not - a pval pointer. + a pval pointer.</simpara> <simpara> Just about any hash function returns SUCCESS or FAILURE (except - for hash_exists(), which returns a boolean truth value). + for hash_exists(), which returns a boolean truth value).</simpara></sect2> <sect2 id="phpdevel-addfunc-retsimple"> <title>Returning simple values</title> <simpara> A number of macros are available to make returning values from a - function easier. + function easier.</simpara> <para> The RETURN_* macros all set the return value and return from the function: <itemizedlist> - <listitem><simpara>RETURN - <listitem><simpara>RETURN_FALSE - <listitem><simpara>RETURN_TRUE - <listitem><simpara>RETURN_LONG(l) - <listitem><simpara>RETURN_STRING(s,dup) If dup is true, duplicates the string - <listitem><simpara>RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l). - <listitem><simpara>RETURN_DOUBLE(d) - </itemizedlist> + <listitem><simpara>RETURN</simpara></listitem> + <listitem><simpara>RETURN_FALSE</simpara></listitem> + <listitem><simpara>RETURN_TRUE</simpara></listitem> + <listitem><simpara>RETURN_LONG(l)</simpara></listitem> + <listitem><simpara>RETURN_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem> + <listitem><simpara>RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem> + <listitem><simpara>RETURN_DOUBLE(d)</simpara></listitem> + </itemizedlist></para> <para> The RETVAL_* macros set the return value, but do not return. <itemizedlist> - <listitem><simpara>RETVAL_FALSE - <listitem><simpara>RETVAL_TRUE - <listitem><simpara>RETVAL_LONG(l) - <listitem><simpara>RETVAL_STRING(s,dup) If dup is true, duplicates the string - <listitem><simpara>RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l). - <listitem><simpara>RETVAL_DOUBLE(d) - </itemizedlist> + <listitem><simpara>RETVAL_FALSE</simpara></listitem> + <listitem><simpara>RETVAL_TRUE</simpara></listitem> + <listitem><simpara>RETVAL_LONG(l)</simpara></listitem> + <listitem><simpara>RETVAL_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem> + <listitem><simpara>RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem> + <listitem><simpara>RETVAL_DOUBLE(d)</simpara></listitem> + </itemizedlist></para> <simpara> The string macros above will all estrdup() the passed 's' argument, so you can safely free the argument after calling the - macro, or alternatively use statically allocated memory. + macro, or alternatively use statically allocated memory.</simpara> <simpara> If your function returns boolean success/error responses, always - use RETURN_TRUE and RETURN_FALSE respectively. + use RETURN_TRUE and RETURN_FALSE respectively.</simpara></sect2> <sect2 id="phpdevel-addfunc-retcomplex"> <title>Returning complex values</title> <simpara> Your function can also return a complex data type such as an - object or an array. + object or an array.</simpara> <para> Returning an object: <orderedlist numeration="arabic"> - <listitem><simpara>Call object_init(return_value). + <listitem><simpara>Call object_init(return_value).</simpara></listitem> <listitem><para>Fill it up with values. The functions available - for this purpose are listed below. + for this purpose are listed below.</para></listitem> <listitem><para> Possibly, register functions for this object. In order to obtain values from the object, the function would have to fetch "this" from the active_symbol_table. Its type @@ -397,80 +397,80 @@ actual registration of the function can be done using: <programlisting> add_method( return_value, function_name, function_ptr ); - </programlisting> - </orderedlist> + </programlisting></para></listitem> + </orderedlist></para> <para> The functions used to populate an object are: <itemizedlist> <listitem><simpara>add_property_long( return_value, property_name, l ) - Add a property named 'property_name', of - type long, equal to 'l' + type long, equal to 'l'</simpara></listitem> <listitem><simpara>add_property_double( return_value, - property_name, d ) - Same, only adds a double + property_name, d ) - Same, only adds a double</simpara></listitem> <listitem><simpara>add_property_string( return_value, - property_name, str ) - Same, only adds a string + property_name, str ) - Same, only adds a string</simpara></listitem> <listitem><simpara>add_property_stringl( return_value, - property_name, str, l ) - Same, only adds a string of length 'l' - </itemizedlist> + property_name, str, l ) - Same, only adds a string of length 'l'</simpara></listitem> + </itemizedlist></para> <para> Returning an array: <orderedlist numeration="arabic"> - <listitem><simpara>Call array_init(return_value). + <listitem><simpara>Call array_init(return_value).</simpara></listitem> <listitem><simpara>Fill it up with values. The functions available - for this purpose are listed below. - </orderedlist> + for this purpose are listed below.</simpara></listitem> + </orderedlist></para> <para> The functions used to populate an array are: <itemizedlist> <listitem><simpara>add_assoc_long(return_value,key,l) - add - associative entry with key 'key' and long value 'l' - <listitem><simpara>add_assoc_double(return_value,key,d) - <listitem><simpara>add_assoc_string(return_value,key,str,duplicate) + associative entry with key 'key' and long value 'l'</simpara></listitem> + <listitem><simpara>add_assoc_double(return_value,key,d)</simpara></listitem> + <listitem><simpara>add_assoc_string(return_value,key,str,duplicate)</simpara></listitem> <listitem><simpara>add_assoc_stringl(return_value,key,str,length,duplicate) - specify the string length + specify the string length</simpara></listitem> <listitem><simpara>add_index_long(return_value,index,l) - add - entry in index 'index' with long value 'l' - <listitem><simpara>add_index_double(return_value,index,d) - <listitem><simpara>add_index_string(return_value,index,str) + entry in index 'index' with long value 'l'</simpara></listitem> + <listitem><simpara>add_index_double(return_value,index,d)</simpara></listitem> + <listitem><simpara>add_index_string(return_value,index,str)</simpara></listitem> <listitem><simpara>add_index_stringl(return_value,index,str,length) - - specify the string length + - specify the string length</simpara></listitem> <listitem><simpara>add_next_index_long(return_value,l) - add an - array entry in the next free offset with long value 'l' - <listitem><simpara>add_next_index_double(return_value,d) - <listitem><simpara>add_next_index_string(return_value,str) + array entry in the next free offset with long value 'l'</simpara></listitem> + <listitem><simpara>add_next_index_double(return_value,d)</simpara></listitem> + <listitem><simpara>add_next_index_string(return_value,str)</simpara></listitem> <listitem><simpara>add_next_index_stringl(return_value,str,length) - - specify the string length - </itemizedlist> + - specify the string length</simpara></listitem> + </itemizedlist></para></sect2> <sect2 id="phpdevel-addfunc-reslist"> <title>Using the resource list</title> <simpara> PHP 3.0 has a standard way of dealing with various types of - resources. This replaces all of the local linked lists in PHP 2.0. + resources. This replaces all of the local linked lists in PHP 2.0.</simpara> <para> Available functions: <itemizedlist> <listitem><simpara>php3_list_insert(ptr, type) - returns the 'id' - of the newly inserted resource + of the newly inserted resource</simpara></listitem> <listitem><simpara>php3_list_delete(id) - delete the resource - with the specified id + with the specified id</simpara></listitem> <listitem><simpara>php3_list_find(id,*type) - returns the pointer of the resource with the specified id, - updates 'type' to the resource's type + updates 'type' to the resource's type</simpara></listitem> </itemizedlist> Typically, these functions are used for SQL drivers but they can be used for anything else; for instance, maintaining file - descriptors. + descriptors.</para> <simpara> - Typical list code would look like this: + Typical list code would look like this:</simpara> <para> <example> @@ -518,7 +518,7 @@ list_entry_type. In addition, one should add shutdown code for any new resource type defined, in list.c's list_entry_destructor() (even if you don't have anything to do on shutdown, you must add - an empty case). + an empty case).</para></sect2> <sect2 id="phpdevel-addfunc-prestable"> <title>Using the persistent resource table</title> @@ -533,13 +533,13 @@ <member>php3_mysql_do_connect</member> <member>php3_mysql_connect()</member> <member>php3_mysql_pconnect()</member> - </simplelist> + </simplelist></para> <para> The general idea of persistence modules is this: <orderedlist numeration="arabic"> <listitem><simpara>Code all of your module to work with the - regular resource list mentioned in section (9). + regular resource list mentioned in section (9).</simpara></listitem> <listitem><simpara>Code extra connect functions that check if the resource already exists in the persistent resource list. If it does, register it as in the regular resource list as a pointer to @@ -551,27 +551,27 @@ resource would be found in the persistent resource list and be used without having to recreate it. You should register these resources with a different type (e.g. LE_MYSQL_LINK for - non-persistent link and LE_MYSQL_PLINK for a persistent link). - </orderedlist> + non-persistent link and LE_MYSQL_PLINK for a persistent link).</simpara></listitem> + </orderedlist></para> <simpara> If you read mysql.c, you'll notice that except for the more complex connect function, nothing in the rest of the module has to - be changed. + be changed.</simpara> <simpara> The very same interface exists for the regular resource list and the persistent resource list, only 'list' is replaced with - 'plist': + 'plist':</simpara> <itemizedlist> <listitem><simpara>php3_plist_insert(ptr, type) - returns the 'id' - of the newly inserted resource + of the newly inserted resource</simpara></listitem> <listitem><simpara>php3_plist_delete(id) - delete the resource - with the specified id + with the specified id</simpara></listitem> <listitem><simpara>php3_plist_find(id,*type) - returns the pointer of the resource with the specified id, - updates 'type' to the resource's type + updates 'type' to the resource's type</simpara></listitem> </itemizedlist> <simpara> @@ -584,11 +584,11 @@ that were passed to the function, and hashes the SQL link with this string as a key. The next time someone calls a pconnect() with the same host/user/passwd, the same key would be generated, - and the function would find the SQL link in the persistent list. + and the function would find the SQL link in the persistent list.</simpara> <simpara> Until further documented, you should look at mysql.c or msql.c to - see how one should use the plist's hash table abilities. + see how one should use the plist's hash table abilities.</simpara> <simpara> One important thing to note: resources going into the persistent @@ -599,7 +599,7 @@ hit), every memory chunk that was allocated using PHP's memory manager is deleted. Since the persistent list isn't supposed to be erased at the end of a request, one mustn't use PHP's memory - manager for allocating resources that go to it. + manager for allocating resources that go to it.</simpara> <simpara> When you register a resource that's going to be in the persistent @@ -612,7 +612,7 @@ every resource, even it requires no destructotion and the destructor would be empty. Remember, since emalloc() and friends aren't to be used in conjunction with the persistent list, you - mustn't use efree() here either. + mustn't use efree() here either.</simpara></sect2> <sect2 id="phpdevel-addfunc-addcfg"> @@ -626,36 +626,36 @@ basis. This means that one directory may have a certain safemodeexecdir for example, while another directory may have another. This configuration granularity is especially handy when - a server supports multiple virtual hosts. + a server supports multiple virtual hosts.</para> <para> The steps required to add a new directive: <orderedlist> - <listitem><simpara>Add directive to php3_ini_structure struct in mod_php3.h. + <listitem><simpara>Add directive to php3_ini_structure struct in mod_php3.h.</simpara></listitem> <listitem><simpara>In main.c, edit the php3_module_startup function and add the appropriate cfg_get_string() or - cfg_get_long() call. + cfg_get_long() call.</simpara></listitem> <listitem><simpara>Add the directive, restrictions and a comment to the php3_commands structure in mod_php3.c. Note the restrictions part. RSRC_CONF are directives that can only be present in the actual Apache .conf files. Any OR_OPTIONS directives can be present anywhere, include normal .htaccess - files. + files.</simpara></listitem> <listitem><simpara>In either php3take1handler() or - php3flaghandler() add the appropriate entry for your directive. + php3flaghandler() add the appropriate entry for your directive.</simpara></listitem> <listitem><simpara>In the configuration section of the _php3_info() function in functions/info.c you need to add your - new directive. + new directive.</simpara></listitem> <listitem><simpara>And last, you of course have to use your new directive somewhere. It will be addressable as - php3_ini.directive. - </orderedlist> + php3_ini.directive.</simpara></listitem> + </orderedlist></para></sect2></sect1> <sect1 id="calling-user-functions"> @@ -689,7 +689,7 @@ <title>HashTable *function_table</title> <simpara> This is the hash table in which the function is to be looked up. - </simpara> + </simpara></sect2> <sect2 id="calling-user-functions.object"> <title>pval *object</title> @@ -701,7 +701,7 @@ be modified by the function that is invoked on it (that function will have access to it via $this). If for some reason you don't want that to happen, send a copy of the object instead. - </simpara> + </simpara></sect2> <sect2 id="calling-user-functions.function-name"> <title>pval *function_name</title> @@ -711,7 +711,7 @@ set to the appropriate values. The function_name is modified by call_user_function() - it's converted to lowercase. If you need to preserve the case, send a copy of the function name instead. - </simpara> + </simpara></sect2> <sect2 id="calling-user-functions.retval"> <title>pval *retval</title> @@ -720,13 +720,13 @@ the invoked function is saved. The structure must be previously allocated - <function>call_user_function</function> does NOT allocate it by itself. - </simpara> + </simpara></sect2> <sect2 id="calling-user-functions.param-count"> <title>int param_count</title> <simpara> The number of parameters being passed to the function. - </simpara> + </simpara></sect2> <sect2 id="calling-user-functions.params"> <title>pval *params[]</title> @@ -737,7 +737,7 @@ are sent as-is to the function, which means if the function modifies its arguments, the original values are changed (passing by reference). If you don't want that behavior, pass a copy instead. - </simpara> + </simpara></sect2></sect1> <sect1 id="phpdevel-errors"> <title>Reporting Errors</title> @@ -805,6 +805,8 @@ </simpara> </sect2> + </sect1> +</appendix> <!-- Keep this comment at the end of the file Local variables: mode: sgml