MySQL :: MySQL 5.6 リファレンスマニュアル

MySQL 5.6 リファレンスマニュアル / ... / C API 関数の概要

23.7.6 C API 関数の概要

C API で使用可能な関数について、ここで概要を説明し、あとのセクションで詳しく説明します。セクション23.7.7「C API 関数の説明」を参照してください。

表 23.4 C API 関数名と説明

関数	説明
`my_init()`	グローバル変数とスレッドセーフプログラムのスレッドハンドラを初期化します
`mysql_affected_rows()`	最後の `UPDATE`、`DELETE`、または `INSERT` クエリーによって変更/削除/挿入された行数を返します
`mysql_autocommit()`	自動コミットモードのオン/オフを切り替えます
`mysql_change_user()`	開いている接続のユーザーおよびデータベースを変更します
`mysql_character_set_name()`	現在の接続のデフォルトの文字セット名を返します
`mysql_client_find_plugin()`	プラグインへのポインタを返します
`mysql_client_register_plugin()`	プラグインを登録します
`mysql_close()`	サーバー接続を閉じます
`mysql_commit()`	トランザクションをコミットします
`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_count()`	最近のステートメントの結果カラムの数を返します
`mysql_field_seek()`	指定したカラムにカラムカーソルを置きます
`mysql_field_tell()`	最後の `mysql_fetch_field()` に使用されたフィールドカーソルの位置を返します
`mysql_free_result()`	結果セットに使用されたメモリーを解放します
`mysql_get_character_set_info()`	デフォルトの文字セットに関する情報を返します
`mysql_get_client_info()`	クライアントバージョン情報を文字列として返します
`mysql_get_client_version()`	クライアントバージョン情報を整数として返します
`mysql_get_host_info()`	接続を説明する文字列を返します
`mysql_get_proto_info()`	接続によって使用されたプロトコルバージョンを返します
`mysql_get_server_info()`	サーバーバージョン番号を返します
`mysql_get_server_version()`	サーバーのバージョン番号を整数として返します
`mysql_get_ssl_cipher()`	現在の SSL 暗号を返します
`mysql_hex_string()`	文字列を 16 進形式でエンコードします
`mysql_info()`	最近実行されたクエリーに関する情報を返します
`mysql_init()`	`MYSQL` 構造を取得するか初期化します
`mysql_insert_id()`	前のクエリーによって `AUTO_INCREMENT` カラムに対して生成された ID を返します
`mysql_kill()`	指定されたスレッドを強制終了します
`mysql_library_end()`	MySQL C API ライブラリをファイナライズします
`mysql_library_init()`	MySQL C API ライブラリを初期化します
`mysql_list_dbs()`	単純な正規表現に一致するデータベース名を返します
`mysql_list_fields()`	単純な正規表現に一致するフィールド名を返します
`mysql_list_processes()`	現在のサーバースレッドのリストを返します。
`mysql_list_tables()`	単純な正規表現に一致するテーブル名を返します
`mysql_load_plugin()`	プラグインをロードします
`mysql_load_plugin_v()`	プラグインをロードします
`mysql_more_results()`	それ以上の結果が存在するかどうかをチェックします
`mysql_next_result()`	複数結果の実行での次の結果を返すか、初期化します
`mysql_num_fields()`	結果セット内のカラムの数を返します
`mysql_num_rows()`	結果セット内の行数を返します
`mysql_options()`	`mysql_real_connect()` の接続オプションを設定します
`mysql_options4()`	`mysql_real_connect()` の接続オプションを設定します
`mysql_ping()`	サーバーへの接続が動作しているかどうかをチェックし、必要に応じて再接続します
`mysql_plugin_options()`	プラグインオプションを設定します
`mysql_query()`	NULL 終端文字列として指定された SQL クエリーを実行します
`mysql_real_connect()`	MySQL サーバーに接続します
`mysql_real_escape_string()`	SQL ステートメントで使用するために文字列内の特殊文字をエスケープし、接続の現在の文字セットを考慮します
`mysql_real_query()`	カウントされる文字列として指定された SQL クエリーを実行します
`mysql_refresh()`	テーブルおよびキャッシュをフラッシュするか、リセットします
`mysql_reload()`	サーバーに付与テーブルをリロードするように伝えます
`mysql_rollback()`	トランザクションをロールバックします
`mysql_row_seek()`	`mysql_row_tell()` から返される値を使用して、結果セット内の行オフセットにシークします
`mysql_row_tell()`	行カーソル位置を返します
`mysql_select_db()`	データベースを選択します
`mysql_server_end()`	MySQL C API ライブラリをファイナライズします
`mysql_server_init()`	MySQL C API ライブラリを初期化します
`mysql_set_character_set()`	現在の接続のデフォルトの文字セットを設定します
`mysql_set_local_infile_default()`	`LOAD DATA LOCAL INFILE` ハンドラコールバックをそれらのデフォルト値に設定します
`mysql_set_local_infile_handler()`	アプリケーション固有の `LOAD DATA LOCAL INFILE` ハンドラコールバックをインストールします
`mysql_set_server_option()`	接続のオプション (`multi-statements` など) を設定します。
`mysql_sqlstate()`	最後のエラーの SQLSTATE エラーコードを返します
`mysql_shutdown()`	データベースサーバーをシャットダウンします
`mysql_ssl_set()`	サーバーへの SSL 接続の確立を準備します
`mysql_stat()`	サーバーステータスを文字列として返します
`mysql_store_result()`	クライアントへの完全な結果セットを取得します
`mysql_thread_end()`	スレッドハンドラをファイナライズします
`mysql_thread_id()`	現在のスレッド ID を返します
`mysql_thread_init()`	スレッドハンドラを初期化します
`mysql_thread_safe()`	クライアントがスレッドセーフとしてコンパイルされた場合に 1 を返します
`mysql_use_result()`	行ごとの結果セットの取得を開始します
`mysql_warning_count()`	以前の SQL ステートメントの警告カウントを返します

