無料スクリプト配布のPHP.TO   PHPの実用的なtips PHPマニュアル MySQLマニュアル Apacheマニュアル PostgreSQLマニュアル マニュアル検索    

第23章 APIとライブラリー

目次

23.1. 埋め込まれたMySQLサーバライブラリ、libmysqld
23.1.1. 埋め込まれたMySQLサーバライブラリーの概括
23.1.2. libmysqld使って行うプログラムの翻訳
23.1.3. 埋め込まれたMySQLサーバの使用に対する規制
23.1.4. 埋め込まれたサーバに対するオプション
23.1.5. 埋め込まれたサーバの例
23.1.6. 埋め込まれたサーバに対するのライセンスの供与
23.2. MySQL C API
23.2.1. C APIデータタイプ
23.2.2. C API機能の概要。
23.2.3. C API機能の説明
23.2.4. 準備されたC APIステートメント。
23.2.5. 準備されたC APIステートメントデータタイプ
23.2.6. 準備されたC APIステートメント機能の概要
23.2.7. 準備されたC APIステートメント機能の詳細
23.2.8. 準備されたC API ステートメントの問題
23.2.9. マルチプルステートメントを実行するC APIハンドリング
23.2.10. 日付とタイム値のC API式取り扱い
23.2.11. C APIスレッド機能の説明
23.2.12. 埋め込まれたC API機能の説明
23.2.13. 自動再接続挙動の管理
23.2.14. C APIを使うときよく尋ねられる質問と問題
23.2.15. クライアントプログラムの構築
23.2.16. スレッド付きクライアントを作る方法
23.3. MySQL PHP API
23.3.1. MySQLとPHPに対する共通問題
23.3.2. mysqlmysqli の両方を PHP内で可能にする
23.4. MySQL Perl API
23.5. MySQL C++ API
23.6. MySQL Python API
23.7. MySQL Tcl API
23.8. MySQLエッフェルラッパー
23.9. MySQLプログラム開発ユーティリティー
23.9.1. msql2mysql — MySQLと一緒に使うため、mSQLプログラムを変換してください。
23.9.2. mysql_config — コンパイルオプションをコンパイルクライアントのために(用に)取得してください。

この章で、MySQLに利用できるAPIを入手する場所およびそれを使用する方法について説明します。CAPIは、MySQLチームによって開発されたので、最も適用範囲の広い内容を含み、他のAPIの基礎をなすものです。この章には、libmysqldライブラリー(埋め込みのサーバー)並びにアプリケーション・デベロッパーに有用な若干のプログラムも含まれています。

23.1. 埋め込まれたMySQLサーバライブラリ、libmysqld

23.1.1. 埋め込まれたMySQLサーバライブラリーの概括

埋め込まれたMySQLサーバライブラリーは、フル機能のMySQLサーバをクライアント・アプリケーションの中で運転することを可能にします。主な利益は埋め込まれたアプリケーションに対するスピードの増加とマネージメントの単純化です。

埋め込みのサーバライブラリは、C/C++で書かれているMySQのクライアント/サーバ用のバージョンに基づいています。従って、埋め込まれたサーバもC/C++で書かれます。他の言語を使って利用可能な埋め込みサーバは存在しません。

APIは埋め込みのMySQLバージョンとクライアント/サーバ用バージョン対するものと同じです。使い古しのアプリケーションを変えて、埋め込まれたライブラリを使うには、あなたは通常、次の機能に対するコールを加えなければなりません。

機能呼び出し時期
mysql_library_init()は他のMySQL機能が呼び出される前のなるべく早期に、main()機能の中に呼び出すべきです。
mysql_library_end()を、あなたのプログラムが終了する前に、呼び出すべきです。
mysql_thread_init()を、MySQLにアクセスするよう、あなたが生成する各スレッドの中に呼び出すべきです。
mysql_thread_end()を、pthread_exit()を呼び出す前に呼び出すべきです。

その後あなたは、自分のコードをlibmysqlclient.aの代わりに、libmysqld.aとリンクさせなければなりません。

mysql_library_xxx()関数もlibmysqlclient.aに含まれているので、あなたのアプリケーションを正しいライブラリにリンクさせることによって、埋め込まれているバージョンとクライアント/サーバ用のバージョンの間に変更を施すことが許されます。詳しくは項23.2.3.40. 「mysql_library_init()を参照してください。

埋め込みサーバと独立サーバの間の1つ違いは、埋め込みサーバの場合、接続のための認証が初期設定によって無効にされていることです。埋め込みサーバに対して認証を使用するには、configureを呼び出して、あなたのMySQLデストリビューションを設定する時、--with-embedded-privilege-controlを規定してください。

23.1.2. libmysqld使って行うプログラムの翻訳

libmysqldライブラリを取得するには、--with-embedded-serverオプションを使って、MySQLを配置すべきです。詳しくは項2.9.2. 「典型的な configure オプション」を参照してください。

あなたのプログラムをlibmysqldとリングさせるとき、MySQLサーバが使用する、システムに固有なpthreadライブラリも含めなければなりません。mysql_config --libmysqld-libsを実行することによって、ライブラリのフルリストを取得することができます。

スレッド機能を自分のコードの中に直接呼び出さない場合でも、スレッド付きプログラムを翻訳し且つリンクさせるための正しいフラグを使用しなければなりません。

Cプログラムを翻訳して、埋め込まれたMySQLサーバライブラリに対して必要なファイルをプログラムの翻訳バージョンの中に含ませるため、GNU C コンパイラー(gcc)を使ってください。コンパイラーには、様々なファイルを見つける場所を知る必要があります。彼にはプグラムを翻訳する方法に関するインストラクションも必要です。次の例は、プログラムをコマンドラインから翻訳出来る方法を示したものです。

gcc mysql_test.c -o mysql_test -lz \
`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`

gccコマンドの直ぐ後に、Cプログラムファイルの名称を記載します。その後に、-oオプションを附与して、後に続くファイル名称は、コンパイラーがアウトプットファイルに附与すべき名称であることを示します。コードの次のラインは、含めるファイルとライブラリおよび、そこでそれが翻訳されるシステムに対するその他の設定を告げます。mysql_configに発生した問題に起因して、(圧縮するための)オプション-lzがここに追加されます。mysql_configピースは、一重引用符でなく、バックチックスの中に含められます。

23.1.3. 埋め込まれたMySQLサーバの使用に対する規制

埋め込まれたサーバには次の制限が適用されます。

  • ユーザが定義した機能(UDF)の使用禁止。

  • コア・ダンプ上でのスタックトレースの禁止。

  • これを親もしくは(複製が禁止されている)子供として設定することはできません。

  • 非常に大きい結果セットはメモリー性能の低いシステム上で使用することができない恐れがあります。

  • あなたは埋め込まれたサーバに、外部プロセスからソケットまたはTCP/IPを使って接続することができません。しかし、あなたは中間アプリケーションに接続することはできませんが、その代わり、遠隔クライアントまたは外部プロセスのために、埋め込みサーバに接続することができます。

これらの制限の幾つかを、mysql_embed.hを編集して、ファイルと再翻訳MySQLを含めることによって、変更することができます。

23.1.4. 埋め込まれたサーバに対するオプション

mysqldサーバ・デーモンを使って附与することができるオプションを、埋め込まれたサーバ・ライブラリと一緒に使うことができます。サーバオプションは、mysql_library_init()に対する引数として、配列の中に附与することができます。これによって、サーバが初期化されます。それらをmy.cnfのようなオプションファイルの中に附与することができます。Cプログラムのためにオプションファイルを規定するため、--defaults-fileオプションをmysql_library_init()の2番目の引数要素の1つとして使ってください。mysql_library_init()機能に関する明細については、項23.2.3.40. 「mysql_library_init()をご参照ください。

オプションファイルを使用すると、クライアント/サーバアプリケーションとMySQLが埋め込まれる場所にあるものの間で行う切り替えを容易にすることができます。共通オプションを[server]グループの下に置いてくさい。これらは両方のMySQLバージョンによって読み取られます。クライアント/サーバに固有なオプションは[mysqld]セクションの下に持ってくるべきです。埋め込まれたMySQLサーバライブラリに固有なオプションを[embedded]セクションの中に配置してください。アプリケーションに固有なオプションは、[ApplicationName_SERVER]と書いたラベルを貼ったセクションの下に配置されます。詳しくは項3.3.2. 「オプションファイルの使用」を参照してください。

23.1.5. 埋め込まれたサーバの例

これら2つのエクザンプルプログラムはLinuxまたはFreeBSDシステムに変更を施すことなく、実行すべきです。その他のオペレーテングシステムに対して、大抵ファイルパスを使って、マイナーな変更を施すことが必要です。これらの例は、問題を把握するに十分な明細を、実のアプリケーションに対する必要部分であるクラッターなしで、あなたに附与するようにデザインされています。最初の例は、非常に直接的なものです。2番目の例は、幾つかのエラーチェックを伴う若干進歩したものです。最初の例の後には、プログラムを編集するため、コマンドライン・エントリーが続きます。第2の例の後には、代わりに編集するために使うことができるGNUメークファイルが続きます。

例1。

test1_libmysqld.c

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

MYSQL *mysql;
MYSQL_RES *results;
MYSQL_ROW record;

static char *server_options[] = \
       { "mysql_test", "--defaults-file=my.cnf", NULL };
int num_elements = (sizeof(server_options) / sizeof(char *)) - 1;

static char *server_groups[] = { "libmysqld_server", 
                                 "libmysqld_client", NULL };

int main(void)
{
   mysql_library_init(num_elements, server_options, server_groups);
   mysql = mysql_init(NULL);
   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);

   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);

   mysql_query(mysql, "SELECT column1, column2 FROM table1");

   results = mysql_store_result(mysql);

   while((record = mysql_fetch_row(results))) {
      printf("%s - %s \n", record[0], record[1]);
   }

   mysql_free_result(results);
   mysql_close(mysql);
   mysql_library_end();

   return 0;
}

上のプログラムを翻訳するためのコマンドラインがここにあります:

gcc test1_libmysqld.c -o test1_libmysqld -lz \
 `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`

例2。

その例を実際に試してみるために、 MySQL ソースディレクトリと同じレベルにtest2_libmysqldディレクトリを生成させてください。test2_libmysqld.cソースとGNUmakefile をダイレクトリーの中にセーブし、GNU maketest2_libmysqldダイレクトリーの内側から運転してください。

test2_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[] = {
  "test2_libmysqld_SERVER", "embedded", "server", NULL
};

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

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

