Go to the first, previous, next, last section, table of contents.


22 MySQL クライアントツールと API

22.1 MySQL C API

C API コードは MySQL とともに配布されます。これは libmysqlclient ライブラリに含まれ、C プログラムからデータベースへ のアクセスを許します。

MySQL ソースディストリビューション内のクライアントの多くは C で書かれています。C API の使 用法を示す例を探すなら、これらのクライアントを調べてください。

他のクライアント API の多く(Java を除く全て)は、MySQL サーバと の通信にこのライブラリを使用します。そのため、例えば、他のクライアントプ ログラムで使用されるのと同じ環境変数の多くの利点を得ることができます。そ れらはライブラリから参照されるからです。これらの変数のリストについては 「14.1 様々な MySQL プログラムの概要」節 を参照して下さい。

クライアントは最大通信バッファサイズを持ちます。最初に割り当てられるバッ ファのサイズ(16K バイト)は自動的に最大サイズ(デフォルトは 24M)まで増加し ます。バッファサイズは必要に応じて増加するため、単純にデフォルトの最大制 限を増加しても、さらに内部で資源を使用することはありません。このサイズチェッ クは主に間違ったクエリと通信パケットのためのチェックです。

通信バッファは一つの SQL ステートメント(クライアントからサーバへの通信)と、 返されるデータ(サーバからクライアントへの通信)の1レコードを含むのに 十分大きくなくてはいけません。各スレッドの 通信バッファは、任意のレコードやクエリを処理するために、指定された制限まで動的 に増大します。例えば、最大 16M のデータを含む BLOB 値がある場合、 少なくとも 16M を通信バッファ制限として持つ必要があります(サーバとクライ アントの両方で)。 クライアントのデフォルトの最大値は 24M ですが、サーバの最大値のデフォルトは 1M です。これはサーバ起動時に、max_allowed_packet パラメータの 値を変更することにより、増やすことが出来ます。 「12.2.3 サーバーパラメーターのチューニング」節参照.

MySQL サーバは、各クエリ後に各通信バッファを net_buffer_length バイトに縮小します。 クライアントでは、接続に割り当てられたバッファのサイズは、接続が閉じられるまで減少しません。 クライアントメモリは接続がクローズされた時に調整されます。

スレッドプログラミングを行なう場合は、MySQL C API を --with-thread-safe-client 付きでコンパイルすべきです。これは C API を接続毎のスレッド安全にします。次の場合に限り、2つのスレッドは同じ接 続を共有できます:

2つのスレッドが同じ接続上で同時に MySQL にクエリを送信することは できません。特に mysql_query()mysql_store_result() の間 で、他のスレッドが同じ接続を使用しないことを確実にする必要があります。
多くのスレッドが mysql_store_result() で取り出された別々の結果セッ トにアクセスできます。
mysql_use_result を使用する場合、結果セットがクローズされるまで、他 のスレッドが同じ接続上で何も尋ねないことを確実にする必要があります。

22.2 C API データ型

MYSQL
この構造体は一つのデータベース接続のハンドルを表わします。これはほとんど全て の MySQL 関数に使用されます。
MYSQL_RES
この構造体はレコードを返すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)の結果を表わ します。クエリから返される情報は、この節の残りでは結果セットと呼 ばれます。
MYSQL_ROW
これはデータの1レコードの安全な型表現です。これは現在バイト文字列の配列として実 装されています。(フィールド値がバイナリデータを含むことがある場合、これを NULL 終端文字列として扱うことはできません。そのような値は内部に NULL バイトを含 むことがあるからです。) 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
フィールドの名前。null終端文字列。
char * table
このフィールドを含むテーブルの名前。計算されたフィールドでない場合のみ有 効です。計算されたフィールドでは、table 値は空文字列です。
char * def
このフィールドのデフォルト値。null終端文字列。 これは 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() を使用する場合は、この変数の値は 0 になります。
unsigned int flags
フィールドの種々のビットフラグ。flags 値は 0 または次のビットの一つ 以上の組み合わせです:
フラグの値 フラグの意味
NOT_NULL_FLAG フィールドは NULL にできない
PRI_KEY_FLAG フィールドはプライマリキーの一部である
UNIQUE_KEY_FLAG フィールドはユニークキーの一部である
MULTIPLE_KEY_FLAG フィールドは非ユニークキーの一部である
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->typeFIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_TIMESTAMP に対してテストする方をお勧めします。 次の例は 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
数値フィールドの小数部桁数。

22.3 C API 関数概要

C API には次に一覧された関数が存在します。これらの関数は次の節でかな り詳細に説明されています。 「22.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_real_escape_string() Escapes special characters in a string for use in a SQL statement taking into account the current charset of the connection.
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() NULL 終端文字列として記述された 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_start_slave() Starts slave replication thread
mysql_stat() 文字列でサーバ状態を返します。
mysql_store_result() クライアントに完全な結果セットを取り出します。
mysql_stop_slave() Stops slave replication thread
mysql_thread_id() 現在のスレッド ID を返します。
mysql_thread_save() Returns 1 if the clients are compiled as threadsafe.
mysql_use_result() 各レコードの動的結果セットを初期化します。

サーバへ接続するには、接続ハンドラを初期化するために mysql_init() を呼びだし、それから mysql_real_connect() をそのハンドラで呼びだし ます (ホスト名、ユーザ名、パスワードのような他の情報に加えて)。 Upon connection, mysql_real_connect() sets the reconnect flag (part of the MYSQL structure) to a value of 1. This flag indicates, in the event that a query cannot be performed because of a lost connection, to try reconnecting to the server before giving up. その接続で の処理が終了した時は、接続を終了させるために mysql_close() を呼びだ します。

接続が有効な間は、クライアントは mysql_query() または mysql_real_query() を使用して SQL クエリをサーバに送信できます。こ の2つの違いは、mysql_query() は NULL終端文字列としてクエリが記述さ れることを期待するのに対し、mysql_real_query() は数えられた文字列を 期待することです。文字列がバイナリデータ(NULバイトを含みことがある)を含む 場合は、mysql_real_query() を使用する必要があります。

SELECT クエリ(例えば、INSERT, UPDATE, DELETE)では、どれくらいのレコードが影響(変更)されたかを mysql_affected_rows() を呼び出すことで見つけ出すことができます。

SELECT クエリでは、選択されたレコードを結果セットとして取り出します。 (注意: いくつかのステートメントは、レコードを返すという点で SELECTに似ています。それは SHOW, DESCRIBE, EXPLAIN です。これらは SELECT ステートメントと同じ方法で扱わ れるべきです。)

クライアントが結果セットを処理するには2つの方法があります。一つ目は、 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() を呼び出し、そ れが使用していたメモリを解放して下さい。

この2つの取り出し機構は相補的なものです。クライアントプログラムは、必要に よってもっとも適切なアプローチを選択すべきです。慣例的に、クライアントは一 般に 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() が 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_errno()mysql_error() 関数の方法によって、MySQL はエラー情報へのア クセスを提供します。これらは、最後に呼び出された成功または失敗し得る関数に ついてのエラーコードとエラーメッセージを返し、エラーがいつ何で発生したかを 確定することができます。

22.4 C API 関数説明

以下の説明では、NULL の引数または戻り値は C プログラミング言語で の NULL を意味します。MySQL NULL 値ではありません。 関数は通常ポインタか整数の値を返します。しかし関数説明に記述がある場合、 ポインタを返す関数は、成功を示すために非 NULL 値を返し、エラーを示すた めに NULL を返します。整数を返す関数は、成功を示すために 0 を返し、 エラーを示すために非0を返します。``非0'' は関数説明が他に述べていない限 り、その意味になることに注意してください; 関数説明が他に述べている場合、 これらに対して 0 以外の固有の値をテストしないでください:

