my_ulonglong mysql_affected_rows(MYSQL *mysql)

説明

mysql_query()またはmysql_real_query()を使ってステートメントを実行した後、UPDATEのために変更されたか、DELETEのために削除されたか、またはINSERTのために挿入された行の数を戻します。SELECTステートメントに対して、mysql_affected_rows()はmysql_num_rows()と同じように作動します。

戻り値

ゼロより大きい整数は影響を与えられたか、復元された横列の数を示します。ゼロは、UPDATEステートメントに対する記録が更新されなかったか、クエリー中のWHEREクローズにマッチした列が存在していなかったか、クエリーがまだ実行されていないことを示します。-1は、クエリーがエラーを戻したか、SELECTクエリーに対して、mysql_store_result()を呼び出す前に、mysql_affected_rows()が呼び出されたことを示します｡mysql_affected_rows()が未サイン値を戻すので、戻り値を(my_ulonglong)-1 (または同等な(my_ulonglong)~0)と比べることによって、-1をチェックすることができます。

エラー

なし。

例

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

UPDATEステートメントに対して、CLIENT_FOUND_ROWSフラグを規定する場合、mysqldに接続するとき、mysql_affected_rows()は、WHEREローズの規定に基づき、マッチさせられた行の数を戻します。そうならないと、デフォルト行動は実際に変えられた横列の数を返すはずです。

REPLACE コマンドを使うとき、古い列を新しい列と入れ替えた場合、この例では、重複するものを削除した後、1本の列が挿入されたので、mysql_affected_rows()は2を戻すことにご注目ください。

INSERT ... ON DUPLICATE KEY UPDATEを使って1本の列を挿入ると、その列が新しい列である場合、mysql_affected_rows()は1を戻し、既存の列を更新すると２を戻します。

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

説明

modeが1の場合、オートコミット モードをオンに、modeが0の場合、オフにそれぞれセットしてください。

戻り値

成功している場合ゼロ。エラーが起こった場合、ゼロ以外。

エラー

なし。

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

説明

ユーザーを変えて、dbによって規定されたデータベースを、mysqlによって規定された接続上の(現)デフォルトデータベースになるように仕向けてください。次のクエリーの中では、このデータベースは明確なデータベース規定者を含まないテーブルリファレンスのためのデフォルトとなります。

接続されたユーザーを認証することができないか、当該ユーザーがデータベースを使う許可を得ていない場合、mysql_change_user()は失敗します。この場合、ユーザーとデータベースは変更されません。

デフォルトデータベースを持ちたくない場合、dbパラメ−タをNULLにセットすることができます。

このコマンドは状態を新しい接続をしたかのようにリセットします。（項23.2.13. 「自動再接続挙動の管理」を参照してください。）それは常に、アクティブな取引のROLLBACKを実施し、すべての一時テーブル閉じてドロップし、ロックされているすべてのテーブルをアンロックします。セッションシステム変数が対応するグローバルシステム変数の値にリセットされます。準備されたステートメントがレリースされ、HANDLER変数が閉じられます。GET_LOCK()を使って取得されたロックが解放されます。たとえユーザーが変わらなかったとしても、これらの効果は起こります。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

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_init()またはliteral>mysql_connect()によって自動的に割り当てられたものである場合､mysql_close()は、mysqlに合わせた接続ハンドルの割り当ても解除します。

戻り値

なし。

エラー

なし。

my_bool mysql_commit(MYSQL *mysql)

説明

現在の取引を確定してください。

この機能のアクションはcompletion_typeシステム変数の値の適用を条件としています。特に、completion_typeの値が２である場合、取引を終えた後に、サーバはリリースを行って、クライアント接続を閉じます。クライアントプログラムはクライアント側から接続を閉じるために、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()を除き、うまく完了されなければなりません。

パラメータの意味は、接続パラメータをNULLにすることができる点を除き、mysql_real_connect()に対する該当パラメータの場合と同じです。この場合、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パラメータと名付けたデータベースを生成させてください。

この機能はけなされます。SQLCREATE DATABASEステートメントを発行するために、代わりに、出来るだけmysql_query()を使用してください。

戻り値

データベースがうまく生成された場合には､ゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

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(result)-1までの範囲に収めるべきです。

この機能は、結果セット構造にクエリーの全結果を含めることを求めるので、mysql_data_seek()は、mysql_use_result()と一緒でなく、mysql_use_result()と併用する場合に限り使用することができます。

戻り値

なし。

エラー

なし。

void mysql_debug(const char *debug)

説明

DBUG_PUSHが或るストリングを処理する場合。mysql_debug()はFred Fish デバッグ ライブラリを使います。この機能を使うには、デバッギングをサポートするよう、クライアントライブラリを編集しなければなりません。Debugging a MySQL Server、Debugging a MySQL Client を参照して下さい。

戻り値

なし。

エラー

なし。

例

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

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

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

説明

dbパラメータと名付けたデータベースをドロップさせてください。

この機能はけなされます。SQLCREATE DATABASEステートメントを発行するために、代わりに、出来るだけmysql_query()を使用してください。

戻り値

データベースがうまくドロップされた場合には､ゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

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特権を持っていなければなりません。

戻り値

コマンドの附与が成功した場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

my_bool mysql_eof(MYSQL_RES *result)

説明

この機能はけなされます。代わりにmysql_errno()またはmysql_error()を使うことができます。

mysql_eof()は結果セットの最後の列が読み込まれたか否かを査定します。

mysql_store_result()に対して成功した呼び出しから結果セットを取得する場合、クライアントは１回のオペレーションで全セットを受け取ります。この場合、NULLのmysql_fetch_row()からの戻りは、結果セットの終わりが届いているので、mysql_eof()を呼び出す必要はないことを常に意味します。mysql_store_result()と一緒に使うとき、mysql_eof()は常に真を戻します｡

一方、mysql_use_result()を使って結果セットの復元を開始させる場合、セットの列は、mysql_fetch_row()を繰り返して呼び出すと、サーバから一つずつ得られます。この処理の途中に接続にエラーが発生した恐れがあるので、mysql_fetch_row()からのNULL戻り値は、結果セットの終わりが正常に届いたことを必ずしも意味しません。この場合、mysql_eof()を使用して、何が起こったかを査定することができます。結果セットが終わりまで届いた場合、mysql_eof()はゼロ以外の値を戻し、エラーが発生した場合にはゼロを戻します。

歴史的に、mysql_eof()は標準MySQLエラー機能mysql_errno()およびmysql_error()より先行されます。それらのエラー機能が同じ情報を提供するので、それらの使用はmysql_eof()より優先され、けなされます。(実際、エラー機能は、エラーが起こるとエラーの理由を示すのに対して、mysql_eof()はブール値だけを戻すので、それらはもっと多くの情報を提供します。)

戻り値

エラーが発生しなかった場合、ゼロ｡結果セットが終わりまで届いた場合、非ゼロ。

エラー

なし。

例

次の例は、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によって規定された接続に対して、mysql_errno()は最近使用したものを選んでを戻します、成功/失敗のあるAPI機能のエラーコードを返します。ゼロの戻り値はエラーが起こらなかったことを意味します。クライアントのエラーメッセージナンバーは、MySQLerrmsg.hヘッダーファイル中に列記されています。サーバのエラーメッセージナンバーは、mysqld_error.hの中に列記されています。Error Codes and Messagesにはエラーも列記されています。

mysql_fetch_row()を含む幾つかの機能は、これらが成功した場合、mysql_errno()をセットしない点にご注目ください。

経験則に従うと、サーバに情報を求めなければならない全ての機能は成功した場合、(必ず)mysql_errno()をリセットします。

mysql_errno()が戻したMySQLに固有なエラーナンバーは、mysql_sqlstate()が戻したSQLSTATE値とは異なっています。.例えば、mysqlクライアントプログラムは以下のフォーマットを使ってエラーを表示します。この場合、1146はmysql_errno()値で、'42S02'は対応するmysql_sqlstate()値です:

shell> SELECT * FROM no_such_table;
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist

戻り値

最後に行ったmysql_xxx()の呼び出しに対するエラーコード、それが失敗した場合、ゼロはエラーがゼロはエラーが発生しなかったことを意味します｡

エラー

なし。

const char *mysql_error(MYSQL *mysql)

説明

mysqlが規定した接続に対して、mysql_error()は、最近呼び出したが失敗したAPI機能に対するエラーを含む、ゼロで終わるストリングを戻します。機能が失敗しなかった場合、mysql_error()の戻し値は前のエラーかもしくはエラーがないことを示す空のストリングとなる場合があります。

経験則に従うと、サーバに情報を求めなければならない全ての機能は成功した場合、(必ず)mysql_errno()をリセットします。

mysql_errno()をリセットする機能に対して、次の２つのテストは同等です：

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

if(mysql_error(&mysql)[0])
{
  // an error occurred
}

クライアントエラーメッセージの言語は、MySQLクライアントライブラリを再編集することによって変更することができます。現在、幾つかの異なった言語で書かれたエラーメッセージの中から、好みのものを選ぶことができます。項4.10.2. 「英語以外のエラーメッセージ」を参照してください。

