svn commit - mysqldoc@docsrva: r11926 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-6.0

[paul.dubois]

Author: paul
Date: 2008-09-30 20:19:16 +0200 (Tue, 30 Sep 2008)
New Revision: 11926

Log:
 r34342@frost:  paul | 2008-09-30 13:20:09 -0500
 mysql_library_init(): Make it clearer that it applies to regular clients,
 not just embedded apps.


Modified:
   trunk/refman-4.1/apis-c.xml
   trunk/refman-5.0/apis-c.xml
   trunk/refman-5.1/apis-c.xml
   trunk/refman-6.0/apis-c.xml

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:34341
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:33355
   + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:34342
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:33355


Modified: trunk/refman-4.1/apis-c.xml
===================================================================
--- trunk/refman-4.1/apis-c.xml	2008-09-30 18:19:10 UTC (rev 11925)
+++ trunk/refman-4.1/apis-c.xml	2008-09-30 18:19:16 UTC (rev 11926)
Changed blocks: 5, Lines Added: 38, Lines Deleted: 27; 4823 bytes

@@ -27,7 +27,7 @@
     Many of the clients in the MySQL source distribution are written in
     C. If you are looking for examples that demonstrate how to use the C
     API, take a look at these clients. You can find these in the
-    <literal>clients</literal> directory in the MySQL source
+    <literal>client</literal> directory in the MySQL source
     distribution.
   </para>
 

@@ -4170,8 +4170,9 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, and
-        <xref linkend="mysql-library-init"/>, for usage information.
+        For usage information, see
+        <xref linkend="c-api-function-overview"/>, and
+        <xref linkend="mysql-library-init"/>.
       </para>
 
       <para>

@@ -4201,13 +4202,30 @@
 
       <para>
         This function should be called to initialize the MySQL library
-        before you call any other MySQL function. If your application
-        uses the embedded server, this call starts the server and
-        initializes any subsystems (<literal>mysys</literal>,
-        <literal>InnoDB</literal>, and so forth) that the server uses.
+        before you call any other MySQL function, whether your
+        application is a regular client program or uses the embedded
+        server. If the application uses the embedded server, this call
+        starts the server and initializes any subsystems
+        (<literal>mysys</literal>, <literal>InnoDB</literal>, and
so
+        forth) that the server uses.
       </para>
 
       <para>
+        After your application is done using the MySQL library, call
+        <function role="capi">mysql_library_end()</function> to clean
+        up. See <xref linkend="mysql-library-end"/>.
+      </para>
+
+      <para>
+        The choice of whether the application acts as a regular client
+        or uses the embedded server depends on whether you use the
+        <literal>libmysqlclient</literal> or
+        <literal>libmysqld</literal> at link time to produce the final
+        executable. For additional information, see
+        <xref linkend="c-api-function-overview"/>.
+      </para>
+
+      <para>
         In a non-multi-threaded environment, the call to
         <function role="capi">mysql_library_init()</function> may be
         omitted, because <function role="capi">mysql_init()</function>

@@ -4226,29 +4244,27 @@
       </para>
 
       <para>
-        After your application is done using the MySQL library, call
-        <function role="capi">mysql_library_end()</function> to clean
-        up. See <xref linkend="mysql-library-end"/>.
-      </para>
-
-      <para>
         The <literal>argc</literal> and <literal>argv</literal>
         arguments are analogous to the arguments to
-        <literal>main()</literal>. The first element of
-        <literal>argv</literal> is ignored (it typically contains the
-        program name). For convenience, <literal>argc</literal> may be
-        <literal>0</literal> (zero) if there are no command-line
-        arguments for the server.
+        <literal>main()</literal>, and enable passing of options to the
+        embedded server. The first element of <literal>argv</literal> is
+        ignored (it typically contains the program name).
         <function role="capi">mysql_library_init()</function> makes a
         copy of the arguments so it is safe to destroy
         <literal>argv</literal> or <literal>groups</literal>
after the
-        call.
+        call. For convenience, <literal>argc</literal> may be
+        <literal>0</literal> (zero) if there are no command-line
+        arguments for the server. This is the usual case for
+        non-embedded applications intended for use only as regular
+        clients, and the call typically is written as
+        <function role="capi">mysql_library_init(0, NULL,
+        NULL)</function>.
       </para>
 
       <para>
