23.2.2 C API機能の概要。

23.2.2. C API機能の概要。

C API中で利用可能な機能の概要をここで一括説明し、後のセクションで各機能について詳細に説明します。項23.2.3. 「C API機能の説明」を参照してください。

機能	摘要
my_init()	グローバル変数およびスレッドに安全なプログラム中のスレッドハンドラーを初期化する。
mysql_affected_rows()	最後の`UPDATE`, `DELETE`または`INSERT`クエリーによって、負荷/削除/挿入された行の数を戻す。
mysql_autocommit()	トグルスイッチを操作して、オートコミットモードをオンまたはオフにする。
mysql_change_user()	オープン接続上のユーザーとデータベースを変更する。
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_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()	はサーバのナンバーを整数として戻します｡
mysql_get_proto_info()	は接続に使用したプロトコルバージョンを戻します。
mysql_get_server_info()	はサーバのバージョンナンバーを戻します。
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_more_results()	は更に結果が存在しているかチェックします。
mysql_next_result()	は複数ステートメントの実効において、次結果を戻し、初期化します。
mysql_num_fields()	は結果セット中のカラムのナンバーを戻します。
mysql_num_rows()	は結果セット中の列のナンバーを戻します。
mysql_options()	は`mysql_connect()`に対する接続オプションをセットします。
mysql_ping()	はサーバへの接続が作動しているかチェックし、必要に応じて再接続します。
mysql_query()	はゼロで終わるストリングとして規定されているSQLクエリーを実効します。
mysql_real_connect()	はMySQLサーバに接続します。　Connects to a MySQL server.
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_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_stat()	はサーバステータスをストリングとして戻します｡
mysql_store_result()	はクライアントに対する結果セットを一式復元します。
mysql_thread_end()	はスレッドハンドラーを最終承認します。
mysql_thread_id()	は現スレッドのIDを戻します｡
mysql_thread_init()	はスレッドハンドラーを初期化します。
mysql_thread_safe()	は、クライアントがスレッドに対して安全になるよう編集されている場合、１を戻します。
mysql_use_result()	は、列ごとに得られた結果セットを各々復元させる作業を開始させます。
mysql_warning_count()	は以前のSQLステートメントに対する警告カウントを戻します。

アプリケーションプログラムには、MySQLとの相互対話のために、この一般アウトラインを使うべきです:

mysql_library_init()を呼び出すことによって、MySQLライブラリを初期化してください。この機能は、mysqlclient C クライアントライブラリと埋め込まれたmysqldサーバライブラリの両方に存在するので、それは、-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_library_init()へのコールは除かれる恐れがあります。なぜならmysql_init()は必要に応じてそれを自動的に呼び出すからです。しかし、マルチスレッド環境では、mysql_library_init()がmysql_init()よって呼び出されると、レース条件が可能となります：mysql_library_init()はスレッドに対して安全でないので、他のクライアントライブラリを呼び出す前に、それを呼び出すべきです。

サーバに接続するには、mysql_init()を呼び出して接続ハンドラーを初期化してから、そのハンドラーを(ホストネーム、ユーザーネームおよびパスワード等の他の情報と一緒に)使って、mysql_real_connect()を呼び出してください。接続と同時に、mysql_real_connect()は、reconnectフラグ(MYSQL構造の一部)を、バージョンが5.0.3より古いAPI中にある1または新しいバージョンのAPI中にある0の値にセットします。このフラグに対する1の値は、ステートメントが失われた接続のために実効できない場合、実効を諦める前にサーバに再び接続しようとすることを示します。MYSQL_OPT_RECONNECTオプションをmysql_options()に使用して、再接続行動を制御することができます。接続を止めたい場合、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クエリーに対して、選択された列を結果セットとして取り出します。(幾つかのステートメントは、列を戻す場合のように、SELECTとなることにご注目ください。これらにはSHOW、DESCRIBE及びEXPLAINが含まれています｡これらをSELECTステートメントの場合と同じ方法で処理すべきです。)

クライアントが結果セットを処理する２つの方法があります。１つの方法は、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()を呼び出してください。

２つの復元メカニズムは相補的関係を持っています。クライアントプログラムに、それらの要件を満たす最も適切なアプローチを選択すべきです。実務においてクライアントはより共通して、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()機能を使ってエラー情報にアクセスする手段を提供します。これらは、どんなエラーがいつ起こったかを査定することを可能にして、最近呼び出した、成功するか失敗することもあり得る機能に対するにエラーコードあるいはエラーメッセージを戻します。