if (result)                   /* 正しい */
    ... error ...

if (result < 0)               /* 間違い */
    ... error ...

if (result == -1)             /* 間違い */
    ... error ...

関数がエラーを返すとき、関数説明の エラー 節が起り得るエラーの 種類を一覧しています。mysql_errno() の呼び出しによってどれが発生 したかを見つけ出すことができます。エラーを表現する文字列は mysql_error() の呼び出しによって得られます。

22.4.1 mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

22.4.1.1 説明

最後の UPDATE, DELETE, INSERT クエリによって影響さ れた(変更された)行数を返します。UPDATE, DELETE, INSERT ステート メントでの mysql_query() 直後に呼び出します。SELECT ステート メントでは、これは mysql_num_rows() に似た動きをします。

mysql_affected_rows() は現在マクロとして実装されています。

22.4.1.2 戻り値

0 より大きい整数は影響された行数または取り出された行数を示します。クエリ の WHERE 節に適合したレコードがない場合またはクエリがまだ実行され ていない場合は 0 です。クエリがエラーを返したか、SELECT クエリに ついて mysql_store_result() が呼ばれる前に mysql_affected_rows() が呼ばれた場合は -1 です。

22.4.1.3 エラー

無し。

22.4.1.4 例

mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%d products updated",mysql_affected_rows(&mysql));

22.4.2 mysql_close()

void mysql_close(MYSQL *mysql)

22.4.2.1 説明

前にオープンされた接続をクローズします。ハンドルが mysql_init() ま たは mysql_connect() で自動的に割り当てられた場合、 mysql_close()mysql で示される接続ハンドルの解放も行ない ます。

22.4.2.2 戻り値

無し。

22.4.2.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.3 mysql_connect()

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

22.4.3.1 説明

この関数は推奨されません。代わりに mysql_real_connect() の使用を お勧めします。

mysql_connect()host 上で動作している MySQL デー タベースエンジンへの接続の確立を試みます。mysql_get_client_info() を除く他のすべての API 関数を実行する前にmysql_connect() が成功終了 している必要があります。

パラメータの意味は mysql_real_connect() の対応するパラメータと同じですが、 接続パラメータは NULL にできることが異なります。この場合 C API は接 続構造体に自動的にメモリを割り当て、mysql_close() 呼び出し時にそれ を解放します。このアプローチの不利な点は接続が失敗した場合にエラーメッセー ジを取り出すことができないことです。(mysql_errno() または mysql_error() からエラー情報を得るには、正しい MYSQL ポイン タを提供する必要があります。)

22.4.3.2 戻り値

mysql_real_connect() と同じ

22.4.3.3 エラー

mysql_real_connect() と同じ

22.4.4 mysql_change_user()

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

22.4.4.1 説明

ユーザを変更し、mysql で示された接続上で、db で示されたデー タベースがデフォルト(現在の)データベースになります。その後のクエリでは、 明示的なデータベースの指定を含んでいないテーブル参照について、このデータベー スがデフォルトになります。

この関数は MySQL 3.23.3 で導入されました。

mysql_change_user() は接続されたユーザが認証されない場合、またはデー タベースを使用する権限を持っていない場合に失敗します。この場合、ユーザとデー タベースは変更されません。

デフォルトデータベースを持ちたくない場合、db パラメータを NULL に設定できます。

22.4.4.2 戻り値

成功時 0。エラーが発生した場合は非0。

22.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
データベース名が長過ぎる。

22.4.4.4 例

if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&mysql));
}

22.4.5 mysql_create_db()

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

22.4.5.1 説明

db 引数によって指定されたデータベースを作成します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL CREATE DATABASE ステートメントを発行することをお勧めします。

22.4.5.2 戻り値

データベースの作成が成功した場合は0。エラーが発生した場合は非0。

22.4.5.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.5.4 例

if(mysql_create_db(&mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database.  Error: %s\n",
           mysql_error(&mysql));
}

22.4.6 mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)

22.4.6.1 説明

クエリ結果セット中の任意のレコードにシークします。これは、結果セット構造体 がクエリのすべての結果を持っていることを要求します。そのため、 mysql_data_seek()mysql_store_result() と共にだけ使用され、 mysql_use_result() と共には使用できません。

オフセットの値は 0 から mysql_num_rows(result)-1 でなくては なりません。

22.4.6.2 戻り値

無し。

22.4.6.3 エラー

無し。

22.4.7 mysql_debug()

void mysql_debug(char *debug)

22.4.7.1 説明

与えられた文字列で DBUG_PUSH を行ないます。mysql_debug() は Fred Fish が作成した debug library を使用します。この関数を使用するためには、デバッ グをサポートするように、クライアントライブラリをコンパイルする必要があり ます。 「H.1 MySQL server のデバッグ」節参照. 「H.2 Debugging a MySQL client」節参照.

22.4.7.2 戻り値

無し。

22.4.7.3 エラー

無し。

22.4.7.4 例

次に示した呼び出しは、クライアントライブラリが、クライアントマシン上の `/tmp/client.trace' にトレースファイルを生成します:

mysql_debug("d:t:O,/tmp/client.trace");

22.4.8 mysql_drop_db()

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

22.4.8.1 説明

db 引数によって指定されたデータベースを破棄します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL DROP DATABASE ステートメントを発行することをお勧めします。

22.4.8.2 戻り値

データベースの破棄が成功した場合は0。エラーが発生した場合は非0。

22.4.8.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.8.4 例

if(mysql_drop_db(&mysql, "my_database"))
  fprintf(stderr, "Failed to drop the database: Error: %s\n",
          mysql_error(&mysql));

22.4.9 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

22.4.9.1 説明

いくつかのデバッグ情報をログにダンプするようにサーバに指示します。この動 作をするためには、接続されたユーザが process 権を持っていなけ ればなりません。

22.4.9.2 戻り値

コマンドが成功した場合は0。コマンドが失敗した場合は非0。

22.4.9.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.10 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

22.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() は非0値を返し、エラーが発生した場合 は 0 を返します。

歴史的に mysql_eof() は標準 MySQL エラー関数 mysql_errno()mysql_error() 以前に遡ります。これらのエラー 関数は同じ情報を提供するので、これらの使用が mysql_eof() よりも好ま れます。mysql_eof() は現在推奨されません。(実際、これらは多くの情 報を提供します。エラー関数はエラーが発生した時のエラーの理由を示しますが、 mysql_eof() は真偽値だけを返します。)

22.4.10.2 戻り値

エラーが発生した場合は0。結果セットの終端に達した場合は非0。

22.4.10.3 エラー

無し。

22.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));
}

22.4.11 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

22.4.11.1 説明

mysql によって指定された接続上で、最後に呼び出された API 関数の成否のエラーコー ドを返します。戻り値0はエラーが発生しなかったことを意味します。クライア ントエラーメッセージ番号は `errmsg.h' にリストされています。サーバ エラーメッセージ番号は `mysqld_error.h' にリストされています。

22.4.11.2 戻り値:

エラーコード値。エラーが発生していない場合は0。

22.4.11.3 エラー

無し。

22.4.12 mysql_error()

char *mysql_error(MYSQL *mysql)

22.4.12.1 説明