[test2_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_library_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_library_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 does not accept the
   * client's options, and vice versa.
   */
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_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-5.1/include
#lib      := $(HOME)/mysql-5.1/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

23.1.6. 埋め込まれたサーバに対するのライセンスの供与

我々は皆さんに、多目的言語(GPL)に基づくコードもしくは互換性のあるライセンスを解放することによって、フリーソフトウェアを昇進させること奨励します。これを行うことができない人々に対するその他のオプションは、 MySQLコードのための商業ライセンスをMySQL ABから買うことです。明細については、http://www.mysql.com/company/legal/licensing/をご参照ください。

23.2. MySQL C API

C APIコードはMySQLを使って配付されます。それはmysqlclientライブラリの中に含まれ、これによって、データベースにアクセスすることが許されます。

ソース・デストリビューション中のクライアントの多くはC言語で書かれています。C APIを使用する方法を示す例を探す場合、これらのクライアントを調べてください。MySQLソースデストリビューション中のclientsダイレクトリーの中でこれらを見つけることができます。

他のクライアントAPIの殆ど(Connector/JおよびConnector/NETを除く全て)はmysqlclientライブラリを使ってMySQLサーバと交信します。これは、例えば、他のクライアントプログラムによって使われると同じ環境変数の多くから利益を得ることができることを意味します。これらの変数のリストについては、章 7. クライアントプログラムとユーティリティ プログラムをご参照ください。

クライアントは最大のコミュニケーションバッファーサイズを持っています。最初に割り当てられたバッファーのサイズ(16KB)は自動的に最大サイズまで増やされます。(この場合の最大は16MB)バッファーサイズは需要保証としてだけ増やされるので、初期設定最大限度を単純に増加させても、使用すべき資源の本質的増加を引き起こしません。このサイズチェックは殆どの場合、エラーステートメントとコミュニケーションパケットに対するチェックです。

コミュニケーションバッファーは、(クライアントからサーバへのトラフィックに対する)シングルSQLステートメント並びに(サーバからクライアントへのトラフィックに対する)返還データの1本の列を含めるに十分な大きさを持っていなければなりません。各スレッッドのコミュニケーションバッファーはクエリーもしくは列を最大限度まで扱うため、ダイナミックに拡大されます。例えば、サイズが16MB未満のデータを含む BLOB 値を持っている場合、(サーバとクライアントの両方の中に)少なくとも16MBのコミュニケーション・バッファー リミットを持っていなければなりません。クライアントのデフォルト最大値は16MBですが、サーバのそれは1MBです。サーバを立ち上げる時、max_allowed_packet パラメータの値を変更することによってこれを増やすことができます。項6.5.2. 「サーバパラメータのチューニング」を参照してください。

MySQLサーバは各クエリーの後、各コミュニケーションバッファーを net_buffer_length バイトに縮小させます。クライアントの場合、接続に関係するバッファーのサイズは接続が閉鎖されるまで減少されません。その時、クライアントのメモリーは改善されます。

詳しくは項23.2.16. 「スレッド付きクライアントを作る方法」をご参照ください。同じプログラムの中にサーバとクライアントを含み(外部MySQLサーバと交信しない)独立したアプリケーションを生成するには、項23.1. 「埋め込まれたMySQLサーバライブラリ、libmysqld」をご参照ください。

23.2.1. C APIデータタイプ

  • MYSQL

    この構造は1データベース接続に対するハンドルを表します。それは殆ど全てのMySQL機能に対して使われます。MYSQL 構造のコピーを作ろうとすべきではありません。このようなコピーが使用可能である保証はありません。

  • MYSQL_RES

    この構造は横列(SELECTSHOWDESCRIBEEXPLAIN)を戻すクエリーの結果を表します。クエリーから返された情報はこのセクションの残りの部分の中で結果セットと呼ばれます。

  • MYSQL_ROW

    これはデータの1本の横列に関して、タイプに安全な表現です。それは現在カウントされたバイトストリングのアレーとして搭載されています。(フィールド値にバイナリーデータが含まれている場合、内部に無効なバイトが含まれている恐れがあるので、これらをゼロで終わるストリングとして扱うことはできません。)横列は mysql_fetch_row() を呼び出すことによって得られます。

  • MYSQL_FIELD

    この構造には、フィールド名、タイプ並びにサイズのようなフィールドに関する情報が含まれています。ここで、その中身(メンバー)について明細に説明します。繰り返して mysql_fetch_field() を呼び出すことによって、各フィールドごとに、MYSQL_FIELD構造を得ることができます。フィールド値はこの構造の一部ではありません; これらは MYSQL_ROW 構造の中に含まれています。

  • MYSQL_FIELD_OFFSET

    これは、MySQLフィールドリストの中に入力してもタイプに安全なオフセットの表示です。(mysql_field_seek() によって使われた。.)オフセットは列の中でゼロで始まるフィールドナンバーです。

  • my_ulonglong

    横列の数および mysql_affected_rows()mysql_num_rows()mysql_insert_id() に使ったタイプ。このタイプは、0 から 1.84e19 までの範囲を提供します。

    幾つかのシステム上では、タイプ my_ulonglong の値をプリントしようと試みる動作は作動しません。このような値をプリントするには、それを unsigned long に変換して、%lu 印刷フォーマットを使ってください。例 :

    printf ("Number of rows: %lu\n", 
            (unsigned long) mysql_num_rows(result));
    
  • my_bool

    (ゼロでない)真または(ゼロの)虚の値に対するブーリアンタイプ。

MYSQL_FIELD 構造には、ここで列記したメンバーが含まれています:

  • char * name

    ゼロで終わるストリングを含むフィールドの名称。フィールドに AS クローズを含むアリアスを附与すると、name はアリアスとなります。

  • char * org_name

    ゼロで終わるストリングを含むフィールドの名称。アリアスは無視されます。

  • char * table

    それが計算フィールドでない場合、このフィールドを含むテーブルの名称。計算されたフィールドの場合、table 値は空のストリングとなります。カラムが画面から選択される場合、table は画面を指定します。テーブルあるいは画面に AS クローズを使ってエイリアスを附与すると、table の値はエイリアスとなります。

  • char * org_table

    ゼロで終わるストリングを含むテーブルの名称。エイリアスは無視されます。カラムを画面から選ぶと、org_table が基盤となるテーブルを指定します。

  • char * db

    ゼロで終わるストリングとして、フィールドを生むデータベースの名称。フィールドが計算フィールドである場合、db は空のストリングとなります。

  • char * catalog

    カタログ名。この価値は常に "def" となります。

  • char * def

    ゼロで終わるストリングを含むこのフィールドのデフォルト値。mysql_list_fields() を使う場合に限り、これはセットされます。

  • unsigned long length

    テーブルの定義に規定したフィールドの幅。

  • unsigned long max_length

    結果セットに対するフィールドの最大幅(結果セット中に実在する列に対する最長フィールド値の長さ)。mysql_store_result() あるいは mysql_list_fields() を使う場合、これにはフィールドに対する最大長さが含まれます。mysql_use_result() を使うと、この変数の値はゼロになります。

    max_length の値は、結果セット中の値のストリング表示の長さとなります。例えば、FLOATカラムを復元する場合にあって、「widest」値が-12.345ある場合、max_lengthは('-12.345'の長さに等しい)7となります。

    準備されたステートメントを使っている場合、バイナリのプロトコルに対して、値の長さは結果セット中の値のタイプによって変わるので、max_lengthは初期設定されません。(項23.2.5. 「準備されたC APIステートメントデータタイプ」を参照してください。)max_length値がとにかく欲しい場合、mysql_stmt_attr_set()を使って、STMT_ATTR_UPDATE_MAX_LENGTHオプションを有効化すると、mysql_stmt_store_result()を呼び出す時、その長さがセットされます。(項23.2.7.3. 「mysql_stmt_attr_set()項23.2.7.27. 「mysql_stmt_store_result()をご参照ください。)

  • unsigned int name_length

    nameの長さ。

  • unsigned int org_name_length

    org_nameの長さ。

  • unsigned int table_length

    tableの長さ。

  • unsigned int org_table_length

    org_tableの長さ。

  • unsigned int db_length

    dbの長さ。

  • unsigned int catalog_length

    catalogの長さ。

  • unsigned int def_length

    defの長さ。

  • unsigned int flags

    フィールドに異なるビットフラグ。flags値を次のビットセットに関してゼロ以上にすることができます:

    フラグ値フラグの説明
    NOT_NULL_FLAGフィールドはNULL
    であることができませんPRI_KEY_FLAGフィールドはプライマリーキーの一部です
    UNIQUE_KEY_FLAGフィールドはユニークキーの一部です
    MULTIPLE_KEY_FLAGフィールドは非ユニークキーの一部です
    UNSIGNED_FLAGフィールドにはUNSIGNED属性が含まれています
    ZEROFILL_FLAGフィールドにはZEROFILL属性が含まれています
    BINARY_FLAGフィールドにはBINARY 属性が含まれています
    AUTO_INCREMENT_FLAGフィールドにはAUTO_INCREMENT 属性が含まれています
    ENUM_FLAGフィールドはENUM (deprecated)です
    SET_FLAGフィールドはSET (deprecated)です
    BLOB_FLAGフィールドはBLOBまたはTEXT (deprecated)です
    TIMESTAMP_FLAGフィールドはTIMESTAMP (deprecated)です

    BLOB_FLAGフラグ、ENUM_FLAGフラグ、SET_FLAGフラグおよびTIMESTAMP_FLAGフラグの使用は、それらはそのタイプではなく、フィールドのタイプを表示するので、けなされます。field->typeを、MYSQL_TYPE_BLOBMYSQL_TYPE_ENUMMYSQL_TYPE_SETもしくは代わりにMYSQL_TYPE_TIMESTAMPに対して出来るだけテストしてください。

    次の例はflags値の典型的な利用を図解したものです:

    if (field->flags & NOT_NULL_FLAG)
        printf("Field can't be null\n");
    

    flags値のブーリアン・ステータス決定するため、次の便利なマクロを使うことができます:

    フラグのステータス摘要
    IS_NOT_NULL(フラグ)このフィールドがNOT NULL
    IS_PRI_KEY(フラグ)であると規定されている場合、真このフィールドがプライマリーキーである場合、真
    IS_BLOB(フラグ) であると規定されている場合、真このフィールドがBLOBまたはTEXT (deprecated; test field->type instead)である場合、真
  • unsigned int decimals

    数値フィールドに対する小数の数。

  • unsigned int charsetnr

    フィールドに対するキャラクター・セットナンバー。

  • enum enum_field_types タイプ

    フィールドのタイプ。type値は次のテーブルに示すMYSQL_TYPE_シンボルの1つにすることができます。

    タイプの値タイプの説明
    MYSQL_TYPE_TINYTINYINT フィールド
    MYSQL_TYPE_SHORTSMALLINT フィールド
    MYSQL_TYPE_LONGINTEGER フィールド
    MYSQL_TYPE_INT24MEDIUMINT フィールド
    MYSQL_TYPE_LONGLONGBIGINT フィールド
    MYSQL_TYPE_DECIMALDECIMAL または NUMERIC フィールド
    MYSQL_TYPE_NEWDECIMAL精密計算 DECIMAL または NUMERIC
    MYSQL_TYPE_FLOATFLOAT フィールド
    MYSQL_TYPE_DOUBLEDOUBLE or REAL フィールド
    MYSQL_TYPE_BITBIT フィールド
    MYSQL_TYPE_TIMESTAMPTIMESTAMP フィールド
    MYSQL_TYPE_DATEDATE フィールド
    MYSQL_TYPE_TIMETIME フィールド
    MYSQL_TYPE_DATETIMEDATETIME フィールド
    MYSQL_TYPE_YEARYEAR フィールド
    MYSQL_TYPE_STRINGCHAR または BINARY フィールド
    MYSQL_TYPE_VAR_STRINGVARCHAR または VARBINARY フィールド
    MYSQL_TYPE_BLOBBLOB or TEXT フィールド (大長を決めるためにmax_lengthを使用)
    MYSQL_TYPE_SETSET フィールド
    MYSQL_TYPE_ENUMENUM フィールド
    MYSQL_TYPE_GEOMETRY空間フィールド
    MYSQL_TYPE_NULLNULL-type field

    フィールドが数値のタイプを持っているかどうか試すためにIS_NUM()マクロを使うことができます。type値をIS_NUM()に渡しください。そうすると、フィールドが数値である場合、それが真であると判定します。

    if (IS_NUM(field->type))
        printf("Field is numeric\n");
    

    ストリングデータタイプに対して、バイナリーデータであるか、非バイナリーデータであるかを区別するには、charsetnr値が63であるかどうか調べてください。もしそうであるなら、キャラクターセットはbinaryで、それは非バイナリーデータでなくバイナリーデータであることを示します。これが、BINARYCHARVARBINARYVARCHAR並びにBLOBTEXT.を区別する方法です。

23.2.2. C API機能の概要。

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

機能摘要
my_init()グローバル変数およびスレッドに安全なプログラム中のスレッドハンドラーを初期化する。
mysql_affected_rows()最後のUPDATE, DELETEまたはINSERTクエリーによって、負荷/削除/挿入された行の数を戻す。
mysql_autocommit()トグルスイッチを操作して、オートコミットモードをオンまたはオフにする。
mysql_change_user()オープン接続上のユーザーとデータベースを変更する。
mysql_close()サーバ接続を閉にする。
mysql_commit()>取引を確約する。
mysql_connect()MySQLサーバに接続する。この機能は忌避されるので、代わりに、mysql_real_connect()を使用してください。
mysql_create_db()データベースを生成してください。この機能は忌避されるので、代わりにSQLステートメントCREATE DATABASEを使ってください。
mysql_data_seek()は、クエリー結果セット中の任意の列ナンバーを探し求めます。
mysql_debug()は、附与されたストリングを使ってDBUG_PUSHを実行します。
mysql_drop_db()はデータベースをドロップします。この機能は忌避されるので、代わりに、SQLステートメントDROP DATABASEを使ってください。
mysql_dump_debug_info()はサーバにデバグ情報をログに書き込ませます。
mysql_eof()は最後の結果セットが読み込まれたか否か査定します。この機能は忌避されるので、代わりにmysql_errno()または mysql_error()を使うことができます。
mysql_errno()は最近取り出したMySQL機能に対するエラーのナンバーを戻します。
mysql_error()は最近取り出したMySQL機能に対するエラーのメッセージを戻します。
mysql_escape_string()SQLステートメントの中で使用するため、ストリング中で行う特別キャラクターの使用を避けるてください。
mysql_fetch_field()は次のテーブルフィールトのタイプを戻します。
mysql_fetch_field_direct()は、フィールドナンバーを附与すると、テーブルフィールドのタイプを戻します。
mysql_fetch_fields()は全フィールド構造のアレーを戻します。
mysql_fetch_lengths()は現列中に全カラムの長さを戻します。
mysql_fetch_row()は結果セットから次列を持ってきます。
mysql_field_seek()はカラムカーソルを規定カラム上に移動させます。
mysql_field_count()最近のステートメントに対する結果のナンバーを戻します。
mysql_field_tell()は最後のmysql_fetch_field()に対して使用したフィールドカーソルの位置に戻します。
mysql_free_result()は結果セットによって使用されたメモリーを解放します。
mysql_get_client_info()はクライアントバージョン情報をすとストリングとして戻します。
mysql_get_client_version()はクライアントバージョン情報をすと整数として戻します。
mysql_get_host_info()は接続を述べたストリングを戻します。
mysql_get_server_version()はサーバのナンバーを整数として戻します。
mysql_get_proto_info()は接続に使用したプロトコルバージョンを戻します。
mysql_get_server_info()はサーバのバージョンナンバーを戻します。
mysql_info()は最近実効したクエリーに関する情報を戻します。
mysql_init()MYSQL構造を取得するか、初期化します。
mysql_insert_id()は前のクエリーによってAUTO_INCREMENTカラムに対して生成されたIDを戻します。
mysql_kill()は附与したスレッドを破壊します。
mysql_library_end()はMySQL C APIライブラリーを最終承認します。
mysql_library_init()はMySQL C APIライブラリーを初期化します。
mysql_list_dbs()はシンプルなレギュラー表現にマッチするデータベースの名称を戻します。
mysql_list_fields()はシンプルなレギュラー表現にマッチするフィールドの名称を戻します。
mysql_list_processes()は現サーバスレッドのリストを戻します。
mysql_list_tables()はシンプルなリギュラー表現にマッチするテーブルの名称を戻します。
mysql_more_results()は更に結果が存在しているかチェックします。
mysql_next_result()は複数ステートメントの実効において、次結果を戻し、初期化します。
mysql_num_fields()は結果セット中のカラムのナンバーを戻します。
mysql_num_rows()は結果セット中の列のナンバーを戻します。
mysql_options()mysql_connect()に対する接続オプションをセットします。
mysql_ping()はサーバへの接続が作動しているかチェックし、必要に応じて再接続します。
mysql_query()はゼロで終わるストリングとして規定されているSQLクエリーを実効します。
mysql_real_connect()はMySQLサーバに接続します。 Connects to a MySQL server.
mysql_real_escape_string()は、接続の現キャラクターセットを考慮して、SQLステートメント中で使用するストリング中に特別なキャラクターを使用することを避けます。
mysql_real_query()はカウントストリングとして規定されているSQLクエリーを実効します。
mysql_refresh()はテーブルとキャッシュをフラッシュするかリセットする。
mysql_reload()は供与されたテーブルを再び取り込むよう告げます。
mysql_rollback()は取引を撤回させます。
mysql_row_seek()mysql_row_tell()から戻った値を使って、結果セット中にから列オフセットを模索すします。
mysql_row_tell()は列カーソルの位置を戻します。
mysql_select_db()はデータベースを選択します。
mysql_server_end()はMySQL C APIライブラリーを最終承認します。
mysql_server_init()はMySQL C APIライブラリーを初期化します。
mysql_set_local_infile_default()LOAD DATA LOCAL INFILEハンドラーをその初期設定値にコールバックするようセットします。
mysql_set_local_infile_handler()アプリケーションに固有なLOAD DATA LOCAL INFILEハンドラーコールバックをインストールします。
mysql_set_server_option()は接続用オプション(multi-statementsを含む)をセットします。
mysql_sqlstate()は最後のエラーに対するSQLSTATEエラーコードを戻します。
mysql_shutdown()はデータベースサーバの操業を停止させます。
mysql_stat()はサーバステータスをストリングとして戻します。
mysql_store_result()はクライアントに対する結果セットを一式復元します。
mysql_thread_end()はスレッドハンドラーを最終承認します。
mysql_thread_id()は現スレッドのIDを戻します。
mysql_thread_init()はスレッドハンドラーを初期化します。
mysql_thread_safe()は、クライアントがスレッドに対して安全になるよう編集されている場合、1を戻します。
mysql_use_result()は、列ごとに得られた結果セットを各々復元させる作業を開始させます。
mysql_warning_count()は以前のSQLステートメントに対する警告カウントを戻します。

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

  1. mysql_library_init()を呼び出すことによって、MySQLライブラリを初期化してください。この機能は、mysqlclient C クライアントライブラリと埋め込まれたmysqldサーバライブラリの両方に存在するので、それは、-libmysqlclient フラグとリンクすることによって、レギュラークライアントプログラムを構築するか、または-libmysqldフラグとリンクすることによって、埋め込みサーバアプリケーションを構築するのに使用されます。

  2. mysql_init()を呼び出して、接続ハンドラーを初期化し、更にmysql_real_connect()を呼び出して、サーバに接続してください。

  3. SQLステートメントを発行して、それらの結果を処理してください。(次の講義で、これを行う方法に関する明細な情報を提供します。)

  4. mysql_close()を呼び出すことによって、MySQLサーバに対する接続を閉じてください。

  5. mysql_library_end()を呼び出すことによって、MySQL ライブラリの使用を終えてください。

mysql_library_init()mysql_library_end()の呼び出しは、MySQLライブラリの適正な初期化と最終承認を確保する目的で実効します。クライアントライブラリとリンクされるアプリケーションのために、それらは改善されたメモリ管理を提供します。mysql_library_end()を呼び出さない場合、メモリブロックが割り当てられたままになります。(これによって、アプリケーションによって使われたメモリの量は増えませんが、若干のメモリ漏れ探知器がそれについて不平を言います。)埋め込まれたサーバーとリンクされるアプリケーションに対して、これらのコールはサーバを立ち上げたり、立ち下げたりします。

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

サーバに接続するには、mysql_init()を呼び出して接続ハンドラーを初期化してから、そのハンドラーを(ホストネーム、ユーザーネームおよびパスワード等の他の情報と一緒に)使って、mysql_real_connect()を呼び出してください。接続と同時に、mysql_real_connect()は、reconnectフラグ(MYSQL構造の一部)を、バージョンが5.0.3より古いAPI中にある1または新しいバージョンのAPI中にある0の値にセットします。このフラグに対する1の値は、ステートメントが失われた接続のために実効できない場合、実効を諦める前にサーバに再び接続しようとすることを示します。MYSQL_OPT_RECONNECTオプションをmysql_options()に使用して、再接続行動を制御することができます。接続を止めたい場合、mysql_close()を呼び出して、それを修了させてください。

クライアントは接続がアクティブである間に、mysql_query()あるいはmysql_real_query()を使って、SQLステートメントをサーバに送ることができます。2つの違いは、mysql_query()クエリーにゼロで終わるストリングを規定するよう期待しますが、mysql_real_query()はカウントストリングを規定するよう期待します。ストリングが(空のバイトを含む恐れのある)バイナリーデータを含んでいる場合、mysql_real_query()を使わなければなりません。

各非SELECTクエリー(例えば、INSERTUPDATEDELETE)に対して、mysql_affected_rows()を呼び出すことによって、幾つの列が変更(影響)されたかを調べることができます。

SELECTクエリーに対して、選択された列を結果セットとして取り出します。(幾つかのステートメントは、列を戻す場合のように、SELECTとなることにご注目ください。これらにはSHOWDESCRIBE及びEXPLAINが含まれています。これらをSELECTステートメントの場合と同じ方法で処理すべきです。)

クライアントが結果セットを処理する2つの方法があります。1つの方法は、mysql_store_result()を呼び出すことによって、全結果セットを直ちに回収する方法です。この機能はサーバからクエリーによって戻された全ての列を取得して、それらをクライアントの中に記憶します。第2の方法は、mysql_use_result()を呼び出すことによって、クライアントが列別結果セットの回収を開始させる方法です。この機能は復元したものを初期化しますが、実際にサーバから横列を取得しません。

両ケースで、mysql_fetch_row()を呼び出すことによって、横列にアクセスします。mysql_store_result()mysql_fetch_row()を使って、前にサーバからフェッチされた横列にアクセスします。mysql_use_result()を使って、mysql_fetch_row()はサーバから実際に列を復元させます。mysql_fetch_lengths()呼び出すことによって、各横列中にあるデータのサイズに関する情報を入手することができます。

結果セットを閉じた後、そめに使用したメモリーを解放するため、mysql_free_result()を呼び出してください。

2つの復元メカニズムは相補的関係を持っています。クライアントプログラムに、それらの要件を満たす最も適切なアプローチを選択すべきです。実務においてクライアントはより共通して、mysql_store_result()を使う傾向があります。

mysql_store_result()を呼び出すと、横列はすべて、クライアントにフェッチされているので、単に連続的に横列にアクセスすできるだけでなく、mysql_data_seek() または mysql_row_seek() を使って、結果セットの中を前後に移動して、結果セット中の現横列の位置を変更することができる利益が生まれます。mysql_num_rows()を呼び出すことによって、そこに存在している横列の数を検知することもできます。一方、mysql_store_result()に対するメモリー要件は結果セットに対して非常に厳しいので、記憶不足が起こる恐れがあります。

mysql_use_result()を利用すると、それは1回に1列しか維持せず、(割り当て間接容量も低くて済む)ので、クライアントには結果セットに対してより低い記憶容量が要求され、mysql_use_result()をより高速にすることができる利益が得られます)。この場合、サーバを縛り付けるのを避けるため、速やかに各横列を処理しなしければならず、それらを全部復元するまで、結果セット中に幾列あるか知ることができず(ただ順次横列にアクセスすることができるだけである)という不利益がが生まれます。さらに、復元の途中で探していた情報を情報が発見できたとしても、必ずすべての横列を復元してください。

