my_ulonglong mysql_affected_rows(MYSQL *mysql)

説明

最後に呼び出された UPDATE によって変更されたレコード数、最後に呼び出された DELETE によって削除されたレコード数、または最後に呼び出された INSERT によって挿入されたレコード数を返します。UPDATE、DELETE、または INSERT のいずれかのステートメントについて mysql_query() を呼び出した後に、この関数を呼び出します。SELECT ステートメントの場合、mysql_affected_rows() を呼び出すと、mysql_num_rows() と同様に動作します。

戻り値

正の整数は、影響を与えた、または取得した、レコード数を示します。0 は、UPDATE によって更新されたレコードがなかったこと、クエリの WHERE 節に一致するレコードがなかったこと、またはクエリが実行されていないことを示します。-1 は、クエリがエラーを返したこと、または SELECT クエリの場合に mysql_store_result() を呼び出す前に mysql_affected_rows() が呼び出されたことを示します。

エラー

ありません。

例

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

mysqld に接続する際にフラグ CLIENT_FOUND_ROWS が指定されている場合、mysql_affected_rows() は UPDATE ステートメントの WHERE 節に一致するレコード数を返します。

注意: REPLACE コマンドで既存のレコードが新しいレコードで置き換えられた場合は mysql_affected_rows() は 2 を返します。これは、レコードが 1 行挿入された後で重複したレコードが削除されたためです。

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

説明

ユーザを変更し、db で指定されたデータベースを mysql で指定された接続のデフォルト（カレント）データベースにします。このデータベースは、その後実行されるクエリで明示的なデータベース指定子のないテーブル参照が行われる際のデフォルトになります。

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

mysql_change_user() は、指定したユーザが認証されない場合、またはそのユーザがデータベースを使用する権限を持たない場合に、失敗します。この場合、ユーザおよびデータベースは変更されません。

デフォルトデータベースを使用しない場合、db パラメータを NULL に設定します。

MySQL 4.0.6 以降、このコマンドは、新しい接続が確立した場合は常に、任意のアクティブなトランザクションの ROLLBACK の実行、すべてのテンポラリテーブルのクローズ、ロックされたすべてのテーブルのアンロック、および状態のリセットを行います。この処理は、ユーザが変更されなかった場合も必ず行われます。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

mysql_real_connect() が返すエラーと同じ。

例

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

const char *mysql_character_set_name(MYSQL *mysql)

説明

現在の接続のデフォルトのキャラクタセットを返します。

戻り値

デフォルトのキャラクタセット。

エラー

ありません。

void mysql_close(MYSQL *mysql)

説明

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

戻り値

ありません。

エラー

ありません。

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

説明

この関数は廃止されています。代わりに mysql_real_connect() を使用してください。

mysql_connect() は、host 上で実行している MySQL データベースエンジンへの接続を確立しようとします。mysql_connect() が正常終了しなければ、他の API 関数（mysql_get_client_info() を除く）を実行できません。

パラメータの意味は、mysql_real_connect() での対応するパラメータと同じですが、接続パラメータに NULL を渡すことができるという違いがあります。この場合、C API は接続構造体に自動的にメモリを割り当てます。このメモリは mysql_close() を呼び出すことによって解放されます。この方法には、接続に失敗したときにエラーメッセージを取得できないという短所があります（mysql_errno() または mysql_error() からエラー情報を取得するには有効な MYSQL ポインタを渡す必要があります）。

戻り値

mysql_real_connect() と同じです。

エラー

mysql_real_connect() と同じです。

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

説明

db パラメータで指定された名前でデータベースを作成します。

この関数は廃止されています。代わりに、mysql_query() を使用して CREATE DATABASE ステートメントを発行してください。

戻り値

データベースが正常に作成された場合は 0。エラーが発生した場合は 0 以外。

エラー

例

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

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

説明

クエリ結果セットの任意のレコードにシークします。offset 値はレコード番号を表し、0 から mysql_num_rows(stmt)-1 の範囲で指定します。

mysql_data_seek() を使用するには、結果セット構造体にクエリの結果全体が格納されている必要があるので、mysql_use_result() ではなく、mysql_store_result() とともに使用する必要があります。

戻り値

ありません。

エラー

ありません。

void mysql_debug(const char *debug)

説明

指定された文字列で DBUG_PUSH を実行します。mysql_debug() は、Fred Fish デバッグライブラリを使用します。この関数を使用するには、デバッグをサポートするためのクライアントライブラリをコンパイルする必要があります。 See 項E.1. 「MySQL サーバのデバッグ」。 See 項E.2. 「MySQL クライアントのデバッグ」。

戻り値

ありません。

エラー

ありません。

例

次のコードを実行すると、クライアントライブラリによってクライアントマシンの /tmp/client.trace にトレースファイルが生成されます。

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

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

説明

db パラメータで指定された名前のデータベースを破棄します。

この関数は廃止されています。代わりに、mysql_query() を使用して DROP DATABASE ステートメントを発行してください。

戻り値

データベースが正常に破棄された場合は 0。エラーが発生した場合は 0 以外。

エラー

例

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

int mysql_dump_debug_info(MYSQL *mysql)

説明

デバッグ情報をログに書き込むようにサーバに指示します。接続ユーザが SUPER 特権を持たない場合は正常に動作しません。

戻り値

正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

my_bool mysql_eof(MYSQL_RES *result)

説明

この関数は廃止されています。代わりに mysql_errno() または mysql_error() を使用できます。

mysql_eof() は、結果セットの最後のレコードが読み込まれたかどうかを判定します。

mysql_store_result() を呼び出して結果セットを取得する場合、クライアントは 1 回の動作で結果セット全体を受け取ります。この場合、mysql_fetch_row() を呼び出して戻り値が NULL であれば、すでに結果セットの最後に到達していたことがわかるので、mysql_eof() を呼び出す必要はありません。mysql_store_result() と一緒に使用する場合、mysql_eof() は常に true を返します。

一方、mysql_use_result() を使用して結果セットの取得を開始した場合は、mysql_fetch_row() を繰り返し呼び出すことによってそのレコードを 1 行ずつサーバから取得します。この手順を実行している途中で接続に異常が発生する場合があるので、mysql_fetch_row() を呼び出して戻り値が NULL であっても、それが必ずしも結果セットの最後に正常に到達したことを意味するわけではありません。この場合は、mysql_eof() を使用することによって、どういう状況なのかを判断できます。mysql_eof() は、結果セットの最後に到達していた場合は 0 以外、エラーが発生していた場合は 0 を返します。

mysql_eof() は、歴史的には標準の MySQL エラー関数である mysql_errno() および mysql_error() の前身です。これらのエラー関数は同じ情報を返すので、すでに廃止されている mysql_eof() よりも優先して使用してください（実際、mysql_eof() が返すのはブール値だけで、エラー関数はエラー発生理由を示すより多くの情報を返します）。

戻り値

エラーが発生していない場合は 0。結果セットの最後に到達していた場合は 0 以外。

エラー

ありません。

例

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

unsigned int mysql_errno(MYSQL *mysql)

説明

mysql_errno() は、mysql で指定される接続について、最後に呼び出された、成功または失敗する可能性のある API 関数のエラーコードを返します。戻り値が 0 の場合、エラーは発生していません。クライアントのエラーメッセージ番号の一覧は、MySQL errmsg.h ヘッダファイルに記述されています。サーバのエラーメッセージ番号の一覧は、mysqld_error.h に記述されています。MySQL ソースディストリビューションに含まれるファイル Docs/mysqld_error.txt には、すべてのエラーメッセージおよびエラー番号の一覧が記述されています。サーバのエラーコードの一覧は、項12.1. 「返されるエラー」 にも記載されています。

注意: mysql_fetch_row() などの一部の関数は、成功した場合に mysql_errno() を設定しません。

大体の目安として、サーバに情報を要求する関数は、成功した場合に mysql_errno() をリセットすると考えてください。

戻り値

最後に呼び出された mysql_xxx 関数が失敗していた場合はそのエラーコード。0 はエラーが発生しなかったことを示します。

エラー

ありません。

const char *mysql_error(MYSQL *mysql)

説明

mysql_error() は、mysql で指定された接続について、最後に呼び出された API 関数が失敗した際のエラーメッセージをヌル終端文字列として返します。関数が失敗しなかった場合、mysql_error() の戻り値はその前のエラーメッセージか、エラーがまったく発生していない場合は空文字列になります。

大体の目安として、サーバに情報を要求する関数は、成功した場合に mysql_error() をリセットすると考えてください。

mysql_errno をリセットする関数では、次の 2 つの比較は同等です。

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

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

クライアントのエラーメッセージの言語は、MySQL クライアントライブラリを再コンパイルすることによって変更できます。現在は、複数の異なる言語でエラーメッセージを返すことができます。 See 項4.7.2. 「英語以外のエラーメッセージ」。

戻り値

エラーの内容を説明するヌル終端文字列。エラーが発生していない場合は空文字列。

エラー

ありません。

この関数の代わりに mysql_real_escape_string() を使用してください。