戻り値

エラーを述べたゼロで終わる文字ストリング。エラーが発生しなかった場合の空ストリング。

エラー

なし。

代わりに、mysql_real_escape_string()を使うべきです!

この機能は、mysql_real_escape_string()と全く同じです。mysql_real_escape_string()は接続ハンドラーをその第一引数として取り込み、現在の文字セットに従うストリングを忌避します。mysql_escape_string()は接続引数を取り込まず、現在の文字セットを尊重しません。

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

説明

結果セットの定義をMYSQL_FIELD構造として規定したカラムに戻ってください。この機能を繰り返して呼び出して、結果セット中のすべてのカラムに関する情報を復元してください。フィールドがまだ残っているときには､mysql_fetch_field()はNULLを戻します。

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

mysql_query()を呼び出して、テーブル上でSELECTを実施したが、mysql_store_result()を呼び出さなかった場合、MySQLは、mysql_fetch_field()を呼び出して、BLOBフィールドの長さを求めると、デフォルトblobの長さ (8KB)を戻します｡(MySQLはBLOBに対する最大長さを知らないので、8KBのサイズが選ばれます。いつか、これを構成可能にすべきです。)結果セットを復元したと同時に、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_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);
}

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

説明

それは結果セットに対する全てのMYSQL_FIELD構造のアレーを戻します。各構造は、フィールドの定義に結果セットの１コラムを規定します。

戻り値

結果セットの全てのカラムのための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);
}

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

説明

それは結果セット内にある現在の列のカラムの長さを戻します。フィールド値をコピーすることを計画する場合、この長さ情報は、strlen()の呼び出しを避けることができるので、最適化に有用です。以上に加え、結果セットにバイナリーデータが含まれている場合、strlen()はゼロの文字を含むフィールドに対して不正確な結果を戻すので、この機能を利用してデータのサイズを査定しなければなりません。

空のカラムのため、およびNULL値を含むカラムのための長さはゼロです。これら２つのケースを区別する方法を調べるには、mysql_fetch_row()の説明をご参照ください。

戻り値

(ゼロで終わる文字群を含まない)各カラムを代表する未サインの長い整数アレー)。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)によって与えられます。rowがmysql_fetch_row()を呼び出して得た戻り値を保持している場合、その値へのポインターは、row[0]から row[mysql_num_fields(result)-1]にとしてアクセスされます。列中のNULL値はNULLポインターによって示されます。

列中のフィールド値の長さは、mysql_fetch_lengths()を呼び出すことによって得ることができます。空のフィールドとNULLを含むフィールドは両方共length 0を含んでいます。フィールド値のためのポインターをチェックすることによって、これらを区別することができます。ポインターがNULLである場合、フィールドもNULLとなります。さもないと、フィールドは空になります。

戻り値

次列のためのMYSQL_ROW構造。NULL復元すべき列がないか、エラーが発生した場合。

エラー

mysql_fetch_row()の呼び出しと呼び出しの間に、エラーはリセットされないことにご注目ください。

例

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_store_result()がNULLを戻した時(および、それによって、結果セットポインターを持っていなかった時)です。この場合、mysql_field_count()を呼び出して、mysql_store_result()が空でない結果を生成し終えているべきであったか否かを査定することができます。これによって、クライアントプログラムが、クエリーがSELECT(またはSELECTのような)ステートメントであったか否かを知ることなく、適正なアクションをとることが許されます。ここの例はこれを実行できる方法を示すものです。

詳しくは 項23.2.14.1. 「なぜmysql_store_result()時々返すNULL の後mysql_query() 成功を返す」 を参照してください。

戻り値

結果セット中にあるカラムの数を表す無署名の整数。

エラー

なし。

例

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)の呼び出しに変えることです。この場合、mysql_field_count()の値からステートメントがSELECTであったか否かを推定しないで、mysql_store_result() から直接、エラーがないかチェックしています。

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

説明

フィールドカーソルを附与附与されたオフセットにセットしてください。mysql_fetch_field()に対する次の呼び出しによって、オフセットに添付されているカラムの定義が復元されます。

列の始めを探すために、ゼロのオフセット値を渡してください。

戻り値

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

エラー

なし。

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()を呼び出すことによって、それが使用しているメモのリーを解放しなければなりません。

それを解放した後、結果セットににアクセスしようと試みてはなりません。

戻り値

なし。

エラー

なし。

void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)

説明

この機能はデフォルトクライアント文字セットに関する情報を提供します。デフォルト文字セットはmysql_set_character_set()機能を使って変更することができます。

例

if (!mysql_set_character_set(&mysql, "utf8"))
{
    MY_CHARSET_INFO cs;
    mysql_get_character_set_info(&mysql, &cs);
    printf("character set information:\n");
    printf("character set name: %s\n", cs.name);
    printf("collation name: %s\n", cs.csname);
    printf("comment: %s\n", cs.comment);
    printf("directory: %s\n", cs.dir);
    printf("multi byte character min. length: %d\n", cs.mbminlen);
    printf("multi byte character max. length: %d\n", cs.mbmaxlen);
}

const char *mysql_get_client_info(void)

説明

それはクライアントライブラリ・バージョンを表すストリングを戻します。

戻り値

MySQLクライアントライブラリ・バージョンを表す文字ストリング。

エラー

なし。

unsigned long mysql_get_client_version(void)

説明

それはクライアントライブラリ・バージョンを表す整数を戻します。値には、XYYZZフォーマットが含まれています。ここでは、Xはメジャーバージョンで、YYはレリースレベルで、ZZはレリースレベル内のバージョンナンバーです。例えば、40102の値は、4.1.2のクライアントバージョンを表します。

戻り値

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

エラー

なし。

const char *mysql_get_host_info(MYSQL *mysql)

説明

それはサーバーホスト名を含む使用接続のタイプを述べたストリングを戻します。

戻り値

サーバーホスト名と接続タイプを示す文字ストリング。

エラー

なし。

unsigned int mysql_get_proto_info(MYSQL *mysql)

説明

それは現在の接続によって使われたプロトコルのバージョンを戻します。

戻り値

現在の接続によって使われたプロトコルのバージョンを表す無署名の整数。

エラー

なし。

const char *mysql_get_server_info(MYSQL *mysql)

説明

それはサーバのバージョンナンバーを表すストリングを戻します。

戻り値

それはサーバのバージョンナンバーを表す文字ストリングを戻します。

エラー

なし。

unsigned long mysql_get_server_version(MYSQL *mysql)

説明

それはサーバのバージョンナンバーを整数として戻します。

戻り値

このフォーマット中のMySQLサーバーバージョンを表すナンバー：

major_version*10000 + minor_version *100 + sub_version

例えば、5.1.5が50105として戻されます。

この機能は、クライアントプログラム中で、バージョンに固有なサーバー能力が幾つか存在するかどうかを速やかに査定するのに有用です。

エラー

なし。

const char *mysql_get_ssl_cipher(MYSQL *mysql)

説明

mysql_get_ssl_cipher()は、或るサーバへの接続に使用したSSL暗号を戻します。mysqlは、mysql_init()から戻された接続ハンドラーです。

この機能はMySQL 5.1.9に追加されました。

戻り値

SSL暗号の名称を持つストリングで、接続に使われたもの、または、暗号が使われていない場合、NULL。

unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)

説明

この機能は、SQLステートメントの中に使うことができる法定SQLストリングを作るために使われます。項8.1.1. 「文字列」を参照してください。

from中のストリングは、２つの16進桁数としてコード化された各文字と一緒に、16進法のフォーマットにコード化されます。結果はtoの中に置かれ、その最後の部位にゼロバイトが付加されます。

fromによって指し示されたストリングは、lengthバイトの長さのものでなければなりません。toバッファーに長さが少なくともlength*2+1バイトを割り当てなければなりません。mysql_hex_string()が戻すとき、toの中身はゼロで終わるストリングです。戻り値は、ゼロで終わる文字を含まないコード化されたストリングの長さに等しい大きさを持っています。

戻り値は、0xvalueまたはX'value'フォーマットを使ったSQLステートメントの中に置くことができます。しかし、戻り値には、0xまたはX'...'は含まれていません｡呼び出し人は、どれを望まれても供給しなくてはなりません。

例

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"0x");
end += mysql_hex_string(end,"What's this",11);
end = strmov(end,",0x");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
*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()と同じような働きをしますが、ポインターを最初のパラメータの終わりのゼロに戻します。

戻り値

toの中に置かれた、ゼロで終わる文字を含まない値の長さ。

エラー

なし。

const char *mysql_info(MYSQL *mysql)

説明

ここに列記したステートメントを除く、最近実行されたステートメント関する情報を復元してください。他の情報に対して、mysql_info()はNULLを戻します。ここで述べたように、ストリング変数のフォーマットはステートメントのタイプによって変ります。ナンバーは説明用のもので、ストリングには適切な値が含まれています。

