C API函式概述

與MySQL互動時，應用程式應使用該一般性原則：

  1.通過呼叫mysql_library_init()，初始化MySQL庫。庫可以是mysqlclient C客戶端庫，或mysqld嵌入式伺服器庫，具體情況取決於應用程式是否與“-libmysqlclient”或“-libmysqld”標誌連結。

  2.通過呼叫mysql_init()初始化連線處理程式，並通過呼叫mysql_real_connect()連線到伺服器。

  3.發出SQL語句並處理其結果。（在下面的討論中，詳細介紹了使用它的方法）。

  4.通過呼叫mysql_close()，關閉與MySQL伺服器的連線。

  5.通過呼叫mysql_library_end()，結束MySQL庫的使用。

  呼叫mysql_library_init()和mysql_library_end()的目的在於，為MySQL庫提供恰當的初始化和結束處理。對於與客戶端庫連結的應用程式，它們提供了改進的記憶體管理功能。如果不呼叫mysql_library_end()，記憶體塊仍將保持分配狀態（這不會增加應用程式使用的記憶體量，但某些記憶體洩漏檢測器將抗議它）。對於與嵌入式伺服器連結的應用程式，這些呼叫會啟動並停止伺服器。

mysql_library_init()和mysql_library_end()實際上是#define符號，這類符號使得它們等效於mysql_server_init()和mysql_server_end()，但其名稱更清楚地指明，無論應用程式使用的是mysqlclient或mysqld庫，啟動或結束MySQL庫時，應呼叫它們。對於早期的MySQL版本，可呼叫mysql_server_init()和mysql_server_end()取而代之。

  如果願意，可省略對mysql_library_init()的呼叫，這是因為，必要時，mysql_init()會自動呼叫它。

  要想連線到伺服器，可呼叫mysql_init()來初始化連線處理程式，然後用該處理程式（以及其他資訊，如主機名、使用者名稱和密碼）呼叫mysql_real_connect()。建立連線後，在低於5.0.3版的API中，mysql_real_connect()會將再連線標誌（MYSQL結構的一部分）設定為1，或在較新的版本中，將其設定為0。對於該標誌，值“1”指明，如果因連線丟失而無法執行語句，放棄之前，會嘗試再次連線到伺服器。從MySQL 5.0.13開始，可以在mysql_options()上使用MYSQL_OPT_RECONNECT選項，以控制再連線行為。完成連線後，呼叫mysql_close()中止它。

  當連線處於活動狀態時，客戶端或許會使用mysql_query()或mysql_real_query()向伺服器發出SQL查詢。兩者的差別在於，mysql_query()預期的查詢為指定的、由Null終結的字串，而mysql_real_query()預期的是計數字符串。如果字串包含二進位制資料（其中可能包含Null位元組），就必須使用mysql_real_query()。

對於每個非SELECT查詢（例如INSERT、UPDATE、DELETE），通過呼叫mysql_affected_rows()，可發現有多少行已被改變（影響）。

  對於SELECT查詢，能夠檢索作為結果集的行。注意，某些語句因其返回行，類似與SELECT。包括SHOW、DESCRIBE和EXPLAIN。應按照對待SELECT語句的方式處理它們。

  客戶端處理結果集的方式有兩種。一種方式是，通過呼叫mysql_store_result()，一次性地檢索整個結果集。該函式能從伺服器獲得查詢返回的所有行，並將它們儲存在客戶端。第二種方式是針對客戶端的，通過呼叫mysql_use_result()，對“按行”結果集檢索進行初始化處理。該函式能初始化檢索結果，但不能從伺服器獲得任何實際行。

  在這兩種情況下，均能通過呼叫mysql_fetch_row()訪問行。通過mysql_store_result()，mysql_fetch_row()能夠訪問以前從伺服器獲得的行。通過mysql_use_result()，mysql_fetch_row()能夠實際地檢索來自伺服器的行。通過呼叫mysql_fetch_lengths()，能獲得關於各行中資料大小的資訊。

 完成結果集操作後，請呼叫mysql_free_result()釋放結果集使用的記憶體。

 這兩種檢索機制是互補的。客戶端程式應選擇最能滿足其要求的方法。實際上，客戶端最常使用的是mysql_store_result()。

  mysql_store_result()的1個優點在於，由於將行全部提取到了客戶端上，你不僅能連續訪問行，還能使用mysql_data_seek()或mysql_row_seek()在結果集中向前或向後移動，以更改結果集內當前行的位置。通過呼叫mysql_num_rows()，還能發現有多少行。另一方面，對於大的結果集，mysql_store_result()所需的記憶體可能會很大，你很可能遇到記憶體溢位狀況。

  mysql_use_result()的1個優點在於，客戶端所需的用於結果集的記憶體較少，原因在於，一次它僅維護一行（由於分配開銷較低，mysql_use_result()能更快）。它的缺點在於，你必須快速處理每一行以避免妨礙伺服器，你不能隨機訪問結果集中的行（只能連續訪問行），你不知道結果集中有多少行，直至全部檢索了它們為止。不僅如此，即使在檢索過程中你判定已找到所尋找的資訊，也必須檢索所有的行。

  通過API，客戶端能夠恰當地對查詢作出響應（僅在必要時檢索行），而無需知道查詢是否是SELECT查詢。可以在每次mysql_query()或mysql_real_query()後，通過呼叫mysql_store_result()完成該操作。如果結果集呼叫成功，查詢為SELECT，而且能夠讀取行。如果結果集呼叫失敗，可呼叫mysql_field_count()來判斷結果是否的確是所預期的。如果mysql_field_count()返回0，查詢不返回資料（表明它是INSERT、UPDATE、DELETE等），而且不返回行。如果mysql_field_count()是非0值，查詢應返回行，但沒有返回行。這表明查詢是失敗了的SELECT。關於如何實現該操作的示例，請參見關於mysql_field_count()的介紹。

  無論是mysql_store_result()還是mysql_use_result()，均允許你獲取關於構成結果集的欄位的資訊（欄位數目，它們的名稱和型別等）。通過重複呼叫mysql_fetch_field()，可以按順序訪問行內的欄位資訊，或者，通過呼叫mysql_fetch_field_direct()，能夠在行內按欄位編號訪問欄位資訊。通過呼叫mysql_field_seek()，可以改變當前欄位的游標位置。對欄位游標的設定將影響後續的mysql_fetch_field()呼叫。此外，你也能通過呼叫mysql_fetch_fields()，一次性地獲得關於欄位的所有資訊。

  為了檢測和通報錯誤，MySQL提供了使用mysql_errno()和mysql_error()函式訪問錯誤資訊的機制。它們能返回關於最近呼叫的函式的錯誤程式碼或錯誤訊息，最近呼叫的函式可能成功也可能失敗，這樣，你就能判斷錯誤是在何時出現的，以及錯誤是什麼。