mysql_real_escape_string() は先頭の引数として接続ハンドラを受け取り、現在のキャラクタセットに従って文字列をエスケープしますが、その 2 点を除けば、この関数と mysql_real_escape_string() は同じです。mysql_escape_string() は接続ハンドラを引数として受け取りません。また、現在のキャラクタセットは参照しません。

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

説明

結果セットに含まれる 1 つのカラムの定義を MYSQL_FIELD 構造体として返します。結果セットに含まれるすべてのカラムの定義を取得するには、この関数を繰り返し呼び出します。定義を取得するカラムが残っていない場合、mysql_fetch_field() は NULL を返します。

新しく SELECT クエリを実行するたびに、mysql_fetch_field() は先頭のカラムの定義を返すようにリセットされます。また、mysql_field_seek() を呼び出した場合も、mysql_fetch_field() が返すフィールドが変わります。

mysql_query() を呼び出してテーブルに対して SELECT を実行した後 mysql_store_result() を呼び出さなかった場合、mysql_fetch_field() を呼び出して BLOB フィールドの長さを要求すると、デフォルトの BLOB 長（8 キロバイト）が返されます（MySQL は BLOB の最大長がわからないので 8 キロバイトを返します。この値は将来設定可能な値にする必要があります）。結果セットを取得した後は、そのクエリにおけるこのカラムの最大値の長さが field->max_length に渡されます。

戻り値

現在のカラムの MYSQL_FIELD 構造体。カラムが残っていない場合は NULL。

エラー

ありません。

例

MYSQL_FIELD *field;

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

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

説明

結果セットのすべての MYSQL_FIELD 構造体の配列を返します。各構造体には、結果セットに含まれる 1 つのカラムのフィールド定義が格納されています。

戻り値

結果セットに含まれるすべてのカラムの MYSQL_FIELD 構造体の配列。

エラー

ありません。

例

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

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

説明

フィールド番号 fieldnr で指定される結果セットのカラムのフィールド定義を MYSQL_FIELD 構造体として返します。この関数を使用すれば、任意のカラムの定義を取得できます。fieldnr の値は 0 から mysql_num_fields(result)-1 の範囲で指定します。

戻り値

指定したカラムの MYSQL_FIELD 構造体。

エラー

ありません。

例

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

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

説明

結果セット内のカレントレコードのカラムの長さを返します。フィールド値をコピーしようとする場合、この関数を使用すれば strlen() を呼び出さなくても長さを取得できるので便利です。また、結果セットにバイナリデータが含まれている場合、strlen() はヌル文字が含まれるフィールドの長さを正しく返さないので、この関数を使用してデータサイズを調べる必要があります。

空のカラムおよび NULL 値を含むカラムの長さは 0 です。この 2 つを区別する方法については、mysql_fetch_row() の説明を参照してください。

戻り値

各カラムのサイズ（ヌル終端文字は数えない）を表す unsigned long 整数の配列。エラーが発生した場合は NULL。

エラー

mysql_fetch_lengths() は結果セットのカレントレコードでのみ有効です。mysql_fetch_row() を呼び出す前または結果セットのすべてのレコードを取得した後で呼び出された場合は NULL を返します。

例

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

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

説明

結果セットの次のレコードを取得します。mysql_store_result() を呼び出した後に mysql_fetch_row() を使用する場合、取得するレコードが残っていなければ NULL を返します。mysql_use_result() を呼び出した後に mysql_fetch_row() を使用する場合、取得するレコードが残っていないか、またはエラーが発生したときに NULL を返します。

レコードに含まれる値の数は mysql_num_fields(result) によって取得します。mysql_fetch_row() を呼び出してその戻り値が row に格納されている場合、値へのポインタは row[0] から row[mysql_num_fields(result)-1] のように表されます。NULL ポインタは、レコードの値が NULL 値であることを示します。

mysql_fetch_lengths() を呼び出すと、レコードのフィールド値の長さを取得できます。空のフィールドおよび NULL を含むフィールドの長さはどちらも 0 ですが、そのフィールドのポインタを調べることによってその 2 つを区別できます。ポインタが NULL の場合、フィールドの値は NULL です。それ以外の場合、フィールドは空です。

戻り値

次のレコードの MYSQL_ROW 構造体。取得するレコードが残っていないか、エラーが発生した場合は NULL。

エラー

注意: mysql_fetch_row() を 1 回呼び出してから、次に呼び出すまでの間にエラーがリセットされることはありません。

例

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

unsigned int mysql_field_count(MYSQL *mysql)

MySQL 3.22.24 より古いバージョンを使用している場合、この関数の代わりに unsigned int mysql_num_fields(MYSQL *mysql) を使用してください。

説明

現在の接続で最後に実行されたクエリの結果セットのカラム数を返します。

通常この関数は、mysql_store_result() が NULL を返したとき（結果セットポインタが返されなかったとき）に使用します。この場合、mysql_field_count() を呼び出すことによって、mysql_store_result() が正常な処理として空の結果セットを返したのかどうかを判断できます。これによって、クライアントプログラムは、クエリが SELECT（または SELECT ライクな）ステートメントかどうかを知らなくても適切な処理を実行できます。以下の例に、この処理の実現方法を示します。

See 項11.1.12.1. 「mysql_query() が正常に終了した後で mysql_store_result() が NULL を返す場合があるのはなぜか」。

戻り値

結果セットに含まれるフィールド数を表す unsigned 整数。

エラー

ありません。

例

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() が返すエラーを直接調べて判断します。

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

説明

フィールドカーソルの位置を指定されたオフセットに設定します。次に mysql_fetch_field() を呼び出すと、そのオフセットに関連付けられたカラムのフィールド定義を返します。

レコードの先頭にシークするには、offset 値に 0 を渡します。

戻り値

シークする前のフィールドカーソルの値。

エラー

ありません。

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

説明

最後に実行された mysql_fetch_field() で使用されたフィールドカーソルの位置を返します。この戻り値を、mysql_field_seek() に引数として渡すことができます。

戻り値

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

エラー

ありません。

void mysql_free_result(MYSQL_RES *result)

説明

mysql_store_result()、mysql_use_result()、mysql_list_dbs() などが結果セットに割り当てたメモリを解放します。結果セットが必要なくなったら、mysql_free_result() を呼び出して、使用していたメモリを解放します。

戻り値

ありません。

エラー

ありません。

char *mysql_get_client_info(void)

説明

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

戻り値

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

エラー

ありません。

unsigned long mysql_get_client_version(void)

説明

クライアントのライブラリバージョンを表す整数を返します。この値は XYYZZ という形式で表され、X はメジャーバージョン、YY はリリースレベル、ZZ はリリースレベル内のバージョン番号です。たとえば、40102 は、クライアントのライブラリバージョンが 4.1.2 であることを表します。

戻り値

MySQL クライアントのライブラリバージョンを表す整数。

エラー

ありません。

char *mysql_get_host_info(MYSQL *mysql)

説明

使用している接続のタイプを表す文字列を返します。この文字列にはサーバのホスト名も含まれます。

戻り値

サーバのホスト名および接続タイプを表す文字列。

エラー

ありません。

unsigned int mysql_get_proto_info(MYSQL *mysql)

説明

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

戻り値

現在の接続に使用しているプロトコルのバージョンを表す unsigned 整数。

エラー

ありません。

char *mysql_get_server_info(MYSQL *mysql)

説明

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

戻り値

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

エラー

ありません。

unsigned long mysql_get_server_version(MYSQL *mysql)

説明

サーバのバージョン番号を整数として返します（4.1 の新機能）。

戻り値

MySQL サーバのバージョンを次の形式で表す番号。

main_version*10000 + minor_version *100 + sub_version

たとえば、バージョンが 4.1.0 の場合、戻り値は 40100 です。

この値を使用すると、クライアントプログラムはサーバのバージョンから特定の機能が存在するかどうかを簡単に判断できます。

エラー

ありません。

char *mysql_info(MYSQL *mysql)

説明

最後に実行したクエリに関する情報を表す文字列を取得します。ただし、対象となるのは、以下の一覧に含まれるステートメントだけです。最後に実行したのが他のステートメントのクエリだった場合は、mysql_info() は NULL を返します。文字列の形式は、以下に説明するように、クエリのタイプによって異なります。数字は例として示したものです。実際の文字列には実行したクエリに即した値が使用されます。

注意: mysql_info() は、INSERT ... VALUES ステートメントが複数レコードを挿入する形式の場合に限り（複数の値リストが指定された場合に限り）、NULL 以外の値を返します。

戻り値

最後に実行したクエリに関する情報を表す文字列。クエリの情報がない場合は NULL。

エラー

ありません。

MYSQL *mysql_init(MYSQL *mysql)

説明

mysql_real_connect() に適応する MYSQL オブジェクトを割り当て、または初期化します。mysql に NULL ポインタを渡した場合、関数は新しいオブジェクトにメモリを割り当て、初期化し、それを返します。それ以外の値を渡した場合は、オブジェクトを初期化し、そのアドレスを返します。mysql_init() が新しいオブジェクトにメモリを割り当てた場合、そのメモリは mysql_close() を呼び出して接続をクローズする際に解放されます。

戻り値

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

エラー

メモリが不足していた場合は NULL を返します。

my_ulonglong mysql_insert_id(MYSQL *mysql)

説明

