manual_clients.html

详细介绍了MYSQL的主要功能几一些代码

    <td><strong>mysql_dump_debug_info()</strong></td>
    <td>让服务器将调试信息写入日志文件。 </td>
  </tr>
  <tr>
    <td><strong>mysql_eof()</strong></td>
    <td>确定是否已经读到一个结果集合的最后一行。这功能被反对; <code>mysql_errno()</code>或<code>mysql_error()</code>可以相反被使用。 
    </td>
  </tr>
  <tr>
    <td><strong>mysql_errno()</strong></td>
    <td>返回最近被调用的<strong>MySQL</strong>函数的出错编号。 </td>
  </tr>
  <tr>
    <td><strong>mysql_error()</strong></td>
    <td>返回最近被调用的<strong>MySQL</strong>函数的出错消息。</td>
  </tr>
  <tr>
    <td><strong>mysql_escape_string()</strong> </td>
    <td>用在SQL语句中的字符串的转义特殊字符。 </td>
  </tr>
  <tr>
    <td><strong>mysql_fetch_field()</strong></td>
    <td>返回下一个表字段的类型。 </td>
  </tr>
  <tr>
    <td><strong>mysql_fetch_field_direct ()</strong></td>
    <td>返回一个表字段的类型，给出一个字段编号。</td>
  </tr>
  <tr>
    <td><strong>mysql_fetch_fields()</strong></td>
    <td>返回一个所有字段结构的数组。 </td>
  </tr>
  <tr>
    <td><strong>mysql_fetch_lengths()</strong></td>
    <td>返回当前行中所有列的长度。 </td>
  </tr>
  <tr>
    <td><strong>mysql_fetch_row()</strong></td>
    <td>从结果集合中取得下一行。 </td>
  </tr>
  <tr>
    <td><strong>mysql_field_seek()</strong></td>
    <td>把列光标放在一个指定的列上。 </td>
  </tr>
  <tr>
    <td><strong>mysql_field_count()</strong></td>
    <td>返回最近查询的结果列的数量。 </td>
  </tr>
  <tr>
    <td><strong>mysql_field_tell()</strong></td>
    <td>返回用于最后一个<code>mysql_fetch_field()</code>的字段光标的位置。 </td>
  </tr>
  <tr>
    <td><strong>mysql_free_result()</strong></td>
    <td>释放一个结果集合使用的内存。 </td>
  </tr>
  <tr>
    <td><strong>mysql_get_client_info()</strong></td>
    <td>返回客户版本信息。 </td>
  </tr>
  <tr>
    <td><strong>mysql_get_host_info()</strong> </td>
    <td>返回一个描述连接的字符串。 </td>
  </tr>
  <tr>
    <td><strong>mysql_get_proto_info()</strong></td>
    <td>返回连接使用的协议版本。 </td>
  </tr>
  <tr>
    <td><strong>mysql_get_server_info()</strong></td>
    <td>返回服务器版本号。 </td>
  </tr>
  <tr>
    <td><strong>mysql_info()</strong> </td>
    <td>返回关于最近执行得查询的信息。 </td>
  </tr>
  <tr>
    <td><strong>mysql_init()</strong></td>
    <td>获得或初始化一个<code>MYSQL</code>结构。 </td>
  </tr>
  <tr>
    <td><strong>mysql_insert_id()</strong></td>
    <td>返回有前一个查询为一个<code>AUTO_INCREMENT</code>列生成的ID。 </td>
  </tr>
  <tr>
    <td><strong>mysql_kill()</strong></td>
    <td>杀死一个给定的线程。 </td>
  </tr>
  <tr>
    <td><strong>mysql_list_dbs()</strong></td>
    <td>返回匹配一个简单的正则表达式的数据库名。 </td>
  </tr>
  <tr>
    <td><strong>mysql_list_fields()</strong></td>
    <td>返回匹配一个简单的正则表达式的列名。 </td>
  </tr>
  <tr>
    <td><strong>mysql_list_processes()</strong></td>
    <td>返回当前服务器线程的一张表。 </td>
  </tr>
  <tr>
    <td><strong>mysql_list_tables()</strong></td>
    <td>返回匹配一个简单的正则表达式的表名。 </td>
  </tr>
  <tr>
    <td><strong>mysql_num_fields()</strong></td>
    <td>返回一个结果集合重的列的数量。 </td>
  </tr>
  <tr>
    <td><strong>mysql_num_rows()</strong></td>
    <td>返回一个结果集合中的行的数量。 </td>
  </tr>
  <tr>
    <td><strong>mysql_options()</strong></td>
    <td>设置对<code>mysql_connect()</code>的连接选项。 </td>
  </tr>
  <tr>
    <td><strong>mysql_ping()</strong></td>
    <td>检查对服务器的连接是否正在工作，必要时重新连接。 </td>
  </tr>
  <tr>
    <td><strong>mysql_query()</strong></td>
    <td>执行指定为一个空结尾的字符串的SQL查询。 </td>
  </tr>
  <tr>
    <td><strong>mysql_real_connect()</strong></td>
    <td>连接一个<strong>MySQL</strong>服务器。 </td>
  </tr>
  <tr>
    <td><strong>mysql_real_query()</strong></td>
    <td>执行指定为带计数的字符串的SQL查询。 </td>
  </tr>
  <tr>
    <td><strong>mysql_reload()</strong></td>
    <td>告诉服务器重装授权表。 </td>
  </tr>
  <tr>
    <td><strong>mysql_row_seek()</strong></td>
    <td>搜索在结果集合中的行，使用从<code>mysql_row_tell()</code>返回的值。 
    </td>
  </tr>
  <tr>
    <td><strong>mysql_row_tell()</strong></td>
    <td>返回行光标位置。 </td>
  </tr>
  <tr>
    <td><strong>mysql_select_db()</strong></td>
    <td>连接一个数据库。 </td>
  </tr>
  <tr>
    <td><strong>mysql_shutdown()</strong></td>
    <td>关掉数据库服务器。 </td>
  </tr>
  <tr>
    <td><strong>mysql_stat()</strong></td>
    <td>返回作为字符串的服务器状态。 </td>
  </tr>
  <tr>
    <td><strong>mysql_store_result()</strong></td>
    <td>检索一个完整的结果集合给客户。 </td>
  </tr>
  <tr>
    <td><strong>mysql_thread_id()</strong></td>
    <td>返回当前线程的ID。 </td>
  </tr>
  <tr>
    <td><strong>mysql_use_result()</strong></td>
    <td>初始化一个一行一行地结果集合的检索。 </td>
  </tr>