API は、クライアントがステートメントがSELECTであるか否かを知ることなく、適切に(必要に応じて横列だけを復元する)ステートメントに返答することを可能にします。各mysql_query()(またはmysql_real_query()の後に、mysql_store_result()を呼び出すことによって、これを行うことができます。結果セットの呼び出しが成功すると、ステートメントはSELECTであったので、横列を読むことができます。結果セットの呼び出しが失敗した場合には、mysql_field_count()を呼び出して、結果が実際に期待できたはずか否か査定してくだしさい。mysql_field_count()がゼロを戻す場合、戻されたステートメントは戻ったが、(それがINSERTUPDATEDELETE等であったことを示す)データがないので、列を戻すことが期待できなかったことになります。mysql_field_count()がゼロでない場合、ステートメントは列を戻していたはずですが、戻しませんでした。これは、ステートメントが機能を停止したSELECTであったことを示します。これを実行できる方法を示す例については、mysql_field_count()に対する説明をご参照ください。

mysql_store_result()mysql_use_result()は両方共、結果セットを作り出すフィールドに関する情報(フィールドの数と名称およびタイプ等)を取得することを可能にします。mysql_fetch_field()を繰り返し呼び出すか、もしくは列の中のフィールドナンバー別にmysql_fetch_field_direct()を呼び出すことによって、フィールド情報に列の中で連続してアクセスすることができます。mysql_field_seek()を呼び出すことによって、現在のカーソルポジションを変更することができます。フィールドカーソルの設定はmysql_fetch_field()に対するその後の呼び出しに影響を及ぼします。mysql_fetch_fields()を呼び出すことによって、フィールドに対する情報を全て直ちに取得することもできます。

エラーを検出して報告するために、MySQLはmysql_errno()機能およびmysql_error()機能を使ってエラー情報にアクセスする手段を提供します。これらは、どんなエラーがいつ起こったかを査定することを可能にして、最近呼び出した、成功するか失敗することもあり得る機能に対するにエラーコードあるいはエラーメッセージを戻します。

23.2.3. C API機能の説明

23.2.3.1. mysql_affected_rows()
23.2.3.2. mysql_autocommit()
23.2.3.3. mysql_change_user()
23.2.3.4. mysql_character_set_name()
23.2.3.5. mysql_close()
23.2.3.6. mysql_commit()
23.2.3.7. mysql_connect()
23.2.3.8. mysql_create_db()
23.2.3.9. mysql_data_seek()
23.2.3.10. mysql_debug()
23.2.3.11. mysql_drop_db()
23.2.3.12. mysql_dump_debug_info()
23.2.3.13. mysql_eof()
23.2.3.14. mysql_errno()
23.2.3.15. mysql_error()
23.2.3.16. mysql_escape_string()
23.2.3.17. mysql_fetch_field()
23.2.3.18. mysql_fetch_field_direct()
23.2.3.19. mysql_fetch_fields()
23.2.3.20. mysql_fetch_lengths()
23.2.3.21. mysql_fetch_row()
23.2.3.22. mysql_field_count()
23.2.3.23. mysql_field_seek()
23.2.3.24. mysql_field_tell()
23.2.3.25. mysql_free_result()
23.2.3.26. mysql_get_character_set_info()
23.2.3.27. mysql_get_client_info()
23.2.3.28. mysql_get_client_version()
23.2.3.29. mysql_get_host_info()
23.2.3.30. mysql_get_proto_info()
23.2.3.31. mysql_get_server_info()
23.2.3.32. mysql_get_server_version()
23.2.3.33. mysql_get_ssl_cipher()
23.2.3.34. mysql_hex_string()
23.2.3.35. mysql_info()
23.2.3.36. mysql_init()
23.2.3.37. mysql_insert_id()
23.2.3.38. mysql_kill()
23.2.3.39. mysql_library_end()
23.2.3.40. mysql_library_init()
23.2.3.41. mysql_list_dbs()
23.2.3.42. mysql_list_fields()
23.2.3.43. mysql_list_processes()
23.2.3.44. mysql_list_tables()
23.2.3.45. mysql_more_results()
23.2.3.46. mysql_next_result()
23.2.3.47. mysql_num_fields()
23.2.3.48. mysql_num_rows()
23.2.3.49. mysql_options()
23.2.3.50. mysql_ping()
23.2.3.51. mysql_query()
23.2.3.52. mysql_real_connect()
23.2.3.53. mysql_real_escape_string()
23.2.3.54. mysql_real_query()
23.2.3.55. mysql_refresh()
23.2.3.56. mysql_reload()
23.2.3.57. mysql_rollback()
23.2.3.58. mysql_row_seek()
23.2.3.59. mysql_row_tell()
23.2.3.60. mysql_select_db()
23.2.3.61. mysql_set_character_set()
23.2.3.62. mysql_set_local_infile_default()
23.2.3.63. mysql_set_local_infile_handler()
23.2.3.64. mysql_set_server_option()
23.2.3.65. mysql_shutdown()
23.2.3.66. mysql_sqlstate()
23.2.3.67. mysql_ssl_set()
23.2.3.68. mysql_stat()
23.2.3.69. mysql_store_result()
23.2.3.70. mysql_thread_id()
23.2.3.71. mysql_use_result()
23.2.3.72. mysql_warning_count()

この説明で使用したNULLパラメータまたは戻り値は、MySQLNULL値ではなく、C プログラミング言語のセンスに含まれるNULL を意味します。

値を返す機能は一般にポインタあるいは整数を返します。特に規定しない限り、ポインタを返す機能は、非NULL値を戻して成功を示すか、NULL値を戻してエラーを示し、整数を返す機能は、ゼロを戻して成功を示すか、非ゼロを戻してエラーを示します。「non-zero」は文字通りの意味を持っていることにご注目ください。機能説明に別な指示がない限り、ゼロ以外の値に対してテストをしてはなりません:

if (result)                   /* correct */
    ... error ...

if (result < 0)               /* incorrect */
    ... error ...

if (result == -1)             /* incorrect */
    ... error ...

機能がエラーを返すとき、機能説明のサブセクションにあるエラーが起こる恐れのあるエラーのタイプを列記します。mysql_errno()を呼び出すことによって、これらのどれが起こったかを見つけることができます。mysql_error()を呼び出すことによって、エラーのストリング表示を得ることができます。

23.2.3.1. mysql_affected_rows()

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を戻し、既存の列を更新すると2を戻します。

23.2.3.2. mysql_autocommit()

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

説明

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

戻り値

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

エラー

なし。

23.2.3.3. mysql_change_user()

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()から取得出来る同じもの。

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

  • ER_UNKNOWN_COM_ERROR

    MySQLサーバはこのコマンドを実行しません。(サーバが多分高齢のため)。

  • ER_ACCESS_DENIED_ERROR

    ユーザー名あるいはパスワードが間違っています。

  • ER_BAD_DB_ERROR

    データベースが存在していませんでした。

  • ER_DBACCESS_DENIED_ERROR

    ユーザーはデータベースに対するアクセス権利を持っていませんでした。

  • ER_WRONG_DB_NAME

    データベース名が長すぎます。

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

23.2.3.4. mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

説明

現在の接続に対するデフォルト文字セットの戻り。

戻り値

デフォルト文字セット

エラー

なし。

23.2.3.5. mysql_close()

void mysql_close(MYSQL *mysql)

説明

前に開かれた接続を閉じてください。ハンドルがmysql_init()またはliteral>mysql_connect()によって自動的に割り当てられたものである場合、mysql_close()は、mysqlに合わせた接続ハンドルの割り当ても解除します。

戻り値

なし。

エラー

なし。

23.2.3.6. mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

説明

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

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

戻り値

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

エラー

なし。

23.2.3.7. mysql_connect()

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()に対するものと同じ。

23.2.3.8. mysql_create_db()

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

説明

dbパラメータと名付けたデータベースを生成させてください。

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.3.9. mysql_data_seek()

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

戻り値

なし。

エラー

なし。

23.2.3.10. mysql_debug()

void mysql_debug(const char *debug)

説明

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

戻り値

なし。

エラー

なし。

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

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

23.2.3.11. mysql_drop_db()

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

説明

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.3.12. mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

説明

サーバに幾つかのデバグ情報をログに書き込むよう指示してください。これを働かせるには、接続されたユーザーはSUPER特権を持っていなければなりません。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.13. mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

説明

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

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

mysql_store_result()に対して成功した呼び出しから結果セットを取得する場合、クライアントは1回のオペレーションで全セットを受け取ります。この場合、NULLmysql_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));
}

23.2.3.14. mysql_errno()

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クライアントプログラムは以下のフォーマットを使ってエラーを表示します。この場合、1146mysql_errno()値で、'42S02'は対応するmysql_sqlstate()値です:

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

戻り値

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

エラー

なし。

23.2.3.15. mysql_error()

const char *mysql_error(MYSQL *mysql)

説明

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

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

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

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

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

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

戻り値

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

エラー

なし。

23.2.3.16. mysql_escape_string()

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

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

23.2.3.17. mysql_fetch_field()

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

23.2.3.18. mysql_fetch_field_direct()

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

23.2.3.19. mysql_fetch_fields()

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

23.2.3.20. mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

説明

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

空のカラムのため、およびNULL値を含むカラムのための長さはゼロです。これら2つのケースを区別する方法を調べるには、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]);
    }
}

23.2.3.21. mysql_fetch_row()

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)によって与えられます。rowmysql_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()の呼び出しと呼び出しの間に、エラーはリセットされないことにご注目ください。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.3.22. mysql_field_count()

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() から直接、エラーがないかチェックしています。

23.2.3.23. mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

説明

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

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

戻り値

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

エラー

なし。

23.2.3.24. mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

説明

最後のmysql_fetch_field()に使用したフィールドカーソルの位置に戻ってください。この値をmysql_field_seek()に対する引数として使うことができます。

戻り値

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

エラー

なし。

23.2.3.25. mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

説明

mysql_store_result()mysql_use_result()mysql_list_dbs()等によって結果セットに割り当てられたメモリーを解放してください。結果セットを処分するとき、mysql_free_result()を呼び出すことによって、それが使用しているメモのリーを解放しなければなりません。

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

戻り値

なし。

エラー

なし。

23.2.3.26. mysql_get_character_set_info()

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

23.2.3.27. mysql_get_client_info()

const char *mysql_get_client_info(void)

説明

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

戻り値

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

エラー

なし。

23.2.3.28. mysql_get_client_version()

unsigned long mysql_get_client_version(void)

説明

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

戻り値

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

エラー

なし。

23.2.3.29. mysql_get_host_info()

const char *mysql_get_host_info(MYSQL *mysql)

説明

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

戻り値

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

エラー

なし。

23.2.3.30. mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

説明

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

戻り値

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

エラー

なし。

23.2.3.31. mysql_get_server_info()

const char *mysql_get_server_info(MYSQL *mysql)

説明

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

戻り値

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

エラー

なし。

23.2.3.32. mysql_get_server_version()

unsigned long mysql_get_server_version(MYSQL *mysql)

説明

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

戻り値

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

major_version*10000 + minor_version *100 + sub_version

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

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

エラー

なし。

23.2.3.33. mysql_get_ssl_cipher()

const char *mysql_get_ssl_cipher(MYSQL *mysql)

説明

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

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

戻り値

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

23.2.3.34. mysql_hex_string()

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

説明

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

from中のストリングは、2つの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の中に置かれた、ゼロで終わる文字を含まない値の長さ。

エラー

なし。

23.2.3.35. mysql_info()

const char *mysql_info(MYSQL *mysql)

説明

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

  • INSERT INTO ... SELECT ...

    ストリングフォーマット:記録:100 Duplicates:0 Warnings: 0

  • INSERT INTO ... VALUES (...),(...),(...)...

    ストリングフォーマット:記録:3 Duplicates:0 Warnings: 0

  • LOAD DATA INFILE ...

    ストリングフォーマット:記録:1 削除:スキップ:0 Warnings: 0

  • ALTER TABLE

    ストリングフォーマット:記録:3 Duplicates:0 Warnings: 0

  • UPDATE:

    ストリングフォーマット:マッチする列:40 変更済み:40 Warnings: 0

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

戻り値

最近実行されたステートメントに関する追加情報を表す文字ストリング。NULLステートメントに対する情報が得られない場合。

エラー

なし。

23.2.3.36. mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

説明

mysql_real_connect()に適したMYSQLオブジェクトを割り当てるか初期化してください。mysqlNULLポインターである場合、機能は、新しいオブジェクトを割り当て、初期化し且つ戻します。さもなければ、オブジェクトは初期化され、オブジェクトのアドレスが戻されます。mysql_init()が新しいオブジェクトを割り当てる場合、それは、接続を閉じるためにmysql_close()が呼び出されるとき、解放されます。

戻り値

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

エラー

メモリが不十分な場合、NULLが戻されます。

23.2.3.37. mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

説明

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

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

  • AUTO_INCREMENTカラムの中に値を記憶するINSERTステートメント。値が、NULLまたは0をカラムに収納することによって、自動的に生み出されるか、あるいは明示的な非スペシャル値であるか否かにかかわらず、これは真実です。

  • マルチ列INSERTステートメントの場合、mysql_insert_id()の戻り値は、MySQLのバージョンによって異なります。

    バージョンナンバー5.1.12以降では、初めに 自動的にかつ 首尾よく生成された AUTO_INCREMENT 値を返します。MySQLバージョンが5.1.12以前のMySQLでは、mysql_insert_id()は、値の挿入が成功したか否かにかかわりなく、最初に自動生成されたAUTO_INCREMENT値を戻します。

    列がうまく挿入されなかった時、mysql_insert_id()はゼロを戻します。

  • MySQL 5.1.12を立ち上げて、INSERT ... SELECT ステートメントを実行したが、自動生成された値がうまく挿入されない場合、mysql_insert_id() は最後に挿入した列のidを戻します。

  • MySQL 5.1.12を立ち上げて、INSERT ... SELECTステートメントがLAST_INSERT_ID(expr)を使う場合、mysql_insert_id()exprを戻します。

  • LAST_INSERT_ID()expr)をカラムに挿入することによって、AUTO_INCREMENT値を生成するINSERTステートメント。

  • LAST_INSERT_ID(expr)を更新することによって、AUTO_INCREMENT値を生成するINSERTステートメント。

  • mysql_insert_id()の値は、結果セットを戻すSELECTのようなステートメントによって影響を受けません。

  • 以前のステートメントがエラーを戻した場合、mysql_insert_id()の値は規定されません。

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

  1. 自動インクレメントカラムが存在し、自動生成された値がうまく挿入された場合、当該値の最初のものが戻されます。

  2. ステートメント中にLAST_INSERT_ID(EXPR)が含まれていた場合、影響されたテーブル中にオートインクレメント・カラムが含まれていたとしても、EXPRが戻されます。

  3. 戻り値は使用したステートメントによって変わります。INSERT INTOステートメントの後に呼び出されたとき:

    • テーブル中にオートインクレメント・カラムが存在していて、テーブル中にうまく挿入されたこのカラムーに対して、明確な幾つかの値があった場合、当該明確な値の最後が戻されます。

    INSERT ...ON DUPLICATE KEYステートメントの後に呼び出されるとき:

    • オートインクレメント・カラムとテーブルが存在していて更に、うまく挿入された幾つかの明確な値もしくは幾つかの更新された列があった場合、挿入されたか更新された値の最後が戻されます。

注意

前のステートメントがAUTO_INCREMENT値を使用していない場合、mysql_insert_id()0値を戻します。後で使用するため、値をセーブする必要がある場合、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カラムに何が起こったかに関する少し正確な情報を提供しようとすることに起因して生まれます。

戻り値

戻り値。

エラー

なし。

23.2.3.38. mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

説明

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.39. mysql_library_end()

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()をご参照ください。

23.2.3.40. mysql_library_init()

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

説明

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

アプリケーションが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の最初の要素は無視されます。(それには大抵プログラム名が含まれています)。便利にするため、もしサーバに対するコマンドーライン引数がない場合、argc0(ゼロ)であることが許されます。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なら0、エラーが起こったら1。

23.2.3.41. mysql_list_dbs()

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.42. mysql_list_fields()

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.43. mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

説明

それは、現在のサーバースレッドを述べた結果セットを戻します。これは、mysqladmin processlistまたはSHOW PROCESSLISTクエリーによって報告されたものと種類が同じ情報です。

mysql_free_result()を使って結果セットを解放しなければなりません。

戻り値

成功するためのMYSQL_RES結果セット。NULLエラーが起こった場合。

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.44. mysql_list_tables()

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.45. mysql_more_results()

my_bool mysql_more_results(MYSQL *mysql)

説明

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

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

戻り値

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

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

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

エラー

なし。

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. 「マルチプルステートメントを実行するC APIハンドリング」をご参照ください。

戻り値

戻り値摘要
0成功し且つ結果が更に存在する。
-1成功し且つ結果が更に存在しない。
>0エラーが発生した。

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。例えば、前の結果セットに対して、mysql_use_result()を呼び出さなかった場合。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.47. mysql_num_fields()

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

23.2.3.48. mysql_num_rows()

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を含む結果セットを戻すステートメントと一緒に使用するよう意図されています。INSERTUPDATEまたはDELETEのようなステートメントのために、影響された列の数をmysql_affected_rows()を使って取得することができます。

戻り値

結果セット中の行の数。

エラー

なし。