前回実行されたクエリで生成した AUTO_INCREMENT カラムの ID を返します。この関数は、AUTO_INCREMENT フィールドを含むテーブルに対して INSERT クエリを実行した後で使用します。

注意: mysql_insert_id() は、前回実行されたクエリで AUTO_INCREMENT 値が生成されなかった場合は、0 を返します。将来のためにその値を保存する必要がある場合は、それを生成するクエリの直後に mysql_insert_id() を呼び出す必要があります。

前回実行されたクエリがエラーを返した場合については、mysql_insert_id() の値は未定義です。

mysql_insert_id() は、AUTO_INCREMENT 値を生成するか、またはカラム値を LAST_INSERT_ID(expr) に設定する INSERT ステートメントおよび UPDATE ステートメントの実行後に更新されます。 See 項6.3.6.2. 「その他の各種関数」。

注意: SQL LAST_INSERT_ID() 関数の値には、必ず最後に生成された AUTO_INCREMENT 値が含まれます。この値はサーバに保持されるので、あるクエリを実行してから次のクエリを実行するまでの間にリセットされることはありません。

戻り値

前回実行されたクエリによって更新された AUTO_INCREMENT フィールドの値。現在の接続でまだ 1 回もクエリが実行されていなかった場合、または前回実行されたクエリで AUTO_INCREMENT 値が更新されなかった場合、0 を返します。

エラー

ありません。

int mysql_kill(MYSQL *mysql, unsigned long pid)

説明

pid で指定するスレッドを強制終了するように、サーバに要求します。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

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

説明

サーバ上のデータベースから wild パラメータで指定される単純な正規表現に一致するデータベース名を検索し、結果セットとして返します。wild にはワイルドカード文字として ‘%’ または ‘_’ を使用できます。NULL ポインタを指定した場合はすべてのデータベース名が一致します。mysql_list_dbs() を呼び出すと、クエリ SHOW databases [LIKE wild] を実行した場合と同じ結果が得られます。

結果セットに割り当てられたメモリを解放するには、mysql_free_result() を呼び出す必要があります。

戻り値

正常終了した場合は MYSQL_RES 結果セット。エラーが発生した場合は NULL。

エラー

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

説明

指定されたテーブルのフィールドから wild パラメータで指定される単純な正規表現に一致するフィールド名を検索し、結果セットとして返します。wild にはワイルドカード文字として ‘%’ または ‘_’ を使用できます。NULL ポインタを指定した場合はすべてのフィールド名が一致します。mysql_list_fields() を呼び出すと、クエリ SHOW COLUMNS FROM tbl_name [LIKE wild] を実行した場合と同じ結果が得られます。

注意: mysql_list_fields() の代わりに SHOW COLUMNS FROM tbl_name を使用することを推奨します。

結果セットに割り当てられたメモリを解放するには、mysql_free_result() を呼び出す必要があります。

戻り値

正常終了した場合は MYSQL_RES 結果セット。エラーが発生した場合は NULL。

エラー

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

説明

現在のサーバスレッドの一覧を表す結果セットを返します。これは、mysqladmin processlist または SHOW PROCESSLIST クエリが返す情報と同じタイプの情報です。

結果セットに割り当てられたメモリを解放するには、mysql_free_result() を呼び出す必要があります。

戻り値

正常終了した場合は MYSQL_RES 結果セット。エラーが発生した場合は NULL。

エラー

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

説明

現在のデータベースから wild パラメータで指定される単純な正規表現に一致するテーブル名を検索し、結果セットとして返します。wild にはワイルドカード文字として ‘%’ または ‘_’ を使用できます。NULL ポインタを指定した場合はすべてのテーブル名が一致します。mysql_list_tables() を呼び出すと、クエリ SHOW tables [LIKE wild] を実行した場合と同じ結果が得られます。

結果セットに割り当てられたメモリを解放するには、mysql_free_result() を呼び出す必要があります。

戻り値

正常終了した場合は MYSQL_RES 結果セット。エラーが発生した場合は NULL。

エラー

unsigned int mysql_num_fields(MYSQL_RES *result)

または

unsigned int mysql_num_fields(MYSQL *mysql)

2 番目の形式は、MySQL 3.22.24 以降では動作しません。MYSQL* 引数を渡すには、この関数の代わりに unsigned int mysql_field_count(MYSQL *mysql) を使用する必要があります。

説明

結果セットのカラム数を返します。

注意: 結果セットへのポインタまたは接続ハンドルへのポインタのどちらを使用しても、カラム数を取得できます。mysql_store_result() または mysql_use_result() が NULL を返した場合（結果セットポインタが返されなかった場合）は、接続ハンドルを使用します。この場合、mysql_field_count() を呼び出すことによって、mysql_store_result() が正常な処理として空の結果セットを返したのかどうかを判断できます。これによって、クライアントプログラムは、クエリが SELECT（または SELECT ライクな）ステートメントかどうかを知らなくても適切な処理を実行できます。以下の例に、この処理の実現方法を示します。

See 項11.1.12.1. 「mysql_query() が正常に終了した後で mysql_store_result() が NULL を返す場合があるのはなぜか」。

戻り値

結果セットに含まれるフィールド数を表す unsigned 整数。

エラー

ありません。

例

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 を返すかどうかを調べる方法もあります。これは、0 を返すのは、何らかの異常が発生した場合だけだからです。

my_ulonglong mysql_num_rows(MYSQL_RES *result)

説明

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

mysql_num_rows() の使い方は、mysql_store_result() と mysql_use_result() のどちらを使用して結果セットを取得するかによって決まります。mysql_store_result() を使用する場合、すぐに mysql_num_rows() を呼び出すことができます。mysql_use_result() を使用する場合、結果セットに含まれるすべてのレコードを取得するまでは、mysql_num_rows() は正しい値を返しません。

戻り値

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

エラー

ありません。

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

説明

この関数を使用して、接続オプションを追加設定し、接続の動作を変えることができます。この関数を複数回呼び出すことで、複数のオプションを設定できます。

mysql_options() は、mysql_init() を実行してから mysql_connect() または mysql_real_connect() を呼び出すまでの間に呼び出す必要があります。

option 引数は、設定するオプションです。arg 引数はそのオプションに設定する値です。オプションが整数の場合、arg には整数値へのポインタを渡す必要があります。

設定可能なオプションの値を次に示します。

注意: MYSQL_READ_DEFAULT_FILE または MYSQL_READ_DEFAULT_GROUP を使用する場合は、グループ client が常に読み込まれます。

オプション設定ファイルの指定されたグループには以下のオプションを指定可能です。

注意: timeout の代わりに connect-timeout が提供されていますが、timeout もしばらくは使用できます。

オプション設定ファイルの詳細については、項4.1.2. 「my.cnf オプション設定ファイル」 を参照してください。

戻り値

正常終了した場合は 0。不明なオプションを使用した場合は 0 以外。

例

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 セクションのオプションを追加で読み込むことを、クライアントに要求しています。

int mysql_ping(MYSQL *mysql)

説明

サーバへの接続が正常かどうかを確認します。切断されていた場合は、自動的に再接続を試みます。

長時間にわたってアイドル状態だったクライアントはこの関数を使用することによって、サーバによって接続が切断されていないかどうかを調べて、必要なら再接続することができます。

戻り値

サーバとの接続が正常な場合は 0。エラーが発生した場合は 0 以外。

エラー

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

説明

ヌル終端文字列 query で指定された SQL クエリを実行します。このクエリは単一 SQL ステートメントで構成されている必要があります。このステートメントには、その終わりを示すセミコロン（‘;’）または \g を追加する必要はありません。

mysql_query() はバイナリデータを含むクエリを扱うことができません。そのようなクエリでは代わりに mysql_real_query() を使用する必要があります（バイナリデータには '\0' が含まれる可能性があり、mysql_query() はそれをクエリ文字列の終わりとして解釈してしまうため）。

クエリが結果セットを返すタイプかどうかを調べるには、mysql_field_count() を使用します。 See 項11.1.3.20. 「mysql_field_count()」。

戻り値

クエリが正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

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 long client_flag)

説明

mysql_real_connect() は、host で動作している MySQL データベースエンジンへの接続を確立しようとします。mysql_real_connect() が正常終了しなければ、他の API 関数（mysql_get_client_info() を除く）を実行できません。

パラメータの指定方法を次に示します。

戻り値

接続が正常に確立した場合は MYSQL* 接続ハンドル。接続が確立しなかった場合は NULL。接続が確立した場合、戻り値は 1 つ目のパラメータの値と同じです。

エラー

例

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

この例では mysql_options() を呼び出して MySQL ライブラリが my.cnf ファイルの [client] および [your_prog_name] セクションを読み込むように設定しています。このように設定することで、非標準的な方法でセットアップされた MySQL に対してもこのプログラムが正常に動作することを保証します。

注意: 接続が確立したとき、mysql_real_connect() によって reconnect フラグ（MYSQL 構造体の一部）の値が 1 に設定されます。このフラグは、接続が切断されてクエリを実行できない場合に、そこでクエリを終了せずに、サーバへの再接続を試みることを意味します。

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

説明

この関数は、SQL ステートメントで使用できる正当な SQL 文字列を作成するために使用します。 See 項6.1.1.1. 「文字列」。