</table>

<p>为了连接服务器，调用<code>mysql_init()</code>以初始化一个连接处理器，然后用该处理器调用<code>mysql_real_connect()</code>(还有其他信息例如主机名、用户名和口令)。当你用该连接完成工作后，调用<code>mysql_close()</code>终止它。</p>

<p>当一个连接活跃时，客户可以用<code>mysql_query()</code>或<code>mysql_real_query()</code>将SQL查询发送到服务器。两者的差别是<code>mysql_query()</code>期望查询作为一个空结尾的字符串来指定而<code>mysql_real_query()</code>期望一个计数的字符串。如果字符串包含二进制数据(它可以包括空字节)，你必须使用<code>mysql_real_query()</code>。</p>

<p>对与每个非--<code>SELECT</code>查询(例如，<code>INSERT</code>、<code>UPDATE</code>、<code>DELETE</code>等)，你可以调用<code>mysql_affected_rows()</code>知道有多少行受到影响(改变)。</p>

<p>对于<code>SELECT</code>查询，你作为一个结果集合来检索选择的行。（注意一些语句是类<code>SELECT</code>的，他们返回行。这些包括<code>SHOW</code>、<code>DESCRIBE</code>和<code>EXPLAIN</code>。他们应该象<code>SELECT</code>语句相同的方式来对待。）</p>

<p>对客户，有两种方法处理结果集合。一种方法是通过调用<code>mysql_store_result()</code>立刻检索全部结果。该函数从服务器获得查询返回的所有行，并将他们存储在客户端。第二种方法是对客户通过调用<code>mysql_use_result()</code>初始化一个一行一行地结果集合的检索。该函数初始化检索，但是实际上不从服务器获得任何行。</p>

<p>在两种情况中，你通过<code>mysql_fetch_row()</code>存取行。用<code>mysql_store_result()</code>、<code>mysql_fetch_row()</code>储存取已经从服务器被取出的行。用<code>mysql_use_result()</code>、<code>mysql_fetch_row()</code>实际上从服务器检索行。调用<code>mysql_fetch_lengths()</code>可获得关于每行中数据值尺寸的信息。</p>