mysql_info()は非 NULL 値をINSERT ... VALUES ステートメントの複数列フォームに対してのみ、返すことにご注目ください (即ち、複数値のリストが指定されている場合のみ)。

戻り値

最近実行されたステートメントに関する追加情報を表す文字ストリング。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カラムのために、以前のINSERT ステートメントによって生成された値を戻します。INSERTステートメントを、AUTO_INCREMENT フィールドを含むテーブルの中で実行した後、この機能を使ってください。

mysql_insert_id()の戻り値は、以下の条件が明確に更新されない限り、常にゼロです。

5.1.12以降のバージョンでは、mysql_insert_id()の戻り値を以下のシーケンスに単純化することができます：

mysql_insert_id()の値は、現在のクライアント接続の中に発行されたステートメントのみによって影響を受けます｡それは、他のクライアントによって発行されたステートメントによって影響を受けません。

詳しくは 項11.10.3. 「情報関数」 を参照してください。

SQLLAST_INSERT_ID()機能の値には、(5.1.12の立ち上げ後)最初に自動生成された値で、うまく挿入された値、または(5.1.12より前に)列がうまく挿入された場合、最初に自動生成された値が含まれてることにもご注目ください。他の違いは、AUTO_INCREMENTカラムを特別でない値にセットした場合、LAST_INSERT_ID()は更新されないことです。

LAST_INSERT_ID()とmysql_insert_id()の違いは、LAST_INSERT_ID()はスクリプト中で容易にされるが、mysql_insert_id()はAUTO_INCREMENTカラムに何が起こったかに関する少し正確な情報を提供しようとすることに起因して生まれます。

戻り値

戻り値。

エラー

なし。

int mysql_kill(MYSQL *mysql, unsigned long pid)

説明

pidによって規定されたスレッドを抹消すようサーバに求めてください。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

void mysql_library_end(void)

説明

この機能は MySQL ライブラリを完成させます。(例えば、サーバとの接続を断った後で)ライブラリの使用を行うとき、それを呼び出すべきです。呼び出しによって起こされるアクションは、あなたのアプリケーションがMySQLクライアント・ライブラリにリンクされているか、 MySQL埋め込みサーバ・ライブラリにリンクされているかによって変わります｡-lmysqlclientフラグを使うことによって、libmysqlclientライブラリに対してリンクされたクライアントプログラムのために、mysql_library_end()は、クリーンアップするために、幾つかのメモリー管理を実施します。-lmysqldフラグを使うことによって、ibmysqldに対してリンクされた埋め込みサーバ・アプリケーションのために、mysql_library_end()は、埋め込みサーバをシャットダウンした後、クリーンアップを行います。

使用情報については、項23.2.2. 「C API機能の概要。」および項23.2.3.40. 「mysql_library_init()」をご参照ください。

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

説明

他のMySQL機能を呼び出す前に、この機能をMySQライブラリを初期化するために呼び出すべきです。アプリケーションが埋め込みサーバーを使っている場合、この呼び出しはサーバを立ち上げ、サーバが使うサブシステム(mysys、InnoDB等)を初期化します。

アプリケーションがMySQLライブラリを使って実行された後、mysql_library_end()を呼び出してクリーンアップしてください。項23.2.3.40. 「mysql_library_init()」を参照してください。

非マルチスレッド環境では、mysql_library_init()へのコールは除かれる恐れがあります。なぜならmysql_init()は必要に応じてそれを自動的に呼び出すからです。しかしながら、マルチスレッドの環境では、もしmysql_library_init()が、mysql_library_init()はスレッドにとって安全でないことを理由に、mysql_library_init()によって取り出される場合、競合条件が可能です。それ故に、他のクライアントライブラリを呼び出すの前に、それを呼びだすべきです。

argc引数とargv引数は、main()に対する引数と類似しています。argvの最初の要素は無視されます。(それには大抵プログラム名が含まれています)。便利にするため、もしサーバに対するコマンドーライン引数がない場合、argc は0(ゼロ)であることが許されます｡mysql_library_init()は引数のコピーを作るので、呼び出し後に起こるargvまたはgroupsの破壊に対して安全になります。

埋め込みサーバを立ち上げることなく、外部サーバに接続したい場合、argc対してネガテブな値を規定しなければなりません。

groups引数を、そこからオプションを読み取るべきオプションファイル内のグループを示すストリングのアレーにすべきです。項3.3.2. 「オプションファイルの使用」を参照してください。配列への最終入力をNULLにすべきです。groups引数がNULLである場合、便利にするため、[server]グループと[embedded]グループが初期設定によって使われます。

追加使用情報については、項23.2.2. 「C API機能の概要。」をご参照ください。

例

#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) {
  if (mysql_library_init(sizeof(server_args) / sizeof(char *),
                        server_args, server_groups)) {
    fprintf(stderr, "could not initialize MySQL library\n");
    exit(1);
  }

  /* Use any MySQL API functions here */

  mysql_library_end();

  return EXIT_SUCCESS;
}

戻り値

Okなら０、エラーが起こったら１。

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 FROMtbl_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エラーが起こった場合。

エラー

my_bool mysql_more_results(MYSQL *mysql)

説明

この機能は、シングルステートメントストリングとして規定された複数のステートメントを実行するとき、もしくは複数の結果セットを戻すCALLステートメントを実行するとき使用します。

現在実行したステートメントより、多くの結果が存在している場合、mysql_more_results()は真となります。この場合、アプリケーションはmysql_next_result()を呼び出して、結果をフェッチしなければなりません。

戻り値

以上の結果が存在する場合は、TRUE。上の結果が存在しない場合は、FALSE (0)。

殆どの場合、もっと多くの結果が存在しないかテストし、存在している場合には、これらの復元を開始する代わりに、mysql_next_result()を呼び出すことができます。

項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」 と 項23.2.3.46. 「mysql_next_result()」を参照して下さい。

エラー

なし。

int mysql_next_result(MYSQL *mysql)

説明

この機能は、シングルステートメントストリングとして規定された複数のステートメントを実行するとき、もしくは複数の結果セットを戻すCALLステートメントを実行するとき使用します。

もっと多くの結果が存在している場合、mysql_next_result()は次のステートメントを読み取り、そのステータスをアプリケーションに返送します。

それが結果セットを戻したクエリーである場合、mysql_next_result()を呼び出す前に、先行ステートメントのために、mysql_free_result()を呼び出さなければなりません｡

mysql_next_result()を呼び出した後の接続は、次のステートメントのために、mysql_real_query()またはmysql_query()を呼び出したかのような状態になります。これは、mysql_store_result()、mysql_warning_count()、mysql_affected_rows()等を呼び出すことができることを意味します。

mysql_next_result()がエラーを戻す場合、他のステートメントは実行されず、フェッチすべき更なる結果も存在しません。

ユーザのプログラムが CALL SQL ステートメントで保存されたプロシージャを実行する場合、必ず CLIENT_MULTI_RESULTSフラグを明確に設定するか、mysql_real_connect()に通信するとき CLIENT_MULTI_STATEMENTS にセットすることで必然的にフラグが設定されるようにしてください。これは、各CALLは、手順の中で実行されたステートメントによって戻すべき結果に加え、呼び出しのステータスを示す結果を戻すことに起因して起こります。更に、CALLは複数の結果を戻すことができるので、これらの結果を、mysql_next_result()を呼び出して、更なる結果がないか査定するループを使って処理すべきです。

mysql_next_result()を使用する方法を示す例については、項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」をご参照ください。

戻り値

エラー

unsigned int mysql_num_fields(MYSQL_RES *result)

代わりに MYSQL* アーギュメントを渡す場合、unsigned int mysql_field_count(MYSQL *mysql)を使用してください。

説明

それは、結果セット中のカラムの数を戻します。

カラムの数をポインターから結果セットもしくは接続ハンドルに取り出すことができることにご注目してください。接続ハンドルは、mysql_store_result()もしくはmysql_use_result()がNULLを戻したが(しかし、結果セットポインターがない)場合に使われるでしょう。この場合、mysql_field_count()を呼び出して、mysql_store_result()が空でない結果を生成し終えているべきであったか否かを査定することができます。これによって、クライアントプログラムが、クエリーがSELECT(またはSELECTのような)ステートメントであったか否かを知ることなく、適正なアクションをとることが許されます。ここの例はこれを実行できる方法を示すものです。

詳しくは 項23.2.14.1. 「なぜmysql_store_result()時々返すNULL の後mysql_query() 成功を返す」 を参照してください。

戻り値

結果セット中にあるカラムの数を表す無署名の整数。

エラー

なし。

例

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であったか否かのチェックに変えて実行することです。これは何かが故障した場合に起こります｡

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()は正しい値を戻しません。

mysql_num_rows()はSELECTを含む結果セットを戻すステートメントと一緒に使用するよう意図されています。INSERT、UPDATEまたはDELETEのようなステートメントのために、影響された列の数をmysql_affected_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はその整数の値を指し示すべきです。

可能なオプション値：