from に指定した文字列が、エスケープされた SQL 文字列にエンコードされます。この際、接続の現在のキャラクタセットが考慮されます。エンコードした結果は to に設定され、末尾には文字列の終わりを示すヌルバイトが付加されます。エンコードされる文字は、NUL（ASCII 0）、'\n'、'\r'、‘\’、‘'’、‘"’、および Ctrl-Z キー（see 項6.1.1. 「リテラル:文字列と数値の記述方法」）です（厳密に言えば、MySQL でエスケープする必要があるのはクエリ内で文字列を引用するためのバックスラッシュおよび引用符だけですが、この関数ではログファイルを読みやすくするために他の文字もエスケープします）。

from で指定する文字列の長さは length バイトである必要があります。to バッファには、少なくとも length*2+1 バイトのメモリを割り当てる必要があります（最悪の場合、1 文字エンコードするのに 2 バイトが必要な可能性があり、さらに文字列の終わりを示すヌルバイトを格納する必要があります）。mysql_real_escape_string() が復帰したとき、to にはヌル終端文字列が格納されています。戻り値はエンコード後の文字列の長さです。ただし、文字列の終わりを示すヌルバイトは含みません。

例

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() と同様の処理を行いますが、1 つ目のパラメータで指定された文字列の終わりを示すヌルバイトへのポインタを返します。

戻り値

to に設定された値の長さ。ただし、文字列の終わりを示すヌルバイトは含みません。

エラー

ありません。

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

説明

query で指定した文字列で表される SQL クエリを実行します。この文字列の長さは length バイトである必要があります。このクエリは単一 SQL ステートメントで構成されている必要があります。このステートメントには、その終わりを示すセミコロン（‘;’）または \g を追加する必要はありません。

バイナリデータには '\0' 文字が含まれる可能性があるので、そのようなデータを含むクエリの場合は、mysql_query() ではなく、mysql_real_query() を使用する必要があります。また、mysql_real_query() はクエリ文字列に対して strlen() を呼び出さないので、mysql_query() よりも高速に動作します。

クエリが結果セットを返すタイプかどうかを調べるには、mysql_field_count() を使用します。 See 項11.1.3.20. 「mysql_field_count()」。

戻り値

クエリが正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

int mysql_reload(MYSQL *mysql)

説明

権限テーブルの再読み込みを MySQL サーバに要求します。接続ユーザには RELOAD 特権が必要です。

この関数は廃止されています。代わりに、mysql_query() を使用して FLUSH PRIVILEGES ステートメントを発行してください。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

説明

クエリ結果セットの任意のレコードにローカーソルを設定します。offset の値はレコードオフセットであり、mysql_row_tell() または mysql_row_seek() の戻り値になります。この値はレコード番号ではありません。結果セット内のレコードに番号を指定してシークする場合は、この関数ではなく、mysql_data_seek() を使用します。

mysql_row_seek() を使用するには、結果セット構造体にクエリの結果全体が格納されている必要があるので、mysql_use_result() ではなく、mysql_store_result() とともに使用する必要があります。

戻り値

シークする前のレコードカーソルの値。mysql_row_seek() を次に呼び出すときにこの値を渡すことができます。

エラー

ありません。

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

説明

最後に実行された mysql_fetch_row() で使用されたレコードカーソルの現在の位置を返します。この戻り値を、mysql_row_seek() に引数として渡すことができます。

mysql_row_tell() は、mysql_use_result() の後ではなく、mysql_store_result() の後でのみ使用できます。

戻り値

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

エラー

ありません。

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

説明

db で指定されたデータベースを mysql で指定された接続のデフォルト（カレント）データベースにします。このデータベースは、その後実行されるクエリで明示的なデータベース指定子のないテーブル参照が行われる際のデフォルトになります。

接続ユーザがデータベースを使用する権限を持つユーザとして認証されない場合、mysql_select_db() は失敗します。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

説明

接続のオプションを有効または無効にします。option には以下のどちらかの値を指定できます。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

int mysql_shutdown(MYSQL *mysql)

説明

データベースサーバにシャットダウンするように要求します。接続ユーザには SHUTDOWN 特権が必要です。

戻り値

正常終了した場合は 0。エラーが発生した場合は 0 以外。

エラー

const char *mysql_sqlstate(MYSQL *mysql)

説明

最後に発生したエラーの SQLSTATE エラーコードを含むヌル終端文字列を返します。エラーコードは 5 文字で示されます。'00000' は、``エラーがない'' ことを意味します。値は ANSI SQL および ODBC によって規定されています。考えられる値の一覧については、項12.1. 「返されるエラー」 を参照してください。

注意: すべての MySQL エラーが SQLSTATE にマッピングされているわけではありません。マッピングされていないエラーの場合は 'HY000'（一般エラー）が使用されます。

この関数は MySQL 4.1.1 で追加されました。

戻り値

SQLSTATE エラーコードを含むヌル終端文字列。

関連項目

See 項11.1.3.12. 「mysql_errno()」。 See 項11.1.3.13. 「mysql_error()」。 See 項11.1.7.18. 「mysql_stmt_sqlstate()」。

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

mysql_ssl_set() は、クライアントライブラリで OpenSSL サポートが有効になっていない場合は何もしません。

mysql は、mysql_init() から返された接続ハンドラです。他のパラメータの指定方法を次に示します。

使用しない SSL パラメータには NULL を指定できます。

戻り値

この関数は常に 0 を返します。SSL が正しくセットアップされていない場合、接続を試みると mysql_real_connect() がエラーを返します。

char *mysql_stat(MYSQL *mysql)

説明

mysqladmin status コマンドの出力と同じ情報を含む文字列を返します。この情報には、使用可能時間（秒単位）、実行中のスレッド数、質問の数、再ロード回数、およびオープンされているテーブルの数が含まれます。

戻り値

サーバステータスを表す文字列。エラーが発生した場合は NULL。

エラー

MYSQL_RES *mysql_store_result(MYSQL *mysql)

説明

正常にデータを取得したクエリ（SELECT、SHOW、DESCRIBE、EXPLAIN）については、mysql_store_result() または mysql_use_result() を呼び出す必要があります。

他のクエリでは mysql_store_result() または mysql_use_result() を呼び出す必要はありませんが、すべてのケースで mysql_store_result() を呼び出しても、異常が発生したり、目立った動作が行われるようなことはありません。mysql_store_result() が 0 を返すかどうかを調べることで、クエリで結果セットが生成されたかどうかを検出できます。これについては後述します。

クエリが結果セットを返すタイプかどうかを調べるには、mysql_field_count() を使用します。 See 項11.1.3.20. 「mysql_field_count()」。

mysql_store_result() は、クエリの結果セット全体をクライアントに読み込み、MYSQL_RES 構造体にメモリを割り当て、この構造体に結果セットを格納します。

クエリが結果セットを返さない場合（たとえば、クエリが INSERT ステートメントだった場合）、mysql_store_result() はヌルポインタを返します。

また、結果セットの読み込みに失敗した場合も、mysql_store_result() はヌルポインタを返します。エラーが発生したかどうかを調べるには、mysql_error() がヌルポインタを返さないかどうか、mysql_errno() が 0 以外の値を返すかどうか、または mysql_field_count() が 0 以外の値を返すかどうかを調べます。

返すレコードが存在しない場合は空の結果セットが返されます（空の結果セットは、戻り値としてのヌルポインタとは異なります）。

mysql_store_result() を呼び出して、戻り値がヌルポインタ以外だった場合、mysql_num_rows() を呼び出すと結果セットに含まれるレコード数を取得できます。

mysql_fetch_row() を呼び出すと、結果セットからレコードを取得できます。mysql_row_seek() および mysql_row_tell() を呼び出すと、結果セット内のカレントレコードの位置を設定および取得できます。

結果セットが必要なくなったら、mysql_free_result() を呼び出す必要があります。

See 項11.1.12.1. 「mysql_query() が正常に終了した後で mysql_store_result() が NULL を返す場合があるのはなぜか」。

戻り値

結果セットが格納された MYSQL_RES 構造体。エラーが発生した場合は NULL。

エラー

mysql_store_result() は、正常終了した場合に mysql_error および mysql_errno をリセットします。

unsigned long mysql_thread_id(MYSQL *mysql)

説明

現在の接続のスレッド ID を返します。この戻り値を、mysql_kill() に引数として渡してスレッドを強制終了することができます。

現在の接続が切断され、mysql_ping() を使用して再接続した場合、スレッド ID は別の値になります。これは、取得したスレッド ID を保管して後で使用することはできないことを意味します。スレッド ID が必要になったときに、取得する必要があります。

戻り値

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

エラー

ありません。

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() を呼び出して、1 行ずつ個別に取得する必要があります。その場合、クエリの結果は直接サーバから読み込まれ、テンポラリテーブルやローカルバッファには格納されません。これは mysql_store_result() を使用する場合よりも多少高速であり、使用するメモリも少なくてすみます。クライアントは、カレントレコードおよび max_allowed_packet バイトまで増える可能性のある通信バッファにメモリを割り当てるだけです。

一方、それぞれのレコードに対するクライアント側での処理量が多い場合、またはユーザが ^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() を呼び出す必要があります。

