ここでは、C API で提供されている関数について簡単に説明します。詳細については、以降のセクションで説明します。 See 項11.1.3. 「C API 関数の説明」。
関数 | 説明 |
mysql_affected_rows() | 最後に実行された
UPDATE 、DELETE 、または
INSERT
のいずれかのクエリによって変更、削除、または挿入されたレコードの数を返す。 |
mysql_change_user() | オープンされた接続のユーザおよびデータベースを変更する。 |
mysql_character_set_name() | 接続のデフォルトのキャラクタセットの名前を返す。 |
mysql_close() | サーバ接続を切断する。 |
mysql_connect() | MySQL
サーバに接続する。この関数は廃止されているので、代わりに
mysql_real_connect()
を使用すること。 |
mysql_create_db() | データベースを作成する。この関数は廃止されているので、代わりに
SQL コマンド CREATE DATABASE
を使用すること。 |
mysql_data_seek() | クエリ結果セットの任意のレコード番号にシークする。 |
mysql_debug() | 指定された文字列で DBUG_PUSH
を実行する。 |
mysql_drop_db() | データベースを破棄する。この関数は廃止されているので、代わりに
SQL コマンド DROP DATABASE
を使用すること。 |
mysql_dump_debug_info() | デバッグ情報をログに書き込むようにサーバに指示する。 |
mysql_eof() | 結果セットの最後のレコードが読み込まれたかどうかを判定する。
この関数は廃止されており、代わりに
mysql_errno() または
mysql_error() を使用できる。 |
mysql_errno() | 最後に呼び出された MySQL 関数のエラー番号を返す。 |
mysql_error() | 最後に呼び出された MySQL 関数のエラーを返す。 |
mysql_escape_string() | 文字列に含まれる特殊文字をエスケープして、SQL ステートメントで使用できるようにする。 |
mysql_fetch_field() | テーブルの次のフィールドの型を返す。 |
mysql_fetch_field_direct() | フィールド番号で指定されたテーブルフィールドの型を返す。 |
mysql_fetch_fields() | すべてのフィールド構造体の配列を返す。 |
mysql_fetch_lengths() | 現在のレコードのすべてのカラムについてその長さを返す。 |
mysql_fetch_row() | 結果セットの次のレコードを取得する。 |
mysql_field_seek() | 指定されたカラムにカラムカーソルを移動する。 |
mysql_field_count() | 最後に実行されたクエリの結果セットのカラム数を返す。 |
mysql_field_tell() | 最後に実行された mysql_fetch_field()
で使用されたフィールドカーソルの位置を返す。 |
mysql_free_result() | 結果セットで使用したメモリを解放する。 |
mysql_get_client_info() | クライアントのバージョン情報を文字列として返す。 |
mysql_get_client_version() | クライアントのバージョン情報を整数として返す。 |
mysql_get_host_info() | 接続を記述する文字列を返す。 |
mysql_get_server_version() | サーバのバージョン番号を整数として返す(4.1 の新機能)。 |
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_escape_string() | 接続の現在のキャラクタセットを考慮して、文字列に含まれる特殊文字をエスケープし、SQL ステートメントで使用できるようにする。 |
mysql_real_query() | バイト文字列として指定されている SQL クエリを実行する。 |
mysql_reload() | 権限テーブルの再読み込みをサーバに指示する。 |
mysql_row_seek() |
mysql_row_tell()
から返された値をオフセットとして、結果セット内のレコードにシークする。 |
mysql_row_tell() | レコードカーソルの位置を返す。 |
mysql_select_db() | データベースを選択する。 |
mysql_set_server_option() | 接続のオプション(multi-statements
など)を設定する。 |
mysql_sqlstate() | 最後に発生したエラーの SQLSTATE
エラーコードを返す。 |
mysql_shutdown() | データベースサーバをシャットダウンする。 |
mysql_stat() | サーバステータスを文字列として返す。 |
mysql_store_result() | 結果セット全体を取得してクライアントに転送する。 |
mysql_thread_id() | 現在のスレッド ID を返す。 |
mysql_thread_safe() | クライアントがスレッドセーフとしてコンパイルされている場合は 1 を返す。 |
mysql_use_result() | レコード単位の結果セットの取得を開始する。 |
mysql_warning_count() | 前回実行した SQL ステートメントの警告数を返す。 |
mysql_commit() | トランザクションをコミットする(4.1 の新機能)。 |
mysql_rollback() | トランザクションをロールバックする(4.1 の新機能)。 |
mysql_autocommit() | 自動コミットモードのオン/オフを切り替える(4.1 の新機能)。 |
mysql_more_results() | まだ取得していない結果セットが存在するかどうかを調べる(4.1 の新機能)。 |
mysql_next_result() | マルチクエリを実行している場合、次の結果セットを取得し、返す(4.1 の新機能)。 |
サーバに接続するには、mysql_init()
を呼び出して接続ハンドラを初期化し、次にそのハンドラ(およびホスト名、ユーザ名、パスワードなどのその他の情報)をパラメータとして
mysql_real_connect()
を呼び出します。接続が確立したとき、mysql_real_connect()
によって reconnect
フラグ(MYSQL
構造体の一部)の値が 1
に設定されます。このフラグは、接続が切断されてクエリを実行できない場合に、そこでクエリを終了せずに、サーバへの再接続を試みることを意味します。接続が必要なくなったら、mysql_close()
を呼び出して接続を切断します。
接続がアクティブな場合、クライアントは
mysql_query()
または
mysql_real_query()
を使用してサーバに SQL
クエリを送信できます。この 2
つの違いは、mysql_query()
はクエリをヌル終端文字列として、mysql_real_query()
はクエリをバイト文字列として、それぞれ受け取ります。文字列にバイナリデータが含まれる(ヌルバイトが含まれる可能性がある)場合は、mysql_real_query()
を使用する必要があります。
非 SELECT
クエリ(たとえば、INSERT
、UPDATE
、DELETE
)を実行した場合、変更された(影響を受けた)レコードの数を知るには、mysql_affected_rows()
を呼び出します。
SELECT
クエリを実行した場合、選択されたレコードを結果セットとして取得します(注意:
SHOW
、DESCRIBE
、および
EXPLAIN
のように、レコードを返すという点で
SELECT
に似ているステートメントがあり、これらは
SELECT
ステートメントと同様に扱う必要があります)。
クライアントが結果セットを処理する方法は 2
つあります。1
つは、mysql_store_result()
を呼び出して結果セット全体を一括して取得する方法です。この関数は、クエリから返されたすべてのレコードをサーバから取得し、クライアントに保存します。もう
1 つは、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()
のメモリ要件は非常に厳しい場合があり、メモリ不足が発生する可能性は高くなります。
mysql_use_result()
の長所は、一度に 1
行のレコードしか保持しないので、クライアントが結果セットで使用するメモリが少なくてすむことです(また、メモリ割り当てのオーバヘッドが少ないので
mysql_use_result()
の実行速度も向上します)。短所は、サーバを拘束しないように各レコードに対する処理を短時間で終わらせる必要があること、結果セット内のレコードに対するランダムアクセス機能がないこと(順次アクセスのみ)、すべてのレコードを取得するまで結果セットに含まれるレコード数がわからないことです。さらに、探していた情報が順次アクセスの途中で見つかった場合でも、最後まですべてのレコードを取得する必要があります。
クライアントは API
を使用することで、クエリが
SELECT
かどうかがわからなくても、クエリに対して適切に応答する(必要に応じてレコードを取得する)ことができます。そのためには、mysql_query()
(または
mysql_real_query()
)を呼び出すたびに
mysql_store_result()
を呼び出します。この呼び出しが正常終了した場合、クエリは
SELECT
だったことになり、レコードを読み込むことができます。呼び出しが失敗した場合、mysql_field_count()
を呼び出して、この結果がクエリの結果として予想されたものだったかどうかを判断します。mysql_field_count()
が 0
を返した場合、クエリが返したデータはなく(INSERT
、UPDATE
、DELETE
などのクエリだったことを意味する)、レコードを返すクエリではなかったと判断されます。mysql_field_count()
が 0
以外の値を返した場合、レコードを返すはずのクエリが実行されたけれども、何も返さなかったと判断されます。これは、SELECT
クエリが失敗したことを意味します。ここに示した方法のコーディング例については、mysql_field_count()
の説明を参照してください。
mysql_store_result()
および
mysql_use_result()
はどちらも、結果セットを構成するフィールドに関する情報(フィールドの数、名前、型など)を取得します。レコードのフィールド情報に順次アクセスするには、mysql_fetch_field()
を繰り返し呼び出すか、またはレコードのフィールド番号を指定して
mysql_fetch_field_direct()
を呼び出します。現在のフィールドカーソルの位置を変更するには、mysql_field_seek()
を呼び出します。フィールドカーソルの位置を変更すると、その後に呼び出された
mysql_fetch_field()
の動作に影響を与えます。mysql_fetch_fields()
を呼び出すと、すべてのフィールドの情報を一括して取得できます。
エラーを検出し、報告する場合、mysql_errno()
および mysql_error()
を使用してエラー情報にアクセスします。この
2
つの関数は、最後に呼び出された、成功または失敗の可能性のある関数のエラーコードまたはエラーメッセージを返します。この結果によって、エラーが発生したタイミングとその内容を判断します。
This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.