C API函數描述(S-W)

標籤：mysql   資料庫   c語言   

25.2.3.59. mysql_select_db()

int mysql_select_db(MYSQL *mysql, const char *db)

描述

使由db指定的資料庫成為由mysql指定的串連上的預設資料庫（當前資料庫）。在後續查詢中，該資料庫將是未包含明確資料庫區分符的表引用的預設資料庫。

除非已串連的使用者具有使用資料庫的許可權，否則mysql_select_db()將失敗。

返回值

0表示成功，非0值表示出現錯誤。

錯誤

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        CR_UNKNOWN_ERROR

出現未知錯誤。

25.2.3.60. mysql_set_character_set()

int mysql_set_character_set(MYSQL *mysql, char *csname)

描述

該函數用於為當前串連設定預設的字元集。字串csname指定了1個有效字元集名稱。串連校對成為字元集的預設校對。該函數的工作方式與SET NAMES語句類似，但它還能設定mysql->charset的值，從而影響了由mysql_real_escape_string()設定的字元集。

該函數是在MySQL 5.0.7中增加的。

返回值

0表示成功，非0值表示出現錯誤。

樣本：

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));

}

if (!mysql_set_charset_name(&mysql, "utf8")) 

{

    printf("New client character set: %s\n", mysql_character_set_name(&mysql));

}

25.2.3.61. mysql_set_server_option()

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

描述

允許或禁止串連的選項。選項可以取下述值之一：

MYSQL_OPTION_MULTI_STATEMENTS_ON	允許多語句支援。
MYSQL_OPTION_MULTI_STATEMENTS_OFF	禁止多語句支援。

返回值

0表示成功，非0值表示出現錯誤。

錯誤

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        ER_UNKNOWN_COM_ERROR

伺服器不支援mysql_set_server_option()（當伺服器版本低於4.1.1時），或伺服器不支援試圖設定的選項。

 25.2.3.62. mysql_shutdown()

int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)

描述

請求資料庫伺服器關閉。已串連的使用者必須具有SHUTDOWN許可權。MySQL 5.1伺服器僅支援1種關閉類型，shutdown_level必須等效於SHUTDOWN_DEFAULT。設計規划了額外的關閉層級，以便能夠選擇所需的層級。對於用舊版本libmysqlclient標頭檔編譯並調用mysql_shutdown()的動態連結可執行程式，需要與舊版的libmysqlclient動態庫一起使用。

在5.5節，“MySQL伺服器關機進程”中，介紹了關機進程。

返回值

0表示成功，非0值表示出現錯誤。

錯誤

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        CR_UNKNOWN_ERROR

出現未知錯誤。

25.2.3.63. mysql_sqlstate()

const char *mysql_sqlstate(MYSQL *mysql)

描述

返回由Null終結的字串，該字串包含關於上次錯誤的SQLSTATE錯誤碼。錯誤碼包含5個字元。‘00000‘表示無錯誤。其值由ANSI SQL和ODBC指定。關於可能取值的列表，請參見附錄B：錯誤碼和訊息。

注意，並非所有的MySQL錯誤均會被映射到SQLSTATE錯誤碼。值‘HY000‘（一般錯誤）用於未映射的錯誤。

返回值

包含SQLSTATE錯誤碼的、由Null終結的字串。

另請參見：

請參見25.2.3.14節，“mysql_errno()”。請參見25.2.3.15節，“mysql_error()”。請參見25.2.7.26節，“mysql_stmt_sqlstate()”。

25.2.3.64. mysql_ssl_set()

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

描述

使用mysql_ssl_set()，可採用SSL建立安全連線。必須在mysql_real_connect()之前調用它。

除非在用戶端庫中允許了OpenSSL支援，否則mysql_ssl_set()不作任何事。

Mysql是從mysql_init()返回的串連處理常式。其他參數的指定如下：

·        key是key檔案的路徑名。

·        cert是認證檔案的路徑名。

·        ca是認證授權檔案的路徑名。

·        capath是指向目錄的路徑名，該目錄中包含以pem格式給出的受信任SSL CA認證。

·        cipher是允許密碼的列表，用於SSL加密。

對於任何未使用的SSL參數，可為其給定NULL。

返回值

該函數總返回0。如果SSL設定不正確，當你嘗試串連時，mysql_real_connect()將返回錯誤。

25.2.3.65. mysql_stat()

char *mysql_stat(MYSQL *mysql)

描述

返回包含特定資訊的字串，該資訊與mysqladmin status命令提供的資訊類似。包括以秒為單位的正常已耗用時間，以及運行線程的數目，問題數，再載入次數，以及開啟的表數目。

返回值

描述伺服器狀態的字元集。如果出現錯誤，返回NULL。

錯誤

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        CR_UNKNOWN_ERROR

出現未知錯誤。

25.2.3.66. 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()進行檢查。請參見25.2.3.22節，“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()。

請參見25.2.13.1節，“為什麼在mysql_query()返回成功後，mysql_store_result()有時會返回NULL”.

返回值

具有多個結果的MYSQL_RES結果集合。如果出現錯誤，返回NULL。

錯誤

如果成功，mysql_store_result()將複位mysql_error()和mysql_errno()。

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_OUT_OF_MEMORY

記憶體溢出。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        CR_UNKNOWN_ERROR

出現未知錯誤。

25.2.3.67. mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

描述

返回當前串連的線程ID。該值可用作mysql_kill()的參量以殺死線程。

如果串連丟失，並使用mysql_ping()進行了再串連，線程ID將改變。這意味著你不應擷取線程ID並儲存它供以後使用。應在需要時擷取它。

返回值

當前串連的線程ID。

錯誤

無。

25.2.3.68. 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_use_result()返回的結果一起使用mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()或mysql_affected_rows()，也不應發出其他查詢，直至mysql_use_result()完成為止。（但是，提取了所有行後，mysql_num_rows()將準確返回提取的行數）。

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

使用libmysqld嵌入式伺服器時，由於在調用mysql_free_result()之前，記憶體使用量將隨著每個檢索的行增加，記憶體效益將基本喪失。

返回值

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

錯誤

如果成功，mysql_use_result()將複位mysql_error()和mysql_errno()。

·        CR_COMMANDS_OUT_OF_SYNC

以不恰當的順序執行了命令。

·        CR_OUT_OF_MEMORY

記憶體溢出。

·        CR_SERVER_GONE_ERROR

MySQL伺服器不可用。

·        CR_SERVER_LOST

在查詢過程中，與伺服器的串連丟失。

·        CR_UNKNOWN_ERROR

出現未知錯誤。

25.2.3.69. mysql_warning_count()unsigned int mysql_warning_count(MYSQL *mysql)

錯誤

返回執行前一個SQL語句期間產生的警示數目。

返回值

警示計數。

錯誤

無。