-        If you want to connect to an external server without starting
-        the embedded server, you have to specify a negative value for
-        <literal>argc</literal>.
+        For embedded applications, if you want to connect to an external
+        server without starting the embedded server, you have to specify
+        a negative value for <literal>argc</literal>.
       </para>
 
       <para>

@@ -4262,11 +4278,6 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, for additional
-        usage information.
-      </para>
-
-      <para>
         <function role="capi">mysql_library_init()</function> was added
         in MySQL 4.1.10. For older versions of MySQL, call
         <function role="capi">mysql_server_init()</function> instead.


Modified: trunk/refman-5.0/apis-c.xml
===================================================================
--- trunk/refman-5.0/apis-c.xml	2008-09-30 18:19:10 UTC (rev 11925)
+++ trunk/refman-5.0/apis-c.xml	2008-09-30 18:19:16 UTC (rev 11926)
Changed blocks: 5, Lines Added: 38, Lines Deleted: 27; 4822 bytes

@@ -27,7 +27,7 @@
     Many of the clients in the MySQL source distribution are written in
     C. If you are looking for examples that demonstrate how to use the C
     API, take a look at these clients. You can find these in the
-    <literal>clients</literal> directory in the MySQL source
+    <literal>client</literal> directory in the MySQL source
     distribution.
   </para>
 

@@ -4320,8 +4320,9 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, and
-        <xref linkend="mysql-library-init"/>, for usage information.
+        For usage information, see
+        <xref linkend="c-api-function-overview"/>, and
+        <xref linkend="mysql-library-init"/>.
       </para>
 
       <para>

@@ -4351,13 +4352,30 @@
 
       <para>
         This function should be called to initialize the MySQL library
-        before you call any other MySQL function. If your application
-        uses the embedded server, this call starts the server and
-        initializes any subsystems (<literal>mysys</literal>,
-        <literal>InnoDB</literal>, and so forth) that the server uses.
+        before you call any other MySQL function, whether your
+        application is a regular client program or uses the embedded
+        server. If the application uses the embedded server, this call
+        starts the server and initializes any subsystems
+        (<literal>mysys</literal>, <literal>InnoDB</literal>, and
so
+        forth) that the server uses.
       </para>
 
       <para>
+        After your application is done using the MySQL library, call
+        <function role="capi">mysql_library_end()</function> to clean
+        up. See <xref linkend="mysql-library-end"/>.
+      </para>
+
+      <para>
+        The choice of whether the application acts as a regular client
+        or uses the embedded server depends on whether you use the
+        <literal>libmysqlclient</literal> or
+        <literal>libmysqld</literal> at link time to produce the final
+        executable. For additional information, see
+        <xref linkend="c-api-function-overview"/>.
+      </para>
+
+      <para>
         In a non-multi-threaded environment, the call to
         <function role="capi">mysql_library_init()</function> may be
         omitted, because <function role="capi">mysql_init()</function>

@@ -4376,29 +4394,27 @@
       </para>
 
       <para>
-        After your application is done using the MySQL library, call
-        <function role="capi">mysql_library_end()</function> to clean
-        up. See <xref linkend="mysql-library-end"/>.
-      </para>
-
-      <para>
         The <literal>argc</literal> and <literal>argv</literal>
         arguments are analogous to the arguments to
-        <literal>main()</literal>. The first element of
-        <literal>argv</literal> is ignored (it typically contains the
-        program name). For convenience, <literal>argc</literal> may be
-        <literal>0</literal> (zero) if there are no command-line
-        arguments for the server.
+        <literal>main()</literal>, and enable passing of options to the
+        embedded server. The first element of <literal>argv</literal> is
+        ignored (it typically contains the program name).
         <function role="capi">mysql_library_init()</function> makes a
         copy of the arguments so it is safe to destroy
         <literal>argv</literal> or <literal>groups</literal>
after the
-        call.
+        call. For convenience, <literal>argc</literal> may be
+        <literal>0</literal> (zero) if there are no command-line
+        arguments for the server. This is the usual case for
+        non-embedded applications intended for use only as regular
+        clients, and the call typically is written as
+        <function role="capi">mysql_library_init(0, NULL,
+        NULL)</function>.
       </para>
 
       <para>
-        If you want to connect to an external server without starting
-        the embedded server, you have to specify a negative value for
-        <literal>argc</literal>.
+        For embedded applications, if you want to connect to an external
+        server without starting the embedded server, you have to specify
+        a negative value for <literal>argc</literal>.
       </para>
 
       <para>

