20 MySQL客戶工具和API
20.1 MySQL C API
C API代碼是隨MySQL分發的，它被包含在MySQLclIEnt庫且允許C程序存取一個數據庫。
在 MySQL源代碼分發中的很多客戶是用C編寫的。如果你正在尋找演示怎樣使用C API的例子，看一下這些客戶程序。
大多數其他客戶 API(除了Java的所有)都使用mysqlclIEnt庫與MySQL服務器通信。這意味著，例如，你能利用很多被其他客戶程序使用的同一環境變量，因為他們從庫中引用。對這些變量的一張表，見12.1 不同的MySQL程序的概述。
客戶有一個最大通訊緩沖區大小。初始分配的緩沖區大小(16K字節) 自動地增加到最大尺寸(缺省的最大值是24M)。因為緩沖區大小只是按保證需求而被增加，簡單地增加缺省的最大限制並不造成更多被消耗。該尺寸檢查主要是一個對錯誤的查詢和通訊包的檢查。
通訊緩沖區必須足夠大以便一個單獨的SQL語句(對客戶-服務器傳輸)和一行返回的數據(對服務器-客戶傳輸)。每個線程的通訊緩沖區被動態擴大到最大限制來處理任何查詢或行。例如，如果你包含大到16M數據的BLOB值，你必須有一個至少16M通訊緩沖區限制(在服務器和客戶兩端)。客戶的缺省最大值是24M，但是在服務器端的缺省最大值是1M。你可以在服務器啟動時通過改變max_allowed_packet參數的值來改變它。見10.2.3 調節服務器參數。
MySQL服務器在每個查詢後縮小每個通訊緩沖區到net_buffer_length個字節。對客戶，與一個連接相關的緩沖區的大小沒被減少，直到連接被關閉，在此時客戶內存被回收。
如果你用線程的編程，你應該用--with-thread-safe-clIEnt編譯MySQL C API，這將使C API線程對每個連接更安全。你可以讓2個線程共享相同的連接，只要如果你做下列事情：
兩個線程不能同時在同一個連接上發送查詢到MySQL。特別是你必須保證在一個mysql_query()和MySQL_store_result()之間沒有其他線程正在使用同一個連接。
許多線程能存取用MySQL_store_result()檢索出來的不同結果集合。
如果你使用MySQL_use_result，你必須保證沒有其他線程在同一個連接上正在詢問任何東西，直到結果集合被關閉。
20.2 C API數據類型
MySQL
這個結構表示對一個數據庫連接的句柄，它被用於幾乎所有的MySQL函數。
MySQL_RES
這個結構代表返回行的一個查詢的(SELECT, SHOW, DESCRIBE, EXPLAIN)的結果。從查詢返回的信息在本章下文稱為結果集合。
MySQL_ROW
這是一個行數據的類型安全(type-safe)的表示。當前它實現為一個計數字節的字符串數組。（如果字段值可能包含二進制數據，你不能將這些視為空終止串，因為這樣的值可以在內部包含空字節) 行通過調用MySQL_fetch_row()獲得。
MySQL_FIELD
這個結構包含字段信息，例如字段名、類型和大小。其成員在下面更詳細地描述。你可以通過重復調用mysql_fetch_field()對每一列獲得MYSQL_FIELD結構。字段值不是這個結構的部分；他們被包含在一個MySQL_ROW結構中。
MySQL_FIELD_OFFSET
這是一個相對一個MySQL字段表的偏移量的類型安全的表示。（由MySQL_fIEld_seek()使用。) 偏移量是在一行以內的字段編號，從0開始。
my_ulonglong
該類型用於行編號和mysql_affected_rows()、mysql_num_rows()和MySQL_insert_id()。這種類型提供0到1.84e19的一個范圍。在一些系統上，試圖打印類型my_ulonglong的值將不工作。為了打印出這樣的值，將它變換到unsigned long並且使用一個%lu打印格式。例如：
printf (Number of rows: %lu\n", (unsigned long) MySQL_num_rows(result));
MySQL_FIELD結構包含列在下面的成員：
char * name
字段名，
是一個空結尾的字符串。
char * table
包含該字段的表的名字，如果它不是可計算的字段。對可計算的字段，table值是一個空字符串。
char * def
這字段的缺省值，是一個空結尾的字符串。只要你使用，只有你使用MySQL_list_fIElds()才可設置它。
enum enum_fIEld_types type
字段類型。type值可以是下列之一：
類型值 類型含義
FIELD_TYPE_TINY TINYINT字段
FIELD_TYPE_SHORT SMALLINT字段
FIELD_TYPE_LONG INTEGER字段
FIELD_TYPE_INT24 MEDIUMINT字段
FIELD_TYPE_LONGLONG BIGINT字段
FIELD_TYPE_DECIMAL DECIMAL或NUMERIC字段
FIELD_TYPE_FLOAT FLOAT字段
FIELD_TYPE_DOUBLE DOUBLE或REAL字段
FIELD_TYPE_TIMESTAMP TIMESTAMP字段
FIELD_TYPE_DATE DATE字段
FIELD_TYPE_TIME TIME字段
FIELD_TYPE_DATETIME DATETIME字段
FIELD_TYPE_YEAR YEAR字段
FIELD_TYPE_STRING 字符串(CHAR或VARCHAR)字段
FIELD_TYPE_BLOB BLOB或TEXT字段(使用max_length決定最大長度）
FIELD_TYPE_SET SET字段
FIELD_TYPE_ENUM ENUM字段
FIELD_TYPE_NULL NULL- 類型字段
FIELD_TYPE_CHAR 不推薦；使用FIELD_TYPE_TINY代替
你可以使用IS_NUM()宏來測試字段是否有一種數字類型。將type值傳給IS_NUM()並且如果字段是數字的，它將計算為TRUE：
if (IS_NUM(fIEld->type))
printf("FIEld is numeric\n");
unsigned int length
字段寬度，在表定義中指定。
unsigned int max_length
對結果集合的字段的最大寬度(對實際在結果集合中的行的最長字段值的長度)。如果你使用mysql_store_result()或mysql_list_fIElds()，這包含字段最大長度。如果你使用MySQL_use_result()，這個變量的值是零。
unsigned int flags
字段的不同位標志。flags值可以是零個或多個下列位設置：
標志值 標志含義
NOT_NULL_FLAG 字段不能是NULL
PRI_KEY_FLAG 字段是一個主鍵的一部分
UNIQUE_KEY_FLAG 字段是一個唯一鍵的一部分
MULTIPLE_KEY_FLAG 字段是一個非唯一鍵的一部分。
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 UNSIGNED_FLAG 字段有UNSIGNED屬性
ZEROFILL_FLAG 字段有ZEROFILL屬性
BINARY_FLAG 字段有BINARY屬性
AUTO_INCREMENT_FLAG 字段有AUTO_INCREMENT屬性
ENUM_FLAG 字段是一個ENUM（不推薦）
BLOB_FLAG 字段是一個BLOB或TEXT（不推薦）
TIMESTAMP_FLAG 字段是一個TIMESTAMP（不推薦）
BLOB_FLAG、ENUM_FLAG和TIMESTAMP_FLAG標志的使用是不推薦的，因為他們指出字段的類型而非它的類型屬性。
對FIELD_TYPE_BLOB、FIELD_TYPE_ENUM或FIELD_TYPE_TIMESTAMP，最好是測試fIEld->type。下面例子演示了一個典型的flags值用法：
if (fIEld->flags & NOT_NULL_FLAG)
printf("FIEld can't be null\n");
你可以使用下列方便的宏決來確定flags值的布爾狀態：
IS_NOT_NULL(flags) 真，如果該字段被定義為NOT NULL
IS_PRI_KEY(flags) 真，如果該字段是一個主鍵
IS_BLOB(flags) 真，如果該字段是一個BLOB或TEXT（不推薦；相反測試fIEld->type）
unsigned int decimals
對數字字段的小數位數。
20.3 C API函數概述
在 C API 中可用的函數列在下面，並且在下一節更詳細地描述。見20.4 C API函數描述。
MySQL_affected_rows() 返回被最新的UPDATE, DELETE或INSERT查詢影響的行數。
MySQL_close() 關閉一個服務器連接。
mysql_connect() 連接一個MySQL服務器。該函數不推薦；使用MySQL_real_connect()代替。
MySQL_change_user() 改變在一個打開的連接上的用戶和數據庫。
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_host_info() 返回一個描述連接的字符串。
MySQL_get_proto_info() 返回連接使用的協議版本。
MySQL_get_server_info() 返回服務器版本號。
MySQL_info() 返回關於最近執行得查詢的信息。
mysql_init() 獲得或初始化一個MySQL結構。
MySQL_insert_id() 返回有前一個查詢為一個AUTO_INCREMENT列生成的ID。
MySQL_kill() 殺死一個給定的線程。
MySQL_list_dbs() 返回匹配一個簡單的正則表達式的數據庫名。
MySQL_list_fIElds() 返回匹配一個簡單的正則表達式的列名。
MySQL_list_processes() 返回當前服務器線程的一張表。
MySQL_list_tables() 返回匹配一個簡單的正則表達式的表名。
MySQL_num_fIElds() 返回一個結果集合重的列的數量。
MySQL_num_rows() 返回一個結果集合中的行的數量。
mysql_options() 設置對MySQL_connect()的連接選項。
MySQL_ping() 檢查對服務器的連接是否正在工作，必要時重新連接。
MySQL_query() 執行指定為一個空結尾的字符串的SQL查詢。
mysql_real_connect() 連接一個MySQL服務器。
MySQL_real_query() 執行指定為帶計數的字符串的SQL查詢。
MySQL_reload() 告訴服務器重裝授權表。
mysql_row_seek() 搜索在結果集合中的行，使用從MySQL_row_tell()返回的值。
MySQL_row_tell() 返回行光標位置。
MySQL_select_db() 連接一個數據庫。
MySQL_shutdown() 關掉數據庫服務器。
MySQL_stat() 返回作為字符串的服務器狀態。
MySQL_store_result() 檢索一個完整的結果集合給客戶。
MySQL_thread_id() 返回當前線程的ID。
MySQL_use_result() 初始化一個一行一行地結果集合的檢索。
為了連接服務器，調用mysql_init()以初始化一個連接處理器，然後用該處理器調用mysql_real_connect()(還有其他信息例如主機名、用戶名和口令)。當你用該連接完成工作後，調用MySQL_close()終止它。
當一個連接活躍時，客戶可以用mysql_query()或mysql_real_query()將SQL查詢發送到服務器。兩者的差別是mysql_query()期望查詢作為一個空結尾的字符串來指定而mysql_real_query()期望一個計數的字符串。如果字符串包含二進制數據(它可以包括空字節)，你必須使用MySQL_real_query()。
對與每個非--SELECT查詢(例如，INSERT、UPDATE、DELETE等)，你可以調用MySQL_affected_rows()知道有多少行受到影響(改變)。
對於SELECT查詢，你作為一個結果集合來檢索選擇的行。（注意一些語句是類SELECT的，他們返回行。這些包括SHOW、DESCRIBE和EXPLAIN。他們應該象SELECT語句相同的方式來對待。）
對客戶，有兩種方法處理結果集合。一種方法是通過調用MySQL_store_result()立刻
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。檢索全部結果。該函數從服務器獲得查詢返回的所有行，並將他們存儲在客戶端。第二種方法是對客戶通過調用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()的一個優點是既然行均被客戶取到，你不僅能順序存取行，你也能mysql_data_seek()或mysql_row_seek()在結果集合中前後移動以改變在結果集合中的當前行位置。你也能通過調用mysql_num_rows()知道有多少行。另一方面，MySQL_store_result()的內存需求對較大結果集合可能很高，並且你最可能遇到out-of-memory情況。
mysql_use_result()的一個優點是客戶為結果集合需要較少的內存，因為它一次只是維持一行(並且因為有較少的分配開銷，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()是非零，查詢應該有返回行，但是沒有。這表明查詢是一個失敗的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()函數提供錯誤信息的存取。他們返回最近調用的可能成功或失敗的函數的錯誤代碼或錯誤消息，允許你確定何時發生一個錯誤和什麼錯誤。
20.4 C API函數描述
在下面的描述中，一個NULL參數或返回值含義是在C編程語言環境的NULL，不是一個MySQL NULL值。
返回一個值的函數一般返回一個指針或一個整數。除非另外指定，返回一個指針的函數返回一個非 NULL值表明成功，或一個NULL值表明一個錯誤，而返回一個整數的函數返回零表示成功，或非零表示一個錯誤。注意，“非零”只有這個含義。除非函數描述另外說明，不要測試一個零以外的其他值：
if (result) /* 正確 */
... error ...
if (result < 0) /* 不正確 */
... error ...
if (result == -1) /* 不正確 */
... error ...
當函數返回一個錯誤時，函數描述的錯誤小節列出錯誤可能的類型。你可以調用mysql_errno()找出發生了這些重的哪一個。錯誤的字符串表示可以調用MySQL_error()獲得。
20.4.1 MySQL_affected_rows()
my_ulonglong mysql_affected_rows(MYSQL *MySQL)
20.4.1.1 說明
返回受到最後一個UPDATE、DELETE或INSERT查詢影響(變化)的行數。可以在針對UPDATE、DELETE或INSERT語句的mysql_query()之後立即調用。對於SELECT語句，mysql_affected_rows()的功能於MySQL_num_rows()相同。
MySQL_affected_rows()目前以一個宏(Macro)來實現。
20.4.1.2 返回值/> 大於零的一個整數表示受到影響或檢索出來的行數。零表示沒有匹配查序中WHERE子句的記錄或目前還沒有查詢被執行。-1表示查詢返回一個錯誤，或對於一個SELECT查詢，mysql_affected_rows()在調用MySQL_store_result()之前被調用。
20.4.1.3 錯誤
沒有。
20.4.1.4 范例
mysql_query(&MySQL,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%d products updated",
mysql_affected_rows(&MySQL));
20.4.2 MySQL_close()
void mysql_close(MYSQL *MySQL)
20.4.2.1 說明
關閉一個以前打開了的連接。如果句柄由mysql_init()或mysql_connect()自動分配，mysql_close()也釋放被MySQL指向的連接句柄。
20.4.2.2 返回值
沒有。
20.4.2.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務者的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.3 MySQL_connect()
MYSQL *mysql_connect(MYSQL *MySQL, const char *host, const char *user, const char *passwd)
20.4.3.1 說明
該函數不推薦使用，而更好使用MySQL_real_connect()。
mysql_connect()試圖建立一個對運行在host的一個MySQL數據庫引擎的連接。mysql_connect()必須在你能執行其他API函數之前成功地完成，除了MySQL_get_clIEnt_info()。
參數的含義與MySQL_connect()相應的參數相同，不同的是連接參數可以是NULL。在這種情況下，C API
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 自動為連接結構分配內存，並且當你調用mysql_close()，釋放它。這種方法的缺點是如果連接失敗，你不能檢索出一條錯誤消息。（為了從mysql_errno()或mysql_error()得到錯誤信息，你必須提供一個有效的MySQL指針。）
20.4.3.2 返回值
同MySQL_real_connect()。
20.4.3.3 錯誤
同MySQL_real_connect()。
20.4.4MySQL_change_user()
my_bool mysql_change_user(MYSQL *MySQL, const char *user, const char *passWord, const char *db)
20.4.4.1 說明
改變用戶並且使得由db指定數據庫成為由MySQL指定的連接上的缺省(當前)數據庫。在隨後的查詢中，這個數據庫是不包括一個明確的數據庫指定符的表引用的缺省值。
這個函數功能在MySQL 3.23.3中引入。
除非連接的用戶能被認證或如果他沒有權限使用數據庫，MySQL_change_user()失敗。在這種情況下，用戶和數據庫都沒被改變。
如果你不想有一個缺省數據庫，db參數可以被設置為NULL。
20.4.4.2 返回值
成功，零。如果發生一個錯誤發生，非零。
20.4.4.3 錯誤
與你能從MySQL_real_connect()得到的相同。
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務者關閉了。
CR_SERVER_LOST
對服務者的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
ER_UNKNOWN_COM_ERROR
MySQL服務器未實現這
個命令(可能是一個老的服務器）
ER_Access_DENIED_ERROR
用戶或口令錯誤。
ER_BAD_DB_ERROR
數據庫不存在。
ER_DBAccess_DENIED_ERROR
用戶沒有數據庫的存取權利。
ER_WRONG_DB_NAME
數據庫名字太長。
20.4.4.4 范例
if (mysql_change_user(&MySQL, "user", "passWord", "new_database"))
{
fprintf(stderr, "Failed to change user. Error: %s\n",
mysql_error(&MySQL));
}
20.4.5 MySQL_create_db()
int mysql_create_db(MYSQL *MySQL, const char *db)
20.4.5.1 說明
創建由db參數命名的數據庫。
這個函數不推薦，而最好使用MySQL_query()發出一條SQL CREATE DATABASE語句。
20.4.5.2 返回值
如果數據庫成功地被創造，零。如果發生一個錯誤，非零。
20.4.5.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務者的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.5.4 范例
if(mysql_create_db(&MySQL, "my_database"))
{
fprintf(stderr, "Failed to create new database. Error: %s\n",
mysql_error(&MySQL));
}
20.4.6 MySQL_data_seek()
void mysql_data_seek(MySQL_RES *result, unsigned long long offset)
20.4.6.1 說明
在一個查詢結果集合中定位任意行。這要求結果集合結構包含查詢的全部結果，這樣mysql_data_seek()可以僅需與mysql_store_result()一起使用，不是與MySQL_use_result()。
偏移量應該是從0到MySQL_num_rows(result)-1范圍的一個值。
20.4.6.2 返回值
無。
20.4.6.3 錯誤
無。
20.4.7 MySQL_debug()
void MySQL_debug(char *debug)
20.4.7.1 說明
用一個給定字符串做一個DBUG_PUSH。mysql_debug()使用Fred Fish 調試庫。為了使用這個函數，你必須編譯客戶庫以支持調試。見G.1 調試一個MySQL服務器和節G.2 調試一個MySQL客戶。
20.4.7.2 返回值
無。
20.4.7.3 錯誤
無。
20.4.7.4 范例
下面所示的調用使得客戶庫在客戶機器上的“/tmp/clIEnt.trace”中產生一個跟蹤文
件：
MySQL_debug("d:t:O,/tmp/clIEnt.trace");
20.4.8 MySQL_drop_db()
int mysql_drop_db(MYSQL *MySQL, const char *db)
20.4.8.1 說明
拋棄由db參數命名的數據庫。
這個函數不推薦，而最好使用MySQL_query()發出一條SQL DROP DATABASE語句。
20.4.8.2 返回值
如果數據庫成功地被破拋棄，零。如果發生一個錯誤，非零。
20.4.8.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務者的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.8.4 范例
if(mysql_drop_db(&MySQL, "my_database"))
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 fprintf(stderr, "Failed to drop the database: Error: %s\n",
mysql_error(&MySQL));
20.4.9 MySQL_dump_debug_info()
int mysql_dump_debug_info(MYSQL *MySQL)
20.4.9.1 說明
指示服務者將一些調試信息寫入日志文件。連接的用戶對此必須有precess權限才能工作。
20.4.9.2 返回值
如果命令成功，零。如果發生一個錯誤，非零。
20.4.9.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務者關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.10 MySQL_eof()
my_bool mysql_eof(MySQL_RES *result)
20.4.10.1 說明
這個函數不推薦，而使用mysql_errno()或MySQL_error()。
MySQL_eof()確定是否已經讀到了一個結果集合的最後一行。
如果你從成功的mysql_store_result()調用獲得一個結果集合，客戶程序用一個操作收到全部集合。在這種情況下，從mysql_fetch_row()返回一個NULL總是意味著已經到達了結果集合的尾部，沒必要調用MySQL_eof()。
在另一方面，如果你使用mysql_use_result()初始化一個結果集合的檢索，該集合的行隨著你重復調用mysql_fetch_row()一個一個地從服務器獲得。因為在這個過程中在連接上可能發生一個錯誤，從mysql_fetch_row()返回一個NULL值並不意味著集合正常到達了尾部。在這種情況下，你能使用mysql_eof()確定發生了什麼。如果到達結果集合的尾部，MySQL_eof()返回非零值，並且如果發生一個錯誤，返回零。
在時間上，mysql_eof()先於標准MySQL錯誤函數mysql_errno()和mysql_error()。因為這些錯誤函數提供相同的信息，他們的使用更好MySQL_eof()，它現在不建議使用。
（事實上，他們提供更多的信息，因為MySQL_eof()值返回一個布爾值，而錯誤函數指出當發生錯誤時的出錯原因。）
20.4.10.2 返回值
如果發生一個錯誤，零。如果到達結果集合的結束，非零。
20.4.10.3 錯誤
無。
20.4.10.4 范例
下列例子顯示你必須如何使用MySQL_eof()：
mysql_query(&MySQL,"SELECT * FROM some_table");
result = mysql_use_result(&MySQL);
while((row = MySQL_fetch_row(result)))
{
// do something with data
}
if(!mysql_eof(result)) // MySQL_fetch_row() failed due to an error
{
fprintf(stderr, "Error: %s\n", mysql_error(&MySQL));
}
然而，你可以用標准MySQL錯誤函數完成同樣的效果：
mysql_query(&MySQL,"SELECT * FROM some_table");
result = mysql_use_result(&MySQL);
while((row = MySQL_fetch_row(result)))
{
// do something with data
}
if(mysql_errno(&mysql)) // MySQL_fetch_row() failed due to an error
{
fprintf(stderr, "Error: %s\n", mysql_error(&MySQL));
}
20.4.11 MySQL_errno()
unsigned int mysql_errno(MYSQL *MySQL)
20.4.11.1 說明
對於由mysql指定的連接，mysql_errno()返回最近調用的可能成功或失敗的API函數的錯誤代碼。返回值零意味著沒有錯誤發生。客戶錯誤消息編號列出在MySQL“errmsg.h”頭文件中。服務器錯誤消息編號列出在“MySQLd_error.h”中。
20.4.11.2 返回值：
一個錯誤代碼值。如果沒有錯誤發生，零。
20.4.11.3 錯誤
無。
20.4.12 MySQL_error()
char *mysql_error(MYSQL *MySQL)
20.4.12.1 說明
對於由mysql指定的連接，MySQL_errno()返回最近調用的可能成功或失敗的API函數的錯誤代碼。如果沒有錯誤發生，返回空字符串("")。這意味著下列兩個測試是等價的：
if(mysql_errno(&MySQL))
{
// an error occurred
}
if(mysql_error(&MySQL)[0] != '\0')
{
// an error occurred
}
客戶錯誤消息的語言可通過重新編譯MySQL客戶庫來改變。目前，你能在幾種不同的語言間選取錯誤消息。見9.1 MySQL支持什麼語言？。
20.4.12.2 返回值
一個描述錯誤的字符串。如果沒有錯誤發生，空字符串。
20.4.12.3 錯誤
無。
20.4.13 MySQL_escape_string()
unsigned int MySQL_escape_string(char *to, const char *from, unsigned int length)
20.4.13.1 說明
把在from中的字符串編碼為在一條SQL語句中可以發給服務器的轉義的SQL字符串，將結果放在to中， 並且加上一個終止的空字節。編碼的字符是NUL（ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’和Control-Z(見7.1 文字：如何寫字符串和數字)。
由from指向的字符串必須是length個字節長。你必須分配to的緩沖區至少length*2+1個字節長。（在更壞的情況，每個字符可能需要使用2個字節被編碼，並且你需要為終止空字節的空間) 當MySQL_escape_string()返回時，to的內容將是空字符終止的字符串。返回值是編碼後的字符串的長度，不包括終止空字符。
20.4.13.2 范例
c
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。har query[1000],*end;
end = strmov(query,"INSERT INTO test_table values(");
*end++ = ''';
end += MySQL_escape_string(end,"What's this",11);
*end++ = ''';
*end++ = ',';
*end++ = ''';
end += MySQL_escape_string(end,"binary data: \0\r\n",16);
*end++ = ''';
*end++ = ')';
if (mysql_real_query(&MySQL,query,(unsigned int) (end - query)))
{
fprintf(stderr, "Failed to insert row, Error: %s\n",
mysql_error(&MySQL));
}
例子中所用的strmov()函數被包括在MySQLclIEnt庫中且功能類似於strcpy()，但是返回一個指向空終止的第一個參數的指針。
20.4.13.3 返回值
放進to的值的長度，不包括終止空字符。
20.4.13.4 錯誤
無。
20.4.14 MySQL_fetch_fIEld()
MYSQL_FIELD *mysql_fetch_fIEld(MySQL_RES *result)
20.4.14.1 說明
返回作為一個MYSQL_FIELD結構的一個結果集合的一個列的定義。重復調用這個函數在結果集合中檢索所有關於列的信息。當沒有剩下更多的字段時，MySQL_fetch_fIEld()返回NULL。
在每次你執行一個新的SELECT查詢，mysql_fetch_field()被重置（reset)以返回有關第一列的信息。由mysql_fetch_fIEld()返回的字段也受調用MySQL_fIEld_seek()的影響。
如果你調用mysql_query()在一張表上執行一個SELECT，但是沒調用mysql_store_result()，如果你調用mysql_fetch_fIEld()詢問一個BLOB字段的長度，MySQL返回缺省BLOB長度(8K字節)。（選擇8K的長度是因為MySQL不知道BLOB的最大長度。這應該在某個時候是它可配置) 一旦你已經檢索了結果集合，fIEld->max_length包含了在特定查詢中對於該列最大值的長度。
20.4.14.2 返回值
當前列的MySQL_FIELD結構。如果沒有列剩下，NULL。
20.4.14.3 錯誤
無。
20.4.14.4 范例
MySQL_FIELD *fIEld;
while((fIEld = MySQL_fetch_fIEld(result)))
{
r /> printf("field name %s\n", fIEld->name);
}
20.4.15 MySQL_fetch_fIElds()
MYSQL_FIELD *mysql_fetch_fIElds(MySQL_RES *result)
20.4.15.1 說明
返回一個結果集合的所有MySQL_FIELD結構的數組。每個結構提供結果結合中一列的字段定義。
20.4.15.2 返回值
一個結果集合的所有MySQL_FIELD結構的一個數組。
20.4.15.3 錯誤
無。
20.4.15.4 范例
unsigned int num_fIElds;
unsigned int i;
MySQL_FIELD *fIElds;
num_fIElds = MySQL_num_fIElds(result);
fIElds = MySQL_fetch_fIElds(result);
for(i = 0; i < num_fIElds; i++)
{
printf("Field %u is %s\n", i, fIElds[i].name);
}
20.4.16 MySQL_fetch_fIEld_direct()
MYSQL_FIELD *mysql_fetch_fIEld_direct(MySQL_RES *result, unsigned int fIEldnr)
20.4.16.1 說明
給定在一個結果集合中的一個列的字段編號fieldnr，返回作為MYSQL_FIELD結構的列的字段定義。你可以使用這個函數檢索任意列的義。fIEldnr的值應該在從0到MySQL_num_fIElds(result)-1范圍內。
20.4.16.2 返回值
指定列的MySQL_FIELD結構。
20.4.16.3 錯誤
無。
20.4.16.4 范例
unsigned int num_fIElds;
unsigned int i;
MySQL_FIELD *fIEld;
num_fIElds = MySQL_num_fIElds(result);
for(i = 0; i < num_fIElds; i++)
{
fIEld = MySQL_fetch_fIEld_direct(result, i);
printf("Field %u is %s\n", i, fIEld->name);
}
20.4.17 MySQL_fetch_lengths()
unsigned long *mysql_fetch_lengths(MySQL_RES *result)
20.4.17.1 說明
返回在結果集合內的當前行的列長度。如果你計劃拷貝字段值，這個長度信息對優化也是有用的，因為你可以避免調用strlen()。另外，如果結果集合中包含二進制數據，你必須使用這個函數確定數據的大小，因為strlen()對包含空字符的任何字段返回不正確的結果。
空列和包含NULL的列的長度值是零。為了看清如何區分這兩種情況，見MySQL_fetch_row()的說明。
20.4.17.2 返回值
表示每列大小的無符號長整數的一個數組(不包括任何終止空字符)。如果出現一個錯誤，NULL。
20.4.17.3 錯誤
mysql_fetch_lengths()只對結果集合的當前行有效。如果你在調用MySQL_fetch_row()之前或在檢索出在結果中的所有以後，它返回NULL。
20.4.17.4 范例
MySQL_ROW row;
r /> unsigned long *lengths;
unsigned int num_fIElds;
unsigned int i;
row = MySQL_fetch_row(result);
if (row)
{
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 num_fIElds = MySQL_num_fIElds(result);
lengths = MySQL_fetch_lengths(result);
for(i = 0; i < num_fIElds; i++)
{
printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
}
}
20.4.18 MySQL_fetch_row()
MYSQL_ROW mysql_fetch_row(MySQL_RES *result)
20.4.18.1 說明
檢索一個結果集合的下一行。當在mysql_store_result()之後使用時，如果沒有更多的行可見所時，mysql_fetch_row()返回NULL。當在mysql_use_result()之後使用時，當沒有更多的行可檢索時或如果出現一個錯誤，MySQL_fetch_row()返回NULL。
在行中值的數量由mysql_num_fIElds(result)給出。如果row保存了從一個對用mysql_fetch_row()調用返回的值，指向該值的指針作為row[0]到row[MySQL_num_fIElds(result)-1]來存取。在行中的NULL值由NULL指針指出。
在行中字段值的長度可以通過調用MySQL_fetch_lengths()獲得。空字段和包含NULL的字段長度都是 0；你可以通過檢查該值的指針區分他們。如果指針是NULL，字段是NULL；否則字段是空的。
20.4.18.2 返回值
下一行的一個MySQL_ROW結構。如果沒有更多的行可檢索或如果出現一個錯誤，NULL。
20.4.18.3 錯誤
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.18.4 范例
MySQL_ROW row;
unsigned int num_fIElds;
unsigned int i;
num_fIElds = MySQL_num_fIElds(result);
while ((row = MySQL_fetch_row(result)))
{
unsigned long *lengths;
lengths = MySQL_fetch_lengths(result);
for(i = 0; i < num_fIElds; i++)
{
printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
}
printf("\n");
}
20.4.19 MySQL_fIEld_count()
unsigned int mysql_fIEld_count(MYSQL *MySQL)
如果你正在使用一個比3.22.24早MySQL版本，你應該使用unsigned int mysql_num_fIElds(MYSQL *MySQL)。
20.4.19.1 說明
返回在連接上的最近查詢的列的數量。
這個函數一般用在MySQL_store_result()返回NULL時（這樣你沒有結果設置指針)。
在這種情況中，你能調用mysql_fIEld_count()確定MySQL_store_result()是否應該產生了一個非空的結果。這允許一個客戶程序執行正確的操作，而不必知道查詢是否是一條SELECT（或類SELECT)語句。下面顯示的例子說明這怎樣可以做到。
見20.4.51 為什麼在mysql_query()返回成功後，MySQL_store_result()有時返回NULL?。
20.4.19.2 返回值
在結果集合中表示字段數量字的一個無符號整數。
20.4.19.3 錯誤
無。
20.4.19.4 范例
MySQL_RES *result;
unsigned int num_fIElds;
unsigned int num_rows;
if (mysql_query(&MySQL,query_string))
{
// error
}
else // query succeeded, process any data returned by it
{
result = mysql_store_result(&MySQL);
if (result) // there are rows
{
num_fIElds = MySQL_num_fIElds(result);
// retrIEve rows, then call MySQL_free_result(result)
}
else // MySQL_store_result() returned nothing; should it have?
{
if(mysql_fIEld_count(&MySQL) == 0)
{
// query does not return data
// (it was not a SELECT)
num_rows = mysql_affected_rows(&MySQL);
}
else // MySQL_store_result() should have returned data
{
fprintf(stderr, "Error: %s\n", mysql_error(&MySQL));
}
}
}
另一個選擇是用mysql_errno(&mysql)代替mysql_fIEld_count(&mysql)調用。在這種情況中，你直接檢查來自mysql_store_result()的一個錯誤而非從MySQL_fIEld_count()值來推斷語句是否是一個SELECT。
20.4.20 MySQL_fIEld_seek()
MYSQL_FIELD_OFFSET mysql_fIEld_seek(MYSQL_RES *result, MySQL_FIELD_OFFSET offset)
20.4.20.1 說明
將字段光標設置到給定的偏移量。下一次調用MySQL_fetch_fIEld()將檢索與該偏移量關聯的列的字段定義。
為了定位於行的起始，傳遞一個值為0的offset值。
20.4.20.2 返回值
字段光標的先前的值。
20.4.20.3 錯誤
無。
20.4.21MySQL_fIEld_tell()
MySQL_FIELD_OF
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。FSET mysql_fIEld_tell(MySQL_RES *result)
20.4.21.1 說明
<
br /> 返回用於最後一個mysql_fetch_fIEld()的字段光標的位置。這個值可用作MySQL_fIEld_seek()的一個參數。
20.4.21.2 返回值
字段光標的當前偏移量。
20.4.21.3 錯誤
無。
20.4.22 MySQL_free_result()
void mysql_free_result(MySQL_RES *result)
20.4.22.1 說明
釋放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等為一個結果集合分配的內存。當你用完了一個結果集合時，你必須調用MySQL_free_result()來釋放它使用的內存。
20.4.22.2 返回值
無。
20.4.22.3 錯誤
無。
20.4.23 MySQL_get_clIEnt_info()
char *MySQL_get_clIEnt_info(void)
20.4.23.1 說明
返回代表客戶庫的版本的字符串。
20.4.23.2 返回值
代表MySQL客戶庫版本的一個字符串。
20.4.23.3 錯誤
無。
20.4.24 MySQL_get_host_info()
char *mysql_get_host_info(MYSQL *MySQL)
20.4.24.1 說明
返回描述正在使用的連接類型的字符串，包括服務其主機名。
20.4.24.2 返回值
表示服務器主機名者和連接類型的字符串。
20.4.24.3 錯誤
無。
20.4.25 MySQL_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *MySQL)
20.4.25.1 說明
返回當前連接使用的協議版本。
20.4.25.2 返回值
表示被當前連接使用的協議版本的一個無符號整數。
20.4.25.3 錯誤
無。
20.4.26 MySQL_get_server_info()
char *mysql_get_server_info(MYSQL *MySQL)
20.4.26.1 說明
返回表示服務器版本號的字符串。
20.4.26.2 返回值
表示服務器版本號的一個字符串。
20.4.26.3 錯誤
無。
20.4.27 MySQL_info()
char *mysql_info(MYSQL *MySQL)
20.4.27.1 說明
檢索一個字符串，它提供有關最近執行的查詢的信息，但是對下面列出的語句。對其他語句，MySQL_info()返回NULL。字符串的格式隨查詢類型而變化，如下所述。數字僅僅是說明性的；字符串將包含對查詢適當的值。
INSERT INTO ... SELECT ...
字符串格式： Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
字符串格式： Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE .
..
字符串格式： Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
字符串繩格式： Records: 3 Duplicates: 0 Warnings: 0
UPDATE
字符串格式： Rows matched: 40 Changed: 40 Warnings: 0
注意，只有多個值在語句中指定，MySQL_info()對INSERT ... VALUES語句才返回非NULL值。
20.4.27.2 返回值
表示最近執行的查詢的附加信息的一個字符串。如果得不到查詢的任何信息，NULL。
20.4.27.3 錯誤
無。
20.4.28 MySQL_init()
MYSQL *mysql_init(MYSQL *MySQL)
20.4.28.1 說明
分配或初始化適合mysql_real_connect()的一個MYSQL對象。如果mysql是一個NULL指針，函數分配、初始化並且返回一個新對象。否則對象被初始化並且返回對象的地址。如果mysql_init()分配一個新對象，它將在調用MySQL_close()關閉連接時被釋放。
20.4.28.2 返回值
一個被初始化的MySQL*句柄。如果沒有足夠的內存來分配一個新對象，NULL。
20.4.28.3 錯誤
在內存不夠的情況下，返回NULL。
20.4.29 MySQL_insert_id()
my_ulonglong mysql_insert_id(MYSQL *MySQL)
20.4.29.1 說明
返回由先前的查詢為一個AUTO_INCREMENT列生成的ID。在你執行一個INSERT查詢向一個包含AUTO_INCREMENT字段的表中插入後，使用這個函數。
注意，如果先前的查詢不產生一個AUTO_INCREMENT值，mysql_insert_id()返回0。如果你需要在以後保存該值，必須在查詢生成了該值後馬上調用MySQL_insert_id()。
也要注意，SQL的LAST_INSERT_ID()函數總是包含最近生成的AUTO_INCREMENT值，並且在查詢之間不被重置，因為該函數的值在服務器端維護。
20.4.29.2 返回值
有先前的查詢更新的AUTO_INCREMENT字段的值。如果在連接上沒有先前的詢問或如果查詢沒更新AUTO_INCREMENT值，返回零。
20.4.29.3 錯誤
無。
20.4.30 MySQL_kill()
int mysql_kill(MYSQL *MySQL, unsigned long pid)
20.4.30.1 說明
要求服務器殺死由pid指定的線程。
20.4.30.2 返回值
成功，零。如果出現一個錯誤，非零。
20.4.30.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 MySQL服務器關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.31 MySQL_list_dbs()
MYSQL_RES *mysql_list_dbs(MYSQL *MySQL, const char *wild)
20.4.31.1 說明
返回一個結果集合，
它用在服務器上的匹配wild參數指定的簡單正則表達式的數據庫名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有的數據庫的一個NULL指針。調用MySQL_list_dbs()類似於執行查詢SHOW databases [LIKE wild]。
你必須用MySQL_free_result()釋放結果集合。
20.4.31.2 返回值
成功，一個MySQL_RES結果集合。如果出現一個錯誤，NULL。
20.4.31.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_OUT_OF_MEMORY
內存溢出。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.32 MySQL_list_fIElds()
MYSQL_RES *mysql_list_fIElds(MYSQL *MySQL, const char *table, const char *wild)
20.4.32.1 說明
返回一個結果集合，它用在給定表中的匹配wild參數指定的簡單正則表達式的列名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有列的一個NULL指針。調用MySQL_list_fIElds()類似於執行查詢SHOW COLUMNS FROM tbl_name [LIKE wild]。
注意，建議你使用SHOW COLUMNS FROM tbl_name而不是MySQL_list_fIElds()。
你必須用MySQL_free_result()釋放結果集合。
20.4.32.2 返回值
成功，一個MySQL_RES的結果集合。如果出線一個錯誤，NULL。
20.4.32.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務者關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.33 MySQL_list_processes()
MYSQL_RES *mysql_list_processes(MYSQL *MySQL)
20.4.33.1 說明
返回一個描述當前服務器線程的結果集合。這是與MySQLadmin processlist或SHOW PROCESSLIST查詢報告的相同信息。
你必須用MySQL_free_result()釋放結果集合。
20.4.33.2 返回值
成功，一個MySQL_RES結果集合。如果發生一個錯誤，NULL。
20.4.33.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務者關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.34 MySQL_list_tables()
MYSQL_RES *mysql_list_tables(MYSQL *MySQL, const char *wild)
20.4.34.1 說明
返回一個結果集合，
它用在當前數據庫中的匹配wild參數指定的簡單正則表達式的表名組成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有表的一個NULL指針。調用MySQL_list_tables()類似於執行詢問SHOW tables [LIKE wild]。
你必須用MySQL_free_result()釋放結果集合。
20.4.34.2 返回值
成功，一個MySQL_RES結果集合。如果出現一個錯誤，NULL。
20.4.34.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不正確的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.35 MySQL_num_fIElds()
unsigned int mysql_num_fIElds(MySQL_RES *result)
或
unsigned int mysql_num_fIElds(MYSQL *MySQL)
第二中形式在MySQL 3.22.24或更新版本上不能工作。為了傳遞一個MYSQL* 參數，你必須使用unsigned int mysql_fIEld_count(MYSQL *MySQL)。
20.4.35.1 說明
在結果集合中返回列的數量。
注意，你也可以通過一個指向一個結果集合或一個連接句柄的指針獲得列的數量。如果mysql_store_result()或mysql_user_result()返回NULL，你將使用連接句柄（而這樣你沒有結果集合指針)。在這種情況下，你可以調用mysql_fIEld_count()確定MySQL_store_result()是否應該產生非空的結果。這允許客戶程序采取成正確的行動，不必知道查詢是否是一個SELECT（或類SELECT)語句。下面被顯示出的例子說明這怎麼可以被做。
見20.4.51 為什麼在mysql_query()返回成功後，MySQL_store_result()有時返回NULL?。
20.4.35.2 返回值
表示一個結果集合中字段數量的一個無符號整數。
20.4.35.3 錯誤
無。
20.4.35.4 范例
MySQL_RES *result;
unsigned int num_fIElds;
unsigned int num_rows;
if (mysql_query(&MySQL,query_string))
{
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。 // error
}
else // query succeeded, process any data returned by it
{
result = mysql_store_result(&MySQL);
if (result) // there are rows
{
num_fIElds = MySQL_num_fIElds(result);
// retrIEve rows, then call MySQL_free_result(result)
}
else // MySQL_store_result() returned nothing; should it have?
{
if (mysql_errno(&MySQL))
{
fprintf(stderr, "Error: %s\n", mysql_error(&MySQL));
}
else if (mysql_fIEld_count(&MySQL) == 0)
{
// query does not return data
// (it was not a SELECT)
num_rows = mysql_affected_rows(&MySQL);
}
}
}
另一個選擇(如果你知道你查詢應該返回了一個結果結合)是用mysql_fIEld_count(&mysql) = 0的一個檢查來代替mysql_errno(&MySQL)。這只會發生在出錯了的情形。
20.4.36 MySQL_num_rows()
my_ulonglong mysql_num_rows(MySQL_RES *result)
20.4.36.1 說明
在結果集合中返回行的數量。
mysql_num_rows()的使用取決於你是否使用mysql_store_result()或mysql_use_result()返回一個結果集合。如果你使用mysql_store_result()，mysql_num_rows()可以馬上被調用。如果你使用mysql_use_result()，MySQL_num_rows()將不會返回正確的值，直到在結果集合中的所有行均被檢索了。
20.4.36.2 返回值
在結果集合中行的數量。
20.4.36.3 錯誤
無。
20.4.37 MySQL_options()
int mysql_options(MYSQL *mysql, enum MySQL_option option, const char *arg)
20.4.37.1 說明
能用於設置額外連接選項並且影響一個連接的行為。這個函數可以被多次調用來設置多個選項。
mysql_options()應該在mysql_init()之後和mysql_connect()或MySQL_real_connect()之前調用。
option參數是你想要設置的選項；arg參數是選項的值。如果選項是一個整數，那麼arg應該指向整數值。
可能的選項值：
選項 參數類型 功能
MySQL_OPT_CONNECT_TIMEOUT unsigned int * 以秒計的連接超時。
MySQL_OPT_COMPRESS 不使用 使用壓縮的客戶機/服務器協議。
MYSQL_OPT_NAMED_PIPE 不使用 使用命名管道連接一個在NT上的MySQL服務器。
MYSQL_INIT_COMMAND char * 當連接MySQL服務器時執行的命令。當重新連接時，將自動重新執行。
MySQL_READ_DEFAULT_FILE char * 從命名的選項文件而不是從“my.cnf”讀取選項。
MYSQL_READ_DEFAULT_GROUP char * 從“my.cnf”或用MySQL_READ_DEFAULT_FILE指定的文件中的命名組中讀取選項。
注意，如果你使用MYSQL_READ_DEFAULT_FILE或MySQL_READ_DEFAULT_GROUP，總是讀取clIEnt。
在選項文件中指定的組可能包含下列選項：
compress 使用壓縮的客戶機/服務器協議。
database 如果在連接命令中沒有指定數據庫，使用這個數據庫。
debug 調試選項
host 缺省主機名
init-command 在連接MySQL服務器時，執行的命令。當重新連接時，將自動重新執行。
passWord 缺省口令
pipe 使用命名管道連接一個在NT上的MySQL服務器。
port 缺省端口號
return-found-rows 告訴MySQL_info()返回找到的行，而不是在使用UPDATE時，返回更新的行。
socket 缺省套接字號
timeout 以秒計的連接超時。
user 缺省用戶
對於選項文件的更多信息，見4.15.4 選項文件。
20.4.37.2 返回值
成功，零。如果你使用了未知的選項，非零。
20.4.37.3 范例
MYSQL MySQL;
mysql_init(&MySQL);
mysql_options(&mysql,MySQL_OPT_COMPRESS,0);
mysql_options(&mysql,MySQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&MySQL,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&MySQL));
}
上例請求客戶使用壓縮的客戶機/服務器協議並且從my.cnf文件的odbc小節讀取額外的選項。
20.4.38 MySQL_ping()
int mysql_ping(MYSQL *MySQL)
20.4.38.1 說明
檢查到服務器的連接是否正在工作。如果它關閉了，自動嘗試一個再連接。
這個函數可被已經空閒很長時間的客戶使用，來檢查服務器是否關閉了連接並且如有必要重新連接。
20.4.38.2 返回值
如果服務器活著，零。如果出現一個錯誤，非零。
20.4.38.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不適當的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.39 MySQL_query()
int
您正在看的MySQL教程是:MySQL數據庫學習手冊之MySQL客戶工具和API。mysql_query(MYSQL *MySQL, const char *query)
20.4.39.1 說明
執行指向空終止的字符串query的SQL查詢，查詢必須由一個單個的SQL語句組成。你不應該在語句後加上一個終止的分號(“；”)或\g。
mysql_query()不能被用於包含二進制數據的查詢；相反你應該使用mysql_real_query()。（二進制數據可能包含“\0”字符，而MySQL_query()將解釋為查詢字符串的結束。）
20.4.39.2 返回值
如果查詢成功，零。如果出現一個錯誤，非零。
20.4.39.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不適當的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
到服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一個未知的錯誤。
20.4.40 MySQL_real_connect()
MYSQL *mysql_real_connect(MYSQL *MySQL, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket,
unsigned int clIEnt_flag)
20.4.40.1 說明
mysql_real_connect()試圖建立到運行host的一個MySQL數據庫引擎的一個連接。 mysql_real_connect()在你可以執行任何其他API函數之前必須成功地完成，除了MySQL_get_clIEnt_info()。
參數指定如下：
* 第一個參數應該是一個現存MYSQL結構的地址。在調用mysql_real_connect()之前，你必須調用mysql_init()初始化MySQL結構。見下面的例子。
* host值可以是一個主機名或一個IP地址。如果host是NULL或字符串"localhost"，假定是到本地主機的一個連接。如果OS支持套接字(Unix)或命名管道(Win32)，使用他們而不是TCP/IP與服務器連接。
* user參數包含用戶的MySQL登錄ID。如果user是NULL，假定是當前用戶。在Unix下，它是當前登錄名。在Windows ODBC下，必須明確地指定當前用戶名字。見16.4 怎樣填寫ODBC管理程序中各種域。
* passwd參數為user包含口令。如果passwd是NULL，只有在user表中對於有一個空白口令字段的用戶的條目將被檢查一個匹配。這允許數據庫主管設置MySQL權限，使用戶獲得不同的口令，取決於他們是否已經指定一個口令。注意：不要試圖在調用MySQL_real_connect()前加密口令；口令加密自動被客戶API處理。
* db是數據庫名。如果db不是NULL，連接將缺省數據庫設置為這個值。
* 如果port不是0，值對於TCP/IP連接將用作端口號。注意host參數決定連接的類型。
* 如果unix_socket不是NULL，字符串指定套接字或應該被使用的命名管道。注意host參數決定連接的類型。
* clIEnt_flag值通常是0，但是在很特殊的情況下可以被設置為下列標志的組合：
標志名字 意味著的標志
CLIENT_FOUND_ROWS 返回找到的(匹配的)行數，不是受到影響的行數。
CLIENT_NO_SCHEMA 不允許db_name.tbl_name.col_name語法。這是為了ODBC；如果你使用該語法，導致語法分析器產生一個錯誤，它是為在一些ODBC程序捕捉錯誤是有用的。
CLIENT_COMPRESS 使用壓縮協議。
CLIENT_ODBC 客戶是一個ODBC客戶。這使MySQLd變得對ODBC更友好。
20.4.40.2 返回值
如果連接成功，一個 MySQL*連接句柄。如果連接失敗，NULL。對一個成功的連接，返回值與第一個參數值相同，除非你傳遞NULL給該參數。
20.4.40.3 錯誤
CR_CONN_HOST_ERROR
不能連接MySQL服務器。
CR_CONNECTION_ERROR
不能連接本地MySQL服務器。
CR_IPSOCK_ERROR
不能創建一個IP套接字。
CR_OUT_OF_MEMORY
內存溢出。
CR_SOCKET_CREATE_ERROR
不能創建一個Unix套接字。
CR_UNKNOWN_HOST
不能找到主機名的IP地址。
CR_VERSION_ERROR
由於試圖使用一個不同協議版本的一個客戶庫與一個服務器連接導致的一個協議失配。如果你使用一個非常老的客戶庫連接一個沒有使用--old-protocol選項啟動的新服務器，這就能發生。
CR_NAMEDPIPEOPEN_ERROR;
不能在 Win32 上創建一個命名管道。
CR_NAMEDPIPEWAIT_ERROR;
不能在 Win32 上等待一個命名管道。
CR_NAMEDPIPESETSTATE_ERROR;
不能在 Win32 上得到一個管道處理器。
20.4.40.4 范例
MYSQL MySQL;
mysql_init(&MySQL);
if (!mysql_real_connect(&MySQL,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&MySQL));
}
20.4.41 MySQL_real_query()
int mysql_real_query(MYSQL *MySQL, const char *query, unsigned int length)
20.4.41.1 說明
執行由query指向的SQL查詢，它應該是一個length個字節的字符串。查詢必須由一個單個的SQL語句組成。你不應該在語句後增加一個終止的分號(“;”)或\g。
對於包含二進制數據的查詢，你必須使用mysql_real_query()而不是mysql_query()，因為二進制代碼數據可能包含“\0”字符，而且，mysql_real_query()比MySQL_query()更快，因為它對查詢字符串調用strlen()。
20.4.41.2 返回值
如果查詢成功，零。如果發生一個錯誤，非零。
20.4.41.3 錯誤
CR_COMMANDS_OUT_OF_SYNC
命令以一個不適當的次序被執行。
CR_SERVER_GONE_ERROR
MySQL服務器關閉了。
CR_SERVER_LOST
對服務器的連接在查詢期間失去。
CR_UNKNOWN_ERROR
發生一