clientグループは、MYSQL_READ_DEFAULT_FILEまたはMYSQL_READ_DEFAULT_GROUPを使う場合、常に読み込まれることにご注目ください。

オプションファイル内の規定れたグループには、以下のオプションを含めることができます：

timeoutはconnect-timeoutに置き換えられましたが、timeoutは、下位互換性について、まだMySQL 5.1.15-betaによってサポートされている点にご注目ください。

オプションファイルの明細については、項3.3.2. 「オプションファイルの使用」をご参照ください。

戻り値

成功のためのゼロ。未知のオプションを使う場合、非ゼロ。

例

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)

説明

サーバへの接続が作動しているかどうか調べる。接続がダウンしたら、自動再接続がが試みられます。

長い間働いていないままでいるクライアントサーバはこの機能を使って、接続が閉じたかどうか調べ、必要に応じて再接続することができます。

戻り値

サーバへの接続が作動しているかどうか調べるゼロ。エラーが起こった場合ゼロ以外。戻り値がゼロ以外であることは、MySQLサーバがダウンしたか、接続がネットワーク問題を含むその他の原因で破壊された恐れがあることを示します。

エラー

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

説明

ゼロで終わるストリングstmt_strを指摘するSQLステートメントを実行してください。通常、ストリングはシングルSQLステートメントによって構成されているので、セミコロンで終わる‘;’)や \gをステートメントに加えるべきではありません。マルチステートメントの実行が有効になっている場合、ストリングには、セミコロンで仕切られた幾つかのステートメントを含めることができます。項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」を参照してください。

バイナリーデータを含むステートメントには、mysql_query()を使うことはできません。これの代わりに、mysql_real_query()を使わなければなりません｡(バイナリーデータには、‘\0’キャラクターを含めることがでます。そのmysql_query()はステートメントストリングの終わりであると解釈されます。

ステートメントが結果セットを返すべきであるかどうか知りたい場合、mysql_field_count()を使ってこれをチェックすることができます。項23.2.3.22. 「mysql_field_count()」を参照してください。

戻り値

コマンドの附与が成功した場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

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()は、有効なMYSQL接続ハンドル構造を必要とする他のAPI機能が実行可能になる前に、うまく完了されなければなりません。

パラメータは次のように規定されます：

プログラムが結果セットを生成する記憶された手順を実行するために、CALLSQLステートメントを使用する場合、あなたは、mysql_real_connect()を呼び出すとき、CLIENT_MULTI_STATEMENTSをセットすることによって、CLIENT_MULTI_RESULTSフラグを明示的もしくは黙示的にセットしなければなりません。このような記憶された手順は各々、複数の結果を生成するので、これを実行しなければなりません。手順の中で実行された命令文によって戻された結果の組並びに呼び出しのステータスを示す結果。

CLIENT_MULTI_STATEMENTSまたはCLIENT_MULTI_RESULTSを有効にした場合、mysql_next_result()を呼び出して、更に結果があるか否かを査定するループを使用することによって、mysql_query()またはmysql_real_query()に対する全ての呼び出しの結果を処理すべきです。(例については、項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」をご覧ください。)

幾つかのパラメータをmysql_real_connect()の呼び出文中の明確な値からでなく、オプションファイルかた取らせせることが可能です。これを行うため、mysql_real_connect()を呼び出す前に、MYSQL_READ_DEFAULT_FILEまたはMYSQL_READ_DEFAULT_GROUPと一緒に、mysql_options()を呼び出してください。その後、各パラメータがオプションファイルから読み取られるように、mysql_real_connect()の呼び出しに、「no-value」値を規定してください。

パラメータのためのオプションファイル中に値が見つからない場合、このセクションの始めの部分で説明したように、そのデフォルト値が使われます。

戻り値

接続が成功した場合MYSQL*接続ハンドル。接続が不成功であった場合 NULL。接続が成功した場合、戻り値は最初のパラメータの値と同じになります。

エラー

例

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ライブラリは、 誰かが非標準的な方法でMySQLをセットした場合でも、プログラムが作動することを確認するmy.cnfファイル中の[client]セクションおよび[your_prog_name]セクションを読み取ります。

接続と同時に、mysql_real_connect()は、reconnect フラグ(MYSQL構造の一部)を、バージョンが5.0.3より古いAPI中にある1の値または0の値にセットすることにご注目ください。このフラグに対する1の値は、ステートメントが失われた接続のために実効できない場合、実効を諦める前にサーバに再び接続しようとすることを示します。MYSQL_OPT_RECONNECTオプションをmysql_options()に対して、再接続行動を制御するのに使用することができます。

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

mysqlは有効なオープン接続でなければならないことにご注目ください。回避はサーバによって使用中の文字セットに依存しているのでこれが必要です。

説明

この機能は、SQLステートメントの中に使うことができる法定SQLストリングを作るために使われます。項8.1.1. 「文字列」を参照してください。

from中のストリングは、現在の接続文字セットを考慮して、エスケープしたSQLストリングに対してコード化されます。結果はtoの中に置かれ、最後の部位にゼロバイトが付加されます。コード化された文字はNUL (ASCII 0)、‘\n’、‘\r’、‘\’, ‘'’, ‘"’およびControl-Z (項8.1. 「リテラル値」参照)です。(厳密に言えば、MySQLはバックスラッシュおよびクエリー中にストリングを引用する引用文字を除外することだけを要求します。この機能はそれらをログファイルの中で読み取るを容易にするため、他の文字を引用します。)

fromによって指定されたストリングは、長さがlengthバイトでなければなりません。toバッファーを割り当て、長さが少なくともlength*2+1バイトにしなければなりません。(最悪の場合、各文字は２バイトを使用するように、コード化する必要があるかもしれないので、端末ゼロバイトのための余裕が必要です。)mysql_real_escape_string()が戻るとき、toの中身はゼロで終わるストリングです。戻り値は、ゼロで終わる文字を含まないコード化されたストリングの長さに等しい大きさを持っています。

接続の文字セットに変更を施す必要がある場合、SET NAMES(またはSET CHARACTER SETステートメントではなく、mysql_set_character_set()機能を使うべきです。mysql_set_character_set() は、SET NAMESのように働きますが、mysql_real_escape_string()が使用した文字セットせっとにも影響を及ぼします。この場合、SET NAMES には影響を及ぼしません。

例

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()と同じような働きをしますが、ポインターを最初のパラメータの終わりのゼロに戻します。

戻り値

toの中に置かれた、ゼロで終わる文字を含まない値の長さ。

エラー

なし。

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

説明

stmt_strによって指定されたSQLステートメントを実行します。それは、lengthバイトの長さ持つべきです。通常、ストリングをシングルSQLステートメントで構成すべきですが、ステートメントには、最後の部分にセミコロン(‘;’)または\gを追加すべきではありません。マルチステートメントの実行が有効になっている場合、ストリングには、セミコロンで仕切られた幾つかのステートメントを含めることができます。項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」を参照してください。

バイナリーデータを含むステートメントには、mysql_query()を使うことはできません。これの代わりに、mysql_real_query()を使わなければなりません｡(バイナリーデータには、‘\0’キャラクターを含めることがでます。そのmysql_query()はステートメントストリングの終わりであると解釈されます。)さらに、mysql_real_query()はmysql_query()より高速です。なぜなら、それはステートメントストトリリング上にstrlen()を呼び出さないからです。

ステートメントが結果セットを返すべきであるかどうか知りたい場合、mysql_field_count()を使ってこれをチェックすることができます。項23.2.3.22. 「mysql_field_count()」を参照してください。

戻り値

コマンドの附与が成功した場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

int mysql_refresh(MYSQL *mysql, unsigned int options)

説明

この機能はテーブルあるいはキャッシュをクリアするか、サーバ情報を模写します。接続されたユーザーはRELOAD特権を持っていなければなりません｡

options引数は以下の値からなるビットマスクです。値複の値を一緒にORして、一回の呼び出しで複数のオペレーションを実施することができます。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

int mysql_reload(MYSQL *mysql)

説明

MySQLサーバに供与されたテーブルを再ロードするよう依頼してください。接続されたユーザーはRELOAD特権を持っていなければなりません｡

この機能はけなされます。代わりに、mysql_query()を使って、SQLFLUSH PRIVILEGESステートメントを発行することは望ましいことです。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

my_bool mysql_rollback(MYSQL *mysql)

説明

現取引のロールバック。

この機能のアクションはcompletion_typeシステム変数の値の適用を条件としています。特に、completion_typeの値が２である場合、取引を終えた後に、サーバはリリースを行って、クライアント接続を閉じます。クライアントプログラムはクライアント側から接続を閉じるために、mysql_close()を呼び出すべきです。

戻り値

成功している場合ゼロ。エラーが起こった場合、ゼロ以外。

エラー

なし。

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_field()に使用した列カーソルの現位置をを戻します。この値を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()は失敗します。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

int mysql_set_character_set(MYSQL *mysql, char *csname)

説明

この機能は現在の接続のためのデフォルト文字セットをセットするのに使います。ストリングcsnameは有効な文字セット名を規定します。接続の照合は文字セットのデフォルト照合となります。この機能はSET NAMESステートメントと同じ働きをしますが、mysql->charsetの値もセットし、これによって、mysql_real_escape_string()によって使用されている文字セットに影響を及ぼします。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

例

MYSQL mysql;

mysql_init(&mysql);
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));
}