戻り値

MYSQL_RES 構造体。エラーが発生した場合は NULL。

エラー

mysql_use_result() は、正常終了した場合に mysql_error および mysql_errno をリセットします。

unsigned int mysql_warning_count(MYSQL *mysql)

説明

前回実行された SQL ステートメントの実行中に発生した警告数を返します。この関数は、MySQL 4.1 で追加されました。

戻り値

警告数。

エラー

ありません。

my_bool mysql_commit(MYSQL *mysql)

説明

現在のトランザクションをコミットします。この関数は、MySQL 4.1 で追加されました。

戻り値

正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

ありません。

my_bool mysql_rollback(MYSQL *mysql)

説明

現在のトランザクションをロールバックします。この関数は、MySQL 4.1 で追加されました。

戻り値

正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

ありません。

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

説明

mode が 1 の場合は自動コミットモードを有効に、mode が 0 の場合は無効にします。この関数は、MySQL 4.1 で追加されました。

戻り値

正常に動作した場合は 0。エラーが発生した場合は 0 以外。

エラー

ありません。

my_bool mysql_more_results(MYSQL *mysql)

説明

現在実行しているクエリの他にまだ取得していない結果セットが存在し、アプリケーションが mysql_next_result() を呼び出して取得する必要がある場合は、true を返します。この関数は、MySQL 4.1 で追加されました。

戻り値

取得されていない結果セットが存在する場合は TRUE（1）。取得されていない結果セットが存在しない場合は FALSE（0）。

注意: ほとんどの場合、この関数の代わりに mysql_next_result() を呼び出して取得されていない結果セットがあるかどうかを調べて、存在する場合は次の結果セットを開始します。

See 項11.1.8. 「C API における複数クエリの実行の取り扱い」。 See 項11.1.3.63. 「mysql_next_result()」。

エラー

ありません。

int mysql_next_result(MYSQL *mysql)

説明

取得されていない結果セットが存在する場合、mysql_next_result() は次のクエリの結果セットを読み込み、ステータスをアプリケーションに返します。この関数は、MySQL 4.1 で追加されました。

注意: 前のクエリが結果セットを返していた場合、mysql_free_result() を呼び出す必要があります。

mysql_next_result() を呼び出した後、接続の状態は次のクエリについて mysql_real_query() を呼び出した後と同様になります。これは、この関数を呼び出した後、この接続で mysql_store_result()、mysql_warning_count()、mysql_affected_rows() などを呼び出すことができることを意味します。

mysql_next_result() がエラーを返した場合、他のステートメントは実行されません。また、取得されていない結果セットも存在しません。

See 項11.1.8. 「C API における複数クエリの実行の取り扱い」。

戻り値

呼び出しが正常に動作し、取得する結果セットが存在していた場合は 0、取得する結果セットが存在しなかった場合は -1、エラーが発生した場合は正の値。

エラー

MYSQL_STMT * mysql_prepare(MYSQL *mysql, const char *query, unsigned long length)

説明

ヌル終端文字列 query で指定された SQL クエリをプリコンパイルし、その後の処理に使用するステートメントハンドルを返します。このクエリは単一 SQL ステートメントで構成されている必要があります。このステートメントには、その終わりを示すセミコロン（‘;’）または \g を追加する必要はありません。

アプリケーションは、SQL 文字列の適当な位置に疑問符（‘?’）を埋め込むことで、SQL ステートメントで 1 つ以上のパラメータマーカーを使用できます。

マーカーは、SQL ステートメントの特定の位置に埋め込まれた場合にのみ適正に処理されます。たとえば、マーカーは INSERT ステートメントの VALUES() のリストでレコードに設定するカラムの値を指定する部分、または WHERE 節でカラムの値と比較する値を指定する部分に使用できます。しかし、SELECT ステートメントが返すカラムを指定する選択リストで識別子（テーブルまたはカラムの名前など）として使用したり、等号（=）などのバイナリ演算子の両方のオペランドを指定することはできません。パラメータの型を決定することができないので、後者の制約が必要になります。一般に、パラメータは、データ操作言語（DML）ステートメントでのみ適正に処理され、データ定義言語（DDL）ステートメントでは処理されません。

パラメータマーカーは、ステートメントを実行する前に、mysql_bind_param() を使用してアプリケーション変数にバインドする必要があります。

戻り値

コンパイルが正常に終了した場合は MYSQL_STMT 構造体へのポインタ。エラーが発生した場合は NULL。

エラー

コンパイルが失敗した場合（mysql_prepare() が NULL を返した場合）、エラーメッセージは mysql_error() を呼び出すことによって取得できます。

例

mysql_prepare() の使用方法については、項11.1.7.5. 「mysql_execute()」 の「例」を参照してください。

unsigned long mysql_param_count(MYSQL_STMT *stmt)

説明

プリコンパイルされたステートメントに含まれるパラメータマーカーの数を返します。

戻り値

ステートメントに含まれるパラメータ数を表す unsigned long 整数。

エラー

ありません。

例

mysql_param_count() の使用方法については、項11.1.7.5. 「mysql_execute()」 の「例」を参照してください。

MYSQL_RES *mysql_get_metadata(MYSQL_STMT *stmt)

説明

mysql_prepare() に渡されたステートメントが結果セットを生成するものである場合、mysql_get_metadata() は MYSQL_RES 構造体へのポインタという形で結果セットメタデータを返します。この構造体を使用して、フィールドの合計数および個々のフィールド情報などのメタ情報を処理できます。この結果セットへのポインタは、結果セットメタデータを処理する以下のフィールドベースの API 関数に引数として渡すことができます。

結果セット構造体は、使用する必要がなくなったら mysql_free_result() に渡して解放する必要があります。これは、mysql_store_result() を呼び出して取得した結果セットを解放する方法と似ています。

mysql_get_metadata() から返される結果セットには、メタデータだけが含まれます。レコードデータは含まれません。レコードを取得するには、ステートメントハンドルをパラメータとして mysql_fetch() を呼び出します。

戻り値

MYSQL_RES 構造体。プリコンパイルしたクエリのメタ情報が存在しない場合は NULL。

エラー

例

mysql_get_metadata() の使用方法については、項11.1.7.13. 「mysql_fetch()」 の「例」を参照してください。

my_bool mysql_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

説明

mysql_bind_param() は、mysql_prepare() に渡された SQL ステートメントに含まれるパラメータマーカーのデータをバインドするために使用します。データは MYSQL_BIND 構造体を使用して渡します。bind は、MYSQL_BIND 構造体の配列のアドレスです。クライアントライブラリは、この配列に、クエリに含まれる各 ‘?’ パラメータに対応する要素が含まれていると仮定します。

たとえば、以下のステートメントをプリコンパイルするとします。

INSERT INTO mytbl VALUES(?,?,?)

パラメータをバインドする場合、MYSQL_BIND 構造体には 3 つの要素が必要であり、以下のように宣言できます。

MYSQL_BIND bind[3];

設定する必要がある MYSQL_BIND の各要素のメンバについては、項11.1.5. 「C API のプリペアドステートメントのデータ型」 を参照してください。

戻り値

正常にバインドできた場合は 0。エラーが発生した場合は 0 以外。

エラー

例

mysql_bind_param() の使用方法については、項11.1.7.5. 「mysql_execute()」 の「例」を参照してください。

int mysql_execute(MYSQL_STMT *stmt)

説明

mysql_execute() は、ステートメントハンドルに関連付けられているプリコンパイルされたクエリを実行します。この呼び出しの際に、現在バインドされているパラメータマーカーの値がサーバに送信され、サーバはマーカーをここで渡されたデータで置き換えます。

ステートメントが UPDATE、DELETE、または INSERT の場合、mysql_stmt_affected_rows() を呼び出すことによって、変更、削除、または挿入されたレコードの合計数を取得できます。これが SELECT などの結果セットを生成するクエリの場合、最初に mysql_fetch() を呼び出してデータを取得してから、他のクエリ処理を必要とする関数を呼び出す必要があります。結果を取得する方法の詳細については、項11.1.7.13. 「mysql_fetch()」 を参照してください。

戻り値

正常に実行した場合は 0。エラーが発生した場合は 0 以外。エラーコードおよびエラーメッセージは、mysql_stmt_errno() および mysql_stmt_error() を呼び出すことによって取得できます。

エラー

例

以下の例では、mysql_prepare()、mysql_param_count()、mysql_bind_param()、mysql_execute()、および mysql_stmt_affected_rows() を使用して、テーブルを作成し、データを挿入する方法を示します。mysql 変数は有効な接続ハンドルとします。

#define STRING_SIZE 50

#define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
#define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
                                                 col2 VARCHAR(40),\
                                                 col3 SMALLINT,\
                                                 col4 TIMESTAMP)"
#define INSERT_SAMPLE "INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[3];
my_ulonglong  affected_rows;
int           param_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
unsigned long str_length;
my_bool       is_null;