@@ -4412,11 +4428,6 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, for additional
-        usage information.
-      </para>
-
-      <para>
         <function role="capi">mysql_library_init()</function> was added
         in MySQL 5.0.3. For older versions of MySQL, call
         <function role="capi">mysql_server_init()</function> instead.


Modified: trunk/refman-5.1/apis-c.xml
===================================================================
--- trunk/refman-5.1/apis-c.xml	2008-09-30 18:19:10 UTC (rev 11925)
+++ trunk/refman-5.1/apis-c.xml	2008-09-30 18:19:16 UTC (rev 11926)
Changed blocks: 5, Lines Added: 38, Lines Deleted: 27; 4688 bytes

@@ -27,7 +27,7 @@
     Many of the clients in the MySQL source distribution are written in
     C. If you are looking for examples that demonstrate how to use the C
     API, take a look at these clients. You can find these in the
-    <literal>clients</literal> directory in the MySQL source
+    <literal>client</literal> directory in the MySQL source
     distribution.
   </para>
 

@@ -4384,8 +4384,9 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, and
-        <xref linkend="mysql-library-init"/>, for usage information.
+        For usage information, see
+        <xref linkend="c-api-function-overview"/>, and
+        <xref linkend="mysql-library-init"/>.
       </para>
 
     </section>

@@ -4409,13 +4410,30 @@
 
       <para>
         This function should be called to initialize the MySQL library
-        before you call any other MySQL function. If your application
-        uses the embedded server, this call starts the server and
-        initializes any subsystems (<literal>mysys</literal>,
-        <literal>InnoDB</literal>, and so forth) that the server uses.
+        before you call any other MySQL function, whether your
+        application is a regular client program or uses the embedded
+        server. If the application uses the embedded server, this call
+        starts the server and initializes any subsystems
+        (<literal>mysys</literal>, <literal>InnoDB</literal>, and
so
+        forth) that the server uses.
       </para>
 
       <para>
+        After your application is done using the MySQL library, call
+        <function role="capi">mysql_library_end()</function> to clean
+        up. See <xref linkend="mysql-library-end"/>.
+      </para>
+
+      <para>
+        The choice of whether the application acts as a regular client
+        or uses the embedded server depends on whether you use the
+        <literal>libmysqlclient</literal> or
+        <literal>libmysqld</literal> at link time to produce the final
+        executable. For additional information, see
+        <xref linkend="c-api-function-overview"/>.
+      </para>
+
+      <para>
         In a non-multi-threaded environment, the call to
         <function role="capi">mysql_library_init()</function> may be
         omitted, because <function role="capi">mysql_init()</function>

@@ -4434,29 +4452,27 @@
       </para>
 
       <para>
-        After your application is done using the MySQL library, call
-        <function role="capi">mysql_library_end()</function> to clean
-        up. See <xref linkend="mysql-library-end"/>.
-      </para>
-
-      <para>
         The <literal>argc</literal> and <literal>argv</literal>
         arguments are analogous to the arguments to
-        <literal>main()</literal>. The first element of
-        <literal>argv</literal> is ignored (it typically contains the
-        program name). For convenience, <literal>argc</literal> may be
-        <literal>0</literal> (zero) if there are no command-line
-        arguments for the server.
+        <literal>main()</literal>, and enable passing of options to the
+        embedded server. The first element of <literal>argv</literal> is
+        ignored (it typically contains the program name).
         <function role="capi">mysql_library_init()</function> makes a
         copy of the arguments so it is safe to destroy
         <literal>argv</literal> or <literal>groups</literal>
after the
-        call.
+        call. For convenience, <literal>argc</literal> may be
+        <literal>0</literal> (zero) if there are no command-line
+        arguments for the server. This is the usual case for
+        non-embedded applications intended for use only as regular
+        clients, and the call typically is written as
+        <function role="capi">mysql_library_init(0, NULL,
+        NULL)</function>.
       </para>
 
       <para>
-        If you want to connect to an external server without starting
-        the embedded server, you have to specify a negative value for
-        <literal>argc</literal>.
+        For embedded applications, if you want to connect to an external
+        server without starting the embedded server, you have to specify
+        a negative value for <literal>argc</literal>.
       </para>
 
       <para>