if (!mysql_set_character_set(&mysql, "utf8")) 
{
    printf("New client character set: %s\n", 
           mysql_character_set_name(&mysql));
}

void
mysql_set_local_infile_default(MYSQL *mysql);

説明

LOAD LOCAL DATA INFILEハンドラーコールバック機能を、Cクライアントライブラリによって内部で使用されているデフォルトにセットしてください。mysql_set_local_infile_handler()が呼び出されなかったか、これがコールバックの各々に対して有効な機能を供給しない場合、ライブラリはこの機能を自動的に呼び出します。

MySQL 4.1.2.にmysql_set_local_infile_default()機能が追加されました。

戻り値

なし。

エラー

なし。

void
mysql_set_local_infile_handler(MYSQL *mysql,
      int (*local_infile_init)(void **, const char *, void *),
      int (*local_infile_read)(void *, char *, unsigned int),
      void (*local_infile_end)(void *),
      int (*local_infile_error)(void *, char*, unsigned int),
      void *userdata);

説明

この機能はLOAD DATA LOCAL INFILEステートメントの実行中に使用すべきコールバックをインストールします。それは、アプリケーションプログラムが(クライアント側の)ローカルデータファイルの読取りを制御することを可能にします。引数は、接続ハンドラー、コールバック機能に対するポインターの組並びにコールバックが情報を共有するのに使用出来るデータエリアに対するポインターです。

mysql_set_local_infile_handler()を使うために、以下のコールバック機能を書き込まなければなりません:

int
local_infile_init(void **ptr, const char *filename, void *userdata);

初期化機能。これは、必要な設定を実行し、デーファイルを開き、データ構造等を割り当てると同時に呼び出されます｡最初のvoid**引数はポインター別のものとなります。コールバックの各々に渡す値に対するポインター(即ち、*ptr)を(void*と同じように)セットすることができます。コールバックは、このポイントされた値を状態情報を維持するのに使用することができます。userdata引数はmysql_set_local_infile_handler()に渡したと同じ値のものです｡

初期化機能は成功に対してゼロ、エラーに対して非ゼロをそれぞれ戻すべきです。

int
local_infile_read(void *ptr, char *buf, unsigned int buf_len);

データ読み取り機能。これはデータファイルを読み取るために、繰り返して呼び出されます。 bufは読み取ったデータを記憶すべきバッファーを指し、buf_lenは、コールバックが読み取り、バッファーに記憶することができるバイトの最大ナンバーとなります。(それはより少ないバイトを読み取ることができますが、より多くのバイトを読み取るべきではありません。)

戻り値は読み取ったバイトの数ですが、データを読み取ることが出来なかったデータがあった時には、これが(EOFを示す)ゼロとなります。エラーがあると、ゼロ未満の値を戻します。

void
local_infile_end(void *ptr)

停止機能。これは、local_infile_read()がゼロ(EOF)またはエラーを戻した後に一度呼び出されます。この機能は、local_infile_init()が割り当てたメモリーの割り当てを解除し、必要なその他のクリーンアップを実施します。それは初期化機能がエラーを戻す場合でも呼び出されます。

int
local_infile_error(void *ptr, 
                   char *error_msg, 
                   unsigned int error_msg_len);

エラー処理機能。これは、テキストエラーメッセージを受け取って、他の機能がエラーを戻す場合、ユーザーに戻すために呼び出されます。error_msgは、メッセージを書き込むべきバッファーを指さし、error_msg_lenはそのバッファーの長さとなります。メッセージはゼロで終わるストリングとして書き込まれるべきなので、メッセージの長さはせいぜいerror_msg_len?1 バイトとなります。

戻り値がエラーナンバーです。

大抵、その他のコールバックはptrを指さすデータ構造中にエラーメッセージを記憶するので、local_infile_error()はメッセージをそこからerror_msgの中にコピーすることができます。

mysql_set_local_infile_handler()をあなたのCコードの中に呼び出し、ポインターをコールバック機能に渡した後、LOAD DATA LOCAL INFILEステートメントを、(例えば、mysql_query()を使って)発行することができます。).クライアントライブラリは自動的にコールバックを呼び出します。LOAD DATA LOCAL INFILE中に規定されたファイル名は、第2パラメータとしてlocal_infile_init()コールバックに第2パラメータとして渡されます。

MySQL 4.1.2.にmysql_set_local_infile_handler()機能が追加されました。

戻り値

なし。

エラー

なし。

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

説明

接続の為のオプションを有効にしたり無効にしたりします。optionに以下の値を持たせることができます。

マルチ・ステートメントサポートを有効化する場合、呼び出し結果を、mysql_next_result()を呼び出して、更なる結果が存在しないか査定するループを使って、mysql_query()またはmysql_real_query()に複写すべきです。(例については、項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」をご覧ください。)

MYSQL_OPTION_MULTI_STATEMENTS_ONを使うマルチ・ステートメントの有効化は、CLIENT_MULTI_STATEMENTSフラグをmysql_real_connect()に渡すことによって、それを有効化する場合と全く同じ効果を持ってはいません:CLIENT_MULTI_STATEMENTSもCLIENT_MULTI_RESULTSを有効化します｡CALL SQLステートメントをプログラムの中で使っている場合、マルチ結果サポートを有効化しなければなりまでん。 これは、MYSQL_OPTION_MULTI_STATEMENTS_ONは、それだけでCALLの使用を許すには不十分であることを意味します。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

int mysql_shutdown(MYSQL *mysql, enum mysql_enum_shutdown_level shutdown_level)

説明

データベースサーバにシャットダウンするように頼む。接続されたユーザーはSHUTDOWN特権を持っていければならない。MySQL 5.1サーバは１つのタイプのシャットダウンしかサポートしていません。 shutdown_levelはSHUTDOWN_DEFAULTと等しくなければなりません。シャットダウンレベルの追加が、望みのレベルが選べるよう計画されています。旧バージョンの libmysqlclientのヘッダーや呼び出しmysql_shutdown()でコンパイルされたダイナミックリンク実行文（ファイルまたはプログラム）は、旧libmysqlclientのダイナミックライブラリと一緒に使用しなければいけません。

シャットダウンプロセスは項4.2.7. 「シャットダウン プロセス」で説明します。

戻り値

成功のためのゼロ。エラーが起こった場合、ゼロ以外。

エラー

const char *mysql_sqlstate(MYSQL *mysql)

説明

最近実行したSQLステートメントに対するSQLSTATEエラーを含む､ゼロで終わるストリングを戻します。エラーコードは５つの文字から成り立っています。'00000'は「no error」を意味します。値はANSI SQLとODBCによって規定されています。可能な値のリストについては、Error Codes and Messagesをご参照ください。

mysql_sqlstate()が戻したMySQLに固有なエラーナンバーは、mysql_errno()が戻したSQLSTATE値とは異なっています。例えば、mysqlクライアントプログラムは以下のフォーマットを使ってエラーを表示します。この場合、1146はmysql_errno()値で、'42S02'は対応するmysql_sqlstate()値です:

shell> SELECT * FROM no_such_table;
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist

すべてのMySQLエラーナンバーがSQLSTATEエラーコードにマップされるわけではありません。値'HY000'(一般エラー)がマップされていないエラーナンバー用に使われます。

戻り値

SQLSTATEエラーコードを含むゼロで終わる文字ストリング。

もご参照ください。

項23.2.3.14. 「mysql_errno()」, 項23.2.3.15. 「mysql_error()」および項23.2.7.26. 「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()は接続を試みるとき、エラーを戻します。

const char *mysql_stat(MYSQL *mysql)

説明

mysqladmin statusコマンドによって提供されたと同等な情報を含む文字ストリングを返します。これには､使用可能時間(秒)と運転スレッドのナンバー、疑問、再ロードならびにオープンテーブルが含まれています。

戻り値

サーバのステータスを述べた文字ストリング。NULLエラーが起こった場合。

エラー

MYSQL_RES *mysql_store_result(MYSQL *mysql)

説明

mysql_query()またはmysql_real_query()を取り出した後、データ(SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等)をうまく復元するすべてのステートメントのために、mysql_store_result()またはmysql_use_result()を呼び出すことができます。結果セットが必要となってから、mysql_free_result() を呼び出さなければなりません｡

他のステートメントのために、mysql_store_result()またはmysql_use_result()を呼び出さなくてもよいが、全てのケースでmysql_store_result()を呼び出すと、被害を及ぼすか、もしくは顕著な性能の劣化を引き起こしません。mysql_store_result()が(後で詳しく述べる)ゼロ以外の値を戻すか否かを調べることによって、あなたはステートメントに結果セットが含まれているか否かを検出することができます。