if (mysql_query(mysql, DROP_SAMPLE_TABLE))
{
  fprintf(stderr, " DROP TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
{
  fprintf(stderr, " CREATE TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}

/* Prepare an INSERT query with 3 parameters */
/* (the TIMESTAMP column is not named; it will */
/* be set to the current date and time) */
stmt = mysql_prepare(mysql, INSERT_SAMPLE, strlen(INSERT_SAMPLE));
if (!stmt)
{
  fprintf(stderr, " mysql_prepare(), INSERT failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
fprintf(stdout, " prepare, INSERT successful\n");

/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, " total parameters in INSERT: %d\n", param_count);

if (param_count != 3) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}

/* Bind the data for all 3 parameters */

/* INTEGER PARAM */
/* This is a number type, so there is no need to specify buffer_length */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= 0;
bind[0].length= 0;

/* STRING PARAM */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= 0;
bind[1].length= &str_length;
 
/* SMALLINT PARAM */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;       
bind[2].is_null= &is_null;
bind[2].length= 0;

/* Bind the buffers */
if (mysql_bind_param(stmt, bind))
{
  fprintf(stderr, " mysql_bind_param() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Specify the data values for the first row */
int_data= 10;             /* integer */
strncpy(str_data, "MySQL", STRING_SIZE); /* string  */
str_length= strlen(str_data);

/* INSERT SMALLINT data as NULL */
is_null= 1;

/* Execute the INSERT statement - 1*/
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute(), 1 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
  
/* Get the total number of affected rows */   
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 1): %ld\n", affected_rows);

if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Specify data values for second row, then re-execute the statement */
int_data= 1000;             
strncpy(str_data, "The most popular open source database", STRING_SIZE); 
str_length= strlen(str_data);
small_data= 1000;         /* smallint */
is_null= 0;               /* reset */

/* Execute the INSERT statement - 2*/
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute, 2 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
  
/* Get the total rows affected */   
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 2): %ld\n", affected_rows);

if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}

/* Close the statement */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

注意: プリペアドステートメント関数を使用した完全な例については、ファイル tests/mysql_client_test.c を参照してください。このファイルは、MySQL ソースディストリビューションまたは BitKeeper ソースリポジトリから取得できます。

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

説明

最後に実行されたステートメントによって変更、削除、または挿入されたレコードの合計数を返します。UPDATE、DELETE、または INSERT のいずれかのステートメントに対して mysql_execute() を呼び出した直後に呼び出される可能性があります。SELECT ステートメントの場合、mysql_stmt_affected_rows() を呼び出すと、mysql_num_rows() と同様に動作します。

戻り値

正の整数は、影響を与えた、または取得した、レコード数を示します。0 は、UPDATE によって更新されたレコードがなかったこと、クエリの WHERE 節に一致するレコードがなかったこと、またはクエリが実行されていないことを示します。?1 は、クエリがエラーを返したこと、または SELECT クエリの場合に mysql_fetch() を呼び出す前に mysql_stmt_affected_rows() が呼び出されたことを示します。

エラー

ありません。

例

mysql_stmt_affected_rows() の使用方法については、項11.1.7.5. 「mysql_execute()」 の「例」を参照してください。

my_bool mysql_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

説明

mysql_bind_result() は、結果セットのカラムをデータバッファおよび長さバッファに関連付ける（バインドする）ために使用します。mysql_fetch() を呼び出してデータを取得する場合、MySQL クライアント/サーバプロトコルによって、バインドされたカラムのデータが指定されたバッファに書き込まれます。

注意: mysql_fetch() を呼び出す前に、すべてのカラムをバッファにバインドする必要があります。bind は、MYSQL_BIND 構造体の配列のアドレスです。クライアントライブラリは、この配列に、結果セットの各カラムに対応した要素が含まれていると仮定します。要素が含まれていない場合、mysql_fetch() は単にデータを取得しません。また、クライアント/サーバプロトコルはデータの値を切り分けて返すことはしないので、バッファのサイズはデータ値を格納できるだけの十分な大きさである必要があります。

カラムは、任意の時点で、結果セットの一部だけが取得された後でも、バインドまたは再バインドすることができます。新しくバインドした場合、それが有効になるのは、次に mysql_fetch() を呼び出したときです。たとえば、アプリケーションが結果セットのカラムをバインドして mysql_fetch() を呼び出すとします。クライアント/サーバプロトコルは、バインドされたバッファにデータを返します。次にアプリケーションがカラムを別のバッファにバインドするとします。プロトコルは、次に mysql_fetch() が呼び出されるまで、新しくバインドされたバッファにデータを書き込みません。

カラムをバインドするには、アプリケーションは mysql_bind_result() を呼び出して、型、アドレス、および長さバッファのアドレスを渡します。設定する必要がある MYSQL_BIND の各要素のメンバについては、項11.1.5. 「C API のプリペアドステートメントのデータ型」 を参照してください。

戻り値

正常にバインドできた場合は 0。エラーが発生した場合は 0 以外。

エラー

例

mysql_bind_result() の使用方法については、項11.1.7.13. 「mysql_fetch()」 の「例」を参照してください。

int mysql_stmt_store_result(MYSQL_STMT *stmt)

説明

クエリが結果セットを正常に生成し（SELECT、SHOW、DESCRIBE、EXPLAIN）、さらにクライアントのバッファに結果セット全体を格納して、その後の mysql_fetch() の呼び出しでバッファされたデータが返されるようにする場合に限り、mysql_stmt_store_result() を呼び出す必要があります。

そのようなクエリ以外では mysql_stmt_store_result() を呼び出す必要はありませんが、呼び出したとしても異常が発生したり、目立った動作が行われるようなことは一切ありません。mysql_get_metadata() が NULL を返すかどうかを調べることで、クエリが結果セットを生成したかどうかを検出できます。詳細については、項11.1.7.3. 「mysql_get_metadata()」 を参照してください。

戻り値

結果セットが正常にバッファに格納された場合は 0。エラーが発生した場合は 0 以外。

エラー

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

説明

ステートメントの結果セットの任意のレコードにシークします。offset 値はレコード番号を表し、0 から mysql_stmt_num_rows(stmt)-1 の範囲で指定します。

mysql_stmt_data_seek() を使用するには、ステートメントの結果セット構造体に最後に実行されたクエリの結果全体が格納されている必要があるので、mysql_stmt_store_result() とともに使用する必要があります。

戻り値

ありません。

エラー

ありません。

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

説明

ステートメントの結果セットの任意のレコードにレコードカーソルを設定します。offset の値はレコードオフセットであり、mysql_stmt_row_tell() または mysql_stmt_row_seek() の戻り値になります。この値はレコード番号ではありません。結果セット内のレコードに番号を指定してシークする場合は、この関数ではなく、mysql_stmt_data_seek() を使用します。

mysql_stmt_row_seek() を使用するには、結果セット構造体にクエリの結果全体が格納されている必要があるので、mysql_stmt_store_result() とともに使用する必要があります。

戻り値

シークする前のレコードカーソルの値。mysql_stmt_row_seek() を次に呼び出すときにこの値を渡すことができます。

エラー

ありません。

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

説明

最後に実行された mysql_fetch() で使用されたレコードカーソルの現在の位置を返します。この戻り値を、mysql_stmt_row_seek() に引数として渡すことができます。

mysql_stmt_row_tell() は、mysql_stmt_store_result() の後でのみ使用できます。

戻り値

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

エラー

ありません。

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

説明

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

mysql_stmt_num_rows() を使用するかどうかは、mysql_stmt_store_result() を使用して結果セット全体をステートメントハンドルに格納したかどうかによって決まります。

mysql_stmt_store_result() を使用する場合、すぐに mysql_stmt_num_rows() を呼び出すことができます。

戻り値

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

エラー

ありません。

int mysql_fetch(MYSQL_STMT *stmt)

説明

mysql_fetch() は、結果セットの次のレコードを取得します。この関数は結果セットが存在する間のみ、すなわち、mysql_execute() を呼び出して結果セットを作成した後、または mysql_execute() を呼び出して結果セット全体をバッファに格納してから mysql_stmt_store_result() を呼び出した後にのみ、呼び出すことができます。

mysql_fetch() は、mysql_bind_result() を呼び出してバインドしたバッファを使用してレコードデータを返します。バッファには、現在のレコードセットのすべてのカラムのデータが格納されます。データの長さは length ポインタに返されます。

注意: アプリケーションは、mysql_fetch() を呼び出す前に、すべてのカラムをバッファにバインドする必要があります。

取得したデータが NULL 値だった場合、対応する MYSQL_BIND 構造体の *is_null の値には TRUE（1）が格納されます。それ以外の値だった場合、アプリケーションが指定したバッファの型に基づいて、データおよびその長さがそれぞれ *buffer 要素および *length 要素に返されます。数値型および時間的な値の型は、以下の表に示すように、それぞれ固定長です。文字列型の長さは、実際のデータの長さによって決まり、data_length によって表されます。

戻り値

エラー

例

以下の例では、mysql_get_metadata()、mysql_bind_result()、および mysql_fetch() を使用して、テーブルからデータを取得する方法を示します（この例では 項11.1.7.5. 「mysql_execute()」 の例で挿入された 2 行のレコードを取得するものと想定しています）。mysql 変数は有効な接続ハンドルとします。

#define STRING_SIZE 50

#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 FROM test_table"

MYSQL_STMT    *stmt;
MYSQL_BIND    bind[4];
MYSQL_RES     *prepare_meta_result;
MYSQL_TIME    ts;
unsigned long length[4];
int           param_count, column_count, row_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
my_bool       is_null[4];

/* Prepare a SELECT query to fetch data from test_table */
stmt = mysql_prepare(mysql, SELECT_SAMPLE, strlen(SELECT_SAMPLE));
if (!stmt)
{
  fprintf(stderr, " mysql_prepare(), SELECT failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");

/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);

if (param_count != 0) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}

/* Fetch result set meta information */
prepare_meta_result = mysql_get_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr, " mysql_get_metadata(), returned no meta information\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Get total columns in the query */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout, " total columns in SELECT statement: %d\n", column_count);

if (column_count != 4) /* validate column count */
{
  fprintf(stderr, " invalid column count returned by MySQL\n");
  exit(0);
}

/* Execute the SELECT query */
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Bind the result buffers for all 4 columns before fetching them */

/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &length[0];

/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];
 
/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;       
bind[2].is_null= &is_null[2];
bind[2].length= &length[2];
 
/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;       
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];