23.2.3.49. mysql_options()

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_INIT_COMMANDchar *サーバに接続する際実行するコマンド。再接続すると、自動的に再実行されます。
MYSQL_OPT_COMPRESS使用しない圧縮されたクライアント/サーバプロトコルを使用。
MYSQL_OPT_CONNECT_TIMEOUTunsigned int *接続タイムアウトまで秒読み。
MYSQL_OPT_GUESS_CONNECTION使用しないlibmysqldに対してリンクされたアプリケーションに対して、これは、ライブラリが埋込サーバを使うべきか、遠隔サーバを使うべきか憶測することを許します。「Guess」は、ホスト名がセットされたが、これがlocalhostでない場合、遠隔サーバを使うことを意味します。この行動はデフォルトです。MYSQL_OPT_USE_EMBEDDED_CONNECTIONおよびMYSQL_OPT_USE_REMOTE_CONNECTIONはそれを無効にするのに使うことができます。このオプションは、libmysqlclientに対してリンクされたアプリケーションの場合、無視されます。
MYSQL_OPT_LOCAL_INFILEユニットに対するオプションポインターポインターが附与されない場合もしくはunsigned int != 0を指さす場合、コマンドLOAD LOCAL INFILEは有効です。
MYSQL_OPT_NAMED_PIPE使用しないNT上のMySQLサーバに接続する指定パイプを使用してください。
MYSQL_OPT_PROTOCOLunsigned int *使用するプロトコルの種類。mysql.h で定義され mysql_protocol_type のEナンバー値のうちの1つであるべきです。
MYSQL_OPT_READ_TIMEOUTunsigned int *サーバからの読み込みタイムアウト(TCP/IPコネクションまたはMySQL 5.1.12以前のWindowsでのみ使用できます)。このオプションを使用すると、最後の接続を10分のTCP/IPClose_Wait_Timeout値より早期に検出することができます。
MYSQL_OPT_RECONNECTmy_bool *は、接続が失われたと判明した場合、は、サーバへの自動再接続を有効か無効にします。再接続は初期設定によってオフになっていますが、このオプションは再接続行動を明確にセットする方法を提供します。
MYSQL_OPT_SET_CLIENT_IPchar *libmysqldに対して (認証サポートを使って編集された libmysqld利用して)リンクされたアプリケーションの場合、これは、ユーザーは認証を目的に、(ストリングとして規定された)規定IPアドレスから接続したと思われることを意味します。このオプションは、libmysqlclientに対してリンクされたアプリケーションの場合、無視されます。
MYSQL_OPT_SSL_VERIFY_SERVER_CERTmy_bool *は、サーバに接続するとき使用したホスト名に対する証明の中に登録されたサーバの固有名の認証を有効化したり、無効化したりします。ミスマッチがあった場合、接続は拒絶されます。この機能は、man-in-the-middleアタックを防止するために使用することができます。認証は初期設定では無効になっています。MySQL 5.1.11に追加。
MYSQL_OPT_USE_EMBEDDED_CONNECTION使用しないlibmysqldに対してリンクされたアプリケーションの場合、これは、接続に埋込サーバを使用することを強要します。このオプションは、libmysqlclientに対してリンクされたアプリケーションの場合、無視されます。
MYSQL_OPT_USE_EMBEDDED_CONNECTION使用しないlibmysqldに対してリンクされたアプリケーションの場合、これは、接続に遠隔サーバを使用することを強要します。このオプションは、libmysqlclientに対してリンクされたアプリケーションの場合、無視されます。
MYSQL_OPT_USE_RESULT使用しないこのオプションは使用されません。
MYSQL_OPT_WRITE_TIMEOUTunsigned int *(現在、TCP/IP接続上のWindowsでのみ有効な)サーバへの書き込みに対するタイムアウト。
MYSQL_READ_DEFAULT_FILEchar *my.cnfから行う代わりに、指定オプションファイルからオプションを読み取ってくさださい。
MYSQL_READ_DEFAULT_GROUPchar *指定グループ、my.cnfまたはMYSQL_READ_DEFAULT_FILEを使って規定したファイルからオプションを読み取ってください。
MYSQL_REPORT_DATA_TRUNCATIONmy_bool *MYSQL_BIND.errorを経由して行う準備されたステートメントに対するデータ・トランランケーションエラーの報告を有効かしたり、無効化します。初期設定:無効化。)
MYSQL_SECURE_AUTHmy_bool*MySQL 4.1.1およびそれより新しいバージョンのMySQLに使用されているパスワードバッシングをサポートしていないサーバへの接続の可否。
MYSQL_SET_CHARSET_DIRchar*文字セットの定義ファイルを含むダイレクトリーに対するパスネーム。
MYSQL_SET_CHARSET_NAMEchar*デフォルト文字セットとして使用すべき文字セットの名称。
MYSQL_SHARED_MEMORY_BASE_NAMEchar*サーバとのコミュニケーションに使用すべ共有メモリオブジェクトの名称。接続したいmysqldサーバのために使用したオプション--shared-memory-base-nameと同じにすべきです。

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

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

オプション摘要
connect-timeout接続タイムアウト(秒)。Linux上で、このタイムアウトはサーバから最初の答えを待つためにも使います。
compress圧縮したクライアント/サーバプロトコルを使ってください。
database接続コマンドの中に規定されなかった場合、このデータベースに接続してください。
debugデバッグオプション。
disable-local-infileLOAD DATA LOCALの使用が無効。
hostデフォルトホストネーム。
init-commandMySQLサーバに接続する時実行すべきコマンド。再接続するとき、自動的に再実行されます。
interactive-timeoutCLIENT_INTERACTIVEmysql_real_connect()に規定すると同じように。項23.2.3.52. 「mysql_real_connect()参照。
local-infile[=(0|1)]引数がないか、引数!= 0の場合、LOAD DATA LOCALの使用を有効にする。
max_allowed_packetサーバから読み取ることができるパケットの最大サイズ。
multi-resultsマルチステートメントまたは記憶された手順の実行からマルチ結果セットを取得することを許す。
multi-statementsクライアントが、マルチステートメントを(‘;’によって仕切られた)シングルストリングの中に送ることを許す。
passwordデフォルトパスワード。
pipeNT上のMySQLサーバに接続するため、指定パイプを使ってください。
protocol={TCP|SOCKET|PIPE|MEMORY}サーバに接続するとき使用すべきプロトコル。
portデフォルトポートナンバー。
return-found-rowsUPDATEを使うとき、更新された列の代わりに見つかった列を戻すようmysql_info()に告げてください。
shared-memory-base-name=名称サーバに接続するとき使用すべき共有メモリー(デフォルトは"MYSQL")。
socketデフォルトソケットファイル。
userデフォルトユーザー。

timeoutconnect-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セクションから追加オプションを読み取ることを求めるものです。

23.2.3.50. mysql_ping()

int mysql_ping(MYSQL *mysql)

説明

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.51. mysql_query()

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

説明

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

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.52. mysql_real_connect()

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機能が実行可能になる前に、うまく完了されなければなりません。

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

  • 最初のパラメータは既存のMYSQL構造にすべきです。mysql_real_connect()を呼び出す前に、mysql_init()を呼び出してMYSQL構造を初期化しなければなりません。mysql_options()を呼び出して、多くの接続オプションを変更することができます。項23.2.3.49. 「mysql_options()を参照してください。

  • (この場合)hostの値をホスト名かIPアドレスにすることができます。hostNULLまたはストリング"localhost"である場合、ローカルホストへの接続と仮定します:Windowsに対して、サーバが共有メモリー接続を有効にしている場合、クライアントはメモリー接続を使って接続します。さもなければ、TCP/IPが使われます。Unixの場合、クライアントはUnix専用のソケットファイルを使って接続します。ローカル接続の場合、mysql_options()に対してMYSQL_OPT_PROTOCOLオプションもしくはMYSQL_OPT_NAMED_PIPEオプションと一緒に使う接続のタイプに影響を及ぼすこともできます。接続のタイプはサーバによってサポートされなくければなりません。Windows上の"."host値に対して、クライアントは指定パイプを使って接続します。指定パイプによる接続が有効化されていないと、エラーが発生します。

  • userパラメータには、ユーザーのMySQLログインIDが含まれています。userNULLまたは空ストリング""である場合、現在のユーザーを想定します。Unixでは、これは現在のログイン名です。Windows ODBCでは、現在のユーザ名を明確に規定しなければなりません。章 24. MySQL コネクタのMyODBCセクションをご参照ください。

  • passwdパラメータには、userに対するパスワードが含まれています。passwdNULLである場合、ブランク(空の)パスワードフィールドを持つユーザーのために行ったuser テーブルへの入力だけがマッチするかチェックされます。これは、データベース管理者がMySQL特権システムを、 ユーザーがパスワードを規定したか否かによって、異なった特権を取得するようにセットすることを可能にします。

    :mysql_real_connect()を呼び出す前に、パスワードを暗号化しようとしてはなりません。パスワードの暗号化はクライアントAPIによって自動的に取り扱われます。

  • dbはデータベース名です。dbNULLでない場合、接続はこの値にデフォルトデータベースを設定します。

  • portが0でない場合、値はTCP/IP接続のためのポートナンバーとして使用されます。hostパラメータが接続のタイプを決めることにご注目ください。

  • unix_socketNULLでない場合、ストリングは使用すべきソケットまたは指定パイプを規定します。hostパラメータが接続のタイプを決めることにご注目ください。

  • client_flagの値は通常0ですが、次のフラグを組み合わせてセットすると、ある種の機能を有効にすることができます:

    フラグ名フラグの説明
    CLIENT_COMPRESS圧縮プロトコルの使用。
    CLIENT_FOUND_ROWS変更した行の数でなく、検出され(マッチした)行の数を戻す。
    CLIENT_IGNORE_SPACE機能名の後にスペースを取ることを許します。全ての機能名を予約されたワードにします。
    CLIENT_INTERACTIVE接続を閉じる前に(wait_timeout秒の代わりに)、interactive_timeout秒間停止します。クライアントのセッションwait_timeout変数は、セッションinteractive_timeout変数の値にセットされます。
    CLIENT_LOCAL_FILESLOAD DATA LOCALハンドリングを有効化します。
    CLIENT_MULTI_RESULTSサーバに、クライアントはマルチ結果セットをマルチステートメントの実効から処理できることを通知します。CLIENT_MULTI_STATEMENTSがセットされる場合、自動的にセットされます。フラグの詳細については、このテーブルの後にあるノートをご参照ください。
    CLIENT_MULTI_STATEMENTSサーバに、クライアントは、(‘;’によって隔離された)シングルストリングの中にマルチステートメントを送ることができることを通知します。このフラグがセットされないと、マルチステートメントの実効は不能になります。フラグの詳細については、このテーブルの後にあるノートをご参照ください。
    CLIENT_NO_SCHEMAdb_name.tbl_name.col_name構文の使用を許しません。これはODBCのためのものです。幾つかODBCプログラム中でバグを捕えるのに役立つあの構文を使うと、それが、パーサーがエラーを生成する原因を引き起こします。
    CLIENT_ODBCクライアントはODBCクライアントです。これはmysqldをODBCにもっと優しくなるように変更します。
    CLIENT_SSLSSL(暗号化されたプロトコル)を使います。このオプションはアプリケーションプログラムによってセットされるべきではありません。これはクライアントライブラリ内部でセットされます。その代わりに、mysql_real_connect()を呼び出す前に、mysql_ssl_set()を使ってください。

プログラムが結果セットを生成する記憶された手順を実行するために、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. 「マルチプルステートメントを実行するC APIハンドリング」をご覧ください。)

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

  • hostに対して、NULLまたは空のストリング("")の値を規定してください。

  • userに対して、NULLまたは空のストリングの値を規定してください。

  • passwdに対して、NULLの値を規定してください。(パスワードに対して、mysql_real_connect()コール中の空ストリングの値がオプションファイルに入るのを禁止することはできません。なぜなら、空のストリングは、MySQLアカウントには空のパスワードが含まれていなければならないことを明示しているからです。)

  • dbに対して、NULLまたは空のストリングの値を規定してください。

  • portに対して、ゼロの値を規定してください。

  • unix_socketに対して、NULLの値を規定してください。

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

戻り値

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

エラー

  • CR_CONN_HOST_ERROR

    MySQLサーバとの接続が失敗した。

  • CR_CONNECTION_ERROR

    ローカルMySQLサーバとの接続が失敗した。

  • CR_IPSOCK_ERROR

    IPソケットの生成に失敗した。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SOCKET_CREATE_ERROR

    Unixソケットの生成に失敗した。

  • CR_UNKNOWN_HOST

    ホスト名のIP アドレスの検出に失敗した。

  • CR_VERSION_ERROR

    異なったバージョンのクライアントライブラリを持つサーバに接続しようと試みたことから発生したプロトコルミスマッチ。これは、--old-protocolオプションを使って立ち上げなかった新しいサーバに接続する非常に古いクライアントライブラリを使った場合に起こることがあります。

  • CR_NAMEDPIPEOPEN_ERROR

    Windows上に指定パイプを生成することに失敗した。

  • CR_NAMEDPIPEWAIT_ERROR

    Windows上に指定パイプを待つことに失敗した。

  • CR_NAMEDPIPESETSTATE_ERROR

    Windows上にパイプハンドラーを取得することに失敗した。

  • CR_SERVER_LOST

    connect_timeoutが> 0で、サーバに接続するまでにconnect_timeout秒未満の時間がかかるか、init-commandを実行している間にサーバが死亡した場合。

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()に対して、再接続行動を制御するのに使用することができます。

23.2.3.53. mysql_real_escape_string()

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バイトにしなければなりません。(最悪の場合、各文字は2バイトを使用するように、コード化する必要があるかもしれないので、端末ゼロバイトのための余裕が必要です。)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の中に置かれた、ゼロで終わる文字を含まない値の長さ。

エラー

なし。

23.2.3.54. mysql_real_query()

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

説明

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.55. mysql_refresh()

int mysql_refresh(MYSQL *mysql, unsigned int options)

説明

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

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

  • REFRESH_GRANT

    FLUSH PRIVILEGESのような供与されたテーブルをリフレッシュしてください。

  • REFRESH_LOG

    FLUSH LOGSのようなログをフラッシュしてください。

  • REFRESH_TABLES

    FLUSH TABLESのようなテーブルキャッシュをフラッシュしてください。

  • REFRESH_HOSTS

    FLUSH HOSTSのようなホストキャッシュをフラッシュしてください。

  • REFRESH_STATUS

    FLUSH STATUSのようなステータス変数をリセットしてください。

  • REFRESH_THREADS

    スレッドキャッシュをフラッシュしてください。

  • REFRESH_SLAVE

    スレイブ模写サーバー上で、マスターサーバ情報をリセットし、RESET SLAVEのようなスレイブを再起動してください。

  • REFRESH_MASTER

    マスター模写サーバ上で、バイナリーログインデックスを除去して、RESET MASTERのようなインデックスファイルを切り捨ててください。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.56. mysql_reload()

int mysql_reload(MYSQL *mysql)

説明

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.57. mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

説明

現取引のロールバック。

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

戻り値

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

エラー

なし。

23.2.3.58. mysql_row_seek()

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()に対する次の呼び出しに渡すことができます。

エラー

なし。

23.2.3.59. mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

説明

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

mysql_row_tell()を、mysql_use_result()の後でなく、mysql_store_result()の後にだけ使うべきです。

戻り値

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

エラー

なし。

23.2.3.60. mysql_select_db()

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

説明

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

接続されたユーザーが認証されることができない限り、mysql_select_db()は失敗します。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.61. mysql_set_character_set()

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

23.2.3.62. mysql_set_local_infile_default()

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()機能が追加されました。

戻り値

なし。

エラー

なし。

23.2.3.63. mysql_set_local_infile_handler()

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()機能が追加されました。

戻り値

なし。

エラー

なし。

23.2.3.64. mysql_set_server_option()

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

説明

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

MYSQL_OPTION_MULTI_STATEMENTS_ONマルチステートメントサポートを有効化します。
MYSQL_OPTION_MULTI_STATEMENTS_OFFマルチステートメントサポートを無効化します。

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • ER_UNKNOWN_COM_ERROR

    サーバがmysql_set_server_option()をサポートしなかった (そのサーバが4.1.1より古いかった場合)もしくはサーバがセットしようと努めたオプションをサポートしなかった。

23.2.3.65. mysql_shutdown()

int mysql_shutdown(MYSQL *mysql, enum mysql_enum_shutdown_level shutdown_level)

説明

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.66. mysql_sqlstate()

const char *mysql_sqlstate(MYSQL *mysql)

説明

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

mysql_sqlstate()が戻したMySQLに固有なエラーナンバーは、mysql_errno()が戻したSQLSTATE値とは異なっています。例えば、mysqlクライアントプログラムは以下のフォーマットを使ってエラーを表示します。この場合、1146mysql_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()をご参照ください。

23.2.3.67. mysql_ssl_set()

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サポートがクライアントライブラリの中で有効でない限り、何も実行できません。

mysqlmysql_init()から戻された接続ハンドラーです。他のパラメータは次のように規定されます:

  • keyはキーファイルに対するパスネームです。

  • keyは証明書ファイルに対するパスネームです。

  • caは証明証明官庁ファイルに対するパスネームです。

  • capathはpemフォーマットの信頼されたSSL CA証明を含むダイレクトリに対するパスネームです。

  • cipherはSSL暗号化のために使用すべき許容暗号のリストです。

未使用SSLパラメータは全てNULLとして与えられます。

戻り値

この機能は常に0を戻します。SSLの設定が不適当である場合、mysql_real_connect()は接続を試みるとき、エラーを戻します。

23.2.3.68. mysql_stat()

const char *mysql_stat(MYSQL *mysql)

説明

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.69. mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

説明

