<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 322165 $ -->

<refentry xml:id="function.mysqlnd-ms-dump-servers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mysqlnd_ms_dump_servers</refname>
  <refpurpose>Returns a list of currently configured servers</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type>
   <methodname>mysqlnd_ms_dump_servers</methodname>
   <methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
  </methodsynopsis>
  <para>
    Returns a list of currently configured servers.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>connection</parameter></term>
    <listitem>
     <para>
      A MySQL connection handle obtained from any of the
      connect functions of the <link linkend="ref.mysqli">mysqli</link>,
      <link linkend="ref.mysql">mysql</link> or
      <link linkend="ref.pdo-mysql">PDO_MYSQL</link> extensions.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &false; on error. Otherwise, returns an array with two entries
   <literal>masters</literal> and <literal>slaves</literal> each of which contains
   an array listing all corresponding servers.
  </para>
  <para>
   The function can be used to check and debug the list of servers currently
   used by the plugin. It is mostly useful when the list of servers changes at
   runtime, for example, when using MySQL Fabric.
  </para>
  <para>
   <literal>masters</literal> and <literal>slaves</literal> server entries
  </para>
  <informaltable>
   <tgroup cols="3">
    <colspec colwidth="1*"/>
    <colspec colwidth="7*"/>
    <colspec colwidth="2*"/>
    <thead>
     <row>
      <entry>Key</entry>
      <entry>Description</entry>
      <entry>Version</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <literal>name_from_config</literal>
      </entry>
      <entry>
       <para>
         Server entry name from config, if appliciable. NULL if no
         configuration name is available.
       </para>
      </entry>
      <entry>Since 1.6.0.</entry>
     </row>
     <row>
      <entry>
       <literal>hostname</literal>
      </entry>
      <entry>
       <para>
         Host name of the server.
       </para>
      </entry>
      <entry>Since 1.6.0.</entry>
     </row>
     <row>
      <entry>
       <literal>user</literal>
      </entry>
      <entry>
       <para>
         Database user used to authenticate against the server.
       </para>
      </entry>
      <entry>Since 1.6.0.</entry>
     </row>
     <row>
      <entry>
       <literal>port</literal>
      </entry>
      <entry>
       <para>
         TCP/IP port of the server.
       </para>
      </entry>
      <entry>Since 1.6.0.</entry>
     </row>
       <row>
      <entry>
       <literal>socket</literal>
      </entry>
      <entry>
       <para>
         Unix domain socket of the server.
       </para>
      </entry>
      <entry>Since 1.6.0.</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1>
  &reftitle.notes;
  <note>
   <para>
    <function>mysqlnd_ms_dump_servers</function> requires
    PECL mysqlnd_ms &gt;> 1.6.0.
   </para>
  </note>
 </refsect1>

  <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>mysqlnd_ms_dump_servers</function> example</title>
     <programlisting role="ini">
<![CDATA[
{
    "myapp": {
        "master": {
            "master1": {
                "host":"master1_host",
                "port":"master1_port",
                "socket":"master1_socket",
                "db":"master1_db",
                "user":"master1_user",
                "password":"master1_pw"
            }
        },
        "slave": {
             "slave_0": {
                 "host":"slave0_host",
                 "port":"slave0_port",
                 "socket":"slave0_socket",
                 "db":"slave0_db",
                 "user":"slave0_user",
                 "password":"slave0_pw"
             },
             "slave_1": {
                 "host":"slave1_host"
             }
        }
    }
}
]]>
    </programlisting>
 <programlisting role="php">
<![CDATA[
<?php
$link = mysqli_connect("myapp", "global_user", "global_pass", "global_db", 1234, "global_socket");
var_dump(mysqlnd_ms_dump_servers($link);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  ["masters"]=>
  array(1) {
    [0]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "master1"
      ["hostname"]=>
      string(12) "master1_host"
      ["user"]=>
      string(12) "master1_user"
      ["port"]=>
      int(3306)
      ["socket"]=>
      string(14) "master1_socket"
    }
  }
  ["slaves"]=>
  array(2) {
    [0]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "slave_0"
      ["hostname"]=>
      string(11) "slave0_host"
      ["user"]=>
      string(11) "slave0_user"
      ["port"]=>
      int(3306)
      ["socket"]=>
      string(13) "slave0_socket"
    }
    [1]=>
    array(5) {
      ["name_from_config"]=>
      string(7) "slave_1"
      ["hostname"]=>
      string(11) "slave1_host"
      ["user"]=>
      string(12) "gloabal_user"
      ["port"]=>
      int(1234)
      ["socket"]=>
      string(13) "global_socket"
    }
  }
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->