/* Bind the result buffers */
if (mysql_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_bind_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Now buffer all results to client */
if (mysql_stmt_store_result(stmt))
{
  fprintf(stderr, " mysql_stmt_store_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

/* Fetch all rows */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_fetch(stmt))
{
  row_count++;
  fprintf(stdout, "  row %d\n", row_count);

  /* column 1 */
  fprintf(stdout, "   column1 (integer)  : ");
  if (is_null[0])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", int_data, length[0]);

  /* column 2 */
  fprintf(stdout, "   column2 (string)   : ");
  if (is_null[1])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %s(%ld)\n", str_data, length[1]);

  /* column 3 */
  fprintf(stdout, "   column3 (smallint) : ");
  if (is_null[2])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", small_data, length[2]);

  /* column 4 */
  fprintf(stdout, "   column4 (timestamp): ");
  if (is_null[3])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
                                               ts.year, ts.month, ts.day,
                                               ts.hour, ts.minute, ts.second,
                                               length[3]);
  fprintf(stdout, "\n");
}

/* Validate rows fetched */
fprintf(stdout, " total rows fetched: %d\n", row_count);
if (row_count != 2)
{
  fprintf(stderr, " MySQL failed to return all rows\n");
  exit(0);
} 

/* Free the prepared result metadata */
mysql_free_result(prepare_meta_result);


/* Close the statement */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

my_bool mysql_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)

説明

アプリケーションはこの関数を使用して、パラメータデータを個別に（または ``切り分けて''）サーバに送信できます。この関数を複数回呼び出すことによって、TEXT または BLOB のどちらかのデータ型のカラムの文字データ値またはバイナリデータ値を複数回に分けて送信することができます。

parameter_number は、データを関連付けるパラメータを示す番号です。パラメータの番号は 0 から始まります。data は送信データを含むバッファへのポインタを、length はバッファ内のデータのバイト数を示します。

戻り値

データをサーバに正常に送信できた場合は 0。エラーが発生した場合は 0 以外。

エラー

例

以下の例では、TEXT 型カラムのデータを切り分けて送信する方法を示します。ここでは、データ値 'MySQL - The most popular open source database' を text_column カラムに挿入します。mysql 変数は有効な接続ハンドルとします。

#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"
  
MYSQL_BIND bind[1];
long       length;

