svn commit - mysqldoc@docsrva: r14548 - trunk/refman-common

[anthony.bedford]

Author: tbedford
Date: 2009-04-08 15:11:56 +0200 (Wed, 08 Apr 2009)
New Revision: 14548

Log:
Added info on getClientOption(), getSessionVariable(), setSessionVariable().

Modified:
   trunk/refman-common/connector-cpp.xml


Modified: trunk/refman-common/connector-cpp.xml
===================================================================
--- trunk/refman-common/connector-cpp.xml	2009-04-08 11:48:02 UTC (rev 14547)
+++ trunk/refman-common/connector-cpp.xml	2009-04-08 13:11:56 UTC (rev 14548)
Changed blocks: 1, Lines Added: 119, Lines Deleted: 0; 4586 bytes

@@ -2396,6 +2396,125 @@
         </itemizedlist>
       </listitem>
 
+      <listitem>
+        <para>
+          &ccpp; includes a method
+          <literal>Connection::getClientOption()</literal> which is not
+          included in the JDBC API specification. The prototype is:
+        </para>
+
+<programlisting>void getClientOption(const std::string &amp; optionName, void * optionValue)</programlisting>
+
+        <para>
+          The method can be used to check the value of connection
+          properties set when establishing a database connection. The
+          values are returned through the <literal>optionValue</literal>
+          argument passed to the method with the type <literal>void
+          *</literal>.
+        </para>
+
+        <para>
+          Currently, <literal>getClientOption()</literal> supports
+          fetching the <literal>optionValue</literal> of the following
+          options:
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <literal>metadataUseInfoSchema</literal>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>defaultStatementResultType</literal>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>defaultPreparedStatementResultType</literal>
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          The connection option <literal>metadataUseInfoSchema</literal>
+          controls whether to use the
+          <literal>Information_Schemata</literal> for returning the meta
+          data of <literal>SHOW</literal> commands. In the case of
+          <literal>metadataUseInfoSchema</literal> the
+          <literal>optionValue</literal> argument should be interpreted
+          as a boolean upon return.
+        </para>
+
+        <para>
+          In the case of both
+          <literal>defaultStatementResultType</literal> and
+          <literal>defaultPreparedStatementResultType</literal>, the
+          <literal>optionValue</literal> argument should be interpreted
+          as an integer upon return.
+        </para>
+
+        <para>
+          The connection property can be either set when establishing
+          the connection through the connection property map or using
+          <literal>void Connection::setClientOption(const std::string
+          &amp; optionName, const void * optionValue)</literal> where
+          <literal>optionName</literal> is assigned the value
+          <literal>metadataUseInfoSchema</literal>.
+        </para>
+
+        <para>
+          Some examples are given below:
+        </para>
+
+<programlisting>int defaultStmtResType;
+int defaultPStmtResType;
+conn-&gt;getClientOption("defaultStatementResultType", (void *) &amp;defaultStmtResType);
+conn-&gt;getClientOption("defaultPreparedStatementResultType", (void *) &amp;defaultPStmtResType);
+
+bool isInfoSchemaUsed;
+conn-&gt;getClientOption("metadataUseInfoSchema", (void *) &amp;isInfoSchemaUsed);</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          &ccpp; also supports the following methods not found in the
+          JDBC API standard:
+        </para>
+
+<programlisting>std::string MySQL_Connection::getSessionVariable(const std::string &amp; varname)</programlisting>
+
+<programlisting>void MySQL_Connection::setSessionVariable(const std::string &amp; varname, const std::string &amp; value)</programlisting>
+
+        <para>
+          Note that both methods are members of the
+          <literal>MySQL_Connection</literal> class. The methods get and
+          set MySQL session variables.
+        </para>
+
+        <para>
+          <literal>setSessionVariable()</literal> is equivalent to
+          executing:
+        </para>
+
+<programlisting>SET SESSION &lt;varname&gt; = &lt;value&gt;</programlisting>
+
+        <para>
+          <literal>getSessionVariable()</literal> is equivalent to
+          executing the following and fetching the first return value:
+        </para>
+
+<programlisting>SHOW SESSION VARIABLES LIKE "&lt;varname&gt;"</programlisting>
+
+        <para>
+          You can use <quote>%</quote> and other placeholders in
+          &lt;varname&gt;, if the underlying MySQL server supports this.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
   </section>