MYSQL C API 學習匯總

1.查詢結果集

(1)資料結構

typedef struct st_mysql_res {

  my_ulonglong 　　row_count;                              // 結果集的行數  (long或long long)

  unsigned 　　intfield_count, current_field;           // 結果集的列數，當前列

  MYSQL_FIELD*　　fields;                                   // 結果集的列資訊

  MYSQL_DATA*　　data;                                     // 結果集的資料

  MYSQL_ROWS*　　data_cursor;                       // 結果集的游標

  MEM_ROOT　　field_alloc;                                   // 記憶體結構

  MYSQL_ROW　　row;                                        // 非緩衝的時候用到

  MYSQL_ROW　　current_row;                           //mysql_store_result時會用到。當前行

  unsigned long *　　lengths;                               //每列的長度

  MYSQL*　　handle;                                          // mysql_use_result會用。

  my_bool　　eof;                                                //是否為行尾

} MYSQL_RES;

 

typedef struct st_mysql_field {  char *　　name;　　　　　　　　　　/* Name of column */  char *　　table;                                           /* Table of column if column was a field */  char *　　def;                                              /* Default value (set by mysql_list_fields) */  enum enum_field_types type;               /* Type of field. Se mysql_com.h for types */  unsigned int 　　length;                              /* Width of column */  unsigned int 　　max_length;                      /* Max width of selected set */  unsigned int　　 flags;                                 /* Div flags */  unsigned int 　　decimals;                           /* Number of decimals in field */} MYSQL_FIELD;  //列資訊的結構 typedef struct st_mysql_data {  my_ulonglong　　 rows;  unsigned int　　 fields;  MYSQL_ROWS *　　data;  MEM_ROOT　　 alloc;} MYSQL_DATA; // 資料集的結構 typedef struct st_mysql_rows {  struct st_mysql_rows *next;　　/* list of rows */  MYSQL_ROW data;} MYSQL_ROWS;        //mysql的資料的鏈表節點。可見mysql的結果集是鏈表結構 typedef char **    MYSQL_ROW;　　/* 返回的每一行的值，全部用字串來表示*/ 

typedef struct st_used_mem {　　/* struct for once_alloc */

  struct st_used_mem *next;　　/* Next block in use */

  unsigned int left;　　/* memory left in block  */

  unsigned int size;　　/* Size of block */

} USED_MEM; 　　//記憶體結構

 

typedef struct st_mem_root {

  USED_MEM *　　free;

  USED_MEM *　　used;

  USED_MEM *　　pre_alloc;

  unsigned 　　intmin_malloc;

  unsigned　　 intblock_size;

  void (*error_handler)(void);

} MEM_ROOT;  //記憶體結構

(2)API

1. . mysql_store_result()

MYSQL_RES *   mysql_store_result(MYSQL *mysql)

對於成功檢索了資料的每個查詢（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必須調用mysql_store_result()或mysql_use_result()。

對於其他查詢，不需要調用mysql_store_result()或mysql_use_result()，但是如果在任何情況下均調用了mysql_store_result()，它也不會導致任何傷害或效能降低。通過檢查mysql_store_result()是否返回0，可檢測查詢是否沒有結果集（以後會更多）。

如果希望瞭解查詢是否應返回結果集，可使用mysql_field_count()進行檢查

mysql_store_result()將查詢的全部結果讀取到用戶端，分配1個MYSQL_RES結構，並將結果置於該結構中。

如果查詢未返回結果集，mysql_store_result()將返回Null指標（例如，如果查詢是INSERT語句）。

如果讀取結果集失敗，mysql_store_result()還會返回Null指標。通過檢查mysql_error()是否返回非Null 字元串，mysql_errno()是否返回非0值，或mysql_field_count()是否返回0，可以檢查是否出現了錯誤。

如果未返回行，將返回空的結果集。（空結果集設定不同於作為傳回值的null 指標）。

一旦調用了mysql_store_result()並獲得了不是Null指標的結果，可調用mysql_num_rows()來找出結果集中的行數。

可以調用mysql_fetch_row()來擷取結果集中的行，或調用mysql_row_seek()和mysql_row_tell()來擷取或設定結果集中的當前行位置。

一旦完成了對結果集的操作，必須調用mysql_free_result()。

 

2. mysql_use_result

MYSQL_RES *  mysql_use_result(MYSQL *mysql)

描述