マルチ・ステートメントサポートを有効化する場合、呼び出し結果を、mysql_next_result()を呼び出して、更なる結果が存在しないか査定するループを使って、mysql_query()またはmysql_real_query()に複写すべきです。(例については、項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」をご覧ください。)

ステートメントが結果セットを返すべきかどうか知りたい場合、mysql_field_count()を使ってこれをチェックすることができます。項23.2.3.22. 「mysql_field_count()」を参照してください。

mysql_store_result()はクライアントに対するクエリーの全結果を読み取り、MYSQL_RES構造を割り当て、この構造の中に結果を配置します。

ステートメントが結果セットを戻さない（例えば、INSERTステートメント）の場合、mysql_store_result()はゼロポインターを戻します。

mysql_store_result()は結果セットが失敗した場合、ゼロポインターも戻します。mysql_error()が空でないストリングをを戻すか、mysql_errno()がゼロ以外を戻すか、mysql_field_count()がゼロを戻すかをチェックすることによって、エラーが起こったか否かをチェックすることができます。

戻された列がない場合､空の結果セットが戻されます｡(空の結果セットは戻り値がゼロポインターと異なっています。)

mysql_store_result()を呼び出し、ゼロポインターでない結果を戻した後、mysql_num_rows()を呼び出して、何個の列が結果セットの中にあるかを検知することができます。

mysql_fetch_row()を呼び出して、結果セットから列をフェッチするか、mysql_row_seek()とmysql_row_tell()を呼び出して、現在の列の位置を取得するか、結果セットの中にセットすることができます。

詳しくは 項23.2.14.1. 「なぜmysql_store_result()時々返すNULL の後mysql_query() 成功を返す」 を参照してください。

戻り値

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。

エラー

なし。

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()に対する呼び出しを行うことによって、各列を個別に復元しなければなりません。これは、サーバから直接クエリーの結果を、それを一時テーブルまたはローカルバッファーに記憶させることなく読み取ります。これは幾らか高速で、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_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()もしくはmysql_affected_rows()をmysql_use_result()から戻された結果と一緒に使ってはなりません。また、mysql_use_result()が終了するまで、他のクエリーを発行してもなりません。(しかしながら、すべての列をフェッチした後、mysql_num_rows()はフェッチした行の数を正確に戻します。）

結果セットが必要となってから、mysql_free_result()を呼び出さなければなりません｡

libmysqld埋込サーバを使うとき、mysql_free_result()が呼び出されるまで、メモリーの使用が戻された各列と共に徐々に増加するので、メモリー利益が本質的に失われます。

戻り値

MYSQL_RES結果構造。NULLエラーが起こった場合。

エラー

mysql_store_result()は成功すると、mysql_error()とmysql_errno()をリセットします。

unsigned int mysql_warning_count(MYSQL *mysql)

説明

前のSQLステートメントの実行中に生成された警告の数を戻します。

戻り値

警告アカウント。

エラー

なし。

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

説明

最後に実行されたステートメントによって、変更、削除または挿入された列の合計数を戻します。mysql_stmt_execute()は、UPDATE、DELETE、あるいは INSERTステートメント　の直後、呼び出されることがあります。SELECTステートメントに対して、mysql_stmt_affected_rows()はmysql_num_rows()と同じように作動します。

戻り値

ゼロより大きい整数は影響を与えられたか、復元された横列の数を示します。ゼロは、UPDATEステートメントに対する記録が更新されなかったか、クエリー中のWHEREクローズにマッチした列が存在していなかったか、クエリーがまだ実行されていないことを示します。-1は、クエリーがエラーを戻したか、SELECTクエリーに対して、mysql_stmt_store_result()を呼び出す前に、mysql_affected_rows()が呼び出されたことを示します｡mysql_affected_rows()が未サイン値を戻すので、戻り値を(my_ulonglong)-1 (または同等な(my_ulonglong)~0)と比べることによって、-1をチェックすることができます。

戻り値に関する追加情報については、項23.2.3.1. 「mysql_affected_rows()」をご参照ください。

エラー

なし。

例

mysql_stmt_affected_rows()の使用については、項23.2.7.10. 「mysql_stmt_execute()」から例をご参照ください。

int mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, void *arg)

説明

ステートメントの持つ属性のために現在の値を得るために使うことができます。

option数は取得したいオプションです。argは、オプション値を含むべき変数さすべきです。オプションが整数である場合、argはその整数の値を指し示すべきです。

オプションとオプションタイプのリストについては、項23.2.7.3. 「mysql_stmt_attr_set()」をご参照ください。

戻り値

OKの場合0optionが未知である場合、ゼロ以外。

エラー

なし。

int mysql_stmt_attr_set(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, const void *arg)

説明

準備されたステートメントのために挙動に影響を附与するために使うことができます。幾つかのオプションをセットするために、この機能を何回でも呼び出すことができます。

option引数は、セットしたいオプションです。arg引数はそのオプションのための値です。オプションが整数である場合、argはその整数の値を指し示すべきです。

可能なオプション値:

STMT_ATTR_CURSOR_TYPEオプションをCURSOR_TYPE_READ_ONLYと一緒に使う場合、mysql_stmt_execute()を取り出すとき、ステートメントのために、カーソルが開かれます。mysql_stmt_execute()の前の呼び出しから、カーソルが既に開かれて存在している場合、それは新しいものを開く前にカーソルを閉じます。mysql_stmt_reset()も再実行のためステートメントを準備する前に、閉じられます｡mysql_stmt_free_result()はどんなカーソルでも開きます。

カーソルを準備されたステートメントのために開く場合、その機能はクライアント側に一時的に記憶させるようにするので、mysql_stmt_store_result()は不要です。

戻り値

OKの場合0optionが未知である場合、ゼロ以外。

エラー

なし。

例

以下の例は、準備されたステートメントのために、カーソルを開き、５になる時間にフェッチするように、列のナンバーをセットします。

MYSQL_STMT *stmt;
int rc;
unsigned long type;
unsigned long prefetch_rows = 5;

stmt = mysql_stmt_init(mysql);
type = (unsigned long) CURSOR_TYPE_READ_ONLY;
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type);
/* ... check return value ... */
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS,
                         (void*) &prefetch_rows);
/* ... check return value ... */

my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

説明

mysql_stmt_bind_param()は、mysql_stmt_prepare()に渡したSQLシテートメント中のパラメータマーカーのためにインプットデータを束ねるのに使われます。それは、MYSQL_BIND構造をデータを供給するのに使います。bindは、MYSQL_BIND構造のアレーのアドレスです。クライアントライブラリはアレーに、各‘?’クエリー中に存在するパラメータマーカーが含まれることを期待します。

次のステートメントを準備すると仮定してください：

INSERT INTO mytbl VALUES(?,?,?)

パラメータを束ねる場合、MYSQL_BIND構造のアレーには、３つの要素が含まれていなければなりません。 このことは、このように宣言することができます：

MYSQL_BIND bind[3];

項23.2.5. 「準備されたC APIステートメントデータタイプ」は各MYSQL_BINDエレメントのメンバーおよび値を提供するためセットすべき方法を説明します。

戻り値

結束作業が成功していたらゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

mysql_stmt_bind_param()を使用するため、例を項23.2.7.10. 「mysql_stmt_execute()」から参照してください。

my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

説明

mysql_stmt_bind_result()は、 結果セット中のアウトプットカラムをデータバッファーおよび長さバッファーに添付(即ち結束)するのに使います｡mysql_stmt_fetch() がデータをフェッチするために呼び出されたるとき、MySQLクライアント/サーバプロトコルはボンドカラムのためのデータを規定されたバッファーの中に置きます｡

全てのカラムは、mysql_stmt_fetch()を呼び出す前に、バッファーと結束されなければなりません。この場合、bindはMYSQL_BIND構造のアレーのアドレスです。クライアントライブラリは結果セットの各コラムに対して、１つの要素が含まれることを期待します。カラムをMYSQL_BIND構造に結びつけないと、mysql_stmt_fetch()は簡単にデータフェッチを怠ります。プロトコルはチャンクでデータ値を返さないので、バッファをデータ値が持てる十分な大きさにべきです。

結果セットが一部複製された後でも、カラムは一回で結束または再結束することができます。新しい結束は、次にmysql_stmt_fetch()が呼び出されたとき有効となります。アプリケーションがカラムを結果セットの中に結束し、mysql_stmt_fetch()を呼び出すと仮定する。クライアント/サーバ・プロトコルは結束されたバッファの中にデータを戻します。その後、アプリケーションがバッファの異なったセットにカラムをバインドすると考えてください。mysql_stmt_fetch()への次のコールが起こるとき、プロトコルは新たにしばられたバッファの中にデータを置きます。

カラムをしばるため、アプリケーションが mysql_stmt_bind_result()を呼び出し、それの中に値を記憶すべきアウトプットバッファのタイプ、アドレス及び長さを渡します。項23.2.5. 「準備されたC APIステートメントデータタイプ」は各MYSQL_BINDエレメントのメンバーおよび値をを受け取るためセットすべき方法を説明します。

戻り値