アプリケーションプログラムでは、MySQL との対話にこの概要を使用してください。

mysql_library_init() を呼び出して、MySQL ライブラリを初期化します。この関数は、libmysqlclient C クライアントライブラリと libmysqld 組み込みサーバーライブラリのどちらにも存在するため、-libmysqlclient フラグでリンクして、通常のクライアントプログラムを構築するか、または -libmysqld フラグでリンクして、組み込みサーバーアプリケーションを構築するかどうかに関係なく使われます。
mysql_init() を呼び出して、接続ハンドラを初期化し、mysql_real_connect() を呼び出して、サーバーに接続します。
SQL ステートメントを発行して、それらの結果を処理します。(次の説明で、これを行う方法に関する詳細を提供します。)
mysql_close() を呼び出して、MySQL サーバーへの接続をクローズします。
mysql_library_end() を呼び出して、MySQL ライブラリの使用を終了します。

mysql_library_init() と mysql_library_end() の呼び出しの目的は、MySQL ライブラリの正しい初期化とファイナライズを提供することです。クライアントライブラリとリンクされたアプリケーションでは、それらは改善されたメモリー管理を提供します。mysql_library_end() を呼び出さない場合、メモリーのブロックは割り当てられたままになります。(これによって、アプリケーションによって使用されるメモリーの量は増えませんが、何らかのメモリーリーク検出ツールがそれに関して報告します。)組み込みサーバーとリンクされたアプリケーションでは、これらの呼び出しはサーバーを起動および停止します。

非マルチスレッド環境では、mysql_init() が必要に応じて自動的に mysql_library_init() を呼び出すため、この呼び出しを省略できます。ただし、mysql_library_init() はマルチスレッド環境でスレッドセーフでないため、mysql_library_init() を呼び出す mysql_init() もスレッドセーフでありません。スレッドを生成する前に mysql_library_init() を呼び出すか、さもなければ mysql_library_init() を呼び出すか、mysql_init() 経由で間接的に呼び出すかに関係なく、相互排他ロックを使用して、呼び出しを保護します。これは、ほかのすべてのクライアントライブラリ呼び出しの前に実行すべきです。

サーバーに接続するには、mysql_init() を呼び出して、接続ハンドラを初期化し、次にそのハンドラで (ホスト名、ユーザー名、およびパスワードなどのその他の情報とともに) mysql_real_connect() を呼び出します。接続時に、mysql_real_connect() は、reconnect フラグ (MYSQL 構造の一部) を、5.0.3 より古い API のバージョンでは 1 の値、または新しいバージョンでは 0 に設定します。このフラグの 1 の値は、切断された接続のためにステートメントを実行できない場合、諦める前にサーバーに再接続しようとすることを示します。mysql_options() に MYSQL_OPT_RECONNECT オプションを使用して、再接続動作を制御できます。接続を終了した場合、mysql_close() を呼び出して、それを終了させます。

接続がアクティブである間に、クライアントは mysql_query() または mysql_real_query() を使用して、SQL ステートメントをサーバーに送信できます。2 つの違いは、mysql_query() では、クエリーが NULL 終端文字列として指定されることを期待しますが、mysql_real_query() ではカウントされる文字列を期待することです。文字列にバイナリデータ (NULL バイトを含む可能性のある) が含まれている場合、mysql_real_query() を使用する必要があります。

SELECT 以外の各クエリー (INSERT、UPDATE、DELETE など) では、mysql_affected_rows() を呼び出すことによって、変更された (影響を受けた) 行数を調べることができます。

SELECT クエリーでは、選択された行を結果セットとして取得します。(一部のステートメントは、行を返すという点で、SELECT に似ていることに注目してください。これらには SHOW、DESCRIBE、および EXPLAIN が含まれます。これらのステートメントを SELECT ステートメントと同じように扱います。)

クライアントが結果セットを処理する方法は 2 つあります。1 つの方法は、mysql_store_result() を呼び出して、結果セット全体を一度に取得することです。この関数はサーバーからクエリーによって返されたすべての行を取得して、それらをクライアントに格納します。2 つ目の方法は、クライアントが 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() がゼロを返す場合、ステートメントはデータを返しておらず (それは 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() 関数によって、エラー情報へのアクセスを提供します。これらは最近呼び出された成功または失敗した可能性のある関数のエラーコードやエラーメッセージを返すため、エラーが発生した時期とそれが何であったかを判断できます。

PREV HOME UP NEXT