mysql c api

標籤：

這裡歸納了C API可使用的函數，並在下一節詳細介紹了它們。 函數 描述 mysql_affected_rows() 返 回上次UPDATE、DELETE或INSERT查詢更改／刪除／插入的行數。 mysql_autocommit() 切換 autocommit模式，ON/OFF mysql_change_user() 更改開啟串連上的使用者和資料庫。 mysql_charset_name() 返 回用於串連的預設字元集的名稱。 mysql_close() 關閉伺服器串連。 mysql_commit() 提 交事務。 mysql_connect() 串連到MySQL伺服器。該函數已不再被重視，使用 mysql_real_connect()取代。 mysql_create_db() 建立資料庫。該函數已不再被重視，使用 SQL語句CREATE DATABASE取而代之。 mysql_data_seek() 在查詢結果集中尋找屬性行編號。 mysql_debug() 用 給定的字串執行DBUG_PUSH。 mysql_drop_db() 撤銷資料庫。該函數已不再被重視，使用SQL語句DROP DATABASE取而代之。 mysql_dump_debug_info() 讓伺服器將調試資訊寫入日誌。 mysql_eof() 確 定是否讀取了結果集的最後一行。該函數已不再被重視，可以使用mysql_errno()或mysql_error()取而代之。 mysql_errno() 返 回上次調用的MySQL函數的錯誤編號。 mysql_error() 返回上次調用的MySQL函數的錯誤訊息。 mysql_escape_string() 為 了用在SQL語句中，對特殊字元進行轉義處理。 mysql_fetch_field() 返回下一個表欄位的類型。 mysql_fetch_field_direct() 給 定欄位編號，返回表欄位的類型。 mysql_fetch_fields() 返回所有欄位結構的數組。 mysql_fetch_lengths() 返 回當前行中所有列的長度。 mysql_fetch_row() 從結果集中擷取下一行 mysql_field_seek() 將 列游標置於指定的列。 mysql_field_count() 返回上次執行語句的結果列的數目。 mysql_field_tell() 返 回上次mysql_fetch_field()所使用欄位游標的位置。 mysql_free_result() 釋放結果集使用的 記憶體。 mysql_get_client_info() 以字串形式返回用戶端版本資訊。 mysql_get_client_version() 以 整數形式返回用戶端版本資訊。 mysql_get_host_info() 返回描述串連的字串。 mysql_get_server_version() 以 整數形式返回伺服器的版本號碼。 mysql_get_proto_info() 返回串連所使用的協議版本。 mysql_get_server_info() 返 回伺服器的版本號碼。 mysql_info() 返回關於最近所執行查詢的資訊。 mysql_init() 獲 取或初始化MYSQL結構。 mysql_insert_id() 返回上一個查詢為AUTO_INCREMENT列產生的ID。 mysql_kill() 殺 死給定的線程。 mysql_library_end() 最終確定MySQL C API庫。 mysql_library_init() 初 始化MySQL C API庫。 mysql_list_dbs() 返回與簡單Regex匹配的資料庫名稱。 mysql_list_fields() 返 回與簡單Regex匹配的欄位名稱。 mysql_list_processes() 返回當前伺服器線程的列表。 mysql_list_tables() 返 回與簡單Regex匹配的表名。 mysql_more_results() 檢查是否還存在其他結果。 mysql_next_result() 在 多語句執行過程中返回/初始化下一個結果。 mysql_num_fields() 返回結果集中的列數。 mysql_num_rows() 返 回結果集中的行數。 mysql_options() 為mysql_connect()設定串連選項。 mysql_ping() 檢 查與伺服器的串連是否工作，如有必要重新串連。 mysql_query() 執行指定為“以Null終結的字串”的SQL查詢。 mysql_real_connect() 連 接到MySQL伺服器。 mysql_real_escape_string() 考慮到串連的當前字元集，為了在SQL語句中使 用，對字串中的特殊字元進行轉義處理。 mysql_real_query() 執行指定為計數字串的SQL查詢。 mysql_refresh() 刷 新或複位表和高速緩衝。 mysql_reload() 通知伺服器再次載入授權表。 mysql_rollback() 回 滾事務。 mysql_row_seek() 使用從mysql_row_tell()返回的值，尋找結果集中的行位移。 mysql_row_tell() 返 回行游標位置。 mysql_select_db() 選擇資料庫。 mysql_server_end() 最 終確定嵌入式伺服器庫。 mysql_server_init() 初始化嵌入式伺服器庫。 mysql_set_server_option() 為 串連設定選項（如多語句）。 mysql_sqlstate() 返回關於上一個錯誤的SQLSTATE錯誤碼。 mysql_shutdown() 關 閉資料庫伺服器。 mysql_stat() 以字串形式返回伺服器狀態。 mysql_store_result() 檢 索完整的結果集至用戶端。 mysql_thread_id() 返回當前線程ID。 mysql_thread_safe() 如 果用戶端已編譯為安全執行緒的，返回1。 mysql_use_result() 初始化逐行的結果集檢索。 mysql_warning_count() 返 回上一個SQL語句的警示數。

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()函數訪問錯誤資訊的機制。它們能返回關於最近調用的函數的錯誤碼或錯 誤訊息，最近調用的函數可能成功也可能失敗，這樣，你就能判斷錯誤是在何時出現的，以及錯誤是什麼。

mysql c api