if (!mysql_prepare(mysql, INSERT_QUERY, strlen(INSERT_QUERY))
{
  fprintf(stderr, "\n prepare failed");
  fprintf(stderr, "\n %s", mysql_error(mysql));
  exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &length;
 bind[0].is_null= 0;

/* Bind the buffers */
if (mysql_bind_param(stmt, bind))
{
  fprintf(stderr, "\n param bind failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Supply data in chunks to server */
 if (!mysql_send_long_data(stmt,0,"MySQL",5))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Supply the next piece of data */
 if (mysql_send_long_data(stmt,0," - The most popular open source database",40))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

 /* Now, execute the query */
 if (mysql_execute(stmt))
{
  fprintf(stderr, "\n mysql_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

my_bool mysql_stmt_close(MYSQL_STMT *)

説明

プリペアドステートメントをクローズします。mysql_stmt_close() では、stmt が示すステートメントハンドルに割り当てられたメモリも解放されます。

現在のステートメントの結果セットの処理が途中か、または取得されていないレコードが残っている場合、この関数を呼び出すと、その状態をキャンセルして、次のクエリを実行できるようにします。

戻り値

ステートメントが正常に解放された場合は 0。エラーが発生した場合は 0 以外。

エラー

例

mysql_stmt_close() の使用方法については、項11.1.7.5. 「mysql_execute()」 の「例」を参照してください。

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

説明

mysql_stmt_errno() は、stmt で指定されるステートメントについて、最後に呼び出された、成功または失敗する可能性のあるステートメント API 関数のエラーコードを返します。戻り値が 0 の場合、エラーは発生していません。クライアントのエラーメッセージ番号の一覧は、MySQL errmsg.h ヘッダファイルに記述されています。サーバのエラーメッセージ番号の一覧は、mysqld_error.h に記述されています。MySQL ソースディストリビューションに含まれるファイル Docs/mysqld_error.txt には、すべてのエラーメッセージおよびエラー番号の一覧が記述されています。サーバのエラーコードの一覧は、項12.1. 「返されるエラー」 にも記載されています。

戻り値

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

エラー

ありません。

const char *mysql_stmt_error(MYSQL_STMT *stmt)

説明

mysql_stmt_error() は、stmt で指定されるステートメントについて、最後に呼び出された、成功または失敗する可能性のあるステートメント API 関数のエラーメッセージを含むヌル終端文字列を返します。エラーが発生していない場合は空文字列（""）を返します。これは、次の 2 つの比較は等価であることを意味します。

if (mysql_stmt_errno(stmt))
{
  // an error occurred
}

if (mysql_stmt_error(stmt)[0])
{
  // an error occurred
}

クライアントのエラーメッセージの言語は、MySQL クライアントライブラリを再コンパイルすることによって変更できます。現在は、複数の異なる言語でエラーメッセージを返すことができます。

戻り値

エラーの内容を説明する文字列。エラーが発生していない場合は空文字列。

エラー

ありません。

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

説明

mysql_stmt_sqlstate() は、stmt で指定されるステートメントについて、最後に呼び出された、成功または失敗する可能性のあるプリペアドステートメント API 関数の SQLSTATE エラーコードを含むヌル終端文字列を返します。エラーコードは 5 文字で示されます。"00000" は、``エラーがない'' ことを意味します。値は ANSI SQL および ODBC によって規定されています。考えられる値の一覧については、項12.1. 「返されるエラー」 を参照してください。

注意: すべての MySQL エラーが SQLSTATE にマッピングされているわけではありません。マッピングされていないエラーの場合は "HY000"（一般エラー）が使用されます。

この関数は MySQL 4.1.1 で追加されました。

戻り値

SQLSTATE エラーコードを含むヌル終端文字列。

void my_init(void)

説明

この関数は、他の MySQL 関数を呼び出す前に、プログラム内で 1 回だけ呼び出す必要があります。MySQL が必要とするいくつかのグローバル変数を初期化します。スレッドセーフなクライアントライブラリを使用している場合、この関数は現在のスレッドに対して mysql_thread_init() の呼び出しも行います。

mysql_init()、mysql_server_init()、および mysql_connect() は、自動的にこの関数を呼び出します。

戻り値

ありません。

my_bool mysql_thread_init(void)

説明

スレッドを作成したら、スレッド固有の変数を初期化するためにこの関数を呼び出す必要があります。

my_init() および mysql_connect() は、自動的にこの関数を呼び出します。

戻り値

正常に動作した場合は 0。エラーが発生した場合は 0 以外。

void mysql_thread_end(void)

説明

mysql_thread_init() を呼び出す前にこの関数を呼び出して、pthread_exit() によって割り当てられたメモリを解放する必要があります。

注意: この関数は、クライアントライブラリからは自動的に呼び出されません。メモリリークを避けるために、明示的に呼び出す必要があります。

戻り値

ありません。

unsigned int mysql_thread_safe(void)

説明

この関数は、クライアントがスレッドセーフとしてコンパイルされたかどうかを示します。

戻り値

クライアントがスレッドセーフの場合は 1、それ以外の場合は 0。

int mysql_server_init(int argc, char **argv, char **groups)

説明

この関数は、組み込みサーバを使用するプログラムで、他の MySQL 関数を呼び出す前に、1 回だけ呼び出す必要があります。まず組み込みサーバを起動し、このサーバが使用するサブシステム（mysys、InnoDB など）をすべて初期化します。この関数を呼び出さなかった場合、プログラムはクラッシュします。MySQL に付属の DBUG パッケージを使用している場合は、MY_INIT() を呼び出した後にこの関数を呼び出す必要があります。

引数の argc および argv は、main() の引数と似ています。argv の最初の要素は、通常はプログラム名であり、無視されます。使いやすくするために、サーバに対してコマンドライン引数がない場合、argc は 0（ゼロ）になります。mysql_server_init() は引数のコピーを作成するので、それを呼び出した後は argv または groups を壊しても問題ありません。

groups の NULL で終端された文字列のリストは、オプション設定ファイルのどのグループをアクティブにするかを選択します。See 項4.1.2. 「my.cnf オプション設定ファイル」。 使いやすくするために、groups が NULL の場合は、[server] および [embedded] グループが読み込まれます。

例

#include <mysql.h>
#include <stdlib.h>

static char *server_args[] = {
  "this_program",       /* this string is not used */
  "--datadir=.",
  "--key_buffer_size=32M"
};
static char *server_groups[] = {
  "embedded",
  "server",
  "this_program_SERVER",
  (char *)NULL
};

int main(void) {
  mysql_server_init(sizeof(server_args) / sizeof(char *),
                    server_args, server_groups);

  /* Use any MySQL API functions here */

  mysql_server_end();

  return EXIT_SUCCESS;
}

戻り値

正常に終了した場合は 0。エラーが発生した場合は 1。

void mysql_server_end(void)

説明

この関数は、他の MySQL 関数をすべて呼び出した後に 1 回呼び出す必要があります。組み込みサーバをシャットダウンします。

戻り値

ありません。

mysql_query() の呼び出しが正常に終了した後で mysql_store_result() が NULL を返す可能性はあります。このような状況が発生した場合、以下のいずれかの条件が成立したことを意味します。

mysql_field_count() を呼び出すことによって、ステートメントが空でない結果セットを生成したかどうかをいつでも調べることができます。mysql_field_count() が 0 を返す場合、結果セットは空であり、最後に実行したクエリは結果を返していません（INSERT または DELETE など）。mysql_field_count() が 0 以外の値を返す場合、ステートメントは空ではない結果セットを返しています。例については、mysql_field_count() 関数の説明を参照してください。

mysql_error() または mysql_errno() を呼び出すことによって、エラーが発生したかどうかを判定できます。

クエリは、結果セットを返す以外に、以下の情報を提供します。

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 は変更されません。

あるテーブル用に生成された ID を別のテーブルに挿入するには、以下の SQL ステートメントを記述します。

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

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

システムでこのエラーが発生した場合、コンパイル/リンク行の最後に -lm を追加して、数学ライブラリをリンクする必要があります。

組み込み MySQL サーバライブラリを使用することで、クライアントアプリケーション内部で完全な機能を備えた MySQL サーバを実行できます。最大の長所は、処理速度が高速になることと、組み込みアプリケーションの管理性が向上することです。

組み込み MySQL サーバライブラリは、C/C++ で記述された MySQL のクライアント/サーババージョンをベースとしています。そのため、組み込みサーバも C/C++ で記述されています。他の言語での組み込みサーバは提供されていません。

組み込みサーババージョンとクライアント/サーババージョンはどちらも同じ API が用意されています。既存のスレッドアプリケーションも、通常は以下の関数への呼び出しを追加するだけで、組み込みサーバライブラリを使用するように変更できます。

次に、libmysqlclient.a ではなく、libmysqld.a を作成したコードにリンクする必要があります。

上記の mysql_server_xxx 関数は libmysqlclient.a にも含まれており、作成したアプリケーションを適切なライブラリとリンクするだけで、組み込みサーババージョンおよびクライアント/サーババージョンのどちらを使用するかを切り替えることができるようになっています。 See 項11.1.11.1. 「mysql_server_init()」。

libmysqld ライブラリを取得するには、--with-embedded-server オプションを使用して MySQL を設定する必要があります。

プログラムを libmysqld とリンクするときは、システム固有の pthread ライブラリおよび MySQL サーバが使用するライブラリもリンクする必要があります。mysql_config --libmysqld-libs を実行すると、ライブラリの詳細なリストを取得できます。

スレッドプログラムをコンパイルおよびリンクするときは、適切なフラグを指定する必要があります。これは、自作コードから直接スレッド関数を呼び出していない場合でも必要です。

組み込み MySQL サーバには以下の制約があります。

上記の制約の中には、mysql_embed.h インクルードファイルを編集して MySQL を再コンパイルすることで変更できるものもあります。

オプション設定ファイルを使用して、クライアント/サーバアプリケーションと組み込み MySQL サーバを使用したアプリケーションを簡単に切り替える推奨方法を以下に示します。 See 項4.1.2. 「my.cnf オプション設定ファイル」。

以下に示すプログラムおよび makefile は、Linux や FreeBSD システムでも何も変更することなく動作するはずです。他のオペレーティングシステムで使用する場合は、一部変更が必要です。この例は、実際のアプリケーションを作成する場合には避けられない混乱を回避して、問題点を理解できるだけの詳細な実例を示すことを目的としています。

この例を実際に動作させるには、mysql-4.0 ソースディレクトリと同じレベルに test_libmysqld ディレクトリを作成します。そのディレクトリに test_libmysqld.c ソースファイルと GNUmakefile を保存し、test_libmysqld ディレクトリ内から GNU make を実行します。

test_libmysqld.c

/*
 * A simple example client, using the embedded MySQL server library
 */

#include <mysql.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>

MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query);

const char *server_groups[] = {
  "test_libmysqld_SERVER", "embedded", "server", NULL
};

int
main(int argc, char **argv)
{
  MYSQL *one, *two;

  /* mysql_server_init() must be called before any other mysql
   * functions.
   *
   * You can use mysql_server_init(0, NULL, NULL), and it will
   * initialize the server using groups = {
   *   "server", "embedded", NULL
   *  }.
   *
   * In your $HOME/.my.cnf file, you probably want to put:

[test_libmysqld_SERVER]
language = /path/to/source/of/mysql/sql/share/english

   * You could, of course, modify argc and argv before passing
   * them to this function.  Or you could create new ones in any
   * way you like.  But all of the arguments in argv (except for
   * argv[0], which is the program name) should be valid options
   * for the MySQL server.
   *
   * If you link this client against the normal mysqlclient
   * library, this function is just a stub that does nothing.
   */
  mysql_server_init(argc, argv, (char **)server_groups);

  one = db_connect("test");
  two = db_connect(NULL);

  db_do_query(one, "SHOW TABLE STATUS");
  db_do_query(two, "SHOW DATABASES");

  mysql_close(two);
  mysql_close(one);

  /* This must be called after all other mysql functions */
  mysql_server_end();

  exit(EXIT_SUCCESS);
}

static void
die(MYSQL *db, char *fmt, ...)
{
  va_list ap;
  va_start(ap, fmt);
  vfprintf(stderr, fmt, ap);
  va_end(ap);
  (void)putc('\n', stderr);
  if (db)
    db_disconnect(db);
  exit(EXIT_FAILURE);
}

MYSQL *
db_connect(const char *dbname)
{
  MYSQL *db = mysql_init(NULL);
  if (!db)
    die(db, "mysql_init failed: no memory");
  /*
   * Notice that the client and server use separate group names.
   * This is critical, because the server will not accept the
   * client's options, and vice versa.
   */
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test_libmysqld_CLIENT");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
    die(db, "mysql_real_connect failed: %s", mysql_error(db));

  return db;
}

void
db_disconnect(MYSQL *db)
{
  mysql_close(db);
}

void
db_do_query(MYSQL *db, const char *query)
{
  if (mysql_query(db, query) != 0)
    goto err;

  if (mysql_field_count(db) > 0)
  {
    MYSQL_RES   *res;
    MYSQL_ROW    row, end_row;
    int num_fields;

    if (!(res = mysql_store_result(db)))
      goto err;
    num_fields = mysql_num_fields(res);
    while ((row = mysql_fetch_row(res)))
    {
      (void)fputs(">> ", stdout);
      for (end_row = row + num_fields; row < end_row; ++row)
        (void)printf("%s\t", row ? (char*)*row : "NULL");
      (void)fputc('\n', stdout);
    }
    (void)fputc('\n', stdout);
    mysql_free_result(res);
  }
  else
    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));

  return;

err:
  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
}

GNUmakefile

# This assumes the MySQL software is installed in /usr/local/mysql
inc      := /usr/local/mysql/include/mysql
lib      := /usr/local/mysql/lib

# If you have not installed the MySQL software yet, try this instead
#inc      := $(HOME)/mysql-4.0/include
#lib      := $(HOME)/mysql-4.0/libmysqld

CC       := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
CFLAGS   := -g -W -Wall
LDFLAGS  := -static
# You can change -lmysqld to -lmysqlclient to use the
# client/server library
LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt

ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD
LDFLAGS += -pthread
else
# Assume Linux
LDLIBS += -lpthread
endif

# This works for simple one-file test programs
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

clean:
        rm -f $(targets) $(objects) *.core

MySQL のソースコードは GNU GPL ライセンス（see 付録?H. GNU General Public License）の対象です。その結果、libmysqld をリンクすることによって MySQL ソースコードをインクルードするプログラムは、（GPL と互換性のあるライセンスの下で）フリーソフトウェアとしてリリースする必要があります。

フリーソフトウェアを作成したら、GPL またはそれと互換性のあるライセンスの下でコードをリリースすることによってフリーソフトウェアを宣伝するようにしてください。それができない場合は、MySQL AB から MySQL コードの商業的ライセンスを購入するという選択肢があります。詳細については、項1.4.3. 「MySQL ライセンス」 を参照してください。