<p>在你用完一个结果集合以后，调用<code>mysql_free_result()</code>释放由它使用的内存。</p>

<p>两种检索机制是互补的。客户程序应该选择最适合他们的要求的途径。在实践中，客户通常更愿意使用<code>mysql_store_result()</code>。</p>

<p><code>mysql_store_result()</code>的一个优点是既然行均被客户取到，你不仅能顺序存取行，你也能<code>mysql_data_seek()</code>或<code>mysql_row_seek()</code>在结果集合中前后移动以改变在结果集合中的当前行位置。你也能通过调用<code>mysql_num_rows()</code>知道有多少行。另一方面，<code>mysql_store_result()</code>的内存需求对较大结果集合可能很高，并且你最可能遇到out-of-memory情况。</p>

<p><code>mysql_use_result()</code>的一个优点是客户为结果集合需要较少的内存，因为它一次只是维持一行(并且因为有较少的分配开销，<code>mysql_use_result()</code>能更快些)。缺点是你必须尽快处理每一行以避免困住服务器，你不必再结果集合中随意存取行(你只能顺序存取行)，而且你不知道在结果集合中有多少行，直到你检索全部结果。还有，你<em>必须</em>检索出所有行，即使你在检索中途确定你已找到了想寻找的信息。 
</p>

<p>API使得客户正确应答查询成为可能(仅检索必要的行)，不用知道查询是否是一个<code>SELECT</code>。你可以通过在<code>mysql_query()</code>（或<code>mysql_real_query()</code>)之后调用<code>mysql_store_result()</code>做到。如果结果集合调用成功并且查询是一个<code>SELECT</code>，你能读取行。如果结果集合调用，调用<code>mysql_field_count()</code>确定结果是否是实际期望的。如果<code>mysql_field_count()</code>返回0，查询没有返回数据(表明它是一个<code>INSERT</code>、<code>UPDATE</code>、DELETE等)，所以不期望返回行。如果<code>mysql_field_count()</code>是非零，查询应该有返回行，但是没有。这表明查询是一个失败的<code>SELECT</code>。见<code>mysql_field_count()</code>如何能做到的例子的描述。</p>

<p><code>mysql_store_result()</code>和<code>mysql_use_result()</code>都允许你获得有关组成结果集合的字段的信息(字段数量、他们的名字和类型等等)。你可以通过重复调用<code>mysql_fetch_field()</code>在行中顺序存取字段信息，或调用<code>mysql_fetch_field_direct()</code>存取行中的字段编号。当前字段光标位置可以通过调用<code>mysql_field_seek()</code>改变，设置字段光标影响到后续<code>mysql_fetch_field()</code>调用。你也能通过调用<code>mysql_fetch_fields()</code>马上获得字段信息。</p>

<p>对于检测和报告错误，<strong>MySQL</strong>借助于<code>mysql_errno()</code>和<code>mysql_error()</code>函数提供错误信息的存取。他们返回最近调用的可能成功或失败的函数的错误代码或错误消息，允许你确定何时发生一个错误和什么错误。 
</p>

<h2><a NAME="C_API_functions" HREF="manual_toc.html#C_API_functions">20.4 C API函数描述</a></h2>

<p>在下面的描述中，一个<code>NULL</code>参数或返回值含义是在C编程语言环境的<code>NULL</code>，不是一个<strong>MySQL</strong> 
<code>NULL</code>值。</p>

<p>返回一个值的函数一般返回一个指针或一个整数。除非另外指定，返回一个指针的函数返回一个非 
<code>NULL</code>值表明成功，或一个<code>NULL</code>值表明一个错误，而返回一个整数的函数返回零表示成功，或非零表示一个错误。注意，“非零”只有这个含义。除非函数描述另外说明，不要测试一个零以外的其他值：</p>

<pre>if (result)                   /* 正确 */
    ... error ...

if (result &lt; 0)               /* 不正确 */
    ... error ...

if (result == -1)             /* 不正确 */
    ... error ...

</pre>

<p>当函数返回一个错误时，函数描述的<strong>错误</strong>小节列出错误可能的类型。你可以调用<code>mysql_errno()</code>找出发生了这些重的哪一个。错误的字符串表示可以调用<code>mysql_error()</code>获得。</p>

<h3><a NAME="mysql_affected_rows" HREF="manual_toc.html#mysql_affected_rows">20.4.1<code> 
mysql_affected_rows()</code></a></h3>