mysql_query()またはmysql_real_query()を取り出した後、データ(SELECTSHOWDESCRIBEEXPLAINCHECK 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. 「マルチプルステートメントを実行するC 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()をリセットします。

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.70. mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

説明

現在接続のスレッドIDを戻します。この値をスレッドを殺すmysql_kill()に対する引数として使うことができます。

接続が失われたとき、mysql_ping()に接続すると、スレッドのIDが変わります。これは、スレッドIDを取得して、後のためにそれを記憶すべきではないことを意味します。要なとき、それを取得すべきです。

戻り値

現在接続のスレッドID。

エラー

なし。

23.2.3.71. mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

説明

データ(SELECTSHOWDESCRIBEEXPLAIN)をうまく復元する全てのクエリーのために、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()をリセットします。

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.3.72. mysql_warning_count()

unsigned int mysql_warning_count(MYSQL *mysql)

説明

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

戻り値

警告アカウント。

エラー

なし。

23.2.4. 準備されたC APIステートメント。

MySQLクライアント/サーバ・プロトコルは準備されたステートメントの使用を規定します。この能力には、mysql_stmt_init()初期化機能によって戻されたMYSQL_STMTステートメントハンドラー・データ構造が使われています。準備された実行は1回以上ステートメントを実行する効率的な方法です。ステートメントはその実行のために最初解析されます。その後、それは初期化機能によって戻されたシテートメントハンドルを使って複数回実行されます。

準備された実行は、基本的にクエリの解析が一度だけなので、一度以上実行されるステートメントの実行を、直接実行するより素早く行います。直接実行の場合、クエリは実行のたびに解析されます。準備された実行はまた、実行のたびにパラメータにデータを送るだけで済むので、ネットワークの通信料を減らす効果があります。

準備されたステートメントは状況によっては、性能の増加をもたらさない場合があります。最も良い結果を得るため、準備されたステートメントと準備されていないステートメントの両方を使って、自分のアプリプリケーションをテストして、最もよい性能が得られる方を選んでください。

プリペアド ステートメントの他の利点は、クライアントとサーバ間のデータ伝達をより効果的にするバイナリ プロトコルを使用していることです。

次のステートメントは準備されたステートメントとして用いることができます:CREATE TABLEステートメント、DELETEステートメント、DOステートメント、INSERTステートメント、REPLACEステートメント、SELECTステートメント、SETステートメント、UPDATE並びに殆どのSHOWステートメント。

MySQL 5.1.10では、次のステートメントがサポートされています:

ANALYZE TABLE
OPTIMIZE TABLE
REPAIR TABLE

MySQL 5.1.12では、次のステートメントがサポートされています:

CACHE INDEX
CHANGE MASTER
CHECKSUM {TABLE | TABLES}
{CREATE | RENAME | DROP} DATABASE
{CREATE | RENAME | DROP} USER
FLUSH {TABLE | TABLES | TABLES WITH READ LOCK | HOSTS | PRIVILEGES
  | LOGS | STATUS | MASTER | SLAVE | DES_KEY_FILE | USER_RESOURCES}
GRANT
REVOKE
KILL
LOAD INDEX INTO CACHE
RESET {MASTER | SLAVE | QUERY CACHE}
SHOW BINLOG EVENTS
SHOW CREATE {PROCEDURE | FUNCTION | EVENT | TABLE | VIEW}
SHOW {AUTHORS | CONTRIBUTORS | WARNINGS | ERRORS}
SHOW {MASTER | BINARY} LOGS
SHOW {MASTER | SLAVE} STATUS
SLAVE {START | STOP}
INSTALL PLUGIN
UNINSTALL PLUGIN

他のステートメントはMySQL 5.1にサポートされていません。

23.2.5. 準備されたC APIステートメントデータタイプ

準備されたステートメントにはいくつかのデータ構造が使われます:

  • ステートメントを準備するため、ステートメントストリングをmysql_stmt_init()をに渡してください。 これによって、ポインターがMYSQL_STMTに戻されます。

  • インプットパラメータを準備されたステートメントに規定するには、MYSQL_BIND構造を設定して、それをmysql_stmt_bind_param()に渡してください。アウトプットカラムを受け取るには、MYSQL_BINDを設定して、これをmysql_stmt_bind_result()に渡してください。

  • MYSQL_TIME構造は一時データを両方向に転送するために使われます。

次の講義で、準備されたステートメントのデータタイプを詳細に説明します。

  • MYSQL_STMT

    この構造は準備されたステートメントを表します。ステートメントはmysql_stmt_init()を呼び出すことによって生成され、これによって、ステートメントハンドル(即ちMYSQL_STMT>)が戻され ます。ハンドルは、それをmysql_stmt_close()を使って選択するまで、そのステートメントを使った後のオペレーションに使われます。

    MYSQL_STMT構造には、アプリケーションに使うよう意図されたメンバーが含まれていません。また、MYSQL_STMT構造のコピーを作ろうとすべきではありません。このようなコピーが使用可能である保証はありません。

    マルチステートメントハンドルには接続が1個して付いていません。ハンドルの数に対する限度は利用できる資源によって変わります。

  • MYSQL_BIND

    この構造は、ステートメント・インプット(サーバに送られたデータ値)とステートメント・アウトプット(サーバから戻された結果値)の両方のために使われます:

    • インプットに対して、MYSQL_BINDは、mysql_stmt_bind_param()と一緒に、パラメータデータを、mysql_stmt_execute()が使う目的でバッファーに固定するために使われます。

    • インプットに対して、MYSQL_BINDmysql_stmt_bind_result()と一緒に、列をフェッチッするのに使用するため、結果セットバッファーをmysql_stmt_fetch()に固定するのに使われます。

    MYSQL_BIND構造を使うために、中身をゼロにして、それを初期化してから、そのメンバーを適当にセットしてください。例えば、3つのMYSQL_BIND 構造のアレイを宣言し、初期化するために、このコードを使ってください:

    MYSQL_BIND bind[3];
    memset(bind, 0, sizeof(bind));
    

    MYSQL_BIND構造はアプリケーションプログラムが使用するめ、次のメンバーを含んでいます。メンバーの幾つかに対して使用するマナーは、構造がインプットに使われるか、アウトプットに使われるかによって変わります。

    • enum enum_field_types buffer_type

      バッファーのタイプ。このメンバーはあなたがステートメントパラメータに固定しているC言語変数のデータタイプを示します。許容されるbuffer_type値はこのセクションで後に列記されています。インプットに対して、buffer_typeはサーバに送る値を含む変数のタイプを示します。アウトプットに対してそれは、サーバから受け取った値を記憶させたい変数のタイプを示します。

    • void *buffer

      データの転送に使用する、バッファーに対するポインター。これは変数のアドレスです。

      インプットの場合、bufferはステートメントのパラメータが記憶される変数に対するポインターです。mysql_stmt_execute()を呼び出すとき、MySQLは変数に記憶した値を取り込んでそれを、ステートメント中の対応するパラメータ・マーカーの場所に置きます。

      アウトプットの場合、bufferはその中に結果セットのコラム値を戻す変数に対するポインターです。mysql_stmt_fetch()を呼び出すとき、MySQLはカラム値を戻し、それをこの変数の中に記憶します。呼び出しに戻って値にアクセスすることができます。

      MySQLが実施する必要のあるクライアント側のC言語の値とサーバ側のSQLの値の間のタイプ変換を最小にするため、対応するSQLの値と同等なタイプを含む変数を使ってください。データが数値タイプである場合、bufferをCタイプの適当な数値に指定すべきです。(charまたは整数変数の場合、あなたは、後で述べるunsignedメンバーをこのリストの中にセットすることによって、変数にis_unsigned属性が含まれているか否かも示すべきです。文字(非バイナリー)タイプおよびバイナリース・トリングデータタイプに対して、bufferをバッファーに指定すべきです。日付データタイプおよび時間データタイプに対して、bufferMYSQL_TIME構造に指すべきです。

      後のセクションにあるタイプ変換に関する注をご参照ください。

    • unsigned long buffer_length

      *bufferの実サイズ(バイト)。これはバッファーに記憶することができるデータの最大量を示します。文字とバイナリーCデータに対して、buffer_length値は、mysql_stmt_bind_param()と一緒に使ってインプット値を規定する*bufferの長さ、またはmysql_stmt_bind_result()と一緒に使うとき、バッファーにフェッチできるアウトプットデータバイトの最大数を規定します。

    • unsigned long *length

      *buffer中に記憶されたデータの実のバイト数を示す*buffer変数に対するポインター。lengthは文字またはバイナリーCデータに使われます。

      インプットパラメータデータを結合する場合、lengthは、*buffer中に記憶されたパラメータ値の実際の長さを示すunsigned long変数を指します。これはmysql_stmt_execute()によって使われます。

      アアウトプット値を結合する場合、mysql_stmt_fetch()の戻り値は長さの解釈を決めます:

      • mysql_stmt_fetch()がゼロを戻す場合、*lengthは、パラメータ値の実の長さを示します。

      • mysql_stmt_fetch()MYSQL_DATA_TRUNCATEDを戻す場合、*lengthはパラメータ価値の切り捨て前の長さを示します。この場合、*lengthbuffer_lengthの最小は、その値の実の値を示します。

      データ値の長さはbuffer_type値によって決まるので、lengthは数値タイプのデータと一時タイプのデータに対して無視されます。

    • my_bool *is_null

      このナンバーは、値がNULLである場合、真で、それがNULLでない場合、虚となるmy_bool変数を指します。インプットに対して、*is_nullを真にセットして、NULL値をステートメントパラメータとして渡すことを示してください。

      is_nullはブーリアンスカラーではないが、pointerの代わりにブーリアンスカラーをさす理由は、NULL値を規定する方法にフレキシビリティを提供することです:

      • データ値がいつもNULLである場合、カラムを結束するとき、MYSQL_TYPE_NULLbuffer_type値として使ってください。他のメンバーは問題ではありません。

      • データ値がいつもNOT NULLである場合、あなたが結束している変数に対して、他のメンバーを適当にセットし、is_null = (my_bool*) 0をセットしてください。

      • その他の場合、他のメンバーを適当にセットし、is_nullmy_bool変数のアドレスにセットしてください。実行と実行の間に変数の値を適当に真か虚にセットして、データ値がNULLであるかNOT NULLであるかを、それぞれ示してください。

      アウトプットに対して、is_nullをさす値は、ステートメントから戻された結果セットカラム値がNULLである場合、列をフェッチした後に真にセットされます。

    • my_bool is_unsigned

      このメンバーは、unsigned (char, short int, int, long long int)であることができるデータタイプと一緒にC変数のために使われます。bufferをさす変数がunsignedである場合、is_unsignedを真にセットし、そうでない場合には、虚にセットしてください。例えば、signed char変数をbufferに結びつける場合、MYSQL_TYPE_TINYのタイプコードを規定し、 is_unsignedを虚にセットしてください。代わりに、unsigned charを結びつける場合、タイプコードは同じですが、is_unsignedを真にすべきです。(charに対して、それがサインされるか否かが規定されないので、signed charまたはunsigned charを使って、サインについて明確にすることがベストです。)

      is_unsignedはクライアント側のC言語変数だけに適用されます。それはクライアント側の対応するSQL値に対するサインの必要性に付いて何も示しません。例えば、intを使ってBIGINT UNSIGNEDカラムのために値を供給する場合、intはサインするタイプなので、is_unsignedを虚にすべきです。unsigned intを使ってBIGINTカラムのために値を供給する場合、unsigned intはサインするタイプなので、is_unsignedを真にすべきです。MySQLは、結果が切り捨てられる場合警告が起こりますが、サイン済みの値と未サインの値の間の変換を両方向に実施します。

    • my_bool *error

      アウトプットに対して、このメンバーをmy_bool変数をさして、列をフェッチした後、そこに記憶されたパラメータに対する切り捨て情報を持たせてください。(切り捨て報告はデフォルトによって有効化されますが、MYSQL_REPORT_DATA_TRUNCATIONオプションを使って、mysql_options()を呼び出すことによって、これを制御することができます。)切り捨て報告を有効化するとき、mysql_stmt_fetch()MYSQL_DATA_TRUNCATEDを戻し、*errorは、その中で切り捨てが起こるMYSQL_BIND構造中で真となります。切り捨ては、サインまたは重要な桁の喪失あるいは、ストリングはコラムに収めるには長すぎたことを示します。

  • MYSQL_TIME

    この構造は、DATETIMEDATETIMEおよびTIMESTAMPデータを直接サーバからかサーバに送り且つ受け取るのに使われます。MYSQL_BIND>構造のbuffer_typeメンバーを 一時タイプ(MYSQL_TYPE_TIME, MYSQL_TYPE_DATEMYSQL_TYPE_DATETIMEMYSQL_TYPE_TIMESTAMP)の一つにセットし、bufferメンバーをMYSQL_TIME構造をさすようにセットしてください。

    MYSQL_TIME構造には、次のテーブルに列記したメンバーが含まれています:

    メンバー摘要
    unsigned int year
    unsigned int month年の月
    unsigned int day月の日
    unsigned int hour日の時間
    unsigned int minute時間の分
    unsigned int second分の秒
    my_bool neg時間がネガテブか否かを示すブーリアンフラグ
    unsigned long second_partマイクロ秒中の秒の部分;現在使用していない

    一時値の或るタイプに適用するMYSQL_TIME構造のこれらの部分だけが使われます。yearmonthおよびdayエレメントは、DATEDATETIMEおよびTIMESTAMP値に対して使用されます。hourminuteおよびsecondエレメントは、TIMEDATETIMEおよびTIMESTAMP値に対して使用されます。項23.2.10. 「日付とタイム値のC API式取り扱い」を参照してください。

以下のテーブルは、インプットのためのMYSQL_BIND構造のbuffer_typeナンバーの中に規定することができる許容値を示します。その値はあなたが結合しているC言語変数のデータタイプに従って選択されるべきです。その値がunsignedである場合、is_unsignedナンバーも真にセットすべきです。テーブルは、使用できるC 変数タイプ、対応するタイプコードおよび供給された値を変換することなく使用できるSQLデータタイプを示します。

入力変数C型buffer_type SQL型のあて先値
signed charMYSQL_TYPE_TINYTINYINT
short intMYSQL_TYPE_SHORTSMALLINT
intMYSQL_TYPE_LONGINT
long long intMYSQL_TYPE_LONGLONGBIGINT
floatMYSQL_TYPE_FLOATFLOAT
doubleMYSQL_TYPE_DOUBLEDOUBLE
MYSQL_TIMEMYSQL_TYPE_TIMETIME
MYSQL_TIMEMYSQL_TYPE_DATEDATE
MYSQL_TIMEMYSQL_TYPE_DATETIMEDATETIME
MYSQL_TIMEMYSQL_TYPE_TIMESTAMPTIMESTAMP
char[]MYSQL_TYPE_STRING (非バイナリデータ用)TEXT, CHAR, VARCHAR
char[]MYSQL_TYPE_BLOB (バイナリデータ用)BLOB, BINARY, VARBINARY
 MYSQL_TYPE_NULLNULL

MYSQL_TYPE_NULLの使用は、is_nullナンバーと関連させて前に説明されています。

以下のテーブルは、インプットのためのMYSQL_BIND構造のbuffer_typeナンバーの中に規定することができる許容値を示します。その値はあなたが結合しているC言語変数のデータタイプに従って選択されるべきです。その値がunsignedである場合、is_unsignedナンバーも真にセットすべきです。テーブルは、受領値のSQLタイプ、このような値が結果セットメタデータ中に持つ対応するタイプコード並びにSQL値を変換することなく受け取るMYSQL_BIND構造と結合する推薦されたC言語データのタイプを示します。

SQL型の受信値buffer_type 出力変数C型
TINYINTMYSQL_TYPE_TINYsigned char
SMALLINTMYSQL_TYPE_SHORTshort int
MEDIUMINTMYSQL_TYPE_INT24int
INTMYSQL_TYPE_LONGint
BIGINTMYSQL_TYPE_LONGLONGlong long int
FLOATMYSQL_TYPE_FLOATfloat
DOUBLEMYSQL_TYPE_DOUBLEdouble
DECIMALMYSQL_TYPE_NEWDECIMALchar[]
YEARMYSQL_TYPE_SHORTshort int
TIMEMYSQL_TYPE_TIMEMYSQL_TIME
DATEMYSQL_TYPE_DATEMYSQL_TIME
DATETIMEMYSQL_TYPE_DATETIMEMYSQL_TIME
TIMESTAMPMYSQL_TYPE_TIMESTAMPMYSQL_TIME
CHAR, BINARYMYSQL_TYPE_STRINGchar[]
VARCHAR, VARBINARYMYSQL_TYPE_VAR_STRINGchar[]
TINYBLOB, TINYTEXTMYSQL_TYPE_TINY_BLOBchar[]
BLOB, TEXTMYSQL_TYPE_BLOBchar[]
MEDIUMBLOB, MEDIUMTEXTMYSQL_TYPE_MEDIUM_BLOBchar[]
LONGBLOB, LONGTEXTMYSQL_TYPE_LONG_BLOBchar[]
BITMYSQL_TYPE_BITchar[]

タイプ変換を避けたい場合、C言語の変数タイプは推薦されたそれらです。クライアント側のC変数とサーバ側の対応するSQL値の間にミスマッチがある場合、MySQLは暗黙のタイプ変換を実施します。

MySQLはサーバ側のSQL値に対するタイプコードを知っています。buffer_type値は、クライアント側に値を保持する変数のタイプコードを示します。2つのコードは一緒になってMySQLにどんな変換を実施しなければならないかを告げます。以下に例を示します。

  • MYSQL_TYPE_LONGint変数と一緒に使用して、整数値をFLOATカラムに記憶されるべきサーバに渡す場合、MySQLはその値を、それを記憶する前に浮動点フォーマットに変換します。

  • SQL MEDIUMINTカラム値をフェッチするが、MYSQL_TYPE_LONGLONGbuffer_type値を規定し、タイプlong long intのC変数をバッファーの行き先として使用する場合、MySQLは(8バイトより少ないメモリーを必要とする)MEDIUMINT値を、long long int(8バイトの変数)の中に記憶させるために変換します。

  • 数値カラムを255の値を使って、char[4]文字アレーの中にフェッチし、MYSQL_TYPE_STRINGbuffer_type値を規定する場合、アレー中の合成値は、'255\0'を含む4バイト・ストリングとなります。

  • DECIMAL値はストリングとして戻されます。これが対応するCタイプがchar[]である理由です。DECIMAL値は、最初のサーバ側の値のストリング表示に対応するサーバによって戻されます。例えば、12.345はクライアントに'12.345'として戻されます。MYSQL_TYPE_NEWDECIMALを規定し、ストリングバッファーをMYSQL_BIND構造につなげる場合、mysql_stmt_fetch()はバッファー中の値を、変換するこなく記憶します。代わりに、数値変数とタイプコード規定する場合、mysql_stmt_fetch()はストリングフォーマットDECIMAL値を数値フォームに変換します。

  • MYSQL_TYPE_BITタイプコードのために、BIT値はストリングバッファーの中に戻されます。(これによって、対応するCタイプもここのchar[]になります。)価値はクライアント側に関する解釈を必要とするビットストリングを表します。値を扱い易いタイプとして戻すため、+ 0を使う次のフォームのクエリーを使って、値が整数に計算されるようにすることができます。

    SELECT bit_col + 0 FROM t
    

    値を復元するため、整数をその値を保持するに十分な大きさの変数に結び付けて、対応する適当な整数タイプコードを規定してください。

変数をカラムをフェッチするのに使用すべきMYSQL_BIND構造に結びつける前に、結果セットの各カラムに対して、タイプコードをチェックすることができます。どの変数タイプがタイプ変換を避けるために使うのに最も良いか決めたい場合、これが望ましいかもしれません。タイプコードを得るため、準備されたステートメントをmysql_stmt_execute()を使って実行した後、mysql_stmt_result_metadata()を呼び出してください。メタデータは、項23.2.7.22. 「mysql_stmt_result_metadata()および項23.2.1. 「C APIデータタイプ」で述べた結果セットのためのタイプコードへのアクセス手段を提供します。

MYSQL_FIELDカラムメタデータ構造のmax_lengthメンバーを(mysql_stmt_attr_set()メンバーを呼び出すことによって)セットさせるようにする場合、結果セットのためのmax_length値が、バイナリー画面の長さではなく、結果値の最も長いストリングを示すことにご注目ください。即ち、max_lengthは、準備されたステートメントのために使用されたバイナリープロトコルを使って値をフェッチするに要するバッファーのサイズに必ずしも対応しません。バッファのサイズはその中に値をフェッチする変数のタイプに従って選択されるべきです。

MYSQL_TYPE_STRINGによって示される)インプット文字(非バイナリー)ストリングの日付に対して、その値はcharacter_set_clientシステム変数によって示される文字セットの中にあると見なします。値が異なった文字セットと一緒にカラムの中に記憶される場合、その文字セットに対して適切な変換が起こります。(MYSQL_TYPE_BLOBによって示される)インプットバイナリーストリングデータに対して、その値はbinary文字セットを含んでいるものとして処理されます。即ち、それはバイトストリングとして処理されるので、変換は起こりません。

サーバから戻されたアウトプットストリング値にバイナリーまたは非バイナリーデータが含まれているか否かを査定するには、結果セットメタデータのcharsetnr値が 63であるか否かをチェックします。 (項23.2.1. 「C APIデータタイプ」参照)そうである場合、文字セットはbinaryで、これは、非バイナリーデータでなく、バイナリーデータであることを示します。これが、BINARYCHARVARBINARYVARCHARおよびBLOB並びにTEXTタイプを区別することを可能にします。

23.2.6. 準備されたC APIステートメント機能の概要

準備されたステートメントの処理に利用可能な機能の概要をここで一括説明し、後のセクションで各機能について詳細に説明します。項23.2.7. 「準備されたC APIステートメント機能の詳細」を参照してください。

機能説明
mysql_stmt_affected_rows()準備されたUPDATEDELETE、またはINSERT ステートメントの行変更、消去、もしくは挿入の回数を返す。
mysql_stmt_attr_get()準備されたステートメントの属性値を入手する。
mysql_stmt_attr_set()準備されたステートメントの属性をセットする。
mysql_stmt_bind_param()準備されたSQLステートメントのパラメータマーカとアプリケーションデータバッファを関連させる。
mysql_stmt_bind_result()結果セットのカラムとアプリケーションデータバッファを関連させる。
mysql_stmt_close()準備されたステートメントに使用されているメモリを開放する。
mysql_stmt_data_seek()ステートメント結果セットの任意の行ナンバーをシークする。
mysql_stmt_errno()最後に実行されたステートメントに対してエラーナンバーを返す。
mysql_stmt_error()最後に実行されたステートメントに対してエラーメッセージを返す。
mysql_stmt_execute()準備されたステートメントを実行する。
mysql_stmt_fetch()結果セットから次のデータの行を入手し、全ての束縛されたカラムのデータを返す。
mysql_stmt_fetch_column()結果セットの現在の行の1カラムからデータを入手する。
mysql_stmt_field_count()最近のステートメントの結果カラムの数を返す。
mysql_stmt_free_result()ステートメントハンドルに割り当てられたリソースを開放する。
mysql_stmt_init()MYSQL_STMT 構成のためのメモリを確保し、初期化する。
mysql_stmt_insert_id()準備されたプログラムに夜AUTO_INCREMENT カラム用に生成されたIDを返す。
mysql_stmt_num_rows()ステートメントのバッファされた結果セットからトータル行を返す。
mysql_stmt_param_count()準備されたSQLステートメント内のパラメータの数を返す。
mysql_stmt_param_metadata()(結果セットの形でパラメータメタデータを返す。)現在、この機能は何もしません。
mysql_stmt_prepare()は実行のため、SQLストリングを用意します。
mysql_stmt_reset()Reset the statement buffers in the server.
mysql_stmt_result_metadata()Returns prepared statement metadata in the form of a result set.
mysql_stmt_row_seek()Seeks to a row offset in a statement result set, using value returned from mysql_stmt_row_tell().
mysql_stmt_row_tell()Returns the statement row cursor position.
mysql_stmt_send_long_data()Sends long data in chunks to server.
mysql_stmt_sqlstate()Returns the SQLSTATE error code for the last statement execution.
mysql_stmt_store_result()Retrieves the complete result set to the client.

ステートメントハンドルを作成するにはmysql_stmt_init() を呼び出してください。準備するにはmysql_stmt_prepare を呼び出してください。パラメータデータを提供するにはmysql_stmt_bind_param() を呼び出してください。ステートメントを実行するにはmysql_stmt_execute() を呼び出してください。mysql_stmt_bind_param()を通して供給された各バッファー中のパラメータを変更することによって、mysql_stmt_execute()を繰り返すことができます。.

ステートメントがSELECTまたは結果セットを生成するその他のステートメントである場合、mysql_stmt_prepare()は、MYSQL_RES結果セットのフォームの中に、mysql_stmt_result_metadata()を通して、結果セットメタデータ情報も戻します。

mysql_stmt_bind_result()を使って、結果バッファーを供給することができるのので、mysql_stmt_fetch()は自動的にデータをこれらのバッファーに戻します。これが列別フェッチングです。

シャンク中のエキストまたはバイナリーデータをmysql_stmt_send_long_data()を使ってサーバに送ることもできます。項23.2.7.25. 「mysql_stmt_data_seek()を参照してください。

ステートメントの実行が終わったとき、それをmysql_stmt_close()を使って閉じなければならないので、それに付属する全ての資源を解放することができます。

mysql_stmt_result_metadata()を呼び出すことによって、SELECTステートメントの結果セットメタデータを取得した場合、mysql_free_result()を使ってメタデータも解放すべきです。

実行ステップ

ステートメントをを準備して実行するために、アプリケーションはこれらのステップに従います:

  1. mysql_stmt_init()を使って準備されたステートメントのハンドルを生成させてください。サーバ上にステートメントを準備するため、mysql_stmt_prepare() を呼び出して、それをSQLステートメントを含むストリングに渡してください。

  2. ステートメントが結果セットを生成する場合、mysql_stmt_result_metadata()を呼び出して、結果セットメタデータを取得してください。このメタデータは、クエリーによって戻された列を含むものとは違いますが、結果セット中に含まれています。メタデータ結果セットは、カラムが結果中に幾つ存在しているかを示し、各カラムに関する情報を含んでいます。

  3. mysql_stmt_bind_param()を使って、パラメータの値をセットしてください。すべてのパラメータをセットしなければなりません。さもなければ、ステートメントがエラーを戻すか、意外な結果を引き起こします。

  4. mysql_stmt_execute()を呼び出してステートメントを実行してください。

  5. ステートメントが結果セットを生成する場合、メタデータバッファーを結束して、mysql_stmt_bind_result()を呼び出すことによって、列の値を復元するために使ってください。

  6. 繰り返しmysql_stmt_fetch()を呼び出すことによって、列が見つからなくなるまで、データを列ごとにバッファーの中にフェッチしてください。

  7. パラメータの値を変えてステートメントを再実行することによって、必要に応じて3回から6回ステップを繰り返し実行してください。

mysql_stmt_prepare()が呼び出されるとき、MySQLクライアント/サーバプロトコルはこれらのアクションを実施します。

  • サーバはステートメントを解析し、ステートメントにIDを割り当てることによって、Okのステータスをクライアントに送り返します。それが結果セットを指向したステートメントである場合、サーバはパラメータの合計ナンバー、カラムカウントおよびそのメタデータも送ります。ステートメントのすべてのsyntaxとsemanticsがこの呼び出し中に、サーバによってチェックされます。

  • クライアントは、そのステートメントを、ステートメントプールにあるその他のステートメントと区別することができるように、このステートメントのIDを更なるオペレーションに使います。

mysql_stmt_execute()が呼び出されるとき、MySQLクライアント/サーバプロトコルはこれらのアクションを実施します。

  • クライアントはステートメントハンドルを使って、サーバーにパラメータデータを送ります。

  • サーバは、クライアントが提供したIDを使ってステートメントを識別し、パラメータ・マーカーを使って新しく供給されたデータと入れ替えて、ステートメントを実行します。ステートメントが結果セットを生成する場合、サーバーはクライアントにデータを送り返します。さもなければ、それは変更、削除または挿入されたOkステータスと列の合計数を送ります。

mysql_stmt_fetch()が呼び出されるとき、MySQLクライアント/サーバプロトコルはこれらのアクションを実施します。

  • クライアントは列別にパケット列からデータを読み取って、それを必要な変換をすることによって、アプリケーションデータバッファの中に置きます。アプリケーションバッファタイプが、サーバーからタイプが戻されたフィールドのそれと同じであると、変換は簡単です。

エラーが発生した場合、mysql_stmt_errno()mysql_stmt_error()およびmysql_stmt_sqlstate()を繰り返し使って、ステートメントエラーコード、エラーメッセージ並びにSQLSTATE値を を得ることができます。

準備されたステートメントのロギング

mysql_stmt_prepare()mysql_stmt_execute() C API ファンクションで準備されたステートメントに対して、サーバは準備そして実行 ラインを一般クエリログに送信します。これによりステートメントがいつ準備、実行されたかわかります。

次のようにステートメントを準備して実行すると考えてください:

  1. mysql_stmt_prepare()を呼び出してステートメントストリング"SELECT ?"を用意します。

  2. mysql_stmt_bind_param()を呼び出して、値3を準備されたステートメント中のパラメータに結びつけます。

  3. mysql_stmt_execute()を呼び出して準備されたステートメントを実行してください。

前のコールの結果として、サーバーは一般クエリーログに次の行を書き込みます:

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

ログ内の各準備実行ラインは、[N]ステートメント識別子でタグされます。これはどの準備されたステートメントがログしているか確認するためです。Nは正の整数です。複数の準備されたステートメントがクライアントに対して同時にアクテブである場合、Nを1より大きくすることができます。各Executeラインは、?パラメータのためにデータ値を取り替えた後の準備されたステートメントを示します。

バージョンの注意:準備 ラインは、[N] なしで、MySQL 4.1.10前は表示されます。実行 ラインはMySQL 4.1.10前では表示されません。

23.2.7. 準備されたC APIステートメント機能の詳細

クエリーを用意して実行するために、次のセクションで詳細を述べる機能を使ってください。

MYSQL_STMT構造を使って運転する全ての機能は接頭語mysql_stmt_で始まることにご注目ください。

MYSQL_STMT ハンドルを作成するには、mysql_stmt_init() ファンクションを使用してください。

23.2.7.1. mysql_stmt_affected_rows()

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

説明

最後に実行されたステートメントによって、変更、削除または挿入された列の合計数を戻します。mysql_stmt_execute()は、UPDATEDELETE、あるいは 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()から例をご参照ください。

23.2.7.2. mysql_stmt_attr_get()

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が未知である場合、ゼロ以外。

エラー

なし。

23.2.7.3. mysql_stmt_attr_set()

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

説明

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

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

可能なオプション値:

オプションアーギュメント型ファンクション
STMT_ATTR_UPDATE_MAX_LENGTHmy_bool *1に設定している場合。mysql_stmt_store_result()中のメタデータMYSQL_FIELD->max_lengthを更新してください。
STMT_ATTR_CURSOR_TYPEunsigned long *mysql_stmt_execute()が起動されている場合開くステートメントのカーソル。*argは CURSOR_TYPE_NO_CURSOR (デフォルトの) あるいは CURSOR_TYPE_READ_ONLYになります。
STMT_ATTR_PREFETCH_ROWSunsigned long *カーソル使用時に、サーバから入手する行の数。*arg は1から最大値 unsigned long.デフォルトは1です。

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が未知である場合、ゼロ以外。

エラー

なし。

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

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 ... */

23.2.7.4. mysql_stmt_bind_param()

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構造のアレーには、3つの要素が含まれていなければなりません。 このことは、このように宣言することができます:

MYSQL_BIND bind[3];

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

戻り値

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

エラー

  • CR_UNSUPPORTED_PARAM_TYPE

    変換はサポートされません。buffer_type値は違法であるか、サポートされているタイプの一つでない可能性があります。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.7.5. mysql_stmt_bind_result()

my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

説明

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

全てのカラムは、mysql_stmt_fetch()を呼び出す前に、バッファーと結束されなければなりません。この場合、bindMYSQL_BIND構造のアレーのアドレスです。クライアントライブラリは結果セットの各コラムに対して、1つの要素が含まれることを期待します。カラムを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エレメントのメンバーおよび値をを受け取るためセットすべき方法を説明します。

戻り値

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

エラー

  • CR_UNSUPPORTED_PARAM_TYPE

    変換はサポートされません。buffer_type値は違法であるか、サポートされているタイプの一つでない可能性があります。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.7.6. mysql_stmt_close()

my_bool mysql_stmt_close(MYSQL_STMT *)

説明

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

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

戻り値

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

エラー

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.7.7. mysql_stmt_data_seek()

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

戻り値

なし。

エラー

なし。

23.2.7.8. mysql_stmt_errno()

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

説明

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

戻り値

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

エラー

なし。

23.2.7.9. mysql_stmt_error()

const char *mysql_stmt_error(MYSQL_STMT *stmt)

説明

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

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

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

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

戻り値

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

エラー

なし。

23.2.7.10. mysql_stmt_execute()

int mysql_stmt_execute(MYSQL_STMT *stmt)

説明

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

ステートメントが、UPDATEDELETEまたは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()はオープンカーソルを閉じます。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

次の例は、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から取得することができます。

23.2.7.11. mysql_stmt_fetch()

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_TYPE_TINY1
MYSQL_TYPE_SHORT2
MYSQL_TYPE_LONG4
MYSQL_TYPE_LONGLONG8
MYSQL_TYPE_FLOAT4
MYSQL_TYPE_DOUBLE8
MYSQL_TYPE_TIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATETIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_STRINGdata length
MYSQL_TYPE_BLOBdata_length

戻り値

戻り値摘要
0データがアプリケーションデータバッファーにフェッチされた場合、成功
1エラーが発生しました。エラーコードとエラーメッセージは、mysql_stmt_errno()およびmysql_stmt_error()を呼び出すことによって取得することができます。
MYSQL_NO_DATAもう列/データは存在しない
MYSQL_DATA_TRUNCATEDデータの切り捨てが発生

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

  • CR_UNSUPPORTED_PARAM_TYPE

    バッファータイプは、MYSQL_TYPE_DATE, MYSQL_TYPE_TIMEMYSQL_TYPE_DATETIMEMYSQL_TYPE_TIMESTAMPですが、データタイプはDATETIMEDATETIMETIMESTAMPではありません。

  • サポートされていない変換に基ずくエラーはすべて、mysql_stmt_bind_result()から返されます。

次の例は、mysql_stmt_result_metadata(), mysql_stmt_bind_result(), and mysql_stmt_fetch()を使って、テーブルからデータをフェッチする方法を明らかにするものです。(この例は項23.2.7.10. 「mysql_stmt_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];
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);
}