mysql によって指定された接続上で、 mysql_error() は 最後に呼び出された API 関数の成否を、エラーメッセージとして返します。 エラー発生しなかった場合は空文字列 ("") が返されます。 これは次の2つのテストが同じであることを意味します:

if(mysql_errno(&mysql))
{
    // an error occurred
}

if(mysql_error(&mysql)[0] != '\0')
{
    // an error occurred
}

クライアントエラーメッセージの言語は MySQL クラ イアントライブラリの再コンパイルで変更できます。現在はいくつかの言語で書かれた クライアントエラーメッセージを選択できます。 「10.1 MySQL がサポートしている言語は?」節参照.

22.4.12.2 戻り値

エラーを表わす文字列。 エラーが発生していない場合は空文字列。

22.4.12.3 エラー

無し。

22.4.13 mysql_escape_string()

You should use mysql_real_escape_string() instead! This is identical to mysql_real_escape_string() except that it takes the connection as the first argument. mysql_real_escape_string() will escape the string according to the current character set while mysql_escape_string() does not respect the current charset setting.

22.4.14 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

22.4.14.1 説明

結果セットの一つのフィールドの定義を MYSQL_FIELD 構造体として返しま す。結果セット内の全てのフィールドについて情報を取り出すには、この関数を繰 り返し呼んでください。mysql_fetch_field() はフィールドが残っていな いと NULL を返します。

mysql_fetch_field() は、新しい SELECT クエリを実行するたびに、 最初のフィールドについての情報を返すようにリセットされます。 mysql_fetch_field() で返されるフィールドは mysql_field_seek() の呼び出しにも影響をうけます。

テーブルを SELECT するために mysql_query() を呼び、しかしま だ mysql_store_result() を呼んでいない場合、 mysql_fetch_field()BLOB フィールドの長さの問い合わせに使 用すると、MySQL はデフォルトの blob 長 (8K bytes) を返します。 (8K サイズになるのは、MySQLBLOB の最大長を知らないから です。これはいつかコンフィグ可能になるべきです。) 一度結果セットを取り出せ ば、field->max_length は指定したクエリ内でのこのフィールドの最大値 の長さを含みます。

22.4.14.2 戻り値

現在のフィールドの MYSQL_FIELD 構造体。フィールドが残っていない場合は NULL

22.4.14.3 エラー

無し。

22.4.14.4 例

MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
    printf("field name %s\n", field->name);
}

22.4.15 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

22.4.15.1 説明

結果セットのすべての MYSQL_FIELD 構造体の配列を返します。各構造体は 結果セットの一つのフィールドのフィールド定義を提供します。

22.4.15.2 戻り値

結果セットの全ての項目の MYSQL_FIELD 構造体の配列。

22.4.15.3 エラー

無し。

22.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);
}

22.4.16 mysql_fetch_field_direct()

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

22.4.16.1 説明

結果セット中のフィールドを示すフィールド番号 fieldnr が与えられ、そ のフィールドのフィールド定義を MYSQL_FIELD 構造体として返します。こ の関数は任意のフィールドについての定義を取り出すことに使用できます。 fieldnr の値は 0 から mysql_num_fields(result)-1 の範囲にす べきです。

22.4.16.2 戻り値

指定されたフィールドの MYSQL_FIELD 構造体。

22.4.16.3 エラー

無し。

22.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);
}

22.4.17 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

22.4.17.1 説明

結果セット中の現在のレコードのフィールドの長さを返します。フィールドの値をコピーする場合、 この長さ情報は最適化にも有用です。strlen() の呼び出しを回避できる ためです。 さらに、結果セットがバイナリデータを持つ場合は、データのサイズを特定するためにこの関数を使わなければなりません。 なぜなら strlen() は NULL 文字を含むフィールドについての結果を正しく返さないからです。

空フィールドの長さと NULL 値を含むフィールドの長さは 0 です。この2 つのケースを区別する方法については、mysql_fetch_row() の説明を参照 して下さい。

22.4.17.2 戻り値

各フィールドのサイズ (終端 NUL 文字は含みません)を提供する unsigned long 整数の配列。 エラーが発生した場合は NULL

22.4.17.3 エラー

mysql_fetch_lengths() は結果セットの現在のレコードについてだけ有効 です。mysql_fetch_row() を呼び出す前、または結果の全てのレコードを 取り出した後にこれを呼んだ場合、NULL が返されます。

22.4.17.4 例

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

row = mysql_fetch_row(result);
if (row)
{
    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]);
    }
}

22.4.18 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

22.4.18.1 説明

結果セットの次のレコードを取り出します。mysql_store_result() の後に使用すると、 これ以上取り出すレコードがない時は、NULL を返します。 mysql_use_result() の後に使用するなら、 これ以上取り出すレコードがない場合やエラーが発生した場合に NULL を返します。

レコード内の値の数は mysql_num_fields(result) によって与えられます。 rowmysql_fetch_row() の呼び出しからの戻り値を保持する場 合、値へのポインタは row[0] から row[mysql_num_fields(result)-1 としてアクセスされます。レコード内の NULL 値はNULL ポインタによって示されます。

レコードのフィールド値の長さは、mysql_fetch_lengths() の呼び出しで 獲得できます。空フィールドと NULL を含むフィールドはどちらも長さ 0 を持ちます; フィールド値のポインタをチェックすることで、これらを区別でき ます。ポインタが NULL の場合、フィールドは NULL です; そうで なければフィールドは空です。

22.4.18.2 戻り値

次のレコードの MYSQL_ROW 構造体、エラーが発生したか、もう取り出すレ コードがない場合は NULL

22.4.18.3 エラー

CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.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");
}

22.4.19 mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

3.22.24 より前の MySQL バージョンを使用している場合、 unsigned int mysql_num_fields(MYSQL *mysql) を代わりに使用すべきで す。

22.4.19.1 説明

接続上の最後のクエリのフィールド数を返します。

この関数は通常 mysql_store_result()NULL を返した時(そし てこのように結果セットポインタを持っていない時)に使用されます。この場合、 mysql_store_result() が空でない結果を提供すべきかどうかを調べるため に、mysql_field_count() を呼び出すことができます。これは、クエリが SELECT(または SELECTに似た)ステートメントであるかを知るこ と無しに、クライアントプログラムに、適切な行動をとらせることができます。下 に示される例は、これをどのように行なうことができるかを説明しています。

22.4.52 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

22.4.19.2 戻り値

結果セット中のフィールド番号を表す unsigned integer。

22.4.19.3 エラー

無し。

22.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_field_count(&mysql) 呼び出しを mysql_errno(&mysql) に置き換えることです。この場合、ステートメント が SELECT かどうかを mysql_field_count() の値から推測するの ではなく、直接 mysql_store_result() からのエラーをチェックします。

22.4.20 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

22.4.20.1 説明

与えられたオフセットにフィールドカーソルを設定します。次の mysql_fetch_field() の呼び出しはそのオフセットに対応したフィールドを取 り出します。

レコードの最初にシークするには、0 の offset 値を渡してください。

22.4.20.2 戻り値

フィールドカーソルの前の値。

22.4.20.3 エラー

無し。

22.4.21 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

22.4.21.1 説明

最後の mysql_fetch_field() に使用したフィールドカーソルの位置を返 します。この値は mysql_field_seek() への引数として使用できます。

22.4.21.2 戻り値

フィールドカーソルの現在のオフセット。

22.4.21.3 エラー

無し。

22.4.22 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

22.4.22.1 説明