結束作業が成功していたらゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

mysql_stmt_bind_result()の使用には、項23.2.7.11. 「mysql_stmt_fetch()」から例を参照してください。

my_bool mysql_stmt_close(MYSQL_STMT *)

説明

準備されたステートメントを閉じてください。mysql_stmt_close()は、stmtをさすシテートメントハンドルの割り当ても解除します。

もし現在のステートメントがペンデングの結果か未読の結果を含む場合、次のクエリーを実行可能にするため、この機能はこれらをキャンセルします。

戻り値

ステートメントが解放された場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

mysql_stmt_affected_rows()を使用するため、項23.2.7.10. 「mysql_stmt_execute()」から例を参照してください｡

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()と併用する場合に限り使用することができます。

戻り値

なし。

エラー

なし。

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

説明

stmtによって規定された接続に対して、mysql_stmt_errno()成功する場合もあり失敗する場合もあるAPI 機能に対するエラーコードから最近使用したものを選んでを戻します。ゼロの戻り値はエラーが起こらなかったことを意味します。クライアントのエラーメッセージナンバーは、MySQLerrmsg.hヘッダーファイル中に列記されています。サーバのエラーメッセージナンバーは、mysqld_error.hの中に列記されています。Error Codes and Messagesにはエラーも列記されています。

戻り値

エラーコード値。エラーが発生しなかった場合、ゼロ｡

エラー

なし。

const char *mysql_stmt_error(MYSQL_STMT *stmt)

説明

stmtによって規定された接続に対して、mysql_stmt_errno()は、成功する場合もあり失敗する場合もあるAPI 機能に対するエラーコードから最近使用したものを選んでを戻します。エラーが発生しなかった場合、空ストリング(<"")が戻されます｡これは次の２つのテストが同等であることを意味します：

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

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

クライアントエラーメッセージの言語は、MySQLクライアントライブラリを再編集することによって変更することができます。現在、幾つかの異なった言語で書かれたエラーメッセージの中から、好みのものを選ぶことができます。

戻り値

エラーを述べた文字ストリング。エラーが発生しなかった場合の空ストリング。

エラー

なし。

int mysql_stmt_execute(MYSQL_STMT *stmt)

説明

mysql_stmt_execute()はステートメントハンドルと結び付けられた準備されたクエリーを実行します。しばられた現在のパラメータマーカー値はこのコールの間にサーバに送られ、サーバはそのマーカーをこの新たに供給されたデータと置き換えます。

ステートメントが、UPDATE、DELETEまたはINSERTである場合､変更、削除もしくは挿入された列の合計ナンバーは、mysql_stmt_affected_rows()を呼び出すことによって見つけることができます。これが結果セットを生成するSELECTのようなステートメントである場合、クエリー処理が起こるその他の機能を呼び出す前に、mysql_stmt_fetch()を呼び出してデータをフェッチしなければなりません。結果をフェッチする方法の詳細情報については、 項23.2.7.11. 「mysql_stmt_fetch()」をご参照ください。

結果セットを生成するステートメントに対して、あなたは、mysql_stmt_execute()に、ステートメントを実行する前に、mysql_stmt_attr_set()を呼び出すことによって、ステートメントのためにカーソルを開くよう求めることができます。ステートメントを複数回実行する場合、新しいものを開く前に、mysql_stmt_execute()はオープンカーソルを閉じます。

戻り値

成功した場合ゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

次の例は、mysql_stmt_init()、mysql_stmt_prepare()、mysql_stmt_param_count()、mysql_stmt_bind_param()、mysql_stmt_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; the server */
/*  sets it to the current date and time) */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(INSERT_SAMPLE)))
{
  fprintf(stderr, " mysql_stmt_prepare(), INSERT failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
fprintf(stdout, " prepare, INSERT successful\n");

/* Get the parameter count from the statement */
param_count= mysql_stmt_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 */

memset(bind, 0, sizeof(bind));

/* 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_stmt_bind_param(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_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_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_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): %lu\n",
                (unsigned long) 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_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_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): %lu\n",
                (unsigned long) 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 source distributionあるいはBitKeeper source repositoryから取得することができます。

int mysql_stmt_fetch(MYSQL_STMT *stmt)

説明

mysql_stmt_fetch()は結果セット中に次列を戻します。結果セットが存在している間だけ、それは呼び出されます：即ち、結果セットを生成するmysql_stmt_execute()に対する呼び出し後またはmysql_stmt_store_result()後で、それは、全結果セットを一時的に蓄えるためmysql_stmt_execute()後に呼び出されます｡

mysql_stmt_fetch()は、mysql_stmt_bind_result()によって束ねられたバッファーを使って列データを戻します。それは、現在の列セット中の全てのカラムのために、これらのバッファーの中にデータを戻し、長さはlengthポインターに戻されます。

mysql_stmt_fetch()を呼び出す前に、すべてのカラムはアプリケーションによって束ねられなければなりません。

フェッチされたデータ値がNULL値である場合、対応するMYSQL_BIND構造の*is_null値にはTRUE (1)が含まれます。さもないと、データとその長さは、アプリケーションによって規定されたバッファータイプに基づき、*bufferエレメント及び*lengthエレメントの中に戻されます。次のテーブルの中に列記されているように、数値と時間の各タイプは一定の長さを持っています。data_lengthによって示されるように、ストリングタイプの長さは実際のデータ値の長さに依存します。

戻り値

切り捨て報告が有効なとき、MYSQL_DATA_TRUNCATEDは戻されます。(報告はデフォルトによって有効化されますが、mysql_options()を使って制御することができます。)この値が返されるとき、いずれのパラメータが取り除かれたか査定するため、MYSQL_BINDパラメータ構造errorメンバーをチェックしてください。

エラー

例

次の例は、mysql_stmt_result_metadata(), mysql_stmt_bind_result(), and mysql_stmt_fetch()を使って、テーブルからデータをフェッチする方法を明らかにするものです。(この例は項23.2.7.10. 「mysql_stmt_execute()」の中に示された例によって挿入された２つの横列を復元することをすることを目指したものです。)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];
my_bool       error[4];

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

/* Get the parameter count from the statement */
param_count= mysql_stmt_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_stmt_result_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr,
         " mysql_stmt_result_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_stmt_execute(stmt))
{
  fprintf(stderr, " mysql_stmt_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

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

memset(bind, 0, sizeof(bind));

/* 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];
bind[0].error= &error[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];
bind[1].error= &error[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];
bind[2].error= &error[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[3].error= &error[3];

/* Bind the result buffers */
if (mysql_stmt_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_stmt_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_stmt_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);
}

int mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset)

説明

現在の結果セット列から１個のカラムをフェッチしてください。bindはデータを置くべきバッファーを提供します。それをmysql_stmt_bind_result()に対すると同じ方法でセットすべきです。columnはどのカラムにフェッチすべきかを示します。最初のカラムには０のナンバーが付いています。offsetはデータの復元を始めるべきデータ値の中のオフセットです。これはピースの中にデータ値をフェッチするのに使われます。値の始まりはオフセット０です。

戻り値

値がうまくドフェッチされた場合､ゼロ。エラーが起こった場合、ゼロ以外。

エラー

unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)

説明

ステートメントハンドラーに対する最近のステートメントのためのカラムのナンバーを戻します。この値は、結果セットを生成しない　INSERT または DELETE のようなステートメントのためのゼロです。

mysql_stmt_prepare()を取り出すことによって、ステートメントを準備した後、mysql_stmt_field_count()を呼び出すことができます。

戻り値

結果セット中にあるカラムの数を表す無署名の整数。

エラー

なし。

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

説明

準備されたステートメントを実行することによって生成された結果セットと関係のあるメモリーを解放してください。ステートメントのために開いているカーソルがある場合、mysql_stmt_free_result()がそれを閉じます。

戻り値

結果セットが解放された場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

説明

Create a MYSQL_STMT handle.ハンドルをmysql_stmt_close(MYSQL_STMT *)を使って解放すべきです。

戻り値

成功の場合MYSQL_STMT構造をさすポインター。NULLメモリー不足の場合

エラー

my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)

説明

AUTO_INCREMENTカラムのために、準備されたINSERT or UPDATEステートメントによって生成された値を戻します。AUTO_INCREMENTフィールドを含むテーブルの上で、準備されたINSERT ステートメントを実行した後、この機能を使ってください｡

明細な情報については、項23.2.3.37. 「mysql_insert_id()」をご参照ください。

戻り値

準備されたステートメントの実行中に自動的に生成されたか明確にセットされたAUTO_INCREMENTカラムのための値またはLAST_INSERT_ID(expr)機能によって生成された値。AUTO_INCREMENT値をセットしない場合、戻り値は定義されません。

エラー

なし。

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()を直ちに呼び出すことができます。

mysql_stmt_num_rows()はSELECTを含む結果セットを戻すステートメントと一緒に使用するよう意図されています。INSERT、UPDATEまたはDELETEのようなステートメントのために、影響された列のナンバーをmysql_stmt_affected_rows()を使って取得することができます。