@@ -4470,11 +4486,6 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, for additional
-        usage information.
-      </para>
-
-      <para>
         <emphasis role="bold">Example</emphasis>
       </para>
 


Modified: trunk/refman-6.0/apis-c.xml
===================================================================
--- trunk/refman-6.0/apis-c.xml	2008-09-30 18:19:10 UTC (rev 11925)
+++ trunk/refman-6.0/apis-c.xml	2008-09-30 18:19:16 UTC (rev 11926)
Changed blocks: 5, Lines Added: 38, Lines Deleted: 27; 4688 bytes

@@ -27,7 +27,7 @@
     Many of the clients in the MySQL source distribution are written in
     C. If you are looking for examples that demonstrate how to use the C
     API, take a look at these clients. You can find these in the
-    <literal>clients</literal> directory in the MySQL source
+    <literal>client</literal> directory in the MySQL source
     distribution.
   </para>
 

@@ -4339,8 +4339,9 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, and
-        <xref linkend="mysql-library-init"/>, for usage information.
+        For usage information, see
+        <xref linkend="c-api-function-overview"/>, and
+        <xref linkend="mysql-library-init"/>.
       </para>
 
     </section>

@@ -4364,13 +4365,30 @@
 
       <para>
         This function should be called to initialize the MySQL library
-        before you call any other MySQL function. If your application
-        uses the embedded server, this call starts the server and
-        initializes any subsystems (<literal>mysys</literal>,
-        <literal>InnoDB</literal>, and so forth) that the server uses.
+        before you call any other MySQL function, whether your
+        application is a regular client program or uses the embedded
+        server. If the application uses the embedded server, this call
+        starts the server and initializes any subsystems
+        (<literal>mysys</literal>, <literal>InnoDB</literal>, and
so
+        forth) that the server uses.
       </para>
 
       <para>
+        After your application is done using the MySQL library, call
+        <function role="capi">mysql_library_end()</function> to clean
+        up. See <xref linkend="mysql-library-end"/>.
+      </para>
+
+      <para>
+        The choice of whether the application acts as a regular client
+        or uses the embedded server depends on whether you use the
+        <literal>libmysqlclient</literal> or
+        <literal>libmysqld</literal> at link time to produce the final
+        executable. For additional information, see
+        <xref linkend="c-api-function-overview"/>.
+      </para>
+
+      <para>
         In a non-multi-threaded environment, the call to
         <function role="capi">mysql_library_init()</function> may be
         omitted, because <function role="capi">mysql_init()</function>

@@ -4389,29 +4407,27 @@
       </para>
 
       <para>
-        After your application is done using the MySQL library, call
-        <function role="capi">mysql_library_end()</function> to clean
-        up. See <xref linkend="mysql-library-end"/>.
-      </para>
-
-      <para>
         The <literal>argc</literal> and <literal>argv</literal>
         arguments are analogous to the arguments to
-        <literal>main()</literal>. The first element of
-        <literal>argv</literal> is ignored (it typically contains the
-        program name). For convenience, <literal>argc</literal> may be
-        <literal>0</literal> (zero) if there are no command-line
-        arguments for the server.
+        <literal>main()</literal>, and enable passing of options to the
+        embedded server. The first element of <literal>argv</literal> is
+        ignored (it typically contains the program name).
         <function role="capi">mysql_library_init()</function> makes a
         copy of the arguments so it is safe to destroy
         <literal>argv</literal> or <literal>groups</literal>
after the
-        call.
+        call. For convenience, <literal>argc</literal> may be
+        <literal>0</literal> (zero) if there are no command-line
+        arguments for the server. This is the usual case for
+        non-embedded applications intended for use only as regular
+        clients, and the call typically is written as
+        <function role="capi">mysql_library_init(0, NULL,
+        NULL)</function>.
       </para>
 
       <para>
-        If you want to connect to an external server without starting
-        the embedded server, you have to specify a negative value for
-        <literal>argc</literal>.
+        For embedded applications, if you want to connect to an external
+        server without starting the embedded server, you have to specify
+        a negative value for <literal>argc</literal>.
       </para>
 
       <para>

@@ -4425,11 +4441,6 @@
       </para>
 
       <para>
-        See <xref linkend="c-api-function-overview"/>, for additional
-        usage information.
-      </para>
-
-      <para>
         <emphasis role="bold">Example</emphasis>
       </para>