對於成功檢索資料的每個查詢（SELECT、SHOW、DESCRIBE、EXPLAIN），必須用mysql_store_result()或mysql_use_result()。

mysql_use_result()將初始化結果集檢索，但並不像mysql_store_result()那樣將結果集實際讀取到用戶端。它必須通過對mysql_fetch_row()的調用，對每一行分別進行檢索。這將直接從伺服器讀取結果，而不會將其儲存在暫存資料表或本地緩衝區內，與mysql_store_result()相比，速度更快而且使用的記憶體也更少。用戶端僅為當前行和通訊緩衝區分配記憶體，分配的記憶體可增加到max_allowed_packet位元組。

另一方面，如果你正在用戶端一側為各行進行大量的處理操作，或者將輸出發送到了使用者可能會鍵入“^S”（停止滾動）的螢幕，就不應使用mysql_use_result()。這會綁定伺服器，並阻止其他線程更新任何錶（資料從這類表獲得）。

使用mysql_use_result()時，必須執行mysql_fetch_row()，直至返回NULL值，否則，未擷取的行將作為下一個檢索的一部分返回。C API給出命令不同步錯誤，如果忘記了執行該操作，將不能運行該命令。

不能對結果集用mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()或mysql_affected_rows()，也不應發出其他查詢，直至mysql_use_result()完成為止。（但是，提取了所有行後，mysql_num_rows()將準確返回提取的行數）。

一旦完成了對結果集的操作，必須調用mysql_free_result()。

傳回值

MYSQL_RES結果結構。如果出現錯誤，返回NULL。

 

3.

mysql_fetch_row

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

描述

檢索結果集的下一行。在mysql_store_result()之後使用時，如果沒有要檢索的行，mysql_fetch_row()返回NULL。

在mysql_use_result()之後使用時，如果沒有要檢索的行或出現了錯誤，mysql_fetch_row()返回NULL。

結果集的列數目由mysql_num_fields(result)給出。如果行中儲存了調用mysql_fetch_row()返回的值，將按照row[0]到row[mysql_num_fields(result)-1]，訪問這些值的指標。行中的NULL值由NULL指標指明。

可以通過調用mysql_fetch_lengths()來獲得行中欄位值的長度。對於空欄位以及包含NULL的欄位，長度為0。通過檢查欄位值的指標，能夠區分它們。如果指標為NULL，欄位為NULL，否則欄位為空白。

傳回值

下一行的MYSQL_ROW結構。如果沒有更多要檢索的行或出現了錯誤，返回NULL。

 4.mysql_num_rows

my_ulonglong mysql_num_rows(MYSQL_RES *result)

mysql_num_rows()的使用取決於是否採用了mysql_store_result()或mysql_use_result()來返回結果集。如果使用了mysql_store_result()，可以立刻調用mysql_num_rows()。如果使用了mysql_use_result()，mysql_num_rows()不返回正確的值，直至檢索了結果集中的所有行為止。

5.mysql_num_fields

unsigned int mysql_num_fields(MYSQL_RES *result)

你可以從指向結果集的指標或指向串連控制代碼的指標獲得行數。如果mysql_store_result()或mysql_use_result()返回NULL，應使用串連控制代碼（因而沒有結果集指標）。在該情況下，可調用mysql_field_count()來判斷mysql_store_result()是否產生了非空結果。這樣，用戶端程式就能採取恰當的行動，而不需要知道查詢是否是SELECT語句（或類似SELECT的語句）。在下面的樣本中，介紹了執行該操作的方式。

6.mysql_fetch_row

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

檢索結果集的下一行。在mysql_store_result()之後使用時，如果沒有要檢索的行，mysql_fetch_row()返回NULL。在mysql_use_result()之後使用時，如果沒有要檢索的行或出現了錯誤，mysql_fetch_row()返回NULL。

行內值的數目由mysql_num_fields(result)給出。如果行中儲存了調用mysql_fetch_row()返回的值，將按照row[0]到row[mysql_num_fields(result)-1]，訪問這些值的指標。行中的NULL值由NULL指標指明。

可以通過調用mysql_fetch_lengths()來獲得行中欄位值的長度。對於空欄位以及包含NULL的欄位，長度為0。通過檢查欄位值的指標，能夠區分它們。如果指標為NULL，欄位為NULL，否則欄位為空白。

傳回值

下一行的MYSQL_ROW結構。如果沒有更多要檢索的行或出現了錯誤，返回NULL。