戻り値

結果セット中の行の数。

エラー

なし。

unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)

説明

準備されたステートメントに存在しているパラメータマーカのナンバーを戻します。

戻り値

ステートメント中のパラメータのナンバーを表す無署名の長い整数。

エラー

なし。

例

mysql_stmt_affected_rows()の使用について、項23.2.7.10. 「mysql_stmt_execute()」から例を参照してください。

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

この機能は現在何もしません。

説明

戻り値

エラー

int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *stmt_str, unsigned long length)

説明

mysql_stmt_init()によって戻されたステートメントハンドルを附与すると、ストリングstmt_strをさすSQLステートメントを用意し、ステータスの値を戻します。ストリングの長さはlength引数によって与えられるべきです。ストリングは一つのSQLステートメントで構成しなければなりません。ステートメントの終にセミコロン‘;’) or \gを加えるべきではありません。

アプリケーションには、疑問詞(‘?’)文字をSQLストリングの適当な位置に埋め込むことによって、複数のパラメータマーカを含めることができます。

マーカはSQLステートメント中の特定の場所でだけ合法的です。例えば、これらは、(列にカラム値を規定する)VALUES()ステートメントのINSERTリストの中またはカラムと比較して比較値を規定するWHERE条項中で容認されます。しかし、それらは、(テーブル名あるいはコラム名称のような)識別子に対しては容認されず、=等号のようなバイナリーオペレーターの両オペランドを規定することも許されません｡パラメータのタイプを決めることは多分不可能なので、後者の規制は必要です。パラメータは一般に、Data Manipulation Language (DML)ステートメントの中でのみ法的に有効で、Data Definition Language (DDL)ステートメント中では無効です。

パラメータマーカーは、ステートメントを実行する前にmysql_stmt_bind_param()を使ってアプリケーション変数に縛り付けなければなりません。

戻り値

ステートメントがうまく準備された場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

準備作業が不成功であった場合(即ち、mysql_stmt_prepare()がゼロを戻す場合)、mysql_stmt_error()を呼び出すことによって、エラーメッセージを取得することができます。

例

mysql_stmt_prepare()の使用については、項23.2.7.10. 「mysql_stmt_execute()」から、例を参照してください。

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

説明

準備されたステートメントをクライアントとサーバ上にリセットして、準備後、陳述してください。これは主にmysql_stmt_send_long_data()を使って送ったデータをリセットするのに使われます。ステートメントに対して開かれているカーソルが全て閉じられます。

他のクエリーを使ってステートメントを再び準備するには、mysql_stmt_prepare()を使います。

戻り値

ステートメントがリセットされた場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)

説明

mysql_stmt_prepare()に渡したステートメントが結果セットを生成するものである場合、mysql_stmt_result_metadata()は、ポインターの形の結果セットメタデータを、フィールドの合計ナンバーと個別フィールド情報を処理するのに利用できるMYSQL_RES構造に戻します。この結果セットポインターは引数として、フィールドベースの結果セットメタデータを処理するAPI機能のいずれにも渡すことができます。

結果セット構造はそれが必要なとき、解放されるべきです。解放は、それをmysql_free_result()に渡すことによって実行されます。これは、mysql_store_result()に対する呼び出しから取得した結果セットを解放すると同じ方法です。

mysql_stmt_result_metadata()によって戻された結果セットにはメタデータだけが含まれています。それは列の結果を含んでいません。列は、mysql_stmt_fetch()を含むステートメントハンドルを使うことによって取得することができます。

戻り値

MYSQL_RES結果構造。NULLメタ情報が準備されたクエリーのために存在しない場合。

エラー

例

mysql_stmt_result_metadata()の用途については、項23.2.7.11. 「mysql_stmt_fetch()」から例をご参照ください。

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_data_seek()は、mysql_stmt_store_result()と併用する場合に限り使用することができます。

戻り値

列カーソルの前の値。この値をmysql_row_seek()に対する次の呼び出しに渡すことができます。

エラー

なし。

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

説明

それは、 最後のmysql_stmt_fetch()に使用した列カーソルの現位置を戻します。この値をmysql_stmt_row_seek()に対する引数として使うことができます。

mysql_stmt_row_tell()を、mysql_stmt_store_result()の後にだけ使うべきです。

戻り値

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

エラー

なし。

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

説明

アプリケーションがパラメータデータを一個ずつサーバ(または「chunks」)に送ることを可能にします。この機能をmysql_stmt_bind_param()の後およびmysql_stmt_execute()の前にこの機能を呼び出してください。それを、文字の一部またはカラムのためのバイナリーデータを送るため、複数回呼び出すことができます。それはTEXT or BLOBデータタイプの一種でなければなりません。

parameter_number>はデータに添付すべきパラメータを示します。パラメータには、ゼロで始まる番号が付いています。dataは送るべきデータを含むバッファーをさすポインターで、lengthはバッファー中のバイトのナンバーを示します。

注:次のmysql_stmt_execute()コールは、最後のmysql_stmt_send_long_data()以来、mysql_stmt_execute() or mysql_stmt_reset()と一緒に使われてきたパラメータに対するバインドバッファーを無視します。

送ったデータをリセットし忘れたい場合、それをmysql_stmt_reset()を使って実行することができます。項23.2.7.21. 「mysql_stmt_reset()」を参照してください。

戻り値

データがうまくサーバーに送られる場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

例

次の例はどのようにチャンクで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;

stmt = mysql_stmt_init(mysql);
if (!stmt)
{
  fprintf(stderr, " mysql_stmt_init(), out of memory\n");
  exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
{
  fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  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_stmt_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_stmt_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_stmt_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_stmt_execute(stmt))
{
  fprintf(stderr, "\n mysql_stmt_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

説明

stmtによって規定された接続に対して、mysql_stmt_sqlstate()は、成功する場合もあり失敗する場合もあるAPI 機能に対するエラーコードから最近使用したものを選んでを戻します。エラーコードは５つの文字から成り立っています。'00000'は「no error」を意味します。値はANSI SQLとODBCによって規定されています。可能な値のリストについては、Error Codes and Messagesをご参照ください。

すべてのMySQLエラーはもうSQLSTATEコードにマップされないことにご注目ください。値'HY000'(一般エラー)がマップされていないエラーナンバー用に使われます。

戻り値

SQLSTATEエラーコードを含むゼロで終わる文字ストリング。

int mysql_stmt_store_result(MYSQL_STMT *stmt)

説明

結果セット(SELECTSHOW, DESCRIBE, EXPLAIN)をうまく生成するすべてのステートメントのため および、クライアントに全結果セットを一時保存して、その後のmysql_stmt_fetch()コールが一時保存データを戻すようにして欲しい場合、mysql_stmt_fetch() を呼び出さなければなりません｡

他のステートメントのためmysql_stmt_store_result()を呼び出すことは不要です。しかし、そうしても、性能を害するか傷つけることはありません。mysql_stmt_result_metadata()がNULLを戻すかチェックすることによって、ステートメントが結果セットを生成したか否かを検知することができます。.明細については、項23.2.7.22. 「mysql_stmt_result_metadata()」をご参照ください。

注:MySQLは、ysql_stmt_store_result()をかなりスローダウンさせ、殆どのアプリケーションがmax_lengthを必要としなくなるので、デフォルトによって、YSQL_FIELD->max_lengthをmax_length中のすべてのカラムに対して計算しません。max_lengthを更新したい場合、mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag)を呼び出してこれを有効にすることができます。項23.2.7.3. 「mysql_stmt_attr_set()」を参照してください。

戻り値

結果がうまく一時保存された場合、ゼロ。エラーが起こった場合、ゼロ以外。

エラー

void my_init(void)

説明

この機能はMySQL機能を呼び出す前に一回プログラム中に呼び出される必要があります。my_init()はMySQLが必要とする幾つかのグローバル変数を初期化します。スレッドに安全なクライアントライブラリを使っている場合、それはこのスレッドのために、mysql_thread_init()も呼び出します｡

my_init() はmysql_init()、mysql_library_init()、mysql_server_init()、そしてmysql_connect()に自動的に呼び出されます。

my_init()にアクセスするため、プログラム には、my_sys.hヘッダーファイルを含めなければなりません:

#include <my_sys.h>

戻り値

なし。

my_bool mysql_thread_init(void)

説明

スレッドに固有名変数を初期化するため、生成された各スレッドごとに、この機能が呼び出される必要があります。

mysql_thread_init()は、my_init() と　mysql_connect()に自動的に呼び出されます。

戻り値

成功している場合ゼロ。エラーが起こった場合、ゼロ以外。

void mysql_thread_end(void)

説明

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

このmysql_thread_end() クライアントライブラリによって自動的に取り出されないことにご注目ください。.それは記憶漏れを避けるために明示的に呼び出されなくてはなりません。

戻り値

なし。

unsigned int mysql_thread_safe(void)

説明

この機能は、スレッドとって安全であるようにクライアントが編集されるか否かを示します。

戻り値

クライアントがスレッドにとって安全であるなら１、さもなければ０。