cvs: ZendAPI / Extending_Zend_Build.xml Extending_Zend_CallingUserFunctions.xml Extending_Zend_ConfigurationMacros.xml Extending_Zend_Creating.xml
Extending_Zend_Printing.xml Extending_Zend_Returning.xml Extending_Zend_Structure.xml Extending_Zend_Using.xml Extending_Zend_Variables.xml
| From: | Hartmut Holzgraefe | Date: | Mon, 25 Mar 2002 08:13:47 +0000 |
| Subject: | cvs: ZendAPI / Extending_Zend_Build.xml Extending_Zend_CallingUserFunctions.xml Extending_Zend_ConfigurationMacros.xml Extending_Zend_Creating.xml Extending_Zend_Printing.xml Extending_Zend_Returning.xml Extending_Zend_Structure.xml Extending_Zend_Using.xml Extending_Zend_Variables.xml |
||
| Groups: | php.zend-engine.cvs | ||
| Request: | Send a blank email to php-zend-engine-cvs+get-36@lists.php.net to get a copy of this message | ||
hholzgra Mon Mar 25 03:13:47 2002 EDT
Modified files:
/ZendAPI Extending_Zend_Build.xml
Extending_Zend_CallingUserFunctions.xml
Extending_Zend_ConfigurationMacros.xml
Extending_Zend_Creating.xml Extending_Zend_Printing.xml
Extending_Zend_Returning.xml Extending_Zend_Structure.xml
Extending_Zend_Using.xml Extending_Zend_Variables.xml
Log:
nuke magic numbers, part #2
Index: ZendAPI/Extending_Zend_Build.xml diff -u ZendAPI/Extending_Zend_Build.xml:1.5 ZendAPI/Extending_Zend_Build.xml:1.6 --- ZendAPI/Extending_Zend_Build.xml:1.5 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Build.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.5 $ --> + <!-- $Revision: 1.6 $ --> <chapter id="zend.build"> <title>PHP's Automatic Build System</title> <para> @@ -53,19 +53,19 @@ <filename>Makefile.in</filename>. </para> <para> - Listing 9.1 shows the previously generated + <xref linkend='example.makefile.in'/>shows the previously generated <filename>Makefile.in</filename>: </para> - <figure> - <title>Listing 9.1. The default <filename>Makefile.in</filename>.</title> + <example id='example.makefile.in'> + <title>The default <filename>Makefile.in</filename>.</title> <programlisting> -# $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ +# $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra Exp $ LTLIBRARY_NAME = libmy_module.la LTLIBRARY_SOURCES = my_module.c LTLIBRARY_SHARED_NAME = my_module.la include $(top_srcdir)/build/dynlib.mk </programlisting> - </figure> + </example> <para> There's not much to tell about this one: It contains the names of the input and output files. You could also specify build @@ -73,13 +73,13 @@ source files. </para> <para> - The default <filename>config.m4</filename> shown in Listing - 9.2 is a bit more complex: + The default <filename>config.m4</filename> shown in + <xref linkend='example.config.m4'/>'/> is a bit more complex: </para> - <figure> - <title>Listing 9.2. The default <filename>config.m4</filename>.</title> + <example id='example.config.m4'> + <title>The default <filename>config.m4</filename>.</title> <programlisting> -dnl $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ +dnl $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra Exp $ dnl config.m4 for extension my_module dnl don't forget to call PHP_EXTENSION(my_module) dnl If your extension references something external, use with: @@ -95,7 +95,7 @@ PHP_EXTENSION(my_module, $ext_shared) fi </programlisting> - </figure> + </example> <para> If you're unfamiliar with M4 files (now is certainly a good time to get familiar), this might be a bit confusing at first; but Index: ZendAPI/Extending_Zend_CallingUserFunctions.xml diff -u ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.8 ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.9 --- ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.8 Sun Feb 24 01:44:44 2002 +++ ZendAPI/Extending_Zend_CallingUserFunctions.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.8 $ --> + <!-- $Revision: 1.9 $ --> <chapter id="zend.calling-user-functions"> <title>Calling User Functions</title> <para> @@ -61,7 +61,7 @@ need separation. </para> <para> - Listing 9.16 and Figure 9.11 show a small demonstration of + <xref linkend='example.call-user-func'/> and Figure 9.11 show a small demonstration of calling a user function. The code calls a function that's supplied to it as argument and directly passes this function's return value through as its own return value. Note the use of the constructor @@ -69,8 +69,8 @@ it this way here (since they should be separate values, the assignment might be safe), but this is bulletproof. </para> - <figure> - <title>Listing 9.16. Calling user functions.</title> + <example id='example.call-user-func'> + <title>Calling user functions.</title> <programlisting> zval **function_name; zval *retval; @@ -98,7 +98,7 @@ zval_copy_ctor(return_value); zval_ptr_dtor(&retval); </programlisting> - </figure> + </example> <para/> <programlisting> <?php Index: ZendAPI/Extending_Zend_ConfigurationMacros.xml diff -u ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.5 ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.6 --- ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.5 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_ConfigurationMacros.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.5 $ --> + <!-- $Revision: 1.6 $ --> <chapter id="zend.configuration-macros"> <title>Reference: Some Configuration Macros</title> <section id="zend.configuration-macros.config-m4"> @@ -9,11 +9,11 @@ <filename>buildconf</filename> and must contain all the instructions to be executed during configuration. For example, these can include tests for required external files, such as header files, libraries, and so on. PHP defines a set of macros - that can be used in this process, the most useful of which are described in Table 9.18. + that can be used in this process, the most useful of which are described in + <xref linkend='tab.m4-macros'/>. </para> - <figure> - <title>Table 9.18. M4 Macros for <filename>config.m4</filename></title> - <informaltable> + <table id='tab.m4-macros'> + <title>M4 Macros for <filename>config.m4</filename></title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.63*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -80,8 +80,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> </chapter> <!-- Index: ZendAPI/Extending_Zend_Creating.xml diff -u ZendAPI/Extending_Zend_Creating.xml:1.6 ZendAPI/Extending_Zend_Creating.xml:1.7 --- ZendAPI/Extending_Zend_Creating.xml:1.6 Tue Mar 19 08:45:21 2002 +++ ZendAPI/Extending_Zend_Creating.xml Mon Mar 25 03:13:46 2002 @@ -1,14 +1,14 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.6 $ --> + <!-- $Revision: 1.7 $ --> <chapter id="zend.creating"> <title>Creating Extensions</title> <para> We'll start with the creation of a very simple extension at first, which basically does nothing more than implement a function that returns the - integer it receives as parameter. Listing 9.3 shows the source. + integer it receives as parameter. <xref linkend='example.simple'/> shows the source. </para> - <figure> - <title>Listing 9.3. A simple extension.</title> + <example id='example.simple'> + <title>A simple extension.</title> <programlisting role="C"> /* include standard header */ #include "php.h" @@ -55,7 +55,7 @@ RETURN_LONG(parameter); } </programlisting> - </figure> + </example> <para> This code contains a complete PHP module. We'll explain the source code in detail shortly, but first we'd like to discuss the build Index: ZendAPI/Extending_Zend_Printing.xml diff -u ZendAPI/Extending_Zend_Printing.xml:1.9 ZendAPI/Extending_Zend_Printing.xml:1.10 --- ZendAPI/Extending_Zend_Printing.xml:1.9 Sun Mar 24 21:23:50 2002 +++ ZendAPI/Extending_Zend_Printing.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.9 $ --> + <!-- $Revision: 1.10 $ --> <chapter id="zend.printing"> <title>Printing Information</title> <para> @@ -25,12 +25,11 @@ <function>zend_error</function> can be used to generate error messages. This function accepts two arguments; the first is the error type (see <filename>zend_errors.h</filename>), and the second is the error message. - <programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting>Table 9.16 shows a list of possible values (see <xref linkend='fig.warning-messages'/>). These + <programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting><xref linkend='tab.error-messages'/> shows a list of possible values (see <xref linkend='fig.warning-messages'/>). These values are also referred to in <filename>php.ini</filename>. Depending on which error type you choose, your messages will be logged. - <figure> - <title>Table 9.16. Zend's Predefined Error Messages.</title> - <informaltable> + <table id='tab.error-messages'> + <title>Zend's Predefined Error Messages.</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.36*"/> @@ -89,8 +88,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <figure id='fig.warning-messages'> <title>Display of warning messages in the browser.</title> <graphic fileref="figures/Extending_Zend_7_warning_messages.png"/> @@ -117,11 +115,11 @@ using <function>php_info_print_table_start</function> and then use the standard functions <function>php_info_print_table_header</function> and <function>php_info_print_table_row</function>. As arguments, both take the number of - columns (as integers) and the column contents (as strings). Listing 9.14 shows a source example; Figure 9.9 shows the output. To print the table footer, use <function>php_info_print_table_end</function>. + columns (as integers) and the column contents (as strings). <xref linkend='example.phpinfo'/> shows a source example and its output. To print the table footer, use <function>php_info_print_table_end</function>. </para> - <figure> + <example id='example.phpinfo'> <title> - Listing 9.14. Source code and screenshot for output in <function>phpinfo</function>. + Source code and screenshot for output in <function>phpinfo</function>. </title> <programlisting> php_info_print_table_start(); @@ -131,7 +129,7 @@ php_info_print_table_end(); </programlisting> <graphic fileref="figures/Extending_Zend_8_phpinfo_output.png"/> - </figure> + </example> </section> <section id="zend.printing.execution"> <title>Execution Information</title> @@ -157,17 +155,17 @@ Finally, the line number currently being executed can be retrieved using the function <function>zend_get_executed_lineno</function>. This function also requires the executor globals as arguments. For - examples of these functions, see Listing 9.15 and Figure 9.10. + examples of these functions, see <xref linkend='example.exec-info'/>. </para> - <figure> - <title>Listing 9.15. Printing execution information.</title> + <example id='example.exec-info'> + <title>Printing execution information.</title> <programlisting> zend_printf("The name of the current function is %s<br>", get_active_function_name(TSRMLS_C)); zend_printf("The file currently executed is %s<br>", zend_get_executed_filename(TSRMLS_C)); zend_printf("The current line being executed is %i<br>", zend_get_executed_lineno(TSRMLS_C)); </programlisting> <graphic fileref="figures/Extending_Zend_9_execution_info.png"/> - </figure> + </example> </section> </chapter> <!-- Index: ZendAPI/Extending_Zend_Returning.xml diff -u ZendAPI/Extending_Zend_Returning.xml:1.6 ZendAPI/Extending_Zend_Returning.xml:1.7 --- ZendAPI/Extending_Zend_Returning.xml:1.6 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Returning.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.6 $ --> + <!-- $Revision: 1.7 $ --> <chapter id="zend.returning"> <title>Returning Values</title> <para> @@ -19,14 +19,20 @@ hassles with accessing the internal structures of the <envar>zval</envar> container, a set of predefined macros is available (as usual). These macros automatically set the - correspondent type and value, as described in Tables 9.14 and 9.15. + correspondent type and value, as described in + <xref linkend='tab.return'/> and <xref linkend='tab.retval'/>. </para> - <figure> - <title>Table 9.14. Predefined Macros for Returning Values from a + <note> + <para> + The macros in <xref linkend='tab.return'/> automatically + <emphasis>return</emphasis> from your function, those in + <xref linkend='tab.retval'/> only <emphasis>set</emphasis> + the return value; they don't return from your function. + </para> + </note> + <table id='tab.return'> + <title>Predefined Macros for Returning Values from a Function</title> - <programlisting>Note: The macros in Table 9.14 automatically return - from your function.</programlisting> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -88,17 +94,11 @@ <entry colname="col2">Returns Boolean true.</entry> </row> </tbody> - </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.15. Predefined Macros for Setting the Return Value + </tgroup> + </table> + <table id='tab.retval'> + <title>Predefined Macros for Setting the Return Value of a Function</title> - <programlisting> - Note: The macros in Table 9.15 only <emphasis>set</emphasis> the - return value; they don't return from your function. - </programlisting> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -177,8 +177,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> Complex types such as arrays and objects can be returned by using <function>array_init</function> and Index: ZendAPI/Extending_Zend_Structure.xml diff -u ZendAPI/Extending_Zend_Structure.xml:1.9 ZendAPI/Extending_Zend_Structure.xml:1.10 --- ZendAPI/Extending_Zend_Structure.xml:1.9 Sun Feb 24 01:56:50 2002 +++ ZendAPI/Extending_Zend_Structure.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.9 $ --> + <!-- $Revision: 1.10 $ --> <chapter id="zend.structure"> <title>Source Discussion</title> <para> @@ -105,10 +105,9 @@ <envar>zval</envar> to conform to the new Zend API. </para> <para> - The parameter list of this declaration is very important; you should keep these parameters in mind (see Table 9.1 for descriptions). - <figure> - <title>Table 9.1. Zend's Parameters to Functions Called from PHP</title> - <informaltable> + The parameter list of this declaration is very important; you should keep these parameters in mind (see <xref linkend='tab.parameters'/> for descriptions). + <table id='tab.parameters'> + <title>Zend's Parameters to Functions Called from PHP</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.79*"/> @@ -166,8 +165,8 @@ </row> </tbody> </tgroup> - </informaltable> - </figure></para> + </table> + </para> </section> <section id="zend.structure.function-block"> <title>Declaration of the Zend Function Block</title> @@ -177,11 +176,12 @@ using an array of <envar>zend_function_entry</envar>. This array consecutively contains all functions that are to be made available externally, with the function's name as it should appear in PHP and its name as defined in the C source. - Internally, <envar>zend_function_entry</envar> is defined as shown in Listing 9.5. + Internally, <envar>zend_function_entry</envar> is defined as shown in + <xref linkend='example.zend-function-entry'/>. </para> <para> - <figure> - <title>Listing 9.5. Internal declaration of <envar>zend_function_entry</envar>.</title> + <example id='example.zend-function-entry'> + <title>Internal declaration of <envar>zend_function_entry</envar>.</title> <programlisting> typedef struct _zend_function_entry { char *fname; @@ -223,9 +223,10 @@ </entry> </row> </tbody> - </tgroup> + </tgroup> </informaltable> - </figure>In the example above, the declaration looks like this: + </example> + In the example above, the declaration looks like this: <programlisting> zend_function_entry firstmod_functions[] = { @@ -261,12 +262,11 @@ with <literal>ZEND_FE</literal>. </para> <para> - Table 9.2 shows a list of all the macros that you can use to - define functions. + <xref linkend='tab.funcdef-macros'/> shows a list of all the macros + that you can use to define functions. </para> - <figure> - <title>Table 9.2. Macros for Defining Functions</title> - <informaltable> + <table id='tab.funcdef-macros'> + <title>Macros for Defining Functions</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.08*"/> @@ -329,8 +329,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> <emphasis>Note:</emphasis> You can't use <literal>ZEND_FE</literal> in conjunction with @@ -351,9 +350,10 @@ This block is stored in the structure <envar>zend_module_entry</envar> and contains all necessary information to describe the contents of this module to Zend. You can - see the internal definition of this module in Listing 9.6. + see the internal definition of this module in + <xref linkend='example.zend-module-entry'/>. </para> - <figure> + <example id='example.zend-module-entry'> <title>Internal declaration of <envar>zend_module_entry</envar>.</title> <programlisting> typedef struct _zend_module_entry zend_module_entry; @@ -514,7 +514,7 @@ </tbody> </tgroup> </informaltable> - </figure> + </example> <para> In our example, this structure is implemented as follows: <programlisting> @@ -535,7 +535,8 @@ </para> <para> For reference purposes, you can find a list of the macros involved - in declared startup and shutdown functions in Table 9.3. These are + in declared startup and shutdown functions in + <xref linkend='tab.init-shutdown'/>. These are not used in our basic example yet, but will be demonstrated later on. You should make use of these macros to declare your startup and shutdown functions, as these require special arguments to be passed @@ -546,9 +547,8 @@ developers decide that a change in the argument list is necessary, you'll have to change your module sources to remain compatible. </para> - <figure> + <table id='tab.init-shutdown'> <title>Macros to Declare Startup and Shutdown Functions</title> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.41*"/> @@ -605,8 +605,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.structure.get-module"> Index: ZendAPI/Extending_Zend_Using.xml diff -u ZendAPI/Extending_Zend_Using.xml:1.7 ZendAPI/Extending_Zend_Using.xml:1.8 --- ZendAPI/Extending_Zend_Using.xml:1.7 Sun Mar 24 21:23:50 2002 +++ ZendAPI/Extending_Zend_Using.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.7 $ --> + <!-- $Revision: 1.8 $ --> <chapter id="zend.using"> <title>Using Extensions</title> <para> @@ -9,7 +9,8 @@ should be <filename>first_module.so</filename>. To use it, you first have to copy it to a place from which it's accessible to PHP. For a simple test procedure, you can copy it to your <filename>htdocs</filename> directory and try it with - the source in Listing 9.4. If you compiled it into the PHP binary, + the source in <xref linkend='example.testfile'/>. + If you compiled it into the PHP binary, omit the call to <function>dl</function>, as the module's functionality is instantly available to your scripts. <warning> @@ -21,8 +22,8 @@ </para> </warning> </para> - <figure> - <title>Listing 9.4. A test file for first_module.so.</title> + <example id='example.testfile'> + <title>A test file for first_module.so.</title> <programlisting role='php'> <![CDATA[ <?php @@ -38,7 +39,7 @@ ?> ]]> </programlisting> - </figure> + </example> <para> Calling this PHP file in your Web browser should give you the output shown in <xref linkend='fig.out-first'/>. Index: ZendAPI/Extending_Zend_Variables.xml diff -u ZendAPI/Extending_Zend_Variables.xml:1.7 ZendAPI/Extending_Zend_Variables.xml:1.8 --- ZendAPI/Extending_Zend_Variables.xml:1.7 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Variables.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.7 $ --> + <!-- $Revision: 1.8 $ --> <chapter id="zend.variables"> <title>Creating Variables</title> <para> @@ -141,7 +141,7 @@ NULL ); </programlisting> - Listing 9.10 shows a sample source that + <xref linkend='example.variable-scopes'/> shows a sample source that creates two variables - <envar>local_variable</envar> with a local scope and <envar>global_variable</envar> with a global scope (see Figure 9.7). The full example can be found on the CD-ROM. @@ -151,8 +151,8 @@ within the function. This is because it's not imported into the local scope using <literal>global $global_variable;</literal> in the PHP source. </para> - <figure> - <title>Listing 9.10. Creating variables with different scopes.</title> + <example id='example.variable-scopes'> + <title>Creating variables with different scopes.</title> <programlisting> ZEND_FUNCTION(variable_creation) { @@ -172,7 +172,7 @@ } </programlisting> <graphic fileref="figures/Extending_Zend_6_variable_creation.png"/> - </figure> + </example> </section> <section id="zend.variables.long"> <title>Longs (Integers)</title> @@ -182,9 +182,9 @@ chapter, you can see that the long data type is directly contained in the union, namely in the <envar>lval</envar> field. The corresponding <envar>type</envar> value for longs is <literal>IS_LONG</literal> - (see Listing 9.11). - <figure> - <title>Listing 9.11. Creation of a long.</title> + (see <xref linkend='example.create-long'/>). + <example id='example.create-long'> + <title>Creation of a long.</title> <programlisting> zval *new_long; @@ -193,7 +193,7 @@ new_long->type = IS_LONG; new_long->value.lval = 10; </programlisting> - </figure> + </example> Alternatively, you can use the macro <literal>ZVAL_LONG</literal>: <programlisting> zval *new_long; @@ -337,18 +337,22 @@ </para> <para> To add new elements to the array, you can use numerous functions, - depending on what you want to do. Tables 9.8, 9.9, and 9.10 + depending on what you want to do. + <xref linkend='tab.api-assoc-arrays'/>, + <xref linkend='tab.api-indexed-arrays'/> and + <xref linkend='tab.api-indexed-array-2'/> describe these functions. All functions return <literal>FAILURE</literal> on failure and <literal>SUCCESS</literal> on success. </para> - <figure> - <title>Table 9.8. Zend's API for Associative Arrays</title> + <table id='tab.api-assoc-arrays'> + <title>Zend's API for Associative Arrays</title> +<!-- <programlisting> -Note: The functions in Table 9.8 all operate on the array "array" with the key "key". +Note: The functions in this table all operate on the array "array" with the key "key". The key string doesn't have to reside in Zend internal memory; it will be duplicated by the API. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -410,15 +414,15 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.9. Zend's API for Indexed Arrays, Part 1</title> + </table> + <table id='tab.api-indexed-arrays'> + <title>Zend's API for Indexed Arrays, Part 1</title> +<!-- <programlisting> -Note: The functions in Table 9.9 all operate on the array "array" with the index "idx". +Note: The functions in this table all operate on the array "array" with the index "idx". The index is always an integer. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -467,15 +471,15 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.10. Zend's API for Indexed Arrays, Part 2</title> + </table> + <table id='tab.api-indexed-array-2'> + <title>Zend's API for Indexed Arrays, Part 2</title> +<!-- <programlisting> -Note: The functions in Table 9.10 all operate on the array "array". +Note: The functions in this table all operate on the array "array". These functions automatically generate a new index based on the highest index found in the array. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -524,17 +528,17 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> All these functions provide a handy abstraction to Zend's internal hash API. Of course, you can also use the hash functions directly - for example, if you already have a <envar>zval</envar> container allocated that you want to insert into an array. This is done using <function>zend_hash_update()</function> - for associative arrays (see Listing 9.12) and - <function>zend_hash_index_update</function> for indexed arrays (see Listing 9.13): - <figure> - <title>Listing 9.12. Adding an element to an associative array.</title> + for associative arrays (see <xref linkend='example.array-add-assoc'/>) and + <function>zend_hash_index_update</function> for indexed arrays + (see <xref linkend='example.array-add-indexed'/>): + <example id='example.array-add-assoc'> + <title>Adding an element to an associative array.</title> <programlisting> zval *new_array, *new_element; char *key = "element_key"; @@ -554,9 +558,9 @@ // do error handling here } </programlisting> - </figure> - <figure> - <title>Listing 9.13. Adding an element to an indexed array.</title> + </example> + <example id='example.array-add-indexed'> + <title>Adding an element to an indexed array.</title> <programlisting> zval *new_array, *new_element; int key = 2; @@ -576,7 +580,7 @@ // do error handling here } </programlisting> - </figure> + </example> </para> <para> To emulate the functionality of @@ -619,16 +623,18 @@ // do error handling here } </programlisting> - You can use the functions described in Table 9.11 to add - members to your object. - </para> - <figure> - <title>Table 9.11. Zend's API for Object Creation</title> - <programlisting> - Note: All functions in Table 9.11 work on the object "object" with the key "key". The key forms the member name, + You can use the functions described in + <xref linkend='tab.object-creation'/> + to add members to your object. + </para> + <table id='tab.object-creation'> + <title>Zend's API for Object Creation</title> +<!-- + <programlisting> + Note: All functions in this table work on the object "object" with the key "key". The key forms the member name, so the resulting member can be accessed via $object->key. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.24*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -688,8 +694,7 @@ </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.variables.resource"> @@ -1039,16 +1044,18 @@ In addition to the macros discussed earlier, a few macros allow easy creation of simple global variables. These are nice to know in case you want to introduce global flags, for example. This is - somewhat bad practice, but Table 9.12 describes macros that do + somewhat bad practice, but Table <xref linkend='tab.macros-global-vars'/> + describes macros that do exactly this task. They don't need any <envar>zval</envar> allocation; you simply have to supply a variable name and value. </para> - <figure> - <title>Table 9.12. Macros for Global Variable Creation</title> - <programlisting> - Note: All macros in Table 9.12 create a global variable of the name "name" with the value "value". + <table id='tab.macros-global-vars'> + <title>Macros for Global Variable Creation</title> +<!-- + <programlisting> + Note: All macros in this table create a global variable of the name "name" with the value "value". </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -1077,8 +1084,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.variables.constant"> <title>Creating Constants</title> @@ -1090,7 +1096,9 @@ <literal>FALSE</literal>, to name just two. </para> <para> - To create your own constants, you can use the macros in Table 9.13. All the macros create a constant with the specified name and value. + To create your own constants, you can use the macros in + <xref linkend='tab.create-const'/>. + All the macros create a constant with the specified name and value. </para> <para> You can also specify flags for each constant: @@ -1120,9 +1128,8 @@ constants that remain in the symbol table independently of the module. </para> - <figure> - <title>Table 9.13. Macros for Creating Constants</title> - <informaltable> + <table id='tab.create-const'> + <title>Macros for Creating Constants</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.53*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -1165,8 +1172,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> </chapter> <!--
Index: ZendAPI/Extending_Zend_Build.xml diff -u ZendAPI/Extending_Zend_Build.xml:1.5 ZendAPI/Extending_Zend_Build.xml:1.6 --- ZendAPI/Extending_Zend_Build.xml:1.5 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Build.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.5 $ --> + <!-- $Revision: 1.6 $ --> <chapter id="zend.build"> <title>PHP's Automatic Build System</title> <para> @@ -53,19 +53,19 @@ <filename>Makefile.in</filename>. </para> <para> - Listing 9.1 shows the previously generated + <xref linkend='example.makefile.in'/>shows the previously generated <filename>Makefile.in</filename>: </para> - <figure> - <title>Listing 9.1. The default <filename>Makefile.in</filename>.</title> + <example id='example.makefile.in'> + <title>The default <filename>Makefile.in</filename>.</title> <programlisting> -# $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ +# $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra Exp $ LTLIBRARY_NAME = libmy_module.la LTLIBRARY_SOURCES = my_module.c LTLIBRARY_SHARED_NAME = my_module.la include $(top_srcdir)/build/dynlib.mk </programlisting> - </figure> + </example> <para> There's not much to tell about this one: It contains the names of the input and output files. You could also specify build @@ -73,13 +73,13 @@ source files. </para> <para> - The default <filename>config.m4</filename> shown in Listing - 9.2 is a bit more complex: + The default <filename>config.m4</filename> shown in + <xref linkend='example.config.m4'/>'/> is a bit more complex: </para> - <figure> - <title>Listing 9.2. The default <filename>config.m4</filename>.</title> + <example id='example.config.m4'> + <title>The default <filename>config.m4</filename>.</title> <programlisting> -dnl $Id: Extending_Zend_Build.xml,v 1.5 2002/02/11 10:10:33 hholzgra Exp $ +dnl $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra Exp $ dnl config.m4 for extension my_module dnl don't forget to call PHP_EXTENSION(my_module) dnl If your extension references something external, use with: @@ -95,7 +95,7 @@ PHP_EXTENSION(my_module, $ext_shared) fi </programlisting> - </figure> + </example> <para> If you're unfamiliar with M4 files (now is certainly a good time to get familiar), this might be a bit confusing at first; but Index: ZendAPI/Extending_Zend_CallingUserFunctions.xml diff -u ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.8 ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.9 --- ZendAPI/Extending_Zend_CallingUserFunctions.xml:1.8 Sun Feb 24 01:44:44 2002 +++ ZendAPI/Extending_Zend_CallingUserFunctions.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.8 $ --> + <!-- $Revision: 1.9 $ --> <chapter id="zend.calling-user-functions"> <title>Calling User Functions</title> <para> @@ -61,7 +61,7 @@ need separation. </para> <para> - Listing 9.16 and Figure 9.11 show a small demonstration of + <xref linkend='example.call-user-func'/> and Figure 9.11 show a small demonstration of calling a user function. The code calls a function that's supplied to it as argument and directly passes this function's return value through as its own return value. Note the use of the constructor @@ -69,8 +69,8 @@ it this way here (since they should be separate values, the assignment might be safe), but this is bulletproof. </para> - <figure> - <title>Listing 9.16. Calling user functions.</title> + <example id='example.call-user-func'> + <title>Calling user functions.</title> <programlisting> zval **function_name; zval *retval; @@ -98,7 +98,7 @@ zval_copy_ctor(return_value); zval_ptr_dtor(&retval); </programlisting> - </figure> + </example> <para/> <programlisting> <?php Index: ZendAPI/Extending_Zend_ConfigurationMacros.xml diff -u ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.5 ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.6 --- ZendAPI/Extending_Zend_ConfigurationMacros.xml:1.5 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_ConfigurationMacros.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.5 $ --> + <!-- $Revision: 1.6 $ --> <chapter id="zend.configuration-macros"> <title>Reference: Some Configuration Macros</title> <section id="zend.configuration-macros.config-m4"> @@ -9,11 +9,11 @@ <filename>buildconf</filename> and must contain all the instructions to be executed during configuration. For example, these can include tests for required external files, such as header files, libraries, and so on. PHP defines a set of macros - that can be used in this process, the most useful of which are described in Table 9.18. + that can be used in this process, the most useful of which are described in + <xref linkend='tab.m4-macros'/>. </para> - <figure> - <title>Table 9.18. M4 Macros for <filename>config.m4</filename></title> - <informaltable> + <table id='tab.m4-macros'> + <title>M4 Macros for <filename>config.m4</filename></title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.63*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -80,8 +80,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> </chapter> <!-- Index: ZendAPI/Extending_Zend_Creating.xml diff -u ZendAPI/Extending_Zend_Creating.xml:1.6 ZendAPI/Extending_Zend_Creating.xml:1.7 --- ZendAPI/Extending_Zend_Creating.xml:1.6 Tue Mar 19 08:45:21 2002 +++ ZendAPI/Extending_Zend_Creating.xml Mon Mar 25 03:13:46 2002 @@ -1,14 +1,14 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.6 $ --> + <!-- $Revision: 1.7 $ --> <chapter id="zend.creating"> <title>Creating Extensions</title> <para> We'll start with the creation of a very simple extension at first, which basically does nothing more than implement a function that returns the - integer it receives as parameter. Listing 9.3 shows the source. + integer it receives as parameter. <xref linkend='example.simple'/> shows the source. </para> - <figure> - <title>Listing 9.3. A simple extension.</title> + <example id='example.simple'> + <title>A simple extension.</title> <programlisting role="C"> /* include standard header */ #include "php.h" @@ -55,7 +55,7 @@ RETURN_LONG(parameter); } </programlisting> - </figure> + </example> <para> This code contains a complete PHP module. We'll explain the source code in detail shortly, but first we'd like to discuss the build Index: ZendAPI/Extending_Zend_Printing.xml diff -u ZendAPI/Extending_Zend_Printing.xml:1.9 ZendAPI/Extending_Zend_Printing.xml:1.10 --- ZendAPI/Extending_Zend_Printing.xml:1.9 Sun Mar 24 21:23:50 2002 +++ ZendAPI/Extending_Zend_Printing.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.9 $ --> + <!-- $Revision: 1.10 $ --> <chapter id="zend.printing"> <title>Printing Information</title> <para> @@ -25,12 +25,11 @@ <function>zend_error</function> can be used to generate error messages. This function accepts two arguments; the first is the error type (see <filename>zend_errors.h</filename>), and the second is the error message. - <programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting>Table 9.16 shows a list of possible values (see <xref linkend='fig.warning-messages'/>). These + <programlisting>zend_error(E_WARNING, "This function has been called with empty arguments");</programlisting><xref linkend='tab.error-messages'/> shows a list of possible values (see <xref linkend='fig.warning-messages'/>). These values are also referred to in <filename>php.ini</filename>. Depending on which error type you choose, your messages will be logged. - <figure> - <title>Table 9.16. Zend's Predefined Error Messages.</title> - <informaltable> + <table id='tab.error-messages'> + <title>Zend's Predefined Error Messages.</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.36*"/> @@ -89,8 +88,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <figure id='fig.warning-messages'> <title>Display of warning messages in the browser.</title> <graphic fileref="figures/Extending_Zend_7_warning_messages.png"/> @@ -117,11 +115,11 @@ using <function>php_info_print_table_start</function> and then use the standard functions <function>php_info_print_table_header</function> and <function>php_info_print_table_row</function>. As arguments, both take the number of - columns (as integers) and the column contents (as strings). Listing 9.14 shows a source example; Figure 9.9 shows the output. To print the table footer, use <function>php_info_print_table_end</function>. + columns (as integers) and the column contents (as strings). <xref linkend='example.phpinfo'/> shows a source example and its output. To print the table footer, use <function>php_info_print_table_end</function>. </para> - <figure> + <example id='example.phpinfo'> <title> - Listing 9.14. Source code and screenshot for output in <function>phpinfo</function>. + Source code and screenshot for output in <function>phpinfo</function>. </title> <programlisting> php_info_print_table_start(); @@ -131,7 +129,7 @@ php_info_print_table_end(); </programlisting> <graphic fileref="figures/Extending_Zend_8_phpinfo_output.png"/> - </figure> + </example> </section> <section id="zend.printing.execution"> <title>Execution Information</title> @@ -157,17 +155,17 @@ Finally, the line number currently being executed can be retrieved using the function <function>zend_get_executed_lineno</function>. This function also requires the executor globals as arguments. For - examples of these functions, see Listing 9.15 and Figure 9.10. + examples of these functions, see <xref linkend='example.exec-info'/>. </para> - <figure> - <title>Listing 9.15. Printing execution information.</title> + <example id='example.exec-info'> + <title>Printing execution information.</title> <programlisting> zend_printf("The name of the current function is %s<br>", get_active_function_name(TSRMLS_C)); zend_printf("The file currently executed is %s<br>", zend_get_executed_filename(TSRMLS_C)); zend_printf("The current line being executed is %i<br>", zend_get_executed_lineno(TSRMLS_C)); </programlisting> <graphic fileref="figures/Extending_Zend_9_execution_info.png"/> - </figure> + </example> </section> </chapter> <!-- Index: ZendAPI/Extending_Zend_Returning.xml diff -u ZendAPI/Extending_Zend_Returning.xml:1.6 ZendAPI/Extending_Zend_Returning.xml:1.7 --- ZendAPI/Extending_Zend_Returning.xml:1.6 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Returning.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.6 $ --> + <!-- $Revision: 1.7 $ --> <chapter id="zend.returning"> <title>Returning Values</title> <para> @@ -19,14 +19,20 @@ hassles with accessing the internal structures of the <envar>zval</envar> container, a set of predefined macros is available (as usual). These macros automatically set the - correspondent type and value, as described in Tables 9.14 and 9.15. + correspondent type and value, as described in + <xref linkend='tab.return'/> and <xref linkend='tab.retval'/>. </para> - <figure> - <title>Table 9.14. Predefined Macros for Returning Values from a + <note> + <para> + The macros in <xref linkend='tab.return'/> automatically + <emphasis>return</emphasis> from your function, those in + <xref linkend='tab.retval'/> only <emphasis>set</emphasis> + the return value; they don't return from your function. + </para> + </note> + <table id='tab.return'> + <title>Predefined Macros for Returning Values from a Function</title> - <programlisting>Note: The macros in Table 9.14 automatically return - from your function.</programlisting> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -88,17 +94,11 @@ <entry colname="col2">Returns Boolean true.</entry> </row> </tbody> - </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.15. Predefined Macros for Setting the Return Value + </tgroup> + </table> + <table id='tab.retval'> + <title>Predefined Macros for Setting the Return Value of a Function</title> - <programlisting> - Note: The macros in Table 9.15 only <emphasis>set</emphasis> the - return value; they don't return from your function. - </programlisting> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -177,8 +177,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> Complex types such as arrays and objects can be returned by using <function>array_init</function> and Index: ZendAPI/Extending_Zend_Structure.xml diff -u ZendAPI/Extending_Zend_Structure.xml:1.9 ZendAPI/Extending_Zend_Structure.xml:1.10 --- ZendAPI/Extending_Zend_Structure.xml:1.9 Sun Feb 24 01:56:50 2002 +++ ZendAPI/Extending_Zend_Structure.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.9 $ --> + <!-- $Revision: 1.10 $ --> <chapter id="zend.structure"> <title>Source Discussion</title> <para> @@ -105,10 +105,9 @@ <envar>zval</envar> to conform to the new Zend API. </para> <para> - The parameter list of this declaration is very important; you should keep these parameters in mind (see Table 9.1 for descriptions). - <figure> - <title>Table 9.1. Zend's Parameters to Functions Called from PHP</title> - <informaltable> + The parameter list of this declaration is very important; you should keep these parameters in mind (see <xref linkend='tab.parameters'/> for descriptions). + <table id='tab.parameters'> + <title>Zend's Parameters to Functions Called from PHP</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.79*"/> @@ -166,8 +165,8 @@ </row> </tbody> </tgroup> - </informaltable> - </figure></para> + </table> + </para> </section> <section id="zend.structure.function-block"> <title>Declaration of the Zend Function Block</title> @@ -177,11 +176,12 @@ using an array of <envar>zend_function_entry</envar>. This array consecutively contains all functions that are to be made available externally, with the function's name as it should appear in PHP and its name as defined in the C source. - Internally, <envar>zend_function_entry</envar> is defined as shown in Listing 9.5. + Internally, <envar>zend_function_entry</envar> is defined as shown in + <xref linkend='example.zend-function-entry'/>. </para> <para> - <figure> - <title>Listing 9.5. Internal declaration of <envar>zend_function_entry</envar>.</title> + <example id='example.zend-function-entry'> + <title>Internal declaration of <envar>zend_function_entry</envar>.</title> <programlisting> typedef struct _zend_function_entry { char *fname; @@ -223,9 +223,10 @@ </entry> </row> </tbody> - </tgroup> + </tgroup> </informaltable> - </figure>In the example above, the declaration looks like this: + </example> + In the example above, the declaration looks like this: <programlisting> zend_function_entry firstmod_functions[] = { @@ -261,12 +262,11 @@ with <literal>ZEND_FE</literal>. </para> <para> - Table 9.2 shows a list of all the macros that you can use to - define functions. + <xref linkend='tab.funcdef-macros'/> shows a list of all the macros + that you can use to define functions. </para> - <figure> - <title>Table 9.2. Macros for Defining Functions</title> - <informaltable> + <table id='tab.funcdef-macros'> + <title>Macros for Defining Functions</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.08*"/> @@ -329,8 +329,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> <emphasis>Note:</emphasis> You can't use <literal>ZEND_FE</literal> in conjunction with @@ -351,9 +350,10 @@ This block is stored in the structure <envar>zend_module_entry</envar> and contains all necessary information to describe the contents of this module to Zend. You can - see the internal definition of this module in Listing 9.6. + see the internal definition of this module in + <xref linkend='example.zend-module-entry'/>. </para> - <figure> + <example id='example.zend-module-entry'> <title>Internal declaration of <envar>zend_module_entry</envar>.</title> <programlisting> typedef struct _zend_module_entry zend_module_entry; @@ -514,7 +514,7 @@ </tbody> </tgroup> </informaltable> - </figure> + </example> <para> In our example, this structure is implemented as follows: <programlisting> @@ -535,7 +535,8 @@ </para> <para> For reference purposes, you can find a list of the macros involved - in declared startup and shutdown functions in Table 9.3. These are + in declared startup and shutdown functions in + <xref linkend='tab.init-shutdown'/>. These are not used in our basic example yet, but will be demonstrated later on. You should make use of these macros to declare your startup and shutdown functions, as these require special arguments to be passed @@ -546,9 +547,8 @@ developers decide that a change in the argument list is necessary, you'll have to change your module sources to remain compatible. </para> - <figure> + <table id='tab.init-shutdown'> <title>Macros to Declare Startup and Shutdown Functions</title> - <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.41*"/> @@ -605,8 +605,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.structure.get-module"> Index: ZendAPI/Extending_Zend_Using.xml diff -u ZendAPI/Extending_Zend_Using.xml:1.7 ZendAPI/Extending_Zend_Using.xml:1.8 --- ZendAPI/Extending_Zend_Using.xml:1.7 Sun Mar 24 21:23:50 2002 +++ ZendAPI/Extending_Zend_Using.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.7 $ --> + <!-- $Revision: 1.8 $ --> <chapter id="zend.using"> <title>Using Extensions</title> <para> @@ -9,7 +9,8 @@ should be <filename>first_module.so</filename>. To use it, you first have to copy it to a place from which it's accessible to PHP. For a simple test procedure, you can copy it to your <filename>htdocs</filename> directory and try it with - the source in Listing 9.4. If you compiled it into the PHP binary, + the source in <xref linkend='example.testfile'/>. + If you compiled it into the PHP binary, omit the call to <function>dl</function>, as the module's functionality is instantly available to your scripts. <warning> @@ -21,8 +22,8 @@ </para> </warning> </para> - <figure> - <title>Listing 9.4. A test file for first_module.so.</title> + <example id='example.testfile'> + <title>A test file for first_module.so.</title> <programlisting role='php'> <![CDATA[ <?php @@ -38,7 +39,7 @@ ?> ]]> </programlisting> - </figure> + </example> <para> Calling this PHP file in your Web browser should give you the output shown in <xref linkend='fig.out-first'/>. Index: ZendAPI/Extending_Zend_Variables.xml diff -u ZendAPI/Extending_Zend_Variables.xml:1.7 ZendAPI/Extending_Zend_Variables.xml:1.8 --- ZendAPI/Extending_Zend_Variables.xml:1.7 Mon Feb 11 05:10:33 2002 +++ ZendAPI/Extending_Zend_Variables.xml Mon Mar 25 03:13:46 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- $Revision: 1.7 $ --> + <!-- $Revision: 1.8 $ --> <chapter id="zend.variables"> <title>Creating Variables</title> <para> @@ -141,7 +141,7 @@ NULL ); </programlisting> - Listing 9.10 shows a sample source that + <xref linkend='example.variable-scopes'/> shows a sample source that creates two variables - <envar>local_variable</envar> with a local scope and <envar>global_variable</envar> with a global scope (see Figure 9.7). The full example can be found on the CD-ROM. @@ -151,8 +151,8 @@ within the function. This is because it's not imported into the local scope using <literal>global $global_variable;</literal> in the PHP source. </para> - <figure> - <title>Listing 9.10. Creating variables with different scopes.</title> + <example id='example.variable-scopes'> + <title>Creating variables with different scopes.</title> <programlisting> ZEND_FUNCTION(variable_creation) { @@ -172,7 +172,7 @@ } </programlisting> <graphic fileref="figures/Extending_Zend_6_variable_creation.png"/> - </figure> + </example> </section> <section id="zend.variables.long"> <title>Longs (Integers)</title> @@ -182,9 +182,9 @@ chapter, you can see that the long data type is directly contained in the union, namely in the <envar>lval</envar> field. The corresponding <envar>type</envar> value for longs is <literal>IS_LONG</literal> - (see Listing 9.11). - <figure> - <title>Listing 9.11. Creation of a long.</title> + (see <xref linkend='example.create-long'/>). + <example id='example.create-long'> + <title>Creation of a long.</title> <programlisting> zval *new_long; @@ -193,7 +193,7 @@ new_long->type = IS_LONG; new_long->value.lval = 10; </programlisting> - </figure> + </example> Alternatively, you can use the macro <literal>ZVAL_LONG</literal>: <programlisting> zval *new_long; @@ -337,18 +337,22 @@ </para> <para> To add new elements to the array, you can use numerous functions, - depending on what you want to do. Tables 9.8, 9.9, and 9.10 + depending on what you want to do. + <xref linkend='tab.api-assoc-arrays'/>, + <xref linkend='tab.api-indexed-arrays'/> and + <xref linkend='tab.api-indexed-array-2'/> describe these functions. All functions return <literal>FAILURE</literal> on failure and <literal>SUCCESS</literal> on success. </para> - <figure> - <title>Table 9.8. Zend's API for Associative Arrays</title> + <table id='tab.api-assoc-arrays'> + <title>Zend's API for Associative Arrays</title> +<!-- <programlisting> -Note: The functions in Table 9.8 all operate on the array "array" with the key "key". +Note: The functions in this table all operate on the array "array" with the key "key". The key string doesn't have to reside in Zend internal memory; it will be duplicated by the API. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -410,15 +414,15 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.9. Zend's API for Indexed Arrays, Part 1</title> + </table> + <table id='tab.api-indexed-arrays'> + <title>Zend's API for Indexed Arrays, Part 1</title> +<!-- <programlisting> -Note: The functions in Table 9.9 all operate on the array "array" with the index "idx". +Note: The functions in this table all operate on the array "array" with the index "idx". The index is always an integer. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -467,15 +471,15 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> - <figure> - <title>Table 9.10. Zend's API for Indexed Arrays, Part 2</title> + </table> + <table id='tab.api-indexed-array-2'> + <title>Zend's API for Indexed Arrays, Part 2</title> +<!-- <programlisting> -Note: The functions in Table 9.10 all operate on the array "array". +Note: The functions in this table all operate on the array "array". These functions automatically generate a new index based on the highest index found in the array. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -524,17 +528,17 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> <para> All these functions provide a handy abstraction to Zend's internal hash API. Of course, you can also use the hash functions directly - for example, if you already have a <envar>zval</envar> container allocated that you want to insert into an array. This is done using <function>zend_hash_update()</function> - for associative arrays (see Listing 9.12) and - <function>zend_hash_index_update</function> for indexed arrays (see Listing 9.13): - <figure> - <title>Listing 9.12. Adding an element to an associative array.</title> + for associative arrays (see <xref linkend='example.array-add-assoc'/>) and + <function>zend_hash_index_update</function> for indexed arrays + (see <xref linkend='example.array-add-indexed'/>): + <example id='example.array-add-assoc'> + <title>Adding an element to an associative array.</title> <programlisting> zval *new_array, *new_element; char *key = "element_key"; @@ -554,9 +558,9 @@ // do error handling here } </programlisting> - </figure> - <figure> - <title>Listing 9.13. Adding an element to an indexed array.</title> + </example> + <example id='example.array-add-indexed'> + <title>Adding an element to an indexed array.</title> <programlisting> zval *new_array, *new_element; int key = 2; @@ -576,7 +580,7 @@ // do error handling here } </programlisting> - </figure> + </example> </para> <para> To emulate the functionality of @@ -619,16 +623,18 @@ // do error handling here } </programlisting> - You can use the functions described in Table 9.11 to add - members to your object. - </para> - <figure> - <title>Table 9.11. Zend's API for Object Creation</title> - <programlisting> - Note: All functions in Table 9.11 work on the object "object" with the key "key". The key forms the member name, + You can use the functions described in + <xref linkend='tab.object-creation'/> + to add members to your object. + </para> + <table id='tab.object-creation'> + <title>Zend's API for Object Creation</title> +<!-- + <programlisting> + Note: All functions in this table work on the object "object" with the key "key". The key forms the member name, so the resulting member can be accessed via $object->key. </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.24*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -688,8 +694,7 @@ </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.variables.resource"> @@ -1039,16 +1044,18 @@ In addition to the macros discussed earlier, a few macros allow easy creation of simple global variables. These are nice to know in case you want to introduce global flags, for example. This is - somewhat bad practice, but Table 9.12 describes macros that do + somewhat bad practice, but Table <xref linkend='tab.macros-global-vars'/> + describes macros that do exactly this task. They don't need any <envar>zval</envar> allocation; you simply have to supply a variable name and value. </para> - <figure> - <title>Table 9.12. Macros for Global Variable Creation</title> - <programlisting> - Note: All macros in Table 9.12 create a global variable of the name "name" with the value "value". + <table id='tab.macros-global-vars'> + <title>Macros for Global Variable Creation</title> +<!-- + <programlisting> + Note: All macros in this table create a global variable of the name "name" with the value "value". </programlisting> - <informaltable> +--> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="*"/> <colspec colnum="2" colname="col2" colwidth="*"/> @@ -1077,8 +1084,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> <section id="zend.variables.constant"> <title>Creating Constants</title> @@ -1090,7 +1096,9 @@ <literal>FALSE</literal>, to name just two. </para> <para> - To create your own constants, you can use the macros in Table 9.13. All the macros create a constant with the specified name and value. + To create your own constants, you can use the macros in + <xref linkend='tab.create-const'/>. + All the macros create a constant with the specified name and value. </para> <para> You can also specify flags for each constant: @@ -1120,9 +1128,8 @@ constants that remain in the symbol table independently of the module. </para> - <figure> - <title>Table 9.13. Macros for Creating Constants</title> - <informaltable> + <table id='tab.create-const'> + <title>Macros for Creating Constants</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.53*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> @@ -1165,8 +1172,7 @@ </row> </tbody> </tgroup> - </informaltable> - </figure> + </table> </section> </chapter> <!--