mysql_store_result(), mysql_use_result(), mysql_list_dbs() 等によって結果セットに割り当てられたメモリを解放 します。結果セットで何かを行なった時、mysql_free_result() を呼び 出してそれが使用したメモリを解放する必要があります。

22.4.22.2 戻り値

無し。

22.4.22.3 エラー

無し。

22.4.23 mysql_get_client_info()

char *mysql_get_client_info(void)

22.4.23.1 説明

クライアントライブラリバージョンを表わす文字列を返します。

22.4.23.2 戻り値

MySQL クライアントライブラリバージョンを表わす文字列。

22.4.23.3 エラー

無し。

22.4.24 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

22.4.24.1 説明

使用中の接続タイプを表わす文字列を返します。サーバのホスト名を含みます。

22.4.24.2 戻り値

サーバホスト名と接続タイプを表わす文字列。

22.4.24.3 エラー

無し。

22.4.25 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

22.4.25.1 説明

現在の接続に使用されているプロトコルバージョンを返します。

22.4.25.2 Return values

現在の接続に使用されているプロトコルバージョンを表わす符号無し整数値。

22.4.25.3 エラー

無し。

22.4.26 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

22.4.26.1 説明

サーバのバージョン番号を表わす文字列を返します。

22.4.26.2 戻り値

サーバのバージョン番号を表わす文字列。

22.4.26.3 エラー

無し。

22.4.27 mysql_info()

char * mysql_info(MYSQL *mysql)

22.4.27.1 説明

最も最近に実行されたクエリについての情報を文字列で返します。が、 以下に挙げる構文に限ります。 他の構文ではmysql_info()NULL を返します。 文字列の形式 はクエリの型によって様々です。次に説明します (数値は例です; 文字列はクエ リに適した値を含みます):

INSERT INTO ... SELECT ...
String format: Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
String format: Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
String format: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
String format: Records: 3 Duplicates: 0 Warnings: 0
UPDATE
String format: Rows matched: 40 Changed: 40 Warnings: 0

注意: 複数の値リストがステートメント中に記述された場合にだけ、 mysql_info() は、INSERT ... VALUES ステートメントに非 NULL値を返します。

22.4.27.2 戻り値

最も最近に実行されたクエリについての追加情報を表わす文字列。クエリに有効 な情報がない場合は NULL ポインタ。

22.4.27.3 エラー

無し。

22.4.28 mysql_init()

MYSQL * mysql_init(MYSQL *mysql)

22.4.28.1 説明

mysql_real_connect() に適した MYSQL オブジェクトの割り当て または初期化を行ないます。引数が NULL ポインタの場合、関数は新し いオブジェクトを割り当てて初期化し返します。そうでなければオブジェクトは 初期化され、オブジェクトのアドレスが返されます。新しいオブジェクトが割り 当てられた場合、mysql_close() はこのオブジェクトを解放します。

22.4.28.2 戻り値

初期化された MYSQL* ハンドル、または新しいオブジェクトを割り当て るのに十分なメモリがなかった場合は NULL ポインタ。

22.4.28.3 エラー

メモリ不足の場合は NULL が返されます。

22.4.29 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

22.4.29.1 説明

前のクエリによって AUTO_INCREMENT フィールドに生成された ID を返します。 AUTO_INCREMENT フィールドを含むテーブルに INSERT クエリを 実行した後で、この関数を使用してください。

注意: 前のクエリが AUTO_INCREMENT 値を生成しなかった場合、 mysql_insert_id()0 を返します。後のために値を保存する必 要がある場合、値を生成するクエリの直後に mysql_insert_id() を呼び出 すことに気をつけてください。

また、SQL LAST_INSERT_ID() 常に最後に生成された AUTO_INCREMENT 値を含み、クエリ間でリセットされないことに注意して下 さい。その関数の値はサーバ内で保守されるからです。

22.4.29.2 戻り値

前のクエリによって更新された AUTO_INCREMENT フィールドの値。接続上 の前のクエリがない場合、クエリが AUTO_INCREMENT 値を更新しなかった 場合には 0 が返ります。

22.4.29.3 エラー

無し。

22.4.30 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

22.4.30.1 説明

pid で指定されたスレッドを殺すようにサーバに頼みます。

22.4.30.2 戻り値

成功時0。失敗時非0。

22.4.30.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.31 mysql_list_dbs()

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

22.4.31.1 説明

サーバ上の、wild 引数で指定された簡易正規表現に適合する、データベー ス名からなる結果セットを返します。wild はワイルドカード文字 `%' または `_' を含むことができます。また、全てのデータベース に適合するように NULL ポインタにできます。mysql_list_dbs() の呼び出しはクエリ SHOW databases [LIKE wild] を実行するのと同様 です。

mysql_free_result() で結果セットを解放する必要があります。

22.4.31.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

22.4.31.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.32 mysql_list_fields()

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

22.4.32.1 説明

与えられたテーブル内の、wild 引数で指定された簡易正規表現に適合する フィールド名からなる結果セットを返します。wild はワイルドカー ド文字 `%' または `_' を含むことができます。また、全てのフィー ルドに適合するように NULL ポインタにできます。 mysql_list_fields() はクエリ SHOW COLUMNS FROM table [LIKE wild] を実行するのと同様です。

注意: mysql_list_fields() の代わりに SHOW COLUMNS FROM tbl_name の使用を勧めます。

mysql_free_result() で結果セットを解放する必要があります。

22.4.32.2 戻り値

成功時 MYSQL_RES 結果セット。エラーが発生した場合は NULL

22.4.32.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.33 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

22.4.33.1 説明

現在のサーバスレッドを示す結果セットを返します。これは mysqladmin processlistSHOW PROCESSLIST クエリで 報告されるものと同じ種類の情報です。

mysql_free_result() で結果セットを解放する必要があります。

22.4.33.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

22.4.33.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.34 mysql_list_tables()

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

22.4.34.1 説明

wild 引数で指定された簡易正規表現に適合する、現在のデータベース 内のテーブル名からなる結果セットを返します。wild はワイルドカード 文字 `%' または `_' を含むことができます。また、全てのテーブル に適合するように NULL ポインタにできます。 mysql_list_tables() はクエリ SHOW tables [LIKE wild] を実 行するのと同様です。

mysql_free_result() で結果セットを解放する必要があります。

22.4.34.2 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

22.4.34.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.35 mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

または

unsigned int mysql_num_fields(MYSQL *mysql)

二番目の形式は MySQL 3.23 以上では動作しません。MYSQL* 引 数を通す場合は、代わりに unsigned int mysql_field_count(MYSQL*mysql) を使用しなくてはいけません。

22.4.35.1 説明

結果セット中のフィールド数を返します。

注意: 結果セットへのポインタまたは接続ハンドルのいずれかからフィールドの数 を得ることができます。mysql_store_result() または mysql_user_result()NULL を返した(つまり結果セットポイン タが無い)場合、接続ハンドルを使用します。この場合、 mysql_field_count() を呼び出して、mysql_store_result() が空 でない結果を提供すべきかどうかを決定できます。これにより、クライアントプロ グラムはクエリが SELECT(または SELECT に似た)ステートメン トだったかどうかを知ることなしに、適切な行動を取ることができます。以下に示 す例はこれをどのように行なうかを説明しています。

22.4.52 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

22.4.35.2 戻り値

結果セット中のフィールド数を表わす符号無し整数。

22.4.35.3 エラー

無し。

22.4.35.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_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_errno(&mysql) コールを mysql_field_count(&mysql) が 0 かどうかのチェックに置き換えることです。これは何かが悪い場合にだけ起こり ます。