23.2.7.12. mysql_stmt_fetch_column()

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

説明

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

戻り値

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

エラー

  • CR_INVALID_PARAMETER_NO

    無効なカラムナンバー。

  • CR_NO_DATA

    結果セットはすでに終わりに達しています。

23.2.7.13. mysql_stmt_field_count()

unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)

説明

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

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

戻り値

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

エラー

なし。

23.2.7.14. mysql_stmt_free_result()

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

説明

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

戻り値

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

エラー

23.2.7.15. mysql_stmt_init()

MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

説明

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

戻り値

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

エラー

  • CR_OUT_OF_MEMORY

    メモリ不足。

23.2.7.16. mysql_stmt_insert_id()

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値をセットしない場合、戻り値は定義されません。

エラー

なし。

23.2.7.17. mysql_stmt_num_rows()

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

戻り値

結果セット中の行の数。

エラー

なし。

23.2.7.18. mysql_stmt_param_count()

unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)

説明

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

戻り値

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

エラー

なし。

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

23.2.7.19. mysql_stmt_param_metadata()

MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)

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

説明

戻り値

エラー

23.2.7.20. mysql_stmt_prepare()

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()を使ってアプリケーション変数に縛り付けなければなりません。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

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

23.2.7.21. mysql_stmt_reset()

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

説明

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

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

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.7.22. mysql_stmt_result_metadata()

MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)

説明

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

  • mysql_num_fields()

  • mysql_fetch_field()

  • mysql_fetch_field_direct()

  • mysql_fetch_fields()

  • mysql_field_count()

  • mysql_field_seek()

  • mysql_field_tell()

  • mysql_free_result()

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

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

戻り値

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

エラー

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.7.23. mysql_stmt_row_seek()

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()に対する次の呼び出しに渡すことができます。

エラー

なし。

23.2.7.24. mysql_stmt_row_tell()

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()の後にだけ使うべきです。

戻り値

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

エラー

なし。

23.2.7.25. mysql_stmt_data_seek()

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()を参照してください。

戻り値

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

エラー

  • CR_INVALID_BUFFER_USE

    パラメータにはストリングあるいはバイナリータイプは含まれていません。

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

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

23.2.7.26. mysql_stmt_sqlstate()

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

説明

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

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

戻り値

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

23.2.7.27. mysql_stmt_store_result()

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_lengthmax_length中のすべてのカラムに対して計算しません。max_lengthを更新したい場合、mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag)を呼び出してこれを有効にすることができます。項23.2.7.3. 「mysql_stmt_attr_set()を参照してください。

戻り値

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

エラー

  • CR_COMMANDS_OUT_OF_SYNC

    コマンドが妥当でないオーダーで実行されました。

  • CR_OUT_OF_MEMORY

    メモリ不足。

  • CR_SERVER_GONE_ERROR

    MySQLサーバが立ち去りました。

  • CR_SERVER_LOST

    サーバへの接続がクエリー中に失われました。

  • CR_UNKNOWN_ERROR

    未知のエラーが起こりました。

23.2.8. 準備されたC API ステートメントの問題

