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

<refentry xml:id="function.mysqlnd-ms-get-last-used-connection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mysqlnd_ms_get_last_used_connection</refname>
  <refpurpose>Returns an array which describes the last used connection</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type>
   <methodname>mysqlnd_ms_get_last_used_connection</methodname>
   <methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
  </methodsynopsis>
  <para>
   Returns an array which describes the last used connection from the plugins
   connection pool currently pointed to by the user connection handle. If using the
   plugin, a user connection handle represents a pool of database connections.
   It is not possible to tell from the user connection handles properties to which
   database server from the pool the user connection handle points.
  </para>
  <para>
   The function can be used to debug or monitor PECL mysqlnd_ms.
  </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, an
   array which describes the connection used to
   execute the last statement on.
  </para>
  <para>
   Array which describes the connection.
  </para>
  <informaltable>
   <tgroup cols="3">
    <colspec colwidth="1*"/>
    <colspec colwidth="7*"/>
    <colspec colwidth="2*"/>
    <thead>
     <row>
      <entry>Property</entry>
      <entry>Description</entry>
      <entry>Version</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <literal>scheme</literal>
      </entry>
      <entry>
       Connection scheme. Either <literal>tcp://host:port</literal>
       or <literal>unix://host:socket</literal>. If you want to
       distinguish connections from each other use a combination
       of <literal>scheme</literal> and <literal>thread_id</literal> as a unique
       key. Neither <literal>scheme</literal> nor <literal>thread_id</literal>
       alone are sufficient to distinguish two connections from each other.
       Two servers may assign the same <literal>thread_id</literal> to two
       different connections. Thus, connections in the pool may have the same
       <literal>thread_id</literal>. Also, do not rely on uniqueness of
       <literal>scheme</literal> in a pool. Your QA engineers may use the
       same MySQL server instance for two distinct logical roles and add it
       multiple times to the pool. This hack is used, for example,
       in the test suite.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>host</literal>
      </entry>
      <entry>
       Database server host used with the connection.
       The host is only set with TCP/IP connections.
       It is empty with Unix domain or Windows named pipe connections,
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>host_info</literal>
      </entry>
      <entry>
        A character string representing the server hostname and the connection type.
      </entry>
      <entry>Since 1.1.2.</entry>
     </row>
     <row>
      <entry>
       <literal>port</literal>
      </entry>
      <entry>
       Database server port used with the connection.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>socket_or_pipe</literal>
      </entry>
      <entry>
       Unix domain socket or Windows named pipe used with the connection.
       The value is empty for TCP/IP connections.
      </entry>
      <entry>Since 1.1.2.</entry>
     </row>
     <row>
      <entry>
       <literal>thread_id</literal>
      </entry>
      <entry>
       Connection thread id.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>last_message</literal>
      </entry>
      <entry>
       Info message obtained from the
       MySQL C API function mysql_info(). Please, see
       <function>mysqli_info</function> for
       a description.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>errno</literal>
      </entry>
      <entry>
       Error code.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>error</literal>
      </entry>
      <entry>
       Error message.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
     <row>
      <entry>
       <literal>sqlstate</literal>
      </entry>
      <entry>
       Error SQLstate code.
      </entry>
      <entry>Since 1.1.0.</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1>
  &reftitle.notes;
  <note>
   <para>
    <function>mysqlnd_ms_get_last_used_connection</function> requires
    PHP &gt;= 5.4.0 and PECL mysqlnd_ms &gt;> 1.1.0. Internally, it is using
    a <literal>mysqlnd</literal> library C call not available with PHP 5.3.
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
  The example assumes that <literal>myapp</literal> refers to a
  plugin configuration file section and represents a connection pool.
  </para>
  <para>
   <example>
    <title><function>mysqlnd_ms_get_last_used_connection</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$link = new mysqli("myapp", "user", "password", "database");
$res = $link->query("SELECT 1 FROM DUAL");
var_dump(mysqlnd_ms_get_last_used_connection($link));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(10) {
  ["scheme"]=>
  string(22) "unix:///tmp/mysql.sock"
  ["host_info"]=>
  string(25) "Localhost via UNIX socket"
  ["host"]=>
  string(0) ""
  ["port"]=>
  int(3306)
  ["socket_or_pipe"]=>
  string(15) "/tmp/mysql.sock"
  ["thread_id"]=>
  int(46253)
  ["last_message"]=>
  string(0) ""
  ["errno"]=>
  int(0)
  ["error"]=>
  string(0) ""
  ["sqlstate"]=>
  string(5) "00000"
}
]]>
    </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
-->