22.4.36 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

22.4.36.1 説明

結果セット中のレコード数を返します。

mysql_num_rows() の使用は、結果セットを返すのに mysql_store_result()mysql_use_result() のどちらを使用す るかに依存します。mysql_store_result() を使用する場合、 mysql_num_rows() はすぐに呼ぶことができます。 mysql_use_result() を使用する場合、結果セットの全てのレコードが取り 出されるまで、mysql_num_rows() は正しい値を返しません。

22.4.36.2 戻り値

結果セットのレコード数。

22.4.36.3 エラー

無し。

22.4.37 mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

22.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_FILEMYSQL_READ_DEFAULT_GROUP を 使用する場合、client グループが常に読まれます。

オプションファイル中に指定されるグループは次のオプションを含むことができま す:

compress 圧縮クライアント/サーバプロトコルを使用する。
database 接続命令中でデータベースが指定されない場合、このデータベースに接続する。
debug デバッグオプション
host デフォルトホスト名
init-command MySQL サーバへの接続時に実行するコマンド。再接続時に自動的に再実行される。
password デフォルトパスワード
pipe NT 上の MySQL サーバへの接続に名前付パイプを使用する。
port デフォルトポート番号
return-found-rows UPDATE 使用時、mysql_info() が更新された行の代わりに見つかった行を返すようにする。
socket デフォルトソケット番号
timeout 接続タイムアウト(秒)。
user デフォルトユーザ

オプションファイルについてのさらなる情報は、 「4.15.4 オプションファイル ( my.cnf )」節 を参照して 下さい。

22.4.37.2 戻り値

成功の場合は0。未知のオプションを使用した場合は非0。

22.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 セクションから追加オプションを読むように、クライアントに 要求します。

22.4.38 mysql_ping()

int mysql_ping(MYSQL *mysql)

22.4.38.1 説明

サーバへの接続が動作しているかどうかをチェックします。ダウンしている場合 は、自動的に再接続を試みます。

この関数は、長い間静かにしているクライアントが、サーバが接続をクローズし たかどうかをチェック(と再接続)するために使用できます。

22.4.38.2 戻り値

サーバが生きている場合0。他の値はエラーを示します。

22.4.38.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.39 mysql_query()

int mysql_query(MYSQL *mysql, const char *query)

22.4.39.1 説明

NULL 終端文字列 query で示される SQL クエリを実行します。クエリはひ とつの SQL ステートメントでなければなりません。終端のセミコロン (`;')や \g をステートメントに追加すべきではありません。

mysql_query() はバイナリデータを含むクエリには使用できません(バ イナリデータは `\0' 文字を含むことがあります。これはクエリ文字列の 最後として解釈されます)。この場合、mysql_real_query() を代わりに 使用してください。

22.4.39.2 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

22.4.39.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.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)

22.4.40.1 説明

host 上で動作している MySQL データベースエンジンへの接続 の確立を試みます。 mysql_get_client_info() 以外の他の API 関数を実行する前に、 mysql_real_connect() が成功している必要があります。

mysql_real_connect() を呼び出す前に、MYSQL 構造体を獲得ま たは初期化するために mysql_init() を呼ぶ必要があることに注意して ください。

mysql_real_connect() の最初の引数に NULL ポインタを記述す ることもできます。これは C API が接続構造体のメモリを割り当て、 mysql_close() 呼び出し時に自動的に解放されます。この方法の不利な 点は、接続が失敗した場合に mysql_real_connect() からのエラーメッ セージを取り出すことができないことです。

最初の引数が NULL ポインタでない場合は、存在する MYSQL 構 造体のアドレスであるべきです。

22.4.40.2 戻り値

接続が成功した場合は MYSQL* 接続ハンドルです。接続が失敗した場合 は C NULL ポインタです。 接続に成功すると、最初のパラメータが NULL でない場合、戻り値はそのパラ メータの値と同じです。

22.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 上の名前つきパイプの wait に失敗した。
CR_NAMEDPIPESETSTATE_ERROR;
Win32 上のパイプハンドラの獲得に失敗した。

22.4.40.4 例

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
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));
}

By using mysql_options() the MySQL library will read the [client] and your_prog_name sections in the my.cnf file which will ensure that your program will work, even if someone has set up MySQL in some not standard way.

Note that upon connection, mysql_real_connect() sets the reconnect flag (part of the MYSQL structure) to a value of 1. This flag indicates, in the event that a query cannot be performed because of a lost connection, to try reconnecting to the server before giving up.

22.4.41 mysql_real_escape_string()

unsigned int mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned int length)

22.4.41.1 説明

from の文字列を、SQL ステートメントとしてサーバに送ることができる ように、現在のキャラクタ・セットを考慮しながら変換します。 結果は to に入り、終端 null 文字を追加します。 変換される文字列は `NUL' (ASCII 0), `\n', `\r', `\', `'', `"', Control-Z です。( 「7.1 リテラル:文字列と数値をどのように書くか?」節参照).

from で示される文字列 はlength バイト長でなければなりません。 to バッファには少なくとも length*2+1 バイト長を割り当てる 必要があります。(最悪の場合、それぞれの文字が2バイトに変換されることがあ り、さらに終端 null バイトのための場所が必要です。) mysql_escape_string() が復帰するとき、to の内容は NUL 終端文字列になります。 戻り値は変換された文字列の長さです。終端 null 文字は含みません。

22.4.41.2 例

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, 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() のように働きますが、最初の引数の終りの null へのポイ ンタを返します。

22.4.41.3 戻り値

to へ置かれた値の長さ。終端 null 文字は含みません。

22.4.41.4 エラー

無し。

22.4.42 mysql_real_query()

int mysql_real_query(MYSQL *mysql, const char *query, unsigned int length)

22.4.42.1 説明

query で示される SQL クエリを実行します。これは length バ イト長です。クエリはひとつの SQL ステートメントでなければなりません。終端 のセミコロン(`;')や \g をステートメントに追加すべきではありま せん。