ここでは、準備されたステートメントに対して現在周知の問題のリストが後に続きます:

  • TIMETIMESTAMP、そして DATETIME 秒の部位をサポートしません。(たとえばDATE_FORMAT()から。

  • 整数をストリングに変換するとき、MySQLサーバが先頭のゼロをプリントしない若干のケースでは、ZEROFILLは準備されたステートメントを使って支持されます。(例えば、MIN(number-with-zerofill)).

  • クライアント中の浮動小数点数をストリングに変換するとき、変換された値の最右桁はオリジナルの値のそれらとは少し違うかもしれません。

  • 準備されたステートメントは、クエリーがプレースホルダーを含んでいないケースでも、クエリーキャッシュを使いません。.項4.13.1. 「クエリ キャッシュの動作」を参照してください。

  • 準備されたステートメントはマルチステートメント ((即ち、‘;’文字によって隔離されたシングルストリングの中にあるマルチステートメント)をサポートしません。これは、準備されたステートメントは、マルチ結果セットをサポートしないので、結果セットを戻す記憶された手順を取り出すことができないことも意味します。

23.2.9. マルチプルステートメントを実行するC APIハンドリング

初期設定によって、mysql_query()及びmysql_real_query()は自分のステートメントストリング引数を、実行すべきシングルステートメントとして解釈し、あなたは結果を、ステートメントが結果セット(SELECTについては一組の列またはINSERTUPDATE等に関する影響された列カウント)を生成するか否かに基づいて処理します。

MySQL 5.1はセミコロン(‘;’)文字によって隔離されたマルチプルステートメントを含むストリングの実行をもサポートしています。この能力は、あなたがmysql_real_connect()を使ってサーバに接続するとき、もしくはmysql_set_server_option()を呼び出すことによる接続後、規定される特別オプションによって有効化されます。.

マルッチプルステートメント・ストリングを実行するとことによって、マルチプル結果セットまたは列カウント・インジケータを生成させることができます。これらの結果処理には、シングルステートメントの処理の場合と異なる方法が関与します。最初のステートメントから結果を処理した後、もっと多くの結果が存在するかどうか調べて、もしあった場合、それらを順番に処理することが必要です。マルチ結果の処理をサポートするため、C API には、mysql_more_results()機能とmysql_next_result()機能が含まれています。これらの機能は一般に、もっと多くの結果が得られる場合に限り、反復するループの終わりに使われます。結果の処理に失敗すると、この方法は、サーバへの接続をドロップさせる結果を生む恐れがあります。

CALLステートメントを記憶された手順に対して実行する場合、マルチ結果処理も必要です。記憶された手順は、終わるとき状態結果を戻しますが、運転(例えば、SELECTステートメントの実行)するとき結果セットを生成します。最終ステータスに加え、結果セットを生成する記憶された手順のために、マルチ結果を復元するよう準備しなければなりません。

マルチステートメント機能とマルチ結果機能はmysql_query()またはmysql_real_query()と一緒にだけ使うことができます。それらは準備されたステートメント・インタフェースと一緒に使うことができません。準備されたステートメントハンドルは一つのステートメントを含むストリングだけを使って働くハンドルと定義されます。項23.2.4. 「準備されたC APIステートメント。」を参照してください。

マルチステートメントの実行と結果の処理を有効にするには、次のオプションを使うことができます:

  • mysql_real_connect()機能には、2つのオプション値が関連する flags引数が含まれています。

    • CLIENT_MULTI_RESULTSはクライアントプログラムがマルチ結果を処理することを可能にします。このオプションmustは、結果セットを生成する記憶された手順のためにCALLステートメントを実行する場合有効化されます。さもなければ、このような手順はエラー Error 1312 (0A000): PROCEDURE proc_name can't return a result set in the given context.

    • CLIENT_MULTI_STATEMENTSmysql_query()およびmysql_real_query()にセミコロンで仕切られたマルチステートメントを含むステートメントストリングを実行することを可能にします。このオプションは、暗黙にCLIENT_MULTI_RESULTSを有効にするので、mysql_real_connect()に対するCLIENT_MULTI_STATEMENTSflags引数は、CLIENT_MULTI_STATEMENTS | CLIENT_MULTI_RESULTSの引数と同等になります。即ち、CLIENT_MULTI_STATEMENTSはマルチステートメントの実行とマルチ結果の処理を十分に有効化します。

  • サーバに対する接続が確立された後、それをMYSQL_OPTION_MULTI_STATEMENTS_ONまたはMYSQL_OPTION_MULTI_STATEMENTS_OFFの引数に渡すことによって、マルチステートメントの実行を可能もしくは不能にするため、mysql_set_server_option()機能を使用することができます。この機能を使ってマルチステートメントの実行を有効にすると、各ステートメントが1個の結果を生成するマルチステートメントストリングに対する「simple」結果の処理も有効化されまが、notは結果セットを生成する記憶された手順を許すに十分です。

次の手順はマルチステートメントの取り扱いに対して示唆された戦略を概説したものです。

  1. CLIENT_MULTI_STATEMENTSmysql_real_connect()に渡して,マルチステートメントの実行とマルチ結果の処理を有効化してください。

  2. mysql_query()またはmysql_real_query()を呼び出し、それが成功したことを確認した後、ステートメントの結果を処理するループを入力してください。

  3. ループを繰り返して入力するたびに、現在のステートメントの結果を処理して、結果セット又は影響された列カウントを復元してください。エラーが起こったら、ループを終了してください。

  4. ループの終わりに、他の結果が存在するかどうか調べ、もしある場合、修正を先導するため、mysql_next_result()を呼び出してください。それ以上結果が得られなくなったら、ループを終了してください。

戦略に関して、実行可能な1つの例を以下で紹介します。

/* connect to server with option CLIENT_MULTI_STATEMENTS */
if (mysql_real_connect (mysql, host_name, user_name, password,
    db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS) == NULL)
{
  printf("mysql_real_connect() failed\n");
  mysql_close(mysql);
  exit(1);
}

/* execute multiple statements */
status = mysql_query(mysql,
                     "DROP TABLE IF EXISTS test_table;\
                      CREATE TABLE test_table(id INT);\
                      INSERT INTO test_table VALUES(10);\
                      UPDATE test_table SET id=20 WHERE id=10;\
                      SELECT * FROM test_table;\
                      DROP TABLE test_table");
if (status)
{
  printf("Could not execute statement(s)");
  mysql_close(mysql);
  exit(0);
}

/* process each statement result */
do {
  /* did current statement return data? */
  result = mysql_store_result(mysql);
  if (result)
  {
    /* yes; process rows and free the result set */
    process_result_set(mysql, result);
    mysql_free_result(result);
  }
  else          /* no result set or error */
  {
    if (mysql_field_count(mysql) == 0)
    {
      printf("%lld rows affected\n",
            mysql_affected_rows(mysql));
    }
    else  /* some error occurred */
    {
      printf("Could not retrieve result set\n");
      break;
    }
  }
  /* more results? -1 = no, >0 = error, 0 = yes (keep looping) */
  if ((status = mysql_next_result(mysql)) > 0)
    printf("Could not execute statement\n");
} while (status == 0);

mysql_close(mysql);

ループの最後の部分を、mysql_next_result()が非ゼロを戻すかどうかの単純なテストに縮小することができます。書き込まれたコードは、更なる結果とエラーを区別し、これによって、メッセージに後者 の発生をプリントすることを許します。

23.2.10. 日付とタイム値のC API式取り扱い

バイナリー(準備されたステートメント)プロトコールはあなたに、日付値とタイム値(DATETIMEDATETIMEおよびTIMESTAMP)を、MYSQL_TIME構造を使って、送り且つ受け取ることを許します。この構造のメンバーは項23.2.5. 「準備されたC APIステートメントデータタイプ」で記述されます。

時間のデータ値を送るため、mysql_stmt_prepare()を使って準備されたステートメントを生成してください。その後、mysql_stmt_execute()を呼び出して、ステートメントを実行する前に、以下の手順を実行して各時間パラメータをセットしてください。

  1. データ値を関連するMYSQL_BIND構造の中に、buffer_typeメンバーを、送ろうとしている時間値の種類を示すタイプにセットしてください。DATE値、TIME値、DATETIME値またはTIMESTAMP値に対して、buffer_typeMYSQL_TYPE_DATEMYSQL_TYPE_TIMEMYSQL_TYPE_DATETIMEまたはMYSQL_TYPE_TIMESTAMPにそれぞれセットしてください。

  2. MYSQL_BIND構想のbufferメンバーを、時間値を渡すMYSQL_TIME構造のアドレスにセットしてください。

  3. 渡すべき時間値のタイプに適したMYSQL_TIME構造のメンバーを書き込んでください。

mysql_stmt_bind_param()を使ってパラメータデータをステートメントに固定(バインド)してください。こうすると、mysql_stmt_execute()を呼び出すことが可能になります。

時間値を復元する手順は、buffer_typeメンバーを受け取りを期待する値のタイプにセットし更に、bufferメンバーを戻り値を置くべきMYSQL_TIME構造のアドレスにセットする以外、同じです。mysql_stmt_execute()を呼び出した後、結果をフェッチする前に、バッファーをステートメントに固定(バインド)するmysql_bind_results()を使ってください。

DATEデータ、TIMEデータ並びにTIMESTAMPデータを挿入する簡単な例がここにあります。mysql変数は有効な接続ハンドルと見なされます。

  MYSQL_TIME  ts;
  MYSQL_BIND  bind[3];
  MYSQL_STMT  *stmt;

  strmov(query, "INSERT INTO test_table(date_field, time_field, \
                               timestamp_field) VALUES(?,?,?");

  stmt = mysql_stmt_init(mysql);
  if (!stmt)
  {
    fprintf(stderr, " mysql_stmt_init(), out of memory\n");
    exit(0);
  }
  if (mysql_stmt_prepare(mysql, query, strlen(query)))
  {
    fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
    exit(0);
  }

  /* set up input buffers for all 3 parameters */
  bind[0].buffer_type= MYSQL_TYPE_DATE;
  bind[0].buffer= (char *)&ts;
  bind[0].is_null= 0;
  bind[0].length= 0;
  ...
  bind[1]= bind[2]= bind[0];
  ...

  mysql_stmt_bind_param(stmt, bind);

  /* supply the data to be sent in the ts structure */
  ts.year= 2002;
  ts.month= 02;
  ts.day= 03;

  ts.hour= 10;
  ts.minute= 45;
  ts.second= 20;

  mysql_stmt_execute(stmt);
  ..

23.2.11. C APIスレッド機能の説明

スレッドを付けたクライアントを生成させたいとき、あなたは次の機能を使う必要があります。項23.2.16. 「スレッド付きクライアントを作る方法」を参照してください。

23.2.11.1. my_init()

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>

戻り値

なし。

23.2.11.2. mysql_thread_init()

my_bool mysql_thread_init(void)

説明

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

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

戻り値

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

23.2.11.3. mysql_thread_end( )

void mysql_thread_end(void)

説明

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

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

戻り値

なし。

23.2.11.4. mysql_thread_safe()

unsigned int mysql_thread_safe(void)

説明

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

戻り値

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

23.2.12. 埋め込まれたC API機能の説明

MySQLアプリケーションには、埋め込みサーバーを使うように書き込むことができます。項23.1. 「埋め込まれたMySQLサーバライブラリ、libmysqld」を参照してください。それをこのようなアプリケーションを書き込むため、libmysqldフラグを使うことによって、ibmysqlclientクライアントライブラリに対してリンクしないで、-lmysqldライブラリに対して、ibmysqldフラグを使ってリンクしなければなりません。しかしながら、アイブラリを初期化し且つ完成させる呼び出しは、クライアントアプリケーションをあなたかが書き込むか、埋込サーバを使うものが書き込むかに関係なく、同じです。ライブラリを初期化するmysql_library_init()を呼び出し、必要な場合、mysql_library_end()も呼び出してください。項23.2.2. 「C API機能の概要。」を参照してください。

23.2.12.1. mysql_server_init()

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

説明

この機能は MySQLライブラリを初期化します。この場合、当該初期化は他のMySQL機能が呼び出される前に実行しなければなりません。しかし、mysql_server_init()は忌避されるので、代わりに、mysql_library_init()を呼び出すべきです。項23.2.3.40. 「mysql_library_init()を参照してください。

戻り値

Okなら0、エラーが起こったら1。

23.2.12.2. mysql_server_end()

void mysql_server_end(void)

説明

この機能はMySQLライブラリを完成化させます。この場合、それをライブラリの使用が必要になったとき行うできです。しかし、mysql_server_init()は忌避されるので、代わりに、mysql_library_end()を呼び出すべきです。項23.2.3.39. 「mysql_library_end()を参照してください。

戻り値

なし。

23.2.13. 自動再接続挙動の管理

実行されるべきステートメントをサーバに送ろうと試みるとき、接続がダウンしているとわかると、MySQLクライアントライブラリはサーバのため、自動再接続を実施します。この場合、ライブラリはサーバーに再接続しようと一回試み、ステートメントを再び送ります。

自動再接続は自分の再接続コートを搭載する必要がないので、便利であるが、再接続が起こると、接続状態の幾つかの局面がリセットされ、それがアプリケーションに知らされません。接続が関係する状態は、次のように影響を与えます:

  • クティブな取引がすべてロールバックされ、オートコミットモードがリセットされます。

  • すべてのテーブルロックが解放されます。

  • すべてのTEMPORARY テーブルが閉じ (且つドロップ)されます。

  • セッション変数が対応する変数値に再初期設定されます。これはSET NAMESのようなステートメントによって暗黙にセットされる変数に影響を与えます。

  • ユーザー可変の設定が失われます。

  • 準備されたステートメントがレリースされます。

  • HANDLER 変数が閉じられます。

  • LAST_INSERT_ID() の値が0にリセットされます。

  • GET_LOCK()を使って取得されたロックが解放されます。

接続のドロップを知り、(閉じるか状態情報の喪失に対して調整アクションを起こせるようにする)ことがアプリケーションにとって重要である場合、自動再接続が無効になっていることを確認してください。MYSQL_OPT_RECONNECTオプションを使って、 mysql_options()を呼び出すことによって、これを暗黙に実行することができます。

my_bool reconnect = 0;
mysql_options(&mysql, MYSQL_OPT_RECONNECT, &reconnect);

MySQLでは5.1、 自動再接続はデフォルトによって無効化されています。

23.2.14. C APIを使うときよく尋ねられる質問と問題

23.2.14.1. なぜmysql_store_result()時々返すNULL の後mysql_query() 成功を返す

mysql_query()の呼び出しが成功した直ぐ後、mysql_store_result()NULLを戻すこは可能です。これが起きるとき、それは次の状態の1つが起こったことを意味します:

  • malloc()機能停止(例えば、結果セットが大きすぎた場合)が起こりました。

  • データが読み込めませんでした。(接続の上に起こったエラー)

  • クエリーがデータを戻さななかった(例えば、INSERTUPDATEまたはDELETE)。

mysql_field_count()を呼び出すことによって、ステートメントが空でない結果を戻すべきか否かをいつでもチェックすることができます。mysql_field_count()はゼロを戻し、結果は空で、最後のクエリーは結果値を戻さないステートメントでした。(例えば、INSERTまたはDELETE)。mysql_field_count()がゼロでない値を戻す場合、ステートメントは空でない結果を戻していなければなりませんでした。については、mysql_field_count()機能の説明をご参照ください。

mysql_error()またはmysql_errno()を呼び出すことによって、エラーがないかテストすることができます。

23.2.14.2. クエリーからどんな結果を得ることができるか

クエリーによって返される結果セットほかに、以下の情報も受けとることができます:

  • mysql_affected_rows()は、INSERTUPDATEまたはDELETEを実行中に、最後のクエリーによって影響を受けた列のナンバーを戻します。

    高速再生成のために、TRUNCATE TABLEを使ってください。

  • mysql_num_rows() は結果セット中に列のナンバーを戻します。mysql_store_result()を使って、mysql_num_rows()>を、mysql_store_result()が戻るとすぐ、戻すことができます。mysql_use_result()を使って、mysql_num_rows()を、すべての列をmysql_fetch_row()を使ってフェッチした後、戻すことができます。

  • mysql_insert_id()は、AUTO_INCREMENTインデックスを使ってテーブル中に列を挿入した最後のクエリーによって生成されたIDを戻します。項23.2.3.37. 「mysql_insert_id()を参照してください。

  • 幾つかのクエリー(LOAD DATA INFILE ...INSERT INTO ... SELECT ...UPDATE) は追加情報を戻します。結果はmysql_info()によって戻されます。それが戻すストリングのフォーマットについては、mysql_info()に対する説明をご参照ください。追加情報がない場合、mysql_info()NULLポインターを戻します。

23.2.14.3. 最後に挿入された列に対するユニークIDを取得する方法

AUTO_INCREMENTカラムを含むテーブルの中に記録を挿入する場合、mysql_insert_id()機能を呼び出すことによって、そのカラムの中に記憶された値を取得することができます。

C アプリケーションから、或る値が(あなたがステートメントが成功したと判定したとみなす)以下のコードを実行することによって、AUTO_INCREMENTカラム中に記憶されたか否かをチェックすることができます。 それは、クエリーがAUTO_INCREMENTインデックスを含むINSERTであったか否かを査定します:

if ((result = mysql_store_result(&mysql)) == 0 &&
    mysql_field_count(&mysql) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

新しいAUTO_INCREMENT値が生成されたとき、mysql_query()を使って、SELECT LAST_INSERT_ID()を実行し、ステートメントによって、結果セットからその値を複製することによって、それを取得することができます。

複数の値を差し込むとき、自動的に増加した最後の値が戻されます。

LAST_INSERT_ID()のために、最近生成されたIDが接続ごとにサーバ中に維持されます。それは他のクライアントによって変更されません。それは、AUTO_INCREMENTカラムを非マジック値(即ち、NULLでも0でもない値)を使って更新する場合でも変更されません。LAST_INSERT_ID()カラムとAUTO_INCREMENTカラムを複数のクライアントから同時に使うことは完全に有効です。各クライアントは、thatクライアントが実行した最後のステートメントに対するIDを受け取ります。

1つのテーブルのために生成されたIDを使って、それを2番目のテーブルに挿入したい場合、このような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

その値がNULLまたは0を記憶することによって、自動的に生成された値または明確な値として規定された値であっても、mysql_insert_id()AUTO_INCREMENTカラムの中に記憶された値を戻すことにご注目ください。LAST_INSERT_ID()は自動的に生成されたAUTO_INCREMENT値だけを戻します。NULLまたは0ではなく、明示された値を記憶させる場合、それは、LAST_INSERT_ID()によって戻された値に影響を与えません。

AUTO_INCREMENTカラム中に最後のIDの取得する方法に関する明細情報:

23.2.14.4. C APIにリンクする問題

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をcompile/linkラインの終わりに追加することによって、計算ライブラリを含めなければなりません。

23.2.15. クライアントプログラムの構築

自分で書いたか、第三者から取得するMySQLクライアントを編集する場合、これらはリンクコマンド中に-lmysqlclient -lzオプションを使ってリンクされなければなりません。-Lオプションを規定して、リンカーにどこでライブラリを見つけるか告げる必要があるかもしれません。例えば、ライブラリを/usr/local/mysql/libの中にインストールする場合、-L/usr/local/mysql/lib -lmysqlclient -lzをリンクコマンド中で使ってください。

MySQLヘッダーファイルを使うクライアントのために、これら (例えば、-I/usr/local/mysql/include)を編集するとき、編集者がヘッダーファイルを見つけることができるように、-Iオプションを規定する必要があるかもしれません。

Unix上でMySQLプログラムをコンパイルすることを単純にするため、我々はあなたにmysql_configスクリプトを提供しました。項23.9.2. 「mysql_config — コンパイルオプションをコンパイルクライアントのために(用に)取得してください。」を参照してください。

MySQLクライアントを編集するために、それを次のように使うことができます:

CFG=/usr/local/mysql/bin/mysql_config
sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"

sh -cは、アウトプットを1つのワードとしてmysql_configから処理しないシェルを取得するすることを必要とします。

23.2.16. スレッド付きクライアントを作る方法

クライアントラウブラリはスレッドに対して殆ど安全です。最も大きい問題は、ソケットから読み込んだnet.c中のサブルーチンが割り込みに対して安全でないということです。これは、長い読み取りをブレークすることができる自分自身の警報装置を持ちたいという考えで実施されました。SIGPIPE中断のために、中断ハンドラーをインストールする場合、ソケットの取り扱いをスレッドに対して安全にすべきです。

接続が終わるとき、プログラムが中断されるのを避けるため、MySQLは、mysql_library_init()mysql_init()またはmysql_connect()上のSIGPIPEの最初の呼び出しをブロックします。自分自身のSIGPIPEハンドラーを使いたい場合、先ずmysql_library_init()を呼び出して、それからハンドラーをインストールすべきです。

我々のウェブサイト(http://www.mysql.com/)で配布している古いバイナリー中では、Windowsのためのそれら以外のクライアントライブラリはスレッドに対して安全なオプションを使って通常にコンパイルされません。新しいバイナリーには、通常のライブラリとスレッドに対して安全なライブラリが両方共含まれています。

他のスレッドからクライアントを遮断でき、MySQLサーバーと語るとき、タイムアウトをセットできる、スレッド付きクライアントを取得するため、サーバが使っているnet_serv.oコードおよび-lmysysライブラリ、-lmystringsライブラリおよび-ldbugライブラリを使うべきです。

中断やタイムアウトが必要でない場合、スレッドに安全なクライアントライブラリ(mysqlclient_r)を編集して使うことができます。項23.2. 「MySQL C API」を参照してください。この場合、net_serv.o オブジェクトファイルあるいは他の MySQLライブラリについて心配する必要はありません。

スレッド付きクライアントを使い、タイムアウトと中断を使いたい時、あなたは thr_alarm.cファイル中にそのルーチンの大いに使用をすることができます。ルーチンをmysysライブラリから使っている場合、忘れてはならない唯一つのことは、my_init()を真っ先にび出すことです。項23.2.11. 「C APIスレッド機能の説明」を参照してください。

全ての場合において、他のMySQL 機能を呼び出す前に、mysql_library_init()を呼び出すことによって、クライアントライブラリを初期化したか確認してください。ライブラリが必要となったとき、mysql_library_end()を呼び出してください。

mysql_real_connect()を除くすべての機能はデフォルトによって、スレッドに対して安全です。次のノートはどのようにスレッドにとって安全なクライアントライブラリをコンパイルして、スレッドにとって安全な方法でそれを使うべきか述べています。(mysql_real_connect()のための次のノートは、mysql_connect()が忌避されるので、実際にmysql_connect()に適用します。)

mysql_real_connect()をスレッドに対して安全にするため、MySQL ディストリビューションにこのコマンドを設定しまければなりません。

shell> ./configure --enable-thread-safe-client

その後、配分を編集して、スレッドに安全なクライアントライブラリ、libmysqlclient_rを生成させてください。(オペレーティング・システムにスレッドに安全なgethostbyname_r()機能が含まれていると想定します。)このライブラリは接続毎に、スレッドに対して安全になっています。2つのスレッドに、次の警告と使って同じ接続を共有させることができます:

  • 2つのスレッドは同じ接続上で同時にMySQLサーバにクエリーを送ることはできません。mysql_query()に対する呼び出しとmysql_store_result()に対する呼び出しの間に、他のスレッドが同じ接続に使われていないか特に確認してください。

  • 多くのスレッドはmysql_store_result()を使って復元される異なった結果セットにアクセスすることができます。

  • mysql_use_resultを使う場合、結果セットが閉じられるまで、他のスレッドが同じ接続を使っていないことを確認してください。しかしながら、スレッドクライアントがmysql_store_result()を使っている同じ接続を共有することは本当に最も良いことです。

  • 同じ接続に複数のスレッドを使いたい場合、mysql_query()mysql_store_result()の呼び出しペアの回にあるりにmutexをロックさせなければなりません。mysql_store_result()の準備が終わった途端に、ロックを解放することが出来、他のスレッドが同じ接続を尋ねることが許されます。

  • POSIXスレッドを使う場合、pthread_mutex_lock()およびpthread_mutex_unlock()をmutexロックを確立し且つ解放するのに使うことができます。

MySQLデータベースに接続を生成しなかったMySQL機能を呼び出しているスレッドを持っている場合、以下を知る必要があります。

mysql_init()またはmysql_connect()を呼び出すとき、MySQLは、(他のものの中から選んだ)デバグライブラリによって使われているスレッドのために、スレッドに固有な変数を生成します。

スレッドがmysql_init()またはmysql_connect()呼び出した後、MySQL機能を呼び出す場合、スレッドには必要なスレッドに固有な変数を定位置に含んでいないので、遅かれ早かれコアダンプになる可能性があります。

順調に働かせるものを手に入れるため、あなたは次のことをしなければなりません:

  1. それが他のMySQL機能でも呼び出す場合、mysql_real_connect()を呼び出す前のプログラムの立ち上げで、my_init()を呼び出してください。

  2. MySQL機能を呼び出す前に、スレッドハンドラーの中に、mysql_thread_init()を呼び出してください。

  3. mysql_thread_end()を呼び出す前に、スレッドの中にpthread_exit()を呼び出してください。これはMySQLスレッドに固有な変数によって使われたメモリを解放します。

クライアントを「undefined symbol」とリンクするとき、libmysqlclient_rエラーが発生した場合、殆どの場合これは、リンク/コンパイルコマンド上にスレッドライブラリを含めなかったことに起因して発生します。

23.3. MySQL PHP API

PHPはダイナミックなWeb ページを作るために使うことが出来るサーバ サイドのHTML用埋め込み式スクリプト言語です。それは殆どのオペレーティング・システムやWebサーバの要求を満たし、MySQLを含む共通データベースの殆どにアクセスすることができます。PHPは独立したプログラムとして運転するか、もしくはアパッチWebサーバと一緒に使用するためのモジュールとして翻訳することができます。

PHPは実際に2つの異なったMySQL APIエクステンションを提供します。

  • mysql:PHPのバージョン4と5の要件を満たすこのエクステンションは、MySQL 4.1より前のバージョンのMySQLと一緒に使用することを目的としたものです。この拡張子はMySQL5.1に使われている改良認証プロトコールも、準備されたステートメントあるいは複数のステートメントもサポートしません。このエクステンションをMySQL5.1と一緒に使いたい場合、--old-passwordsオプションを使うために、MySQLサーバーを設定したくなるでしょう。(項B.1.2.3. 「Client does not support authentication protocolをご参照ください)この拡張子は http://php.net/mysqlのPHPウェブサイトに記録されています。

  • mysqli - は「改良されたMySQL」をサーポートし、;それはMySQL.1.1およびそのその後バージョンで使用するよう意図されています。このエクステンションはMySQLとその現シリーズの中で使用される検証プロトコル5.1並びに準備されたステートメント用APIとマルチステートメント用APIを完全にサポートしています。これに加え、このエクステンションは進歩したオブジェクト指向のプログラミングインタフェースをも提供します。mysqliエクステンションのために書かれた文書をhttp://php.net/mysqliで読むことができます。更に明細な情報はhttp://www.zend.com/php5/articles/php5-mysqli.phpに掲載してありますのでご覧ください。

Linux上にPHPを構築する時、mysqlエクステンションとmysqliエクステンションの両方が有効化される問題を経験した場合には、項23.3.2. 「mysqlmysqli の両方を PHP内で可能にする」をご参照ください。

PHPとその資料は、PHP ウェブサイトから入手することができます。MySQLはWindowsオペレーティング・システムのためのmysqlエクステンションとmysqliエクステンションをに提供します。MySQLが提供するエクステンションの好ましい使用法については、同ウェブページをご覧ください。

23.3.1. MySQLとPHPに対する共通問題

  • Error: Maximum Execution Time Exceededこれはphp.iniファイルに入るPHPの限界で、ここに、必要とに応じて、30秒からそれより若干長い最高実行時間を設定します。スクリプト毎に許されるRAMを8MBにする代わりに、2倍の16MBにすることは悪い考えではありません。

  • Fatal error: Call to unsupported or undefined function mysql_connect() in ...:これは、PHPバージョンがMySQLをサポートするように編集されていないことを意味します。ダイナミックMySQLモジュールを編集して、それをPHPに装着するか、あるいは組み込みのMySQLサポートを使って編集することができます。このプロセスはPHPマニュアルに詳述されています。

  • Error: Undefined reference to 'uncompress':これは、クライアント・ライブラリが圧縮されたクライアント/サーバ・プロトコルに対するサポートを使って編集されていることを意味します。その解決策は、-lmysqlclientと結合するとき、-lzを最後に加えることです。

  • Error: Client does not support authentication protocol:これは、MySQL 4.4.1かそれより新しいバージョンのMySQLを使って古いmysql エクステンションを使おうとする時、最もしばしば起こります。可能な解決は:MySQL4.0にグレードを下げ、PHP5およびもっと新しいmysqliエクステンションに切り替えるか、あるいは--old-passwordsの付いたMySQLサーバーに構成を設定することです。 明細な情報については、項B.1.2.3. 「Client does not support authentication protocolをご参照ください。

PHP4の旧式なコードを持つそれらには、これのような、古いMySQLライブラリと新しいMySQLライブラリに対する互換性レイヤを利用することができます: http://www.coggeshall.org/oss/mysql2i.

23.3.2. mysqlmysqli の両方を PHP内で可能にする

Linux上にPHPを構築する時、mysqlエクステンションとmysqliエクステンションの両方が有効化される問題を経験した場合には、以下の手順を試してみるべきです。

  1. PHPをこのように設定してください。

    ./configure --with-mysqli=/usr/bin/mysql_config --with-mysql=/usr  
    

  2. Makefileを編集し、EXTRA_LIBSを編集し、探してください。 それは(すべてが1行の上にある)これのように見えるかもしれません。

    EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl
    -lxml2 -lz -lm -lxml2 -lz -lm -lmysqlclient -lz -lcrypt -lnsl -lm
    -lxml2 -lz -lm -lcrypt -lxml2 -lz -lm -lcrypt
    

    ラインが(すべてが1行の上にある)これのように見えるように、すべての重複部分を除去してください:

    EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl
    -lxml2
    

  3. PHPを構築して搭載してください。

    make
    make install
    

23.4. MySQL Perl API

PerlDBIモジュールはデータベースにアクセスする一般的なインタフェースを提供します。そのままで、多くの異なったデータベースエンジンで作動するDBIスクリプトを書くことができます。DBIを使うためにあなたは、DBIモジュール並びにアクセスしたい各タイプのサーバごとに、データベースドライバ(DBD)モジュールをインストールしなくてはなりません。MySQLの場合、このドライバーはDBD::mysqlモジュールです。

Perl DBIは推薦されたPerlインタフェースです。それは、時代遅れとみなされるべき古い(タイプの)インタフェースであるmysqlperlを置き換えます。

Perl DBIサポートをインストールするためのインストラクションは項2.15. 「Perl のインストールに関する注釈」に掲載されていますのでご覧ください。

DBIに関する情報はコマンドライン、オンラインで入手するか、あるいは印刷物として取得するこができます。

  • DBIDBD::mysqlモジュールをインストールさせるとすぐ、コマンドラインにおいてperldocコマンドを使って、それらに関する情報を得ることができます。

    shell> perldoc DBI
    shell> perldoc DBI::FAQ
    shell> perldoc DBD::mysql
    

    この情報を、pod2manpod2html等を他のフォーマットに翻訳するためにも使うことができます。

  • Perl DBIに関するオンライン情報を得るために、DBI Webサイトhttp://dbi.perl.org/をご訪問くさだい。そのサイトは一般的DBIメーリングリストのホストとしての機能を具備しています。MySQL ABは DBD::mysqlに特に関するリストを主催しています。項1.6.1. 「MySQL メーリング リスト」をご参照ください。

  • 印刷された情報を掲載した公式DBIブックは、Programming the Perl DBI (Alligator Descartes and Tim Bunce, O'Reilly & Associates, 2000)です。このブックに関する情報はWebサイト、http://dbi.perl.org/から入手することがででます。

    MySQLを使ったDBIの使用に特に焦点をあてた情報を見たい場合には、MySQL and Perl for the Web (Paul DuBois, New Riders, 2001)をご参照ください。このブックのWebサイトはhttp://www.kitebird.com/mysql-perl/です。

23.5. MySQL C++ API

MySQL++はC++のためのMySQL APIです。Warren Youngがこのプロジェクトを引き継ぎました。更に明細な情報は以下に掲載してありますのでご覧ください。http://www.mysql.com/products/mysql++/。

23.6. MySQL Python API

MySQLdbは Python DB API バージョン2.0に準拠した Python用MySQLサポ-トを提供します。それはhttp://sourceforge.net/projects/mysql-python/に掲載してありますのでご覧ください。

23.7. MySQL Tcl API

MySQLtclはTclプログラミング言語からMySQLデータベースサーバーにアクセスするためのシンプルなAPIです。それはhttp://www.xdobry.de/mysqltcl/に掲載してありますのでご覧ください。

23.8. MySQLエッフェルラッパー

Eiffel MySQLは、Michael Ravitsが書いたEiffelプログラミング言語を使ったMySQLデータベースサーバに対するインタフェースです。それはhttp://efsa.sourceforge.net/archive/ravits/mysql.htmに掲載してありますのでご覧ください。

23.9. MySQLプログラム開発ユーティリティー

このセクションで、MySQLプログラムを開発する時、あなたにとって有用であると思われる幾つかのユーティリティーについて説明します。

  • msql2mysql

    mSQLプログラムをMySQLに変換するシェルスクリプト。それはすべてのケースを扱うわけではありませんが、変換するとき良いスタートを与えます。

  • mysql_config

    MySQLプログラムを翻訳するとき必要なオプション値を作り出すシェルスクリプト。

23.9.1. msql2mysql — MySQLと一緒に使うため、mSQLプログラムを変換してください。

MySQL APIは最初、mSQLデータベースシステムのためのそれに非常に類似するように開発されました。このため、mSQLプログラムはMySQLと一緒に使用するため、C API機能の名前を変えることによって、比較的容易にしばしば変換することができます。

msql2mysqlユーテリティープログラムは、mSQL C API機能コールのそのMySQL同等言語への変換を実施し、msql2mysqlはインプットファイルを定位置に変換して、それを変換する前に、オリジナルのコピーを作ります。例えば、次のコマンドをmsql2mysql のように使用してください。

shell> cp client-prog.c client-prog.c.orig
shell> msql2mysql client-prog.c
client-prog.c converted

その後、client-prog.cを調べて、必要に応じて変換後の修正を行ってください。

msql2mysqlは機能名を取り替えるため、replaceユーティリティーを使います。詳しくは項7.19. 「replace — 文字列置き換えユーティリティ」を参照してください。

23.9.2. mysql_config — コンパイルオプションをコンパイルクライアントのために(用に)取得してください。

mysql_configはMySQクライアントを編集して、それをMySQLに接続するのに有用な情報をあなたに提供します。

mysql_configは次のオプションをサポートします。

  • --cflags

    検知すべきコンパイラーフラグは、ファイルとクリテカルなコンパイラーフラグ並びに libmysqlclientライブラリを編集するとき使う定義等です。

  • --include

    MySQLを見いだすコンパイラオプションにはファイルが含まれています。(通常、このオプションの代わりに--cflagsを使うことにご留意ください。)

  • --libmysqld-libs, --embedded

    MySQLが埋め込まれているサーバとリンクするのに必要なライブラリとオプション。

  • --libs

    MySQLクライアントライブラリとリンクするのに必要なライブラリとオプション。

  • --libs_r

    スレッドに対して安全なMySQLクライアントライブラリとリンクするのに必要なライブラリとオプション。

  • --port

    MySQLを配置するとき規定されたデフォルトTCP/IPポート番号。

  • --socket

    MySQLを配置するとき規定されたデフォルトUnixソケットファイル。

  • --version

    配付されたMySQLのバージョン番号。

オプションの付いていないmysql_configを呼び出すと、それがサポートするすべてのオプションとそれらの値のリストが表示されます。

shell> mysql_config
Usage: /usr/local/mysql/bin/mysql_config [options]
Options:
  --cflags         [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
  --include        [-I/usr/local/mysql/include/mysql]
  --libs           [-L/usr/local/mysql/lib/mysql -lmysqlclient -lz
                    -lcrypt -lnsl -lm -L/usr/lib -lssl -lcrypto]
  --libs_r         [-L/usr/local/mysql/lib/mysql -lmysqlclient_r
                    -lpthread -lz -lcrypt -lnsl -lm -lpthread]
  --socket         [/tmp/mysql.sock]
  --port           [3306]
  --version        [4.0.16]
  --libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -lpthread -lz
                    -lcrypt -lnsl -lm -lpthread -lrt]

mysql_configをコンマンドラインの中で使って、それが特定のオプションに対して表示する値を含めることができます。例えば、MySQLクライアントプログラムをコンパイルするために、mysql_configを次のように使います。

shell> CFG=/usr/local/mysql/bin/mysql_config
shell> sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"

このような方法でmysql_configを使う時、バックチック(‘`’)文字の中にそれが呼び出されているか確認してください。それは、シェルに、それを実行し、周囲のコマンドの中にそのアウトプットを代替えすることを告げます。


powered by SEO.CUG.NET