<p><code>my_ulonglong mysql_affected_rows(MYSQL *mysql)</code> </p>

<h4>20.4.1.1 说明</h4>

<p>返回受到最后一个<code>UPDATE</code>、<code>DELETE</code>或<code>INSERT</code>查询影响(变化)的行数。可以在针对<code>UPDATE</code>、<code>DELETE</code>或<code>INSERT</code>语句的<code>mysql_query()</code>之后立即调用。对于<code>SELECT</code>语句，<code>mysql_affected_rows()</code>的功能于<code>mysql_num_rows()</code>相同。</p>

<p><code>mysql_affected_rows()</code>目前以一个宏(macro)来实现。</p>

<h4>20.4.1.2 返回值</h4>

<p>大于零的一个整数表示受到影响或检索出来的行数。零表示没有匹配查序中<code>WHERE</code>子句的记录或目前还没有查询被执行。-1表示查询返回一个错误，或对于一个<code>SELECT</code>查询，<code>mysql_affected_rows()</code>在调用<code>mysql_store_result()</code>之前被调用。</p>

<h4>20.4.1.3 错误</h4>

<p>没有。 </p>

<h4>20.4.1.4 范例</h4>

<pre>mysql_query(&amp;mysql,&quot;UPDATE products SET cost=cost*1.25 WHERE group=10&quot;);
printf(&quot;%d products updated&quot;,mysql_affected_rows(&amp;mysql));
<a NAME="IDX724"></a> </pre>

<h3><a NAME="mysql_close" HREF="manual_toc.html#mysql_close">20.4.2<code> mysql_close()</code></a></h3>

<p><code>void mysql_close(MYSQL *mysql)</code> </p>

<h4>20.4.2.1 说明</h4>

<p>关闭一个以前打开了的连接。如果句柄由<code>mysql_init()</code>或<code>mysql_connect()</code>自动分配，<code>mysql_close()</code>也释放被<code>mysql</code>指向的连接句柄。</p>

<h4>20.4.2.2 返回值</h4>

<p>没有。 </p>

<h4>20.4.2.3 错误</h4>

<dl COMPACT="mysql_close">
  <dt><code>CR_COMMANDS_OUT_OF_SYNC</code> </dt>
  <dd>命令以一个不正确的次序被执行。 </dd>
  <dt><code>CR_SERVER_GONE_ERROR</code> </dt>
  <dd><strong>MySQL</strong>服务器关闭了。</dd>
  <dt><code>CR_SERVER_LOST</code> </dt>
  <dd>对服务者的连接在查询期间失去。</dd>
  <dt><code>CR_UNKNOWN_ERROR</code> </dt>
  <dd>发生一个未知的错误。 </dd>
</dl>

<p><a NAME="IDX725"></a> </p>

<h3><a NAME="mysql_connect" HREF="manual_toc.html#mysql_connect">20.4.3<code> 
mysql_connect()</code></a></h3>

<p><code>MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char 
*passwd)</code> </p>

<h4>20.4.3.1 说明</h4>

<p>该函数不推荐使用，而更好使用<code>mysql_real_connect()</code>。 </p>

<p><code>mysql_connect()</code>试图建立一个对运行在<code>host</code>的一个<strong>MySQL</strong>数据库引擎的连接。<code>mysql_connect()</code>必须在你能执行其他API函数之前成功地完成，除了<code>mysql_get_client_info()</code>。</p>

<p>参数的含义与<code>mysql_connect()</code>相应的参数相同，不同的是连接参数可以是<code>NULL</code>。在这种情况下，C 
API 自动为连接结构分配内存，并且当你调用<code>mysql_close()</code>，释放它。这种方法的缺点是如果连接失败，你不能检索出一条错误消息。（为了从<code>mysql_errno()</code>或<code>mysql_error()</code>得到错误信息，你必须提供一个有效的<code>MYSQL</code>指针。）</p>

<h4>20.4.3.2 返回值</h4>

<p>同<code>mysql_real_connect()</code>。 </p>

<h4>20.4.3.3 错误</h4>

<p>同<code>mysql_real_connect()</code>。</p>

<p><a NAME="IDX726"></a> </p>

<h3><a NAME="mysql_change_user" HREF="manual_toc.html#mysql_change_user">20.4.4<code>mysql_change_user()</code></a></h3>

<p><code>my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password,