バイナリデータを含むクエリは mysql_real_query() を使 用しなければなりません。バイナリデータは `\0' 文字を含むこと があるからです。 また、mysql_real_query()mysql_query() よりも速いです。 クエリの strlen() を呼ばないからです。

22.4.42.2 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

22.4.42.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.43 mysql_reload()

int mysql_reload(MYSQL *mysql)

22.4.43.1 説明

MySQL サーバに、アクセス権テーブルを再読み込みするように依頼し ます。接続されたユーザは reload 権限を持つ必要があります。

この関数は推奨されません。代わりに、SQL FLUSH PRIVILEGES ステートメ ントを発行する mysql_query() の使用が推奨されます。

22.4.43.2 戻り値

成功時0。失敗時非0。

22.4.43.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.44 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

22.4.44.1 説明

レコードカーソルをクエリ結果セット中の絶対レコードに設定します。これは、結 果セット構造体がクエリのすべての結果を持っていることを要求します。そのため、 mysql_row_seek()mysql_store_result() と共にだけ使用でき、 mysql_use_result() と共には使用できません。

オフセットは mysql_row_tell() または mysql_row_seek() 呼びだ しからの戻り値であるべきです。この値は単純なレコード番号ではありません;レ コード番号を使用して結果セット内のレコードにシークしたい場合は、 mysql_data_seek() を代わりに使用してください。

22.4.44.2 戻り値

レコードカーソルの前の値。この値はその後の mysql_row_seek() 呼びだ しに渡すことができます。

22.4.44.3 エラー

無し。

22.4.45 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

22.4.45.1 説明

最後の mysql_fetch_row() についてレコードカーソルの現在の位置を返します。 この値は mysql_row_seek() への引数として使用できます。

mysql_row_tell()mysql_store_result() の後にだけ使用すべ きで、mysql_use_result() の後には使用すべきではありません。

22.4.45.2 戻り値

行カーソルの現在のオフセット。

22.4.45.3 エラー

無し。

22.4.46 mysql_select_db()

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

22.4.46.1 説明

mysql で示される現在の接続に、デフォルト(現在の)データベースとし て db で示されるデータベースを使用するように指示します。以降のク エリでは、明示的にデータベースを指定しないテーブル参照について、このデー タベースがデフォルトになります。

接続されたユーザがデータベースを使用する権限を持っていると証明されなけれ ば、mysql_select_db() は失敗します。

22.4.46.2 戻り値

成功時0。失敗時非0。

22.4.46.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.47 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

22.4.47.1 説明

データベースサーバにシャットダウンするように要求します。接続されたユーザ は shutdown 権限を持っている必要があります。

22.4.47.2 戻り値

成功時0。失敗時非0。

22.4.47.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.48 mysql_stat()

char *mysql_stat(MYSQL *mysql)

22.4.48.1 説明

mysqladmin status で提供されるのと同様の情報を文字列として返しま す。これは秒での uptime と、実行中のスレッド数、問い合わせ数、再読み込み 数、オープンテーブル数を含みます。

22.4.48.2 戻り値

サーバ状態を表わす文字列。エラーが発生した場合 NULL

22.4.48.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.49 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

22.4.49.1 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_store_result() はクエリのすべての結果をクライアントへ読み込み、 MYSQL_RES 構造体を割り当て、この構造体に結果を配置します。

返されるレコードが無い場合、空の結果セットが返されます。 (空の結果セットは NULL 戻り値とは異なります。)

一度 mysql_store_result() を呼び出したら、結果セット中にいくつのレ コードがあるかを見つけるために、mysql_num_rows() を呼び出すことがで きます。

結果セットからレコードを取り出すために mysql_fetch_row() を呼び出す ことができます。また、結果セット内の現在のレコード位置を設定/取得するため に mysql_row_seek()mysql_row_tell() を呼び出すことができ ます。

一度結果セットで行なうと、mysql_free_result() を呼び出す必要があ ります。

22.4.52 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

22.4.49.2 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL

22.4.49.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.50 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

22.4.50.1 説明

現在の接続のスレッド ID を返します。この値は、スレッドを殺すための mysql_kill() への引数として使用できます。

接続が失われて、mysql_ping() で再接続した場合、スレッド ID は変更さ れます。これはスレッド ID を後で使うために取得して格納すべきではないことを 意味します。必要な時にそれを取得すべきです。

22.4.50.2 戻り値

現在の接続のスレッド ID。

22.4.50.3 エラー

無し。

22.4.51 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

22.4.51.1 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、 mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_use_result() は結果セット検索を開始しますが, mysql_store_result() のように、実際にクライアントに結果セットを読み 取りません. 代わりに、各レコードは mysql_fetch_row() 呼びだしが行な われることにより、個々に取り出されます。 mysql_use_result() はクエリの結果を、一時テーブルやローカルバッファ に格納すること無く、サーバから直接読み込みます。これは mysql_store_result() よりもいくらか速く、少ないメモリを使用します。 この場合、クライアントは現在の行と接続バッファ ( max_allowed_packet bytes まで増加する ) のメモリだけを割り当てます。

一方、クライアント側で各行に ついて多くの処理を行なう場合や、ユーザが ^S (スクロール停止) を入 力できるような画面に出力を送る場合は、mysql_use_result() を使用す べきではありません。これはサーバと連携しており、他のスレッドが データが取り出されるテーブルを更新する事を邪魔します。

mysql_use_result() 使用時、NULL 値を取り出すまで mysql_fetch_row() を実行する必要があります。そうしないと、次のク エリは前のクエリから結果を取り出します。これを忘れると、C API はエラー Commands out of sync; You can't run this command now を与えます!

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() を呼び出す必要があ ります。

22.4.51.2 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL

22.4.51.3 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

22.4.52 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?

mysql_query() の呼び出しが成功した後に mysql_store_result()NULL を返すことがあります。これが 起こったとき、次の条件のどれかの発生を意味します:

ステートメントが空でない結果を提供するかどうかは mysql_field_count() の呼び出しによっていつでもチェックできます。 mysql_field_count() が 0 を返す場合、結果は空で最後のクエリは値を 返さないステートメントです (例えば、INSERTDELETE)。 mysql_field_count() が非 0 値を返す場合、ステートメントは空でない 結果を提供します。 例はmysql_field_count() 関数の説明を参照してください。

mysql_error() または mysql_errno() を呼び出すことによって エラーのテストもできます。

22.4.53 クエリから得られる結果は何か?

クエリによって返される結果セットに加えて、次の情報も得ることができます:

22.4.54 最後に挿入された行のユニーク ID をどのように得られるか?

AUTO_INCREMENT 属性を持つ項目を含むテーブルにレコードを挿入する場 合、mysql_insert_id() 関数で与えられた ID を得ることができます。

mysql_query() に渡すクエリ文字列内のLAST_INSERT_ID() 関数 を使用することでも、ID を取り出すことができます。

次のコードを実行することで、AUTO_INCREMENT インデックスが使用され たかどうかチェックできます。これは、クエリが AUTO_INCREMENT イン デックスを伴う INSERT だったかどうかもチェックできます:

if (mysql_error(&mysql)[0] == 0 &&
    mysql_num_fields(result) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

生成された最後の ID は接続毎にサーバ内で維持されています。他のクライアント によって変更はされません。他の AUTO_INCREMENT 項目を非マジック値 (すなわち、NULL でなく 0 でない値) で更新する場合でも、それは変更 されません。

また、他のテーブルにその ID を挿入しようとする場合、次で行なうことができます:

INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # generate ID by inserting NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # use ID in second table

22.4.55 C API でのリンクの問題

C API でリンクする時、いくつかのシステム上では次のエラーになります:

gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl

Undefined        first referenced
 symbol          in file
floor            /usr/local/lib/mysql/libmysqlclient.a(password.o)
ld: fatal: Symbol referencing errors. No output written to client

これは、あなたのシステム上では、コンパイル/リンク行の最後に、math ライブ ラリ (-lm) を含める必要があることを意味します。

22.4.56 スレッド安全クライアントを作る方法

クライアントは `ほとんど' スレッド安全です。一番大きな問題は `net.c' (ソケットから読み込みをするサブルーチンを含むファイル) が割 り込み安全でないことです。これは、サーバからの長い読み込みを中断できるよ うに、自身のアラームを持ちたいだろうという考慮で行なわれました。

標準クライアントライブラリはスレッドオプションでコンパイルされていません。

スレッド安全クライアントを得るためには、-lmysys, -lstring, -ldbug ライブラリとサーバが使用する net_serv.o を使用しま す。

スレッドクライアントを使用する時、`thr_alarm.c' ルーチンを大いに使 用できます。mysys ライブラリからのルーチンを使用する場合、覚えて おかなければならないことは my_init() を最初に呼ぶことだけです!

mysql_real_connect() を除く全ての関数は現在スレッド安全です。スレッ ド安全クライアントライブラリをコンパイルし、それをスレッド安全なマナーで使 用するための方法を、次の注意で説明します。(この mysql_real_connect() についての注意は、実際には mysql_connect() にも有効です。しかし mysql_connect() は推奨 されませんので、とにかく mysql_real_connect() を使用すべきです。)

mysql_real_connect() をスレッド安全にするためには、クライアントを次の コマンドで再コンパイルする必要があります:

shell> CPPFLAGS=-DTHREAD_SAFE_CLIENT ./configure ...

標準クライアントのリンク時に未定義シンボルのためいくつかのエラーが出るで しょう。これはデフォルトでは pthread ライブラリが含まれていないためです。

結果の `libmysqlclient.a' ライブラリはスレッド安全です。これの意味す ることは、同じ接続ハンドル(mysql_real_connect() で返される)に、同時 に2つのスレッドからクエリを行なわない限り、クライアントコードはスレッド安 全ということです; クライアント/サーバプロトコルは、与えられた接続上で同時 に一つの要求だけを許します。複数のスレッドから同じ接続を使用したい場合は、 mysql_query()mysql_store_result() の組み合わせのまわりで mutex lock を行なう必要があります。一度 mysql_store_result() の用意 ができると、ロックは解放でき、他のスレッドが同じ接続にクエリを行なうことが できます。(他の言葉で言うと、正しいロックプロトコルを使用する限り、別のス レッドは、mysql_store_result() で生成される別の MYSQL_RES ポ インタを使用できます。) POSIX スレッドでプログラムを行なう場合、 pthread_mutex_lock()pthread_mutex_unlock() を、mutex lock の確立と解放に使用できます。

mysql_store_result() でなく mysql_use_result() を使用する場 合、mysql_use_result() の回りと mysql_fetch_row() 呼び出しに ロックが必要です。しかし、スレッド化クライアントに本当に一番良いのは、 mysql_use_result() を使用しないことです。

22.5 MySQL Perl API

ここでは Perl DBI インターフェースについて述べる。 以前のインターフェースは mysqlperl であった。 DBI/DBD が Perl インターフェースとして現在推奨されているので、 mysqlperl に関してはここでは述べない。

22.5.1 DBI with DBD::mysql

DBI は多くのデーターベースとの一般的なインターフェースである。 これは、多くのデーターベースと動作するスクリプトを変更なしに書けることを意味する。 そのためには、それぞれのデータベース用のデータベースドライバ (DBD) が必要である。 MySQL では、そのドライバは DBD::mysql である。

Perl5 DBI に関する詳細は、DBIウェッブページを参照のこと:

http://www.symbolstone.org/technology/perl/DBI/index.html

Object Oriented Programming (OOP) に関する詳細は、Perl OOP ページを参照のこと:

http://language.perl.com/info/documentation.html

Installation instructions for MySQL Perl support are given in 「4.10 Perl のインストールについて」節.

22.5.1.1 The DBI interface

Portable DBI methods

connect データベースサーバと接続する
disconnect データベースサーバとの接続を切る
prepare SQL文を設定する
execute 設定されたSQL文を実行する
do SQL文を設定し、実行する
quote 挿入するためのクォート文字、または BLOB
fetchrow_array フィールドの配列として次のレコードを取り出す
fetchrow_arrayref フィールドの配列参照として次のレコードを取り出す
fetchrow_hashref ハッシュテーブルへの参照として次のレコードを取り出す
fetchall_arrayref 配列の配列として全データを取り出す
finish 命令を終了し、リソースからシステムを切り離す
rows 影響のあったレコードの数を返す
data_sources ローカルホスト上で利用できるデータベースの配列を返す
ChopBlanks fetchrow_* メソッドが空白を取り除くかどうかを管理する
NUM_OF_PARAMS 設定された命令文中の placeholder の数
NULLABLE どのフィールドに NULL 値があるか?
trace Perform tracing for debugging

MySQL 固有メソッド

insertid 最後の AUTO_INCREMENT
is_blob どのフィールドが BLOB か?
is_key どのフィールドがキーか?
is_num どのフィールドが数値型か?
is_pri_key どのフィールドがプライマリキーか?
is_not_null どのフィールドが NULL 値か? NULLABLE 参照。
length 利用可能なフィールドサイズの最大値
max_length 実際に存在しているフィールドサイズの最大値
NAME フィールド名
NUM_OF_FIELDS 返されたフィールドの数
table 返されたセットのテーブル名
type 全てのフィールドの型
_CreateDB データベースを作成する
_DropDB データベースを削除する。 ***このメソッドは危険である***

以下の節に、より詳細な Perl メソッドの解説がある。 Variables used for method return values have these meanings:

$dbh
Database handle
$sth
Statement handle
$rc
Return code (often a status)
$rv
Return value (often a row count)

汎用 DBI メソッド

Generally the 'do' statement is MUCH faster (and is preferable) than prepare/execute for statements that doesn't contain parameters.
connect($data_source, $username, $password)
データソースとのデータベース接続をするために connect を使う。 $data_source 値は DBI:driver_name: ではじめること。 DBD::mysql ドライバーを用いた connect の使用例:
$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);
ユーザー名またはパスワードが未設定の場合、 DBI は環境変数である DBI_USERDBI_PASS をそれぞれ使う。 ホスト名を指定しない場合は、'localhost' がデフォルトとなる。 ポート番号を指定しない場合は、MySQL ポート(3306) がデフォルトとなる。 As of Msql-Mysql-modules version 1.2009, the $data_source value allows certain modifiers:
mysql_read_default_file=file_name
Read `filename' as an option file. For information on option files, see 「4.15.4 オプションファイル ( my.cnf )」節.
mysql_read_default_group=group_name
The default group when reading an option file is normally the [client] group. By specifying the mysql_read_default_group option, the default group becomes the [group_name] group.
mysql_compression=1
Use compressed communication between the client and server (MySQL 3.22.3 or later).
mysql_socket=/path/to/socket
Specify the pathname of the Unix socket that is used to connect to the server (MySQL 3.21.15 or later).
Multiple modifiers may be given; each must be preceded by a semicolon. For example, if you want to avoid hardcoding the user name and password into a DBI script, you can take them from the user's `~/.my.cnf' option file instead by writing your connect call like this:
$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);
This call will read options defined for the [client] group in the option file. If you wanted to do the same thing, but use options specified for the [perl] group as well, you could use this:
$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl",
                $user, $password);
disconnect
disconnect メソッドは、データベースとのデータベースハンドルを切断する。 プログラムを終了する直前に呼び出されるのが典型的である。 例:
$rc = $dbh->disconnect;
prepare($statement)
データベースエンジンで実行するためのSQL文を設定し、execute メソッドで 使用出来るステートメントハンドル ($sth) を返す。 Typically you handle SELECT statements (and SELECT-like statements such as SHOW, DESCRIBE and EXPLAIN) by means of prepare and execute. 例:
$sth = $dbh->prepare($statement)
    or die "Can't prepare $statement: $dbh->errstr\n";
execute
execute メソッドは、設定されたSQL文を実行する。非 SELECT 文のときは、 影響のあったレコードの数を返す。 もしなんの変化もなかったなら、 execute"0E0" (これは Perl では ゼロ 扱いですが、 真 でもある) を返す。 SELECT 文のときは、SQL要求を開始するのみである。 データを操作する fetch_* メソッドの内の一つを記述する必要がある。 例:
$rv = $sth->execute
          or die "can't execute the query: $sth->errstr;
do($statement)
do メソッドはSQL文を設定・実行し、影響のあったレコードの数を返す。 このメソッドは、「非 select」文、すなわち、高度(ドライバーの限界のため)で設定できない文、 一度の実行(inserts, deletes など)で済む文のときに一般的に用いられる。 例:
$rv = $dbh->do($statement)
        or die "Can't execute $statement: $dbh- >errstr\n";
quote($string)
quote メソッドは、文字列中にエスケープ文字があるときに用いられ、 クォート文字を文の外側に付加する。 例:
$sql = $dbh->quote($string)
fetchrow_array
このメソッドはデータの次のレコードを取り出し、フィールドの値の配列として返す。 例:
while(@row = $sth->fetchrow_array) {
        print qw($row[0]\t$row[1]\t$row[2]\n);
}
fetchrow_arrayref
このメソッドはデータの次のレコードを取り出し、フィールドの値の配列への参照として返す。 例:
while($row_ref = $sth->fetchrow_arrayref) {
        print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}
fetchrow_hashref
このメソッドはデータのレコードを取り出し、名前・値のペアのフィールドを含んだ ハッシュテーブルへの参照を返す。このメソッドは、上で示した配列参照 (訳注:fetchrow_arrayref)よりもかなり効率的ではない。例:
while($hash_ref = $sth->fetchrow_hashref) {
        print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
                $hash_ref- > title}\n);
}
fetchall_arrayref
このメソッドは、SQL文より返されたデータ(レコード)の全てを得るために使う。 このメソッドは、各レコードへの参照の配列の配列への参照を返す。 入れ子のループを使ってデータを利用・表示する。例:
my $table = $sth->fetchall_arrayref
                or die "$sth->errstr\n";
my($i, $j);
for $i ( 0 .. $#{$table} ) {
        for $j ( 0 .. $#{$table->[$i]} ) {
                print "$table->[$i][$j]\t";
        }
        print "\n";
}
finish
そのステートメントハンドルからそれ以上データを取り出さないことを示す。ステートメントハンドルや、つかんでいたシステムリソースを解放するためにこのメソッドを呼び出す。例:
$rc = $sth->finish;
rows
最後の命令により、(データの更新、削除、などで)影響のあったレコードの数を返す。 このメソッドは do あるいは 非 SELECT execute 文を 実行した後に、たいてい使われる。例: Example:
$rv = $sth->rows;
NULLABLE
配列の各要素に対し、ブール値の配列への参照を返す。 TRUE であればそのフィールドに NULL 値が含まれていることを示す。例: Example:
$null_possible = $sth->{NULLABLE};
NUM_OF_FIELDS
この属性は、SELECT 文や SHOW FIELDS 文によって返された フィールドの数を示している。命令文が結果を返したかどうかをチェックするのに、 これを使うことが出来る:0値は、INSERT, DELETE または UPDATE のような非 SELECT 文を示している。例: Example:
$nr_of_fields = $sth->{NUM_OF_FIELDS};
data_sources($driver_name)
このメソッドは、'localhost' ホスト上の MySQL サーバで 利用可能なデータベースの名前を含んだ配列を返す。例:
@dbs = DBI->data_sources("mysql");
ChopBlanks
この属性は、 fetchrow_* メソッドが返り値から前後の空白を 除去するかどうかを決定する。例:
$sth->{'ChopBlanks'} =1;
trace($trace_level)
trace($trace_level, $trace_filename)
The trace method enables or disables tracing. When invoked as a DBI class method, it affects tracing for all handles. When invoked as a database or statement handle method, it affects tracing for the given handle (and any future children of the handle). Setting $trace_level to 2 provides detailed trace information. Setting $trace_level to 0 disables tracing. Trace output goes to the standard error output by default. If $trace_filename is specified, the file is opened in append mode and output for all traced handles is written to that file. Example:
DBI->trace(2);                # trace everything
DBI->trace(2,"/tmp/dbi.out"); # trace everything to /tmp/dbi.out
$dth->trace(2);               # trace this database handle
$sth->trace(2);               # trace this statement handle
You can also enable DBI tracing by setting the DBI_TRACE environment variable. Setting it to a numeric value is equivalent to calling DBI->(value). Setting it to a pathname is equivalent to calling DBI->(2,value).

MySQL 固有メソッド

The methods shown below are MySQL-specific and not part of the DBI standard. Several of them are now deprecated: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, and table. Where DBI-standard alternatives exist, they are noted below.

insertid
MySQL の特徴である AUTO_INCREMENT を使うとき、 新しい自動繰り上がり値がここに記憶される。例: Example:
$new_id = $sth->{insertid};
As an alternative, you can use $dbh->{'mysql_insertid'}.
is_blob
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドが BLOB 値であることを示す。例:
$keys = $sth->{is_blob};
is_key
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドがキーであることを示す。 例:
$keys = $sth->{is_key};
is_num
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドが数値型であることを示す。 例:
$nums = $sth->{is_num};
is_pri_key
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドがプライマリーキーであることを示す。 例:
$pri_keys = $sth->{is_pri_key};
is_not_null
配列の各要素に対し、ブール値の配列への参照を返す。FALSE であれば そのフィールドが NULL 値を含むことを示す。 例:
$not_nulls = $sth->{is_not_null};
is_not_null is deprecated; 前述の NULLABLE 属性を使用するほうが望ましい。それが DBI の標準である。
length
max_length
それぞれのメソッドは、フィールドサイズの配列への参照を返す。length 配列は、 (テーブル記述で定義された)各フィールドの利用可能最大値を示す。 max_length 配列は、テーブル中に実際に存在している最大値を示す。例:
$lengths = $sth->{length};
$max_lengths = $sth->{max_length};
NAME
フィールド名の配列への参照を返す。 例:
$names = $sth->{NAME};
table
テーブル名の配列への参照を返す。 例:
$tables = $sth->{table};
type
フィールドの型の配列への参照を返す。 例:
$types = $sth->{type};

22.5.2 DBI/DBD に関するそれ以上の情報

DBI に関するそれ以上の情報は perldoc コマンドで得られる。

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

他のフォーマットに変換するツール、pod2man, pod2html なども 使うことが出来る。

そしてもちろん、DBI の最新情報は DBI ウェッブページで見ることが出来る:

http://www.symbolstone.org/technology/perl/DBI/index.html

22.6 MySQL Eiffel wrapper

The MySQL Contrib directory contains an Eiffel wrapper written by Michael Ravits

You can also find this at: http://www.netpedia.net/hosting/newplayer/

22.7 MySQL Java connectivity (JDBC)

There are 2 supported JDBC drivers for MySQL (the twz and mm driver). You can find a copy of these at http://www.mysql.com/Contrib. For documentation consult any JDBC documentation and the drivers own documentation for MySQL specific features.

22.8 MySQL PHP API

PHP is a server-side, HTML embedded scripting language that may be used to create dynamic web pages. It contains support for accessing several databases, including MySQL. PHP may be run as a separate program, or compiled as a module for use with the Apache web server.

The distribution and documentation are available at the PHP website.

22.8.1 Common problems with MySQL and PHP

22.9 MySQL C++ APIs

Two API's is available in the MySQL Contrib directory.

22.10 MySQL Python APIs

The MySQL Contrib directory contains a Python interface written by Joseph Skinner.

You can also use the Python interface to iODBC to access a MySQL server. mxODBC

22.11 MySQL Tcl APIs

Tcl at binevolve. The Contrib directory contains a Tcl interface that is based on msqltcl 1.50.

22.12 MySQL Ruby API

以下のサイトに、Ruby の MySQL インターフェースがあります。

www.tmtm.org とみたまさひろ氏の Web ページ


Go to the first, previous, next, last section, table of contents.