Go to the first, previous, next, last section, table of contents.


8 MySQL APIs

This chapter describes the APIs available for MySQL, where to get them, and how to use them. The C API is the most extensively covered, as it was developed by the MySQL team, and is the basis for most of the other APIs.

8.1 MySQL PHP API

PHP is a server-side, HTML-embedded scripting language that may be used to create dynamic Web pages. It contains support for accessing several databases, including MySQL. PHP may be run as a separate program or compiled as a module for use with the Apache Web server.

The distribution and documentation are available at the PHP web site.

8.1.1 Common Problems with MySQL and PHP

8.2 MySQL Perl API

ここでは Perl DBI インターフェースについて述べる。 以前のインターフェースは mysqlperl であった。 DBI/DBD が Perl インターフェースとして現在推奨されているので、 mysqlperl に関してはここでは述べない。

8.2.1 DBI with DBD::mysql

DBI は多くのデーターベースとの一般的なインターフェースである。 これは、多くのデーターベースと動作するスクリプトを変更なしに書けることを意味する。 そのためには、それぞれのデータベース用のデータベースドライバ (DBD) が必要である。 MySQL では、そのドライバは DBD::mysql である。

Perl5 DBI に関する詳細は、DBIウェッブページを参照のこと:

http://www.symbolstone.org/technology/perl/DBI/index.html

Object Oriented Programming (OOP) に関する詳細は、Perl OOP ページを参照のこと:

http://language.perl.com/info/documentation.html

Note that if you want to use transactions with Perl, you need to have Msql-Mysql-modules version 1.2216 or newer.

Installation instructions for MySQL Perl support are given in 「M.2 Perl Installation Comments」節.

8.2.2 The DBI Interface

Portable DBI Methods

connect データベースサーバと接続する
disconnect データベースサーバとの接続を切る
prepare SQL文を設定する
execute 設定されたSQL文を実行する
do SQL文を設定し、実行する
quote 挿入するためのクォート文字、または BLOB
fetchrow_array フィールドの配列として次のレコードを取り出す
fetchrow_arrayref フィールドの配列参照として次のレコードを取り出す
fetchrow_hashref ハッシュテーブルへの参照として次のレコードを取り出す
fetchall_arrayref 配列の配列として全データを取り出す
finish 命令を終了し、リソースからシステムを切り離す
rows 影響のあったレコードの数を返す
data_sources ローカルホスト上で利用できるデータベースの配列を返す
ChopBlanks fetchrow_* メソッドが空白を取り除くかどうかを管理する
NUM_OF_PARAMS 設定された命令文中の placeholder の数
NULLABLE どのフィールドに NULL 値があるか?
trace Perform tracing for debugging

MySQL 固有メソッド

insertid 最後の AUTO_INCREMENT
is_blob どのフィールドが BLOB か?
is_key どのフィールドがキーか?
is_num どのフィールドが数値型か?
is_pri_key どのフィールドがプライマリキーか?
is_not_null どのフィールドが NULL 値か? NULLABLE 参照。
length 利用可能なフィールドサイズの最大値
max_length 実際に存在しているフィールドサイズの最大値
NAME フィールド名
NUM_OF_FIELDS 返されたフィールドの数
table 返されたセットのテーブル名
type 全てのフィールドの型
_CreateDB データベースを作成する
_DropDB データベースを削除する。 ***このメソッドは危険である***

以下の節に、より詳細な Perl メソッドの解説がある。 Variables used for method return values have these meanings:

$dbh
Database handle
$sth
Statement handle
$rc
Return code (often a status)
$rv
Return value (often a row count)

汎用 DBI メソッド

Generally the 'do' statement is MUCH faster (and is preferable) than prepare/execute for statements that doesn't contain parameters.
connect($data_source, $username, $password)
データソースとのデータベース接続をするために connect を使う。 $data_source 値は DBI:driver_name: ではじめること。 DBD::mysql ドライバーを用いた connect の使用例:
$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);
ユーザー名またはパスワードが未設定の場合、 DBI は環境変数である DBI_USERDBI_PASS をそれぞれ使う。 ホスト名を指定しない場合は、'localhost' がデフォルトとなる。 ポート番号を指定しない場合は、MySQL ポート(3306) がデフォルトとなる。 As of Msql-Mysql-modules Version 1.2009, the $data_source value allows certain modifiers:
mysql_read_default_file=file_name
Read `filename' as an option file. For information on option files, see 「4.1.2 my.cnf オプションファイル」節.
mysql_read_default_group=group_name
The default group when reading an option file is normally the [client] group. By specifying the mysql_read_default_group option, the default group becomes the [group_name] group.
mysql_compression=1
Use compressed communication between the client and server (MySQL Version 3.22.3 or later).
mysql_socket=/path/to/socket
Specify the pathname of the Unix socket that is used to connect to the server (MySQL Version 3.21.15 or later).
Multiple modifiers may be given; each must be preceded by a semicolon. For example, if you want to avoid hardcoding the user name and password into a DBI script, you can take them from the user's `~/.my.cnf' option file instead by writing your connect call like this:
$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);
This call will read options defined for the [client] group in the option file. If you wanted to do the same thing but use options specified for the [perl] group as well, you could use this:
$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl",
                $user, $password);
disconnect
disconnect メソッドは、データベースとのデータベースハンドルを切断する。 プログラムを終了する直前に呼び出されるのが典型的である。 例:
$rc = $dbh->disconnect;
prepare($statement)
データベースエンジンで実行するためのSQL文を設定し、execute メソッドで 使用出来るステートメントハンドル ($sth) を返す。 Typically you handle SELECT statements (and SELECT-like statements such as SHOW, DESCRIBE, and EXPLAIN) by means of prepare and execute. 例:
$sth = $dbh->prepare($statement)
    or die "Can't prepare $statement: $dbh->errstr\n";
execute
execute メソッドは、設定されたSQL文を実行する。非 SELECT 文のときは、 影響のあったレコードの数を返す。 もしなんの変化もなかったなら、 execute"0E0" (これは Perl では ゼロ 扱いですが、 真 でもある) を返す。 If an error occurs, execute returns undef. SELECT 文のときは、SQL要求を開始するのみである。 データを操作する fetch_* メソッドの内の一つを記述する必要がある。 例:
$rv = $sth->execute
          or die "can't execute the query: $sth->errstr;
do($statement)
do メソッドはSQL文を設定・実行し、影響のあったレコードの数を返す。 このメソッドは、「非 select」文、すなわち、高度(ドライバーの限界のため)で設定できない文、 一度の実行(inserts, deletes など)で済む文のときに一般的に用いられる。 例:
$rv = $dbh->do($statement)
        or die "Can't execute $statement: $dbh- >errstr\n";
quote($string)
quote メソッドは、文字列中にエスケープ文字があるときに用いられ、 クォート文字を文の外側に付加する。 例:
$sql = $dbh->quote($string)
fetchrow_array
このメソッドはデータの次のレコードを取り出し、フィールドの値の配列として返す。 例:
while(@row = $sth->fetchrow_array) {
        print qw($row[0]\t$row[1]\t$row[2]\n);
}
fetchrow_arrayref
このメソッドはデータの次のレコードを取り出し、フィールドの値の配列への参照として返す。 例:
while($row_ref = $sth->fetchrow_arrayref) {
        print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}
fetchrow_hashref
このメソッドはデータのレコードを取り出し、名前・値のペアのフィールドを含んだ ハッシュテーブルへの参照を返す。このメソッドは、上で示した配列参照 (訳注:fetchrow_arrayref)よりもかなり効率的ではない。例:
while($hash_ref = $sth->fetchrow_hashref) {
        print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
                $hash_ref- > title}\n);
}
fetchall_arrayref
このメソッドは、SQL文より返されたデータ(レコード)の全てを得るために使う。 このメソッドは、各レコードへの参照の配列の配列への参照を返す。 入れ子のループを使ってデータを利用・表示する。例:
my $table = $sth->fetchall_arrayref
                or die "$sth->errstr\n";
my($i, $j);
for $i ( 0 .. $#{$table} ) {
        for $j ( 0 .. $#{$table->[$i]} ) {
                print "$table->[$i][$j]\t";
        }
        print "\n";
}
finish
そのステートメントハンドルからそれ以上データを取り出さないことを示す。ステートメントハンドルや、つかんでいたシステムリソースを解放するためにこのメソッドを呼び出す。例:
$rc = $sth->finish;
rows
最後の命令により、(データの更新、削除、などで)影響のあったレコードの数を返す。 このメソッドは do あるいは 非 SELECT execute 文を 実行した後に、たいてい使われる。例: Example:
$rv = $sth->rows;
NULLABLE
配列の各要素に対し、ブール値の配列への参照を返す。 TRUE であればそのフィールドに NULL 値が含まれていることを示す。例: Example:
$null_possible = $sth->{NULLABLE};
NUM_OF_FIELDS
この属性は、SELECT 文や SHOW FIELDS 文によって返された フィールドの数を示している。命令文が結果を返したかどうかをチェックするのに、 これを使うことが出来る:0値は、INSERT, DELETE または UPDATE のような非 SELECT 文を示している。例: Example:
$nr_of_fields = $sth->{NUM_OF_FIELDS};
data_sources($driver_name)
このメソッドは、'localhost' ホスト上の MySQL サーバで 利用可能なデータベースの名前を含んだ配列を返す。例:
@dbs = DBI->data_sources("mysql");
ChopBlanks
この属性は、 fetchrow_* メソッドが返り値から前後の空白を 除去するかどうかを決定する。例:
$sth->{'ChopBlanks'} =1;
trace($trace_level)
trace($trace_level, $trace_filename)
The trace method enables or disables tracing. When invoked as a DBI class method, it affects tracing for all handles. When invoked as a database or statement handle method, it affects tracing for the given handle (and any future children of the handle). Setting $trace_level to 2 provides detailed trace information. Setting $trace_level to 0 disables tracing. Trace output goes to the standard error output by default. If $trace_filename is specified, the file is opened in append mode and output for all traced handles is written to that file. Example:
DBI->trace(2);                # trace everything
DBI->trace(2,"/tmp/dbi.out"); # trace everything to
                              # /tmp/dbi.out
$dth->trace(2);               # trace this database handle
$sth->trace(2);               # trace this statement handle
You can also enable DBI tracing by setting the DBI_TRACE environment variable. Setting it to a numeric value is equivalent to calling DBI->(value). Setting it to a pathname is equivalent to calling DBI->(2,value).

MySQL 固有メソッド

The methods shown below are MySQL-specific and not part of the DBI standard. Several of them are now deprecated: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, and table. Where DBI-standard alternatives exist, they are noted below.

insertid
MySQL の特徴である AUTO_INCREMENT を使うとき、 新しい自動繰り上がり値がここに記憶される。例: Example:
$new_id = $sth->{insertid};
As an alternative, you can use $dbh->{'mysql_insertid'}.
is_blob
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドが BLOB 値であることを示す。例:
$keys = $sth->{is_blob};
is_key
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドがキーであることを示す。 例:
$keys = $sth->{is_key};
is_num
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドが数値型であることを示す。 例:
$nums = $sth->{is_num};
is_pri_key
配列の各要素に対し、ブール値の配列への参照を返す。TRUE であれば そのフィールドがプライマリーキーであることを示す。 例:
$pri_keys = $sth->{is_pri_key};
is_not_null
配列の各要素に対し、ブール値の配列への参照を返す。FALSE であれば そのフィールドが NULL 値を含むことを示す。 例:
$not_nulls = $sth->{is_not_null};
is_not_null is deprecated; 前述の NULLABLE 属性を使用するほうが望ましい。それが DBI の標準である。
length
max_length
それぞれのメソッドは、フィールドサイズの配列への参照を返す。length 配列は、 (テーブル記述で定義された)各フィールドの利用可能最大値を示す。 max_length 配列は、テーブル中に実際に存在している最大値を示す。例:
$lengths = $sth->{length};
$max_lengths = $sth->{max_length};
NAME
フィールド名の配列への参照を返す。 例:
$names = $sth->{NAME};
table
テーブル名の配列への参照を返す。 例:
$tables = $sth->{table};
type
フィールドの型の配列への参照を返す。 例:
$types = $sth->{type};

8.2.3 DBI/DBD に関するそれ以上の情報

DBI に関するそれ以上の情報は perldoc コマンドで得られる。

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

他のフォーマットに変換するツール、pod2man, pod2html なども 使うことが出来る。

そしてもちろん、DBI の最新情報は DBI ウェッブページで見ることが出来る:

http://www.symbolstone.org/technology/perl/DBI/index.html

8.3 MySQL ODBC サポート

MySQLMyODBC プログラムで ODBC 機能を提供します。 This chapter will teach you how to install MyODBC, and how to use it. Here, you will also find a list of common programs that are known to work with MyODBC.

8.3.1 How To Install MyODBC

MyODBC is a 32-bit ODBC (2.50) level 0 (with level 1 and level 2 features) driver for connecting an ODBC-aware application to MySQL. MyODBC works on Windows95, Windows98, NT, and on most Unix platforms.

MyODBC はパブリック・ドメインで、最新の物は以下にあります: http://www.mysql.com/downloads/api-myodbc.html.

日本語文字コードに対応させた物は: http://www.SoftAgency.co.jp/.

If you have problem with MyODBC and your program also works with OLEDB, you should try the OLEDB driver that you can find in the Contrib section. 「D Contributed Programs」節参照.

Normally you only need to install MyODBC on Windows machines. You only need MyODBC for Unix if you have a program like ColdFusion that is running on the Unix machine and uses ODBC to connect to the databases.

もし、UNIX に MyODBC をインストールしたいなら、 ODBC マネージャーも必要でしょう。 MyODBC は UNIX の ODBC マネージャー でも動作することが知られています。 MySQL useful links page の ODBC-related links 節に、見つけることができます。 「1.2.3 便利な MySQL 関連リンク」節参照.

To install MyODBC on Windows, you should download the appropriate MyODBC .zip file (for Windows or NT/Win2000), unpack it with WINZIP, or some similar program, and execute the SETUP.EXE file.

Windows/NT の場合、MyODBC をインストール時にいかのような エラーになるかもしれません:

An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart
Windows and try installing again (before running any applications which
use ODBC)

The problem in this case is that some other program is using ODBC and because of how Windows is designed, you may not in this case be able to install a new ODBC drivers with Microsoft's ODBC setup program. In most cases you can continue by just pressing Ignore to copy the rest of the MyODBC files and the final installation should still work. これを解決するには、一度 ’セーフモード’でコンピュータを立ち上げ直し、 (windows リブート時に、F8キーを押すことで、セーフモードの選択が可能です) MyODBC をインストールして、リブートします:

MyODBC の設定画面には、MySQL 接続時のオプションがいくつか 設定できるようになっています。 もし問題がある場合は、これらを試します。

8.3.2 ODBC 管理プログラムの各種項目を埋めるには?

Windows95 上のサーバ名の記述には3つの可能性があります:

ODBC setup を埋める方法の例:

Windows DSN name:   test
Description:        This is my test database
MySql Database:     test
Server:             194.216.84.21
User:               monty
Password:           my_password
Port:

Windows DSN name 項目の値は、あなたのwindows ODBC setup における 一意の名前です。

ODBC setup 画面で、Server, User, Password, Port フィールドを設定する必要はありません。 しかし、ここで設定をすると、後でサーバーに接続する際に、 設定した値がデフォルト値として使用されます。 使用時に値を変更するオプションはあります。

ポート番号が設定されていないなら、デフォルトポート (3306) が使用 されます。

もしオプションを Read options from C:\my.cnf にすると, clientodbc グループは `C:\my.cnf' ファイルから読まれます。 mysql_options() で使用できる全てのオプションが利用可能です。 「8.4.3.159 mysql_options()」節参照.

8.3.3 Connect parameters for MyODBC

One can specify the following parameters for MyODBC on the [Servername] section of an ODBC.INI file or through the InConnectionString argument in the SQLDriverConnect() call.

Parameter Default value Comment
user ODBC (on Windows) The username used to connect to MySQL.
server localhost The hostname of the MySQL server.
database The default database
option 0 A integer by which you can specify how MyODBC should work. See below.
port 3306 The TCP/IP port to use if server is not localhost.
stmt A statement that will be executed when connection to MySQL.
password The password for the server user combination.
socket The socket or Windows pipe to connect to.

The option argument is used to tell MyODBC that the client isn't 100% ODBC compliant. On Windows, one normally sets the option flag by toggling the different options on the connection screen but one can also set this in the opton argument. The following options are listed in the same order as they appear in the MyODBC connect screen:

Bit Meaning
1 The client can't handle that MyODBC returns the real width of a column.
2 The client can't handle that MySQL returns the true value of affected rows. If this flag is set then MySQL returns 'found rows' instead. One must have MySQL 3.21.14 or newer to get this to work.
4 Make a debug log in c:\myodbc.log. This is the same as putting MYSQL_DEBUG=d:t:O,c::\myodbc.log in `AUTOEXEC.BAT'
8 Don't set any packet limit for results and parameters.
16 Don't prompt for questions even if driver would like to prompt
32 Simulate a ODBC 1.0 driver in some context.
64 Ignore use of database name in 'database.table.column'.
128 Force use of ODBC manager cursors (experimental).
256 Disable the use of extended fetch (experimental)
512 Pad CHAR fields to full column length.
1024 SQLDescribeCol() will return fully qualifed column names
2048 Use the compressed server/client protocol
4096 Tell server to ignore space after function name and before '(' (needed by PowerBuilder). This will make all function names keywords!
8192 Connect with named pipes to a mysqld server running on NT.
16384 Change LONGLONG columns to INT columns (Some applications can't handle LONGLONG).
32768 Return 'user' as Table_qualifier and Table_owner from SQLTables (experimental)
65536 Read parameters from the client and odbc groups from `my.cnf'
131072 Add some extra safety checks (should not bee needed but...)

If you want to have many options, you should add the above flags! For example setting option to 12 (4+8) gives you debugging without package limits!

The default `MYODBC.DLL' is compiled for optimal performance. If you want to to debug MyODBC (for example to enable tracing), you should instead use MYODBCD.DLL. To install this file, copy `MYODBCD.DLL' over the installed MYODBC.DLL file.

8.3.4 MyODBC での問題をどのように報告すべきか?

MyODBC は以下でテストされました: Access, Admndemo.exe, C++-Builder, Borland Builder 4, Centura Team Developer (formerly Gupta SQL/Windows), ColdFusion (on Solaris and NT with svc pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, Powerdesigner 32 bit, VC++, and Visual Basic.

If you know of any other applications that work with MyODBC, please send mail to myodbc@lists.mysql.com about this!

With some programs you may get an error like: Another user has modifies the record that you have modified. In most cases this can be solved by doing one of the following things:

If the above doesn't help, you should do a MyODBC trace file and try to figure out why things go wrong.

8.3.5 MyODBC で動作することが知られているプログラム

Most programs should work with MyODBC, but for each of those listed below, we have tested it ourselves or received confirmation from some user that it works:

Program
Comment
Access
To make Access work:
ADO
When you are coding with the ADO API and MyODBC you need to put attention in some default properties that aren't supported by the MySQL server. For example, using the CursorLocation Property as adUseServer will return for the RecordCount Property a result of -1. To have the right value, you need to set this property to adUseClient, like is showing in the VB code below:
Dim myconn As New ADODB.Connection
Dim myrs As New Recordset
Dim mySQL As String
Dim myrows As Long

myconn.Open "DSN=MyODBCsample"
mySQL = "SELECT * from user"
myrs.Source = mySQL
Set myrs.ActiveConnection = myconn
myrs.CursorLocation = adUseClient
myrs.Open
myrows = myrs.RecordCount

myrs.Close
myconn.Close
Another workaround is to use a SELECT COUNT(*) statement for a similar query to get the correct row count.
Active server pages (ASP)
You should use the option flag Return matching rows.
BDE applications
To get these to work, you should set the option flags Don't optimize column widths and Return matching rows.
Borland Builder 4
When you start a query you can use the property Active or use the method Open. Note that Active will start by automatically issuing a SELECT * FROM ... query that may not be a good thing if your tables are big!
ColdFusion (On Unix)
The following information is taken from the ColdFusion documentation: Use the following information to configure ColdFusion Server for Linux to use the unixODBC driver with MyODBC for MySQL data sources. Allaire has verified that MyODBC Version 2.50.26 works with MySQL Version 3.22.27 and ColdFusion for Linux. (Any newer version should also work.) You can download MyODBC at http://www.mysql.com/downloads/api-myodbc.html ColdFusion Version 4.5.1 allows you to us the ColdFusion Administrator to add the MySQL data source. However, the driver is not included with ColdFusion Version 4.5.1. Before the MySQL driver will appear in the ODBC datasources drop-down list, you must build and copy the MyODBC driver to `/opt/coldfusion/lib/libmyodbc.so'. The Contrib directory contains the program mydsn-xxx.zip which allows you to build and remove the DSN registry file for the MyODBC driver on Coldfusion applications.
DataJunction
You have to change it to output VARCHAR rather than ENUM, as it exports the latter in a manner that causes MySQL grief.
Excel
Works. Some tips:
Word
To retrieve data from MySQL to Word/Excel documents, you need to use the MyODBC driver and the Add-in Microsoft Query help. For example, create a db with a table containing 2 columns of text:
odbcadmin
ODBC のテストプログラム.
Delphi
DBE 3.2 以上を必ず使用してください。 MySQL に接続する際には、'Don't optimize column width' オプションをセッ トします。 Also, here is some potentially useful Delphi code that sets up both an ODBC entry and a BDE entry for MyODBC (the BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton bryan@flesherfab.com for this):
fReg:= TRegistry.Create;
  fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True);
  fReg.WriteString('Database', 'Documents');
  fReg.WriteString('Description', ' ');
  fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll');
  fReg.WriteString('Flag', '1');
  fReg.WriteString('Password', '');
  fReg.WriteString('Port', ' ');
  fReg.WriteString('Server', 'xmark');
  fReg.WriteString('User', 'winuser');
  fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True);
  fReg.WriteString('DocumentsFab', 'MySQL');
  fReg.CloseKey;
  fReg.Free;

  Memo1.Lines.Add('DATABASE NAME=');
  Memo1.Lines.Add('USER NAME=');
  Memo1.Lines.Add('ODBC DSN=DocumentsFab');
  Memo1.Lines.Add('OPEN MODE=READ/WRITE');
  Memo1.Lines.Add('BATCH COUNT=200');
  Memo1.Lines.Add('LANGDRIVER=');
  Memo1.Lines.Add('MAX ROWS=-1');
  Memo1.Lines.Add('SCHEMA CACHE DIR=');
  Memo1.Lines.Add('SCHEMA CACHE SIZE=8');
  Memo1.Lines.Add('SCHEMA CACHE TIME=-1');
  Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT');
  Memo1.Lines.Add('SQLQRYMODE=');
  Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE');
  Memo1.Lines.Add('ENABLE BCD=FALSE');
  Memo1.Lines.Add('ROWSET SIZE=20');
  Memo1.Lines.Add('BLOBS TO CACHE=64');
  Memo1.Lines.Add('BLOB SIZE=32');

  AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);
C++ Builder
BDE 3.0で,テストされました。唯一の知られた問題は、 テーブルスキーマが変化する時、クエリフィールドが更新されないことです。 BDE は、index PRIMARY だけを認識し、プライマリーキーは認識していないように思えま す。これはさほど問題ではないですが。
Vision
You should use the option flag Return matching rows.
Visual Basic
テーブルの更新を可能にするため、テーブルにプライマリーキーを作成しなくてはなりま せん。 Visual Basic with ADO can't handle big integers. This means that some queries like SHOW PROCESSLIST will not work properly. The fix is to set add the option OPTION=16834 in the ODBC connect string or set the Change BIGINT columns to INT option in the MyODBC connect screen. You may also want to set the Return matching rows option.
VisualInterDev
If you get the error [Microsoft][ODBC Driver Manager] Driver does not support this parameter the reason may be that you have a BIGINT in your result. Try setting the Change BIGINT columns to INT option in the MyODBC connect screen.
Visual Objects
You should use the option flag Don't optimize column widths.

8.3.6 AUTO_INCREMENT フィールドの値を ODBC で得る方法

共通の問題は、INSERT で自動的に生成されるIDの値を得ることです。 ODBCでは、以下のようにします( 例中の autoAUTO_INCREMENT フィー ルドです):

INSERT INTO foo (auto,text) VALUES(NULL,'text');
SELECT LAST_INSERT_ID();

もしくは、他のテーブルにIDを挿入するだけなら以下のようにします:

INSERT INTO foo (auto,text) VALUES(NULL,'text');
INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text');

8.4.5.3 最後に挿入された行のユニーク ID をどのように得られるか?」節参照.

For the benefit of some ODBC applications (at least Delphi and Access), the following query can be used to find a newly inserted row:

SELECT * FROM tbl_name WHERE auto IS NULL;

8.3.7 Reporting Problems with MyODBC

もし MyODBC 使用時に難しい問題にあたった場合、 ODBC マネージャのログファイル (ODBCADMIN からリクエストしたときのログ) と MyODBC のログを取り始めるべきです。 これはいかなる問題にも解決の糸口になるはずです。

MyODBC のログを取るには、以下のように行ないます:

  1. Ensure that you are using myodbcd.dll and not myodbc.dll. The easiest way to do this is to get myodbcd.dll from the MyODBC distribution and copy it over the myodbc.dll, which is probably in your C:\windows\system32 or C:\winnt\system32 directory. Note that you probably want to restore the old myodbc.dll file when you have finished testing, as this is a lot faster than myodbcd.dll.
  2. Tag the `Trace MyODBC' option flag in the MyODBC connect/configure screen. The log will be written to file `C:\myodbc.log'. If the trace option is not remembered when you are going back to the above screen, it means that you are not using the myodbcd.dll driver (see above).
  3. Start your application and try to get it to fail.

Check the MyODBC trace file, to find out what could be wrong. You should be able to find out the issued queries by searching after the string >mysql_real_query in the `myodbc.log' file.

You should also try duplicating the queries in the mysql monitor or admndemo to find out if the error is MyODBC or MySQL.

If you find out something is wrong, please only send the relevant rows (max 40 rows) to myodbc@lists.mysql.com. Please never send the whole MyODBC or ODBC log file!

If you are unable to find out what's wrong, the last option is to make an archive (tar or zip) that contains a MyODBC trace file, the ODBC log file, and a README file that explains the problem. You can send this to ftp://support.mysql.com/pub/mysql/secret. Only we at MySQL AB will have access to the files you upload, and we will be very discrete with the data!

If you can create a program that also shows this problem, please upload this too!

If the program works with some other SQL server, you should make an ODBC log file where you do exactly the same thing in the other SQL server.

Remember that the more information you can supply to us, the more likely it is that we can fix the problem!

8.4 MySQL C API

C API コードは MySQL とともに配布されます。これは libmysqlclient ライブラリに含まれ、C プログラムからデータベースへ のアクセスを許します。

MySQL ソースディストリビューション内のクライアントの多くは C で書かれています。C API の使 用法を示す例を探すなら、これらのクライアントを調べてください。

他のクライアント API の多く(Java を除く全て)は、MySQL サーバと の通信にこのライブラリを使用します。そのため、例えば、他のクライアントプ ログラムで使用されるのと同じ環境変数の多くの利点を得ることができます。そ れらはライブラリから参照されるからです。これらの変数のリストについては 「4.8 MySQL Client-Side Scripts and Utilities」節 を参照して下さい。

クライアントは最大通信バッファサイズを持ちます。最初に割り当てられるバッ ファのサイズ(16K バイト)は自動的に最大サイズ(デフォルトは 16M)まで増加し ます。バッファサイズは必要に応じて増加するため、単純にデフォルトの最大制 限を増加しても、さらに内部で資源を使用することはありません。このサイズチェッ クは主に間違ったクエリと通信パケットのためのチェックです。

通信バッファは一つの SQL ステートメント(クライアントからサーバへの通信)と、 返されるデータ(サーバからクライアントへの通信)の1レコードを含むのに 十分大きくなくてはいけません。各スレッドの 通信バッファは、任意のレコードやクエリを処理するために、指定された制限まで動的 に増大します。例えば、最大 16M のデータを含む BLOB 値がある場合、 少なくとも 16M を通信バッファ制限として持つ必要があります(サーバとクライ アントの両方で)。 クライアントのデフォルトの最大値は 16M ですが、サーバの最大値のデフォルトは 1M です。これはサーバ起動時に、max_allowed_packet パラメータの 値を変更することにより、増やすことが出来ます。 「5.5.2 サーバーパラメーターのチューニング」節参照.

MySQL サーバは、各クエリ後に各通信バッファを net_buffer_length バイトに縮小します。 クライアントでは、接続に割り当てられたバッファのサイズは、接続が閉じられるまで減少しません。 クライアントメモリは接続がクローズされた時に調整されます。

スレッドプログラミングについては、 「8.4.7 スレッドクライアントを作る方法」節参照. を参考にしてください。

8.4.1 C API データ型

MYSQL
この構造体は一つのデータベース接続のハンドルを表わします。これはほとんど全て の MySQL 関数に使用されます。
MYSQL_RES
この構造体はレコードを返すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)の結果を表わ します。クエリから返される情報は、この節の残りでは結果セットと呼 ばれます。
MYSQL_ROW
これはデータの1レコードの安全な型表現です。これは現在バイト文字列の配列として実 装されています。(フィールド値がバイナリデータを含むことがある場合、これを NULL 終端文字列として扱うことはできません。そのような値は内部に NULL バイトを含 むことがあるからです。) mysql_fetch_row() の呼び出しによりレコードが獲得 されます。
MYSQL_FIELD
この構造体はフィールドについての情報、つまりフィールドの名前、型、サイズ 等を含んでいます。このメンバは後でさらに詳細に説明されています。 mysql_fetch_field() を繰り返し呼び出すことにより、各フィールドの MYSQL_FIELD 構造体を得ることができます。 フィールド値はこの構造体の一部ではありません; それは MYSQL_ROW 構造 体に含まれています。
MYSQL_FIELD_OFFSET
これは、MySQL フィールドリストへのオフセットの安全な型表現です。 (mysql_field_seek() で使用されます。)オフセットはレコード内のフィールド 番号で、0 から始まります。
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));

MYSQL_FIELD 構造体は次のメンバを含みます:

char * name
フィールドの名前。null終端文字列。
char * table
このフィールドを含むテーブルの名前。計算されたフィールドでない場合のみ有 効です。計算されたフィールドでは、table 値は空文字列です。
char * def
このフィールドのデフォルト値。null終端文字列。 これは mysql_list_fields() 使用時にだけ設定されます。
enum enum_field_types type
フィールドの型。 type 値は次の一つです:
型の値 型の意味
FIELD_TYPE_TINY TINYINT フィールド
FIELD_TYPE_SHORT SMALLINT フィールド
FIELD_TYPE_LONG INTEGER フィールド
FIELD_TYPE_INT24 MEDIUMINT フィールド
FIELD_TYPE_LONGLONG BIGINT フィールド
FIELD_TYPE_DECIMAL DECIMAL または NUMERIC フィールド
FIELD_TYPE_FLOAT FLOAT フィールド
FIELD_TYPE_DOUBLE DOUBLE または REAL フィールド
FIELD_TYPE_TIMESTAMP TIMESTAMP フィールド
FIELD_TYPE_DATE DATE フィールド
FIELD_TYPE_TIME TIME フィールド
FIELD_TYPE_DATETIME DATETIME フィールド
FIELD_TYPE_YEAR YEAR フィールド
FIELD_TYPE_STRING 文字列 (CHAR または VARCHAR) フィールド
FIELD_TYPE_BLOB BLOB または TEXT フィールド (最大長を確定するには max_length を使用して下さい)
FIELD_TYPE_SET SET フィールド
FIELD_TYPE_ENUM ENUM フィールド
FIELD_TYPE_NULL NULL型 フィールド
FIELD_TYPE_CHAR 非推奨; FIELD_TYPE_TINY を代わりに使用してください
IS_NUM() マクロで、フィールドが数値タイプかどうかをテストできます。 フィールドが数値の場合、type メンバを IS_NUM() に渡すと TRUE と評価します:
if (IS_NUM(field->type))
    printf("Field is numeric\n");
unsigned int length
フィールドの幅。これはテーブル定義で指定されたものです。
unsigned int max_length
結果セットのフィールドの最大幅(実際の結果セットの中のレコードの最長フィールド値 の長さ)。mysql_store_result() または mysql_list_fields() を 使用する場合は、これはフィールドの最大幅になります。 mysql_use_result() を使用する場合は、この変数の値は 0 になります。
unsigned int flags
フィールドの種々のビットフラグ。flags 値は 0 または次のビットの一つ 以上の組み合わせです:
フラグの値 フラグの意味
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 である (非推奨)
BLOB_FLAG フィールドは BLOB または TEXT である (非推奨)
TIMESTAMP_FLAG フィールドは TIMESTAMP である (非推奨)
BLOB_FLAG, ENUM_FLAG, TIMESTAMP_FLAG の使用は推奨さ れません。これらは型の属性ではなくフィールドの型を示すからです。代わり に field->typeFIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_TIMESTAMP に対してテストする方をお勧めします。 次の例は flags 値の典型的な使用を示しています:
if (field->flags & NOT_NULL_FLAG)
    printf("Field can't be null\n");
flags 値の真偽状態を調べるために、次の便利なマクロを使用でき ます:
IS_NOT_NULL(flags) このフィールドが NOT NULL として定義されていれば真
IS_PRI_KEY(flags) このフィールドがプライマリキーならば真
IS_BLOB(flags) このフィールドが BLOB または TEXT ならば真 (非推奨; 代わりに field->type をテストして下さい)
unsigned int decimals
数値フィールドの小数部桁数。

8.4.2 C API 関数概要

C API には次に一覧された関数が存在します。これらの関数は次の節でかな り詳細に説明されています。 「8.4.3 C API 関数説明」節参照。

mysql_affected_rows() 最後の UPDATE, DELETE, INSERT クエリによって変更/削 除/挿入されたレコード数を返します。
mysql_close() サーバ接続をクローズします。
mysql_connect() MySQL サーバに接続します。この関数は推奨されません; 代わりに mysql_real_connect() を使用してください。
mysql_change_user() 接続中ののユーザとデータベースを変更します。
mysql_character_set_name() 接続のデフォルト文字セットの名前を返します。
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_real_escape_string() Escapes special characters in a string for use in a SQL statement taking into account the current charset of the connection.
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_host_info() 接続を説明する文字列を返します。
mysql_get_proto_info() 接続に使用されるプロトコルバージョンを返します。
mysql_get_server_info() サーバのバージョン番号を返します。
mysql_info() 最後に実行されたクエリについての情報を返します。
mysql_init() MYSQL 構造体を獲得または初期化します。
mysql_insert_id() AUTO_INCREMENT フィールドに最後に生成された ID を返します。
mysql_kill() 指定されたスレッドを殺します。
mysql_list_dbs() 簡易正規表現に適合するデータベース名を返します。
mysql_list_fields() 簡易正規表現に適合するフィールド名を返します。
mysql_list_processes() 現在のサーバスレッドのリストを返します。
mysql_list_tables() 簡易正規表現に適合するテーブル名を返します。
mysql_num_fields() 結果セット中のフィールド数を返します。
mysql_num_rows() 結果セット中のレコード数を返します。
mysql_options() mysql_connect() のための接続オプションを設定します。
mysql_ping() サーバへの接続が動作しているかどうかをチェックします。 必要であれば再接続します。
mysql_query() NULL 終端文字列として記述された SQL クエリを実行します。
mysql_real_connect() MySQL サーバに接続します。
mysql_real_query() 数えられた文字列として記述された SQL クエリを実行します。
mysql_reload() 権限テーブルを再読み込みするようにサーバに指示します。
mysql_row_seek() 結果セット内のあるレコードへシークします。mysql_row_tell() から返される値を 使用します。
mysql_row_tell() レコードカーソルの位置を返します。
mysql_select_db() データベースを選択します。
mysql_shutdown() データベースサーバをシャットダウンします。
mysql_stat() 文字列でサーバ状態を返します。
mysql_store_result() クライアントに完全な結果セットを取り出します。
mysql_thread_id() 現在のスレッド ID を返します。
mysql_thread_save() Returns 1 if the clients are compiled as thread-safe.
mysql_use_result() 各レコードの動的結果セットを初期化します。

サーバへ接続するには、接続ハンドラを初期化するために mysql_init() を呼びだし、それから mysql_real_connect() をそのハンドラで呼びだし ます (ホスト名、ユーザ名、パスワードのような他の情報に加えて)。 Upon connection, mysql_real_connect() sets the reconnect flag (part of the MYSQL structure) to a value of 1. This flag indicates, in the event that a query cannot be performed because of a lost connection, to try reconnecting to the server before giving up. その接続で の処理が終了した時は、接続を終了させるために mysql_close() を呼びだ します。

接続が有効な間は、クライアントは mysql_query() または mysql_real_query() を使用して SQL クエリをサーバに送信できます。こ の2つの違いは、mysql_query() は NULL終端文字列としてクエリが記述さ れることを期待するのに対し、mysql_real_query() は数えられた文字列を 期待することです。文字列がバイナリデータ(NULバイトを含みことがある)を含む 場合は、mysql_real_query() を使用する必要があります。

SELECT クエリ(例えば、INSERT, UPDATE, DELETE)では、どれくらいのレコードが変更(影響)されたかを mysql_affected_rows() を呼び出すことで見つけ出すことができます。

SELECT クエリでは、選択されたレコードを結果セットとして取り出します。 (注意: いくつかのステートメントは、レコードを返すという点で SELECTに似ています。それは SHOW, DESCRIBE, EXPLAIN です。これらは SELECT ステートメントと同じ方法で扱わ れるべきです。)

クライアントが結果セットを処理するには2つの方法があります。一つ目は、 mysql_store_result() を呼び出すことで、結果セット全体を一度にすべて 取り出すことです。この関数はサーバからクエリによって返されるすべてのレコー ドを取得し、それをクライアントに格納します。二つ目は、 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() の必要メモリは、大き な結果セットではとても高く、out-of-memory 状態に遭遇する可能性が高くなりま す。

mysql_use_result() の利点は、一度に一つのレコードだけを保持するため、 クライアントが結果セットに要求するメモリが少ないことです(そして、割当のオー バーヘッドも少ないので、mysql_use_result() はより速くなります)。不 利な点は、サーバの拘束を避けるため、各レコードを素早く処理する必要があるこ と、結果セット中でレコードのランダムアクセスができないこと(レコードを順番 にアクセスすることしかできません)、そして、すべてのレコードを取り出さない 限り、結果セット中にいくつのレコードがあるかを知ることができないことです。 さらに、あなたが探している情報を、検索の途中で見つけることができて、問題が 解決したとしても、すべてのレコードを取り出さなければなりません

API はクライアントがクエリが SELECT であるかどうかを知ることなしに、 (必要時だけレコードを取り出す)クエリに適切に応答できるようにします。 それぞれの mysql_query()(または mysql_real_query())の後で、 mysql_store_result() を呼び出すことで、これが可能です。結果セットの 呼び出しが成功すると、クエリは SELECT であり、レコードを読むことが できます。結果セット呼び出しが失敗した場合は、結果が実際に期待されたもので あるかどうかを確定するために、mysql_field_count() を呼び出してくだ さい。mysql_field_count() が 0 を返す場合は、クエリはデータを返しま せん(クエリが INSERT, UPDATE, DELETE 等であることを 示します)。つまりレコードが返ることを期待できません。 mysql_field_count() が 0 でない場合は、クエリはレコードを返すべきな のに、返さなかったということです。これはクエリが 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_errno()mysql_error() 関数の方法によって、MySQL はエラー情報へのア クセスを提供します。これらは、最後に呼び出された成功または失敗し得る関数に ついてのエラーコードとエラーメッセージを返し、エラーがいつ何で発生したかを 確定することができます。

8.4.3 C API 関数説明

以下の説明では、NULL の引数または戻り値は C プログラミング言語で の NULL を意味します。MySQL NULL 値ではありません。 関数は通常ポインタか整数の値を返します。しかし関数説明に記述がある場合、 ポインタを返す関数は、成功を示すために非 NULL 値を返し、エラーを示すた めに NULL を返します。整数を返す関数は、成功を示すために 0 を返し、 エラーを示すために非0を返します。``非0'' は関数説明が他に述べていない限 り、その意味になることに注意してください; 関数説明が他に述べている場合、 これらに対して 0 以外の固有の値をテストしないでください:

if (result)                   /* 正しい */
    ... error ...

if (result < 0)               /* 間違い */
    ... error ...

if (result == -1)             /* 間違い */
    ... error ...

関数がエラーを返すとき、関数説明の エラー 節が起り得るエラーの 種類を一覧しています。mysql_errno() の呼び出しによってどれが発生 したかを見つけ出すことができます。エラーを表現する文字列は mysql_error() の呼び出しによって得られます。

8.4.3.1 mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

8.4.3.2 説明

最後の UPDATE によって変更されたレコード数、または、DELETE によって削除されたレコード数、INSERT によって挿入されたレコード数を 返します。UPDATE, DELETE, INSERT ステートメントでの mysql_query() 直後に呼び出します。SELECT ステートメントでは、 mysql_affected_rows()mysql_num_rows() に似た動きをします。

8.4.3.3 戻り値

0 より大きい整数は影響された行数または取り出された行数を示します。0 は UPDATE ステートメントで更新されたレコードがないこと、またはクエリの WHERE 節に適合したレコードがないこと、またはまだなんのクエリも実行 していないことを示します。-1 はクエリがエラーを返したこと、あるいは SELECT クエリで、mysql_affected_rows()mysql_store_result() 呼び出しよりも先に呼び出されたことを揣摩します。

8.4.3.4 エラー

無し。

8.4.3.5 例

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

If one specifies the flag CLIENT_FOUND_ROWS when connecting to mysqld, mysql_affected_rows() will return the number of rows matched by the WHERE statement for UPDATE statements.

Note that when one uses a REPLACE command, mysql_affected_rows() will return 2 if the new row replaced and old row. This is because in this case one row was inserted and then the duplicate was deleted.

8.4.3.6 mysql_close()

void mysql_close(MYSQL *mysql)

8.4.3.7 説明

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

8.4.3.8 戻り値

無し。

8.4.3.9 エラー

無し。

8.4.3.10 mysql_connect()

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

8.4.3.11 説明

この関数は推奨されません。代わりに mysql_real_connect() の使用を お勧めします。

mysql_connect()host 上で動作している MySQL デー タベースエンジンへの接続の確立を試みます。mysql_get_client_info() を除く他のすべての API 関数を実行する前にmysql_connect() が成功終了 している必要があります。

パラメータの意味は mysql_real_connect() の対応するパラメータと同じですが、 接続パラメータは NULL にできることが異なります。この場合 C API は接 続構造体に自動的にメモリを割り当て、mysql_close() 呼び出し時にそれ を解放します。このアプローチの不利な点は接続が失敗した場合にエラーメッセー ジを取り出すことができないことです。(mysql_errno() または mysql_error() からエラー情報を得るには、正しい MYSQL ポイン タを提供する必要があります。)

8.4.3.12 戻り値

mysql_real_connect() と同じ

8.4.3.13 エラー

mysql_real_connect() と同じ

8.4.3.14 mysql_change_user()

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

8.4.3.15 説明

ユーザを変更し、mysql で示された接続上で、db で示されたデー タベースがデフォルト(現在の)データベースになります。その後のクエリでは、 明示的なデータベースの指定を含んでいないテーブル参照について、このデータベー スがデフォルトになります。

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

mysql_change_user() は接続されたユーザが認証されない場合、またはデー タベースを使用する権限を持っていない場合に失敗します。この場合、ユーザとデー タベースは変更されません。

デフォルトデータベースを持ちたくない場合、db パラメータを NULL に設定できます。

8.4.3.16 戻り値

成功時 0。エラーが発生した場合は非0。

8.4.3.17 エラー

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
データベース名が長過ぎる。

8.4.3.18 例

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

8.4.3.19 mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

8.4.3.20 Description

Returns the default character set for the current connection.

8.4.3.21 Return Values

The default character set

8.4.3.22 Errors

None.

8.4.3.23 mysql_create_db()

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

8.4.3.24 説明

db 引数によって指定されたデータベースを作成します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL CREATE DATABASE ステートメントを発行することをお勧めします。

8.4.3.25 戻り値

データベースの作成が成功した場合は0。エラーが発生した場合は非0。

8.4.3.26 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.27 例

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

8.4.3.28 mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)

8.4.3.29 説明

クエリ結果セット中の任意のレコードにシークします。これは、結果セット構造体 がクエリのすべての結果を持っていることを要求します。そのため、 mysql_data_seek()mysql_store_result() と共にだけ使用され、 mysql_use_result() と共には使用できません。

オフセットの値は 0 から mysql_num_rows(result)-1 でなくては なりません。

8.4.3.30 戻り値

無し。

8.4.3.31 エラー

無し。

8.4.3.32 mysql_debug()

void mysql_debug(char *debug)

8.4.3.33 説明

与えられた文字列で DBUG_PUSH を行ないます。mysql_debug() は Fred Fish が作成した debug library を使用します。この関数を使用するためには、デバッ グをサポートするように、クライアントライブラリをコンパイルする必要があり ます。 「G.1 MySQL server のデバッグ」節参照. 「G.2 Debugging a MySQL client」節参照.

8.4.3.34 戻り値

無し。

8.4.3.35 エラー

無し。

8.4.3.36 例

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

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

8.4.3.37 mysql_drop_db()

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

8.4.3.38 説明

db 引数によって指定されたデータベースを破棄します。

この関数は推奨されません。代わりに mysql_query() を使って、SQL DROP DATABASE ステートメントを発行することをお勧めします。

8.4.3.39 戻り値

データベースの破棄が成功した場合は0。エラーが発生した場合は非0。

8.4.3.40 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.41 例

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

8.4.3.42 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

8.4.3.43 説明

いくつかのデバッグ情報をログにダンプするようにサーバに指示します。この動 作をするためには、接続されたユーザが process 権を持っていなけ ればなりません。

8.4.3.44 戻り値

コマンドが成功した場合は0。コマンドが失敗した場合は非0。

8.4.3.45 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.46 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

8.4.3.47 説明

この関数は推奨されません。mysql_errno()mysql_error() が 代わりに使用できます。

mysql_eof() は結果セットの最後のレコードが読まれたかどうかを調べま す。

mysql_store_result() の呼び出しが成功して、結果セットを入手した場合、 クライアントは一つのオペレーションですべてのセットを受け取ります。この場合、 mysql_fetch_row() から返される NULL は、常に結果セットの終端 に達したことを意味し、mysql_eof() を呼ぶ必要はありません。

一方、結果セット取り出しの初期化のために mysql_use_result() を使用 する場合、セットのレコードは mysql_fetch_row() を繰り返し呼ぶことに より、ひとつずつサーバから獲得されます。この処理中に接続上でエラーが発生し 得るため、mysql_fetch_row() からの戻り値 NULL は、通常必ずし も結果セットの終端に達したことを意味しません。この場合 mysql_eof() を使用して、何が起こったかを検出できます。結果セットの 終端に達した場合は mysql_eof() は非0値を返し、エラーが発生した場合 は 0 を返します。

歴史的に mysql_eof() は標準 MySQL エラー関数 mysql_errno()mysql_error() 以前に遡ります。これらのエラー 関数は同じ情報を提供するので、これらの使用が mysql_eof() よりも好ま れます。mysql_eof() は現在推奨されません。(実際、これらは多くの情 報を提供します。エラー関数はエラーが発生した時のエラーの理由を示しますが、 mysql_eof() は真偽値だけを返します。)

8.4.3.48 戻り値

エラーが発生しなかった場合は0。結果セットの終端に達した場合は非0。

8.4.3.49 エラー

無し。

8.4.3.50 例

次の例は 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));
}

8.4.3.51 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

8.4.3.52 説明

mysql によって指定された接続上で、最後に呼び出された API 関数の成否のエラーコー ドを返します。戻り値0はエラーが発生しなかったことを意味します。クライア ントエラーメッセージ番号は `errmsg.h' にリストされています。サーバ エラーメッセージ番号は `mysqld_error.h' にリストされています。 In the MySQL source distribution you can find a complete list of error messages and error numbers in the file `Docs/mysqld_error.txt'.

8.4.3.53 戻り値:

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

8.4.3.54 エラー

無し。

8.4.3.55 mysql_error()

char *mysql_error(MYSQL *mysql)

8.4.3.56 説明

mysql によって指定された接続上で、 mysql_error() は 最後に呼び出された API 関数の成否を、エラーメッセージとして返します。 エラー発生しなかった場合は空文字列 ("") が返されます。 これは次の2つのテストが同じであることを意味します:

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

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

クライアントエラーメッセージの言語は MySQL クラ イアントライブラリの再コンパイルで変更できます。現在はいくつかの言語で書かれた クライアントエラーメッセージを選択できます。 「4.6.2 Non-English Error Messages」節参照.

8.4.3.57 戻り値

エラーを表わす文字列。 エラーが発生していない場合は空文字列。

8.4.3.58 エラー

無し。

8.4.3.59 mysql_escape_string()

You should use mysql_real_escape_string() instead!

This is identical to mysql_real_escape_string() except that it takes the connection as the first argument. mysql_real_escape_string() will escape the string according to the current character set while mysql_escape_string() does not respect the current charset setting.

8.4.3.60 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

8.4.3.61 説明

結果セットの一つのフィールドの定義を MYSQL_FIELD 構造体として返しま す。結果セット内の全てのフィールドについて情報を取り出すには、この関数を繰 り返し呼んでください。mysql_fetch_field() はフィールドが残っていな いと NULL を返します。

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

テーブルを SELECT するために mysql_query() を呼び、しかしま だ mysql_store_result() を呼んでいない場合、 mysql_fetch_field()BLOB フィールドの長さの問い合わせに使 用すると、MySQL はデフォルトの blob 長 (8K bytes) を返します。 (8K サイズになるのは、MySQLBLOB の最大長を知らないから です。これはいつかコンフィグ可能になるべきです。) 一度結果セットを取り出せ ば、field->max_length は指定したクエリ内でのこのフィールドの最大値 の長さを含みます。

8.4.3.62 戻り値

現在のフィールドの MYSQL_FIELD 構造体。フィールドが残っていない場合は NULL

8.4.3.63 エラー

無し。

8.4.3.64 例

MYSQL_FIELD *field;

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

8.4.3.65 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

8.4.3.66 説明

結果セットのすべての MYSQL_FIELD 構造体の配列を返します。各構造体は 結果セットの一つのフィールドのフィールド定義を提供します。

8.4.3.67 戻り値

結果セットの全ての項目の MYSQL_FIELD 構造体の配列。

8.4.3.68 エラー

無し。

8.4.3.69 例

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

8.4.3.70 mysql_fetch_field_direct()

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

8.4.3.71 説明

結果セット中のフィールドを示すフィールド番号 fieldnr が与えられ、そ のフィールドのフィールド定義を MYSQL_FIELD 構造体として返します。こ の関数は任意のフィールドについての定義を取り出すことに使用できます。 fieldnr の値は 0 から mysql_num_fields(result)-1 の範囲にす べきです。

8.4.3.72 戻り値

指定されたフィールドの MYSQL_FIELD 構造体。

8.4.3.73 エラー

無し。

8.4.3.74 例

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

8.4.3.75 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

8.4.3.76 説明

結果セット中の現在のレコードのフィールドの長さを返します。フィールドの値をコピーする場合、 この長さ情報は最適化にも有用です。strlen() の呼び出しを回避できる ためです。 さらに、結果セットがバイナリデータを持つ場合は、データのサイズを特定するためにこの関数を使わなければなりません。 なぜなら strlen() は NULL 文字を含むフィールドについての結果を正しく返さないからです。

空フィールドの長さと NULL 値を含むフィールドの長さは 0 です。この2 つのケースを区別する方法については、mysql_fetch_row() の説明を参照 して下さい。

8.4.3.77 戻り値

各フィールドのサイズ (終端 NUL 文字は含みません)を提供する unsigned long 整数の配列。 エラーが発生した場合は NULL

8.4.3.78 エラー

mysql_fetch_lengths() は結果セットの現在のレコードについてだけ有効 です。mysql_fetch_row() を呼び出す前、または結果の全てのレコードを 取り出した後にこれを呼んだ場合、NULL が返されます。

8.4.3.79 例

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

8.4.3.80 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

8.4.3.81 説明

結果セットの次のレコードを取り出します。mysql_store_result() の後に使用すると、 これ以上取り出すレコードがない時は、NULL を返します。 mysql_use_result() の後に使用するなら、 これ以上取り出すレコードがない場合やエラーが発生した場合に NULL を返します。

レコード内の値の数は mysql_num_fields(result) によって与えられます。 rowmysql_fetch_row() の呼び出しからの戻り値を保持する場 合、値へのポインタは row[0] から row[mysql_num_fields(result)-1 としてアクセスされます。レコード内の NULL 値はNULL ポインタによって示されます。

レコードのフィールド値の長さは、mysql_fetch_lengths() の呼び出しで 獲得できます。空フィールドと NULL を含むフィールドはどちらも長さ 0 を持ちます; フィールド値のポインタをチェックすることで、これらを区別でき ます。ポインタが NULL の場合、フィールドは NULL です; そうで なければフィールドは空です。

8.4.3.82 戻り値

次のレコードの MYSQL_ROW 構造体、エラーが発生したか、もう取り出すレ コードがない場合は NULL

8.4.3.83 エラー

CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.84 例

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

8.4.3.85 mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

3.22.24 より前の MySQL バージョンを使用している場合、 unsigned int mysql_num_fields(MYSQL *mysql) を代わりに使用すべきで す。

8.4.3.86 説明

接続上の最後のクエリのフィールド数を返します。

この関数は通常 mysql_store_result()NULL を返した時(そし てこのように結果セットポインタを持っていない時)に使用されます。この場合、 mysql_store_result() が空でない結果を提供すべきかどうかを調べるため に、mysql_field_count() を呼び出すことができます。これは、クエリが SELECT(または SELECTに似た)ステートメントであるかを知るこ と無しに、クライアントプログラムに、適切な行動をとらせることができます。下 に示される例は、これをどのように行なうことができるかを説明しています。

8.4.5.1 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

8.4.3.87 戻り値

結果セット中のフィールド番号を表す unsigned integer。

8.4.3.88 エラー

無し。

8.4.3.89 例

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
    // error
}
else // query succeeded, process any data returned by it
{
    result = mysql_store_result(&mysql);
    if (result)  // there are rows
    {
        num_fields = mysql_num_fields(result);
        // retrieve rows, then call mysql_free_result(result)
    }
    else  // mysql_store_result() returned nothing; should it have?
    {
        if(mysql_field_count(&mysql) == 0)
        {
            // query does not return data
            // (it was not a SELECT)
            num_rows = mysql_affected_rows(&mysql);
        }
        else // mysql_store_result() should have returned data
        {
            fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
        }
    }
}

別の方法は、mysql_field_count(&mysql) 呼び出しを mysql_errno(&mysql) に置き換えることです。この場合、ステートメント が SELECT かどうかを mysql_field_count() の値から推測するの ではなく、直接 mysql_store_result() からのエラーをチェックします。

8.4.3.90 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

8.4.3.91 説明

与えられたオフセットにフィールドカーソルを設定します。次の mysql_fetch_field() の呼び出しはそのオフセットに対応したフィールドを取 り出します。

レコードの最初にシークするには、0 の offset 値を渡してください。

8.4.3.92 戻り値

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

8.4.3.93 エラー

無し。

8.4.3.94 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

8.4.3.95 説明

最後の mysql_fetch_field() に使用したフィールドカーソルの位置を返 します。この値は mysql_field_seek() への引数として使用できます。

8.4.3.96 戻り値

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

8.4.3.97 エラー

無し。

8.4.3.98 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

8.4.3.99 説明

mysql_store_result(), mysql_use_result(), mysql_list_dbs() 等によって結果セットに割り当てられたメモリを解放 します。結果セットで何かを行なった時、mysql_free_result() を呼び 出してそれが使用したメモリを解放する必要があります。

8.4.3.100 戻り値

無し。

8.4.3.101 エラー

無し。

8.4.3.102 mysql_get_client_info()

char *mysql_get_client_info(void)

8.4.3.103 説明

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

8.4.3.104 戻り値

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

8.4.3.105 エラー

無し。

8.4.3.106 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

8.4.3.107 説明

使用中の接続タイプを表わす文字列を返します。サーバのホスト名を含みます。

8.4.3.108 戻り値

サーバホスト名と接続タイプを表わす文字列。

8.4.3.109 エラー

無し。

8.4.3.110 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

8.4.3.111 説明

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

8.4.3.112 Return Values

現在の接続に使用されているプロトコルバージョンを表わす符号無し整数値。

8.4.3.113 エラー

無し。

8.4.3.114 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

8.4.3.115 説明

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

8.4.3.116 戻り値

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

8.4.3.117 エラー

無し。

8.4.3.118 mysql_info()

char * mysql_info(MYSQL *mysql)

8.4.3.119 説明

最も最近に実行されたクエリについての情報を文字列で返します。が、 以下に挙げる構文に限ります。 他の構文ではmysql_info()NULL を返します。 文字列の形式 はクエリの型によって様々です。次に説明します (数値は例です; 文字列はクエ リに適した値を含みます):

INSERT INTO ... SELECT ...
String format: Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
String format: Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
String format: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
String format: Records: 3 Duplicates: 0 Warnings: 0
UPDATE
String format: Rows matched: 40 Changed: 40 Warnings: 0

注意: 複数の値リストがステートメント中に記述された場合にだけ、 mysql_info() は、INSERT ... VALUES ステートメントに非 NULL値を返します。

8.4.3.120 戻り値

最も最近に実行されたクエリについての追加情報を表わす文字列。クエリに有効 な情報がない場合は NULL ポインタ。

8.4.3.121 エラー

無し。

8.4.3.122 mysql_init()

MYSQL * mysql_init(MYSQL *mysql)

8.4.3.123 説明

mysql_real_connect() に適した MYSQL オブジェクトの割り当て または初期化を行ないます。引数が NULL ポインタの場合、関数は新し いオブジェクトを割り当てて初期化し返します。そうでなければオブジェクトは 初期化され、オブジェクトのアドレスが返されます。新しいオブジェクトが割り 当てられた場合、mysql_close() はこのオブジェクトを解放します。

8.4.3.124 戻り値

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

8.4.3.125 エラー

メモリ不足の場合は NULL が返されます。

8.4.3.126 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

8.4.3.127 説明

前のクエリによって AUTO_INCREMENT フィールドに生成された ID を返します。 AUTO_INCREMENT フィールドを含むテーブルに INSERT クエリを 実行した後で、この関数を使用してください。

注意: 前のクエリが AUTO_INCREMENT 値を生成しなかった場合、 mysql_insert_id()0 を返します。後のために値を保存する必 要がある場合、値を生成するクエリの直後に mysql_insert_id() を呼び出 すことに気をつけてください。

mysql_insert_id() is updated after INSERT and UPDATE statements that generate an AUTO_INCREMENT value or that set a column value to LAST_INSERT_ID(expr). 「6.3.5.2 その他の関数」節参照.

また、SQL LAST_INSERT_ID() 常に最後に生成された AUTO_INCREMENT 値を含み、クエリ間でリセットされないことに注意して下 さい。その関数の値はサーバ内で保守されるからです。

8.4.3.128 戻り値

前のクエリによって更新された AUTO_INCREMENT フィールドの値。接続上 の前のクエリがない場合、クエリが AUTO_INCREMENT 値を更新しなかった 場合には 0 が返ります。

8.4.3.129 エラー

無し。

8.4.3.130 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

8.4.3.131 説明

pid で指定されたスレッドを殺すようにサーバに頼みます。

8.4.3.132 戻り値

成功時0。失敗時非0。

8.4.3.133 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.134 mysql_list_dbs()

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

8.4.3.135 説明

サーバ上の、wild 引数で指定された簡易正規表現に適合する、データベー ス名からなる結果セットを返します。wild はワイルドカード文字 `%' または `_' を含むことができます。また、全てのデータベース に適合するように NULL ポインタにできます。mysql_list_dbs() の呼び出しはクエリ SHOW databases [LIKE wild] を実行するのと同様 です。

mysql_free_result() で結果セットを解放する必要があります。

8.4.3.136 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

8.4.3.137 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.138 mysql_list_fields()

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

8.4.3.139 説明

与えられたテーブル内の、wild 引数で指定された簡易正規表現に適合する フィールド名からなる結果セットを返します。wild はワイルドカー ド文字 `%' または `_' を含むことができます。また、全てのフィー ルドに適合するように NULL ポインタにできます。 mysql_list_fields() はクエリ SHOW COLUMNS FROM table [LIKE wild] を実行するのと同様です。

注意: mysql_list_fields() の代わりに SHOW COLUMNS FROM tbl_name の使用を勧めます。

mysql_free_result() で結果セットを解放する必要があります。

8.4.3.140 戻り値

成功時 MYSQL_RES 結果セット。エラーが発生した場合は NULL

8.4.3.141 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.142 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

8.4.3.143 説明

現在のサーバスレッドを示す結果セットを返します。これは mysqladmin processlistSHOW PROCESSLIST クエリで 報告されるものと同じ種類の情報です。

mysql_free_result() で結果セットを解放する必要があります。

8.4.3.144 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

8.4.3.145 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.146 mysql_list_tables()

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

8.4.3.147 説明

wild 引数で指定された簡易正規表現に適合する、現在のデータベース 内のテーブル名からなる結果セットを返します。wild はワイルドカード 文字 `%' または `_' を含むことができます。また、全てのテーブル に適合するように NULL ポインタにできます。 mysql_list_tables() はクエリ SHOW tables [LIKE wild] を実 行するのと同様です。

mysql_free_result() で結果セットを解放する必要があります。

8.4.3.148 戻り値

成功時 MYSQL_RES 結果セット。失敗した場合は NULL

8.4.3.149 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.150 mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

または

unsigned int mysql_num_fields(MYSQL *mysql)

二番目の形式は MySQL 3.23 以上では動作しません。MYSQL* 引 数を通す場合は、代わりに unsigned int mysql_field_count(MYSQL*mysql) を使用しなくてはいけません。

8.4.3.151 説明

結果セット中のフィールド数を返します。

注意: 結果セットへのポインタまたは接続ハンドルのいずれかからフィールドの数 を得ることができます。mysql_store_result() または mysql_use_result()NULL を返した(つまり結果セットポイン タが無い)場合、接続ハンドルを使用します。この場合、 mysql_field_count() を呼び出して、mysql_store_result() が空 でない結果を提供すべきかどうかを決定できます。これにより、クライアントプロ グラムはクエリが SELECT(または SELECT に似た)ステートメン トだったかどうかを知ることなしに、適切な行動を取ることができます。以下に示 す例はこれをどのように行なうかを説明しています。

8.4.5.1 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

8.4.3.152 戻り値

結果セット中のフィールド数を表わす符号無し整数。

8.4.3.153 エラー

無し。

8.4.3.154 例

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 かどうかのチェックに置き換えることです。これは何かが悪い場合にだけ起こり ます。

8.4.3.155 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

8.4.3.156 説明

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

mysql_num_rows() の使用は、結果セットを返すのに mysql_store_result()mysql_use_result() のどちらを使用す るかに依存します。mysql_store_result() を使用する場合、 mysql_num_rows() はすぐに呼ぶことができます。 mysql_use_result() を使用する場合、結果セットの全てのレコードが取り 出されるまで、mysql_num_rows() は正しい値を返しません。

8.4.3.157 戻り値

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

8.4.3.158 エラー

無し。

8.4.3.159 mysql_options()

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

8.4.3.160 説明

特別な接続オプションを設定し、接続の振舞いに影響を与えるために使用できます。 この関数は複数のオプションを設定するために複数回呼ぶことができます。

mysql_options()mysql_init() の後で、 mysql_connect()mysql_real_connect() の前に呼ばれなければ なりません。

option 引数は設定したいオプションです; arg 引数はオプション に対する値です。オプションが整数の場合、arg は整数値へのポインタで す。

有効なオプション値:

オプション 引数型 機能
MYSQL_OPT_CONNECT_TIMEOUT unsigned int * 接続タイムアウト(秒)。
MYSQL_OPT_COMPRESS 使用しない 圧縮クライアント/サーバプロトコルを使用する。
MYSQL_OPT_NAMED_PIPE 使用しない NT 上の MySQL サーバへの接続に名前付パイプを使用する。
MYSQL_INIT_COMMAND char * MySQL サーバへの接続時に実行するコマンド。再接続時に自動的に再実行される。
MYSQL_READ_DEFAULT_FILE char * `my.cnf' の代わりに指定されたオプションファイルからオプションを読み込む。
MYSQL_READ_DEFAULT_GROUP char * `my.cnf' または MYSQL_READ_DEFAULT_FILE で指定されたファイルから指定されたグループのオプションを読み込む。

注意: MYSQL_READ_DEFAULT_FILEMYSQL_READ_DEFAULT_GROUP を 使用する場合、client グループが常に読まれます。

オプションファイル中に指定されるグループは次のオプションを含むことができま す:

connect_timeout 接続タイムアウト(秒)。On Linux this timeout is also used for waiting for the first answer from the server.
compress 圧縮クライアント/サーバプロトコルを使用する。
database 接続命令中でデータベースが指定されない場合、このデータベースに接続する。
debug デバッグオプション
host デフォルトホスト名
init-command MySQL サーバへの接続時に実行するコマンド。再接続時に自動的に再実行される。
password デフォルトパスワード
pipe NT 上の MySQL サーバへの接続に名前付パイプを使用する。
port デフォルトポート番号
return-found-rows UPDATE 使用時、mysql_info() が更新された行の代わりに見つかった行を返すようにする。
socket デフォルトソケット番号
user デフォルトユーザ

Note that timeout has been replaced by connect_timeout, but timeout will still work for a while.

オプションファイルについてのさらなる情報は、 「4.1.2 my.cnf オプションファイル」節 を参照して 下さい。

8.4.3.161 戻り値

成功の場合は0。未知のオプションを使用した場合は非0。

8.4.3.162 例

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 セクションから追加オプションを読むように、クライアントに 要求します。

8.4.3.163 mysql_ping()

int mysql_ping(MYSQL *mysql)

8.4.3.164 説明

サーバへの接続が動作しているかどうかをチェックします。ダウンしている場合 は、自動的に再接続を試みます。

この関数は、長い間静かにしているクライアントが、サーバが接続をクローズし たかどうかをチェック(と再接続)するために使用できます。

8.4.3.165 戻り値

サーバが生きている場合0。他の値はエラーを示します。

8.4.3.166 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.167 mysql_query()

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

8.4.3.168 説明

NULL 終端文字列 query で示される SQL クエリを実行します。クエリはひ とつの SQL ステートメントでなければなりません。終端のセミコロン (`;')や \g をステートメントに追加すべきではありません。

mysql_query() はバイナリデータを含むクエリには使用できません(バ イナリデータは `\0' 文字を含むことがあります。これはクエリ文字列の 最後として解釈されます)。この場合、mysql_real_query() を代わりに 使用してください。

If you want to know if the query should return a result set or not, you can use mysql_field_count() to check for this. 「8.4.3.85 mysql_field_count()」節参照.

8.4.3.169 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

8.4.3.170 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.171 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 int client_flag)

8.4.3.172 説明

host 上で動作している MySQL データベースエンジンへの接続 の確立を試みます。 mysql_get_client_info() 以外の他の API 関数を実行する前に、 mysql_real_connect() が成功している必要があります。

mysql_real_connect() を呼び出す前に、MYSQL 構造体を獲得ま たは初期化するために mysql_init() を呼ぶ必要があることに注意して ください。

mysql_real_connect() の最初の引数に NULL ポインタを記述す ることもできます。これは C API が接続構造体のメモリを割り当て、 mysql_close() 呼び出し時に自動的に解放されます。この方法の不利な 点は、接続が失敗した場合に mysql_real_connect() からのエラーメッ セージを取り出すことができないことです。

最初の引数が NULL ポインタでない場合は、存在する MYSQL 構 造体のアドレスであるべきです。

8.4.3.173 戻り値

接続が成功した場合は MYSQL* 接続ハンドルです。接続が失敗した場合 は C NULL ポインタです。 接続に成功すると、戻り値はその最初のパラメータの値と同じです。

8.4.3.174 エラー

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 上の名前つきパイプの wait に失敗した。
CR_NAMEDPIPESETSTATE_ERROR
Windows 上のパイプハンドラの獲得に失敗した。
CR_SERVER_LOST
If connect_timeout > 0 and it took longer then connect_timeout seconds to connect to the server or if the server died while executing the init-command.

8.4.3.175 例

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

By using mysql_options() the MySQL library will read the [client] and your_prog_name sections in the my.cnf file which will ensure that your program will work, even if someone has set up MySQL in some non-standard way.

Note that upon connection, mysql_real_connect() sets the reconnect flag (part of the MYSQL structure) to a value of 1. This flag indicates, in the event that a query cannot be performed because of a lost connection, to try reconnecting to the server before giving up.

8.4.3.176 mysql_real_escape_string()

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

8.4.3.177 説明

This function is used to create a legal SQL string that you can use in a SQL statement. 「6.1.1.1 文字列」節参照.

from の文字列を、SQL ステートメントとしてサーバに送ることができる ように、現在のキャラクタ・セットを考慮しながら変換します。 結果は to に入り、終端 null 文字を追加します。 変換される文字列は `NUL' (ASCII 0), `\n', `\r', `\', `'', `"', Control-Z です。( 「6.1.1 文字列と数値をどのように書くか?」節参照).

from で示される文字列 はlength バイト長でなければなりません。 to バッファには少なくとも length*2+1 バイト長を割り当てる 必要があります。(最悪の場合、それぞれの文字が2バイトに変換されることがあ り、さらに終端 null バイトのための場所が必要です。) mysql_escape_string() が復帰するとき、to の内容は NUL 終端文字列になります。 戻り値は変換された文字列の長さです。終端 null 文字は含みません。

8.4.3.178 例

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() のように働きますが、最初の引数の終りの null へのポイ ンタを返します。

8.4.3.179 戻り値

to へ置かれた値の長さ。終端 null 文字は含みません。

8.4.3.180 エラー

無し。

8.4.3.181 mysql_real_query()

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

8.4.3.182 説明

query で示される SQL クエリを実行します。これは length バ イト長です。クエリはひとつの SQL ステートメントでなければなりません。終端 のセミコロン(`;')や \g をステートメントに追加すべきではありま せん。

バイナリデータを含むクエリは mysql_real_query() を使 用しなければなりません。バイナリデータは `\0' 文字を含むこと があるからです。 また、mysql_real_query()mysql_query() よりも速いです。 クエリの strlen() を呼ばないからです。

If you want to know if the query should return a result set or not, you can use mysql_field_count() to check for this. 「8.4.3.85 mysql_field_count()」節参照.

8.4.3.183 戻り値

クエリが成功した場合は0。クエリが失敗した場合は非0。

8.4.3.184 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.185 mysql_reload()

int mysql_reload(MYSQL *mysql)

8.4.3.186 説明

MySQL サーバに、アクセス権テーブルを再読み込みするように依頼し ます。接続されたユーザは reload 権限を持つ必要があります。

この関数は推奨されません。代わりに、SQL FLUSH PRIVILEGES ステートメ ントを発行する mysql_query() の使用が推奨されます。

8.4.3.187 戻り値

成功時0。失敗時非0。

8.4.3.188 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.189 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

8.4.3.190 説明

レコードカーソルをクエリ結果セット中の絶対レコードに設定します。これは、結 果セット構造体がクエリのすべての結果を持っていることを要求します。そのため、 mysql_row_seek()mysql_store_result() と共にだけ使用でき、 mysql_use_result() と共には使用できません。

オフセットは mysql_row_tell() または mysql_row_seek() 呼びだ しからの戻り値であるべきです。この値は単純なレコード番号ではありません;レ コード番号を使用して結果セット内のレコードにシークしたい場合は、 mysql_data_seek() を代わりに使用してください。

8.4.3.191 戻り値

レコードカーソルの前の値。この値はその後の mysql_row_seek() 呼びだ しに渡すことができます。

8.4.3.192 エラー

無し。

8.4.3.193 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

8.4.3.194 説明

最後の mysql_fetch_row() についてレコードカーソルの現在の位置を返します。 この値は mysql_row_seek() への引数として使用できます。

mysql_row_tell()mysql_store_result() の後にだけ使用すべ きで、mysql_use_result() の後には使用すべきではありません。

8.4.3.195 戻り値

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

8.4.3.196 エラー

無し。

8.4.3.197 mysql_select_db()

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

8.4.3.198 説明

mysql で示される現在の接続に、デフォルト(現在の)データベースとし て db で示されるデータベースを使用するように指示します。以降のク エリでは、明示的にデータベースを指定しないテーブル参照について、このデー タベースがデフォルトになります。

接続されたユーザがデータベースを使用する権限を持っていると証明されなけれ ば、mysql_select_db() は失敗します。

8.4.3.199 戻り値

成功時0。失敗時非0。

8.4.3.200 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.201 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

8.4.3.202 説明

データベースサーバにシャットダウンするように要求します。接続されたユーザ は shutdown 権限を持っている必要があります。

8.4.3.203 戻り値

成功時0。失敗時非0。

8.4.3.204 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.205 mysql_stat()

char *mysql_stat(MYSQL *mysql)

8.4.3.206 説明

mysqladmin status で提供されるのと同様の情報を文字列として返しま す。これは秒での uptime と、実行中のスレッド数、問い合わせ数、再読み込み 数、オープンテーブル数を含みます。

8.4.3.207 戻り値

サーバ状態を表わす文字列。エラーが発生した場合 NULL

8.4.3.208 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.209 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

8.4.3.210 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、mysql_store_result() または mysql_use_result() を呼び出す必要があります。

You don't have to call mysql_store_result() or mysql_use_result() for other queries, but it will not do any harm or cause any notable performance if you call mysql_store_result() in all cases. You can detect if the query didn't have a result set by checking if mysql_store_result() returns 0 (more about this later one).

If you want to know if the query should return a result set or not, you can use mysql_field_count() to check for this. 「8.4.3.85 mysql_field_count()」節参照.

mysql_store_result() はクエリのすべての結果をクライアントへ読み込み、 MYSQL_RES 構造体を割り当て、この構造体に結果を配置します。

mysql_store_results() returns a null pointer if the query didn't return a result sets (If the query was, for example, an INSERT statement).

mysql_store_results() returns also null pointer if reading of the result set failed. You can check if you got an error by checking if mysql_error() doesn't return a null pointer, if mysql_errno() returns <> 0 or if mysql_field_count() returns <> 0.

返されるレコードが無い場合、空の結果セットが返されます。 (空の結果セットは NULL 戻り値とは異なります。)

一度 mysql_store_result() を呼び出して null ポインターでない 結果を得る事ができたら、結果セット中にいくつのレ コードがあるかを見つけるために、mysql_num_rows() を呼び出すことがで きます。

結果セットからレコードを取り出すために mysql_fetch_row() を呼び出す ことができます。また、結果セット内の現在のレコード位置を設定/取得するため に mysql_row_seek()mysql_row_tell() を呼び出すことができ ます。

一度結果セットで行なうと、mysql_free_result() を呼び出す必要があ ります。

8.4.5.1 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?」節参照.

8.4.3.211 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL

8.4.3.212 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.3.213 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

8.4.3.214 説明

現在の接続のスレッド ID を返します。この値は、スレッドを殺すための mysql_kill() への引数として使用できます。

接続が失われて、mysql_ping() で再接続した場合、スレッド ID は変更さ れます。これはスレッド ID を後で使うために取得して格納すべきではないことを 意味します。必要な時にそれを取得すべきです。

8.4.3.215 戻り値

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

8.4.3.216 エラー

無し。

8.4.3.217 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

8.4.3.218 説明

データを取り出すクエリ(SELECT, SHOW, DESCRIBE, EXPLAIN)が成功する毎に、 mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_use_result() は結果セット検索を開始しますが, mysql_store_result() のように、実際にクライアントに結果セットを読み 取りません. 代わりに、各レコードは mysql_fetch_row() 呼びだしが行な われることにより、個々に取り出されます。 mysql_use_result() はクエリの結果を、一時テーブルやローカルバッファ に格納すること無く、サーバから直接読み込みます。これは mysql_store_result() よりもいくらか速く、少ないメモリを使用します。 この場合、クライアントは現在の行と接続バッファ ( max_allowed_packet bytes まで増加する ) のメモリだけを割り当てます。

一方、クライアント側で各行に ついて多くの処理を行なう場合や、ユーザが ^S (スクロール停止) を入 力できるような画面に出力を送る場合は、mysql_use_result() を使用す べきではありません。これはサーバと連携しており、他のスレッドが データが取り出されるテーブルを更新する事を邪魔します。

mysql_use_result() 使用時、NULL 値を取り出すまで mysql_fetch_row() を実行する必要があります。そうしないと、次のク エリは前のクエリから結果を取り出します。これを忘れると、C API はエラー Commands out of sync; You can't run this command now を与えます!

mysql_use_result() から返される結果では、 mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows(), mysql_affected_rows() を使用できません。 また、mysql_use_result() が終了するまで他のクエリの発行もできませ ん。(全ての行をフェッチした後に、フェッチされた行数を知るために mysql_num_rows を呼び出すことができます。)

一度結果セットで行なうと、mysql_free_result() を呼び出す必要があ ります。

8.4.3.219 戻り値

結果の MYSQL_RES 結果構造体。エラーがある場合 NULL

8.4.3.220 エラー

CR_COMMANDS_OUT_OF_SYNC
不当な順にコマンドが実行された。
CR_OUT_OF_MEMORY
メモリ不足。
CR_SERVER_GONE_ERROR
MySQL サーバがいなくなった。
CR_SERVER_LOST
サーバへの接続がクエリ中に失われた。
CR_UNKNOWN_ERROR
未知のエラーが発生した。

8.4.4 C Threaded Function Descriptions

You need to use the following functions when you want to create a threaded client. 「8.4.7 スレッドクライアントを作る方法」節参照.

8.4.4.1 my_init()

8.4.4.2 Description

This function needs to be called once in the program before calling any MySQL function. This initializes some global variables that MySQL needs. If you are using a thread safe client library, this will also call my_thread_init() for this thread.

This is automatically called by mysql_init() and mysql_connect().

8.4.4.3 Return Values

none.

8.4.4.4 my_thread_init()

8.4.4.5 Description

This function needs to be called for each created thread to initialize thread specific variables.

This is automatically called by my_init() and mysql_connect().

8.4.4.6 Return Values

none.

8.4.4.7 my_thread_end()

8.4.4.8 Description

This function needs to be called before calling pthread_exit() to freed memory allocated by my_thread_init().

Note that this function is NOT invoked automatically by the client library!

8.4.4.9 Return Values

none.

8.4.5 Common questions and problems when using the C API

8.4.5.1 mysql_query() が成功を返した後、mysql_store_result()NULL を返す時があるのは何故?

mysql_query() の呼び出しが成功した後に mysql_store_result()NULL を返すことがあります。これが 起こったとき、次の条件のどれかの発生を意味します:

ステートメントが空でない結果を提供するかどうかは mysql_field_count() の呼び出しによっていつでもチェックできます。 mysql_field_count() が 0 を返す場合、結果は空で最後のクエリは値を 返さないステートメントです (例えば、INSERTDELETE)。 mysql_field_count() が非 0 値を返す場合、ステートメントは空でない 結果を提供します。 例はmysql_field_count() 関数の説明を参照してください。

mysql_error() または mysql_errno() を呼び出すことによって エラーのテストもできます。

8.4.5.2 クエリから得られる結果は何か?

クエリによって返される結果セットに加えて、次の情報も得ることができます:

8.4.5.3 最後に挿入された行のユニーク ID をどのように得られるか?

AUTO_INCREMENT 属性を持つ項目を含むテーブルにレコードを挿入する場 合、mysql_insert_id() 関数で与えられた ID を得ることができます。

mysql_query() に渡すクエリ文字列内のLAST_INSERT_ID() 関数 を使用することでも、ID を取り出すことができます。

次のコードを実行することで、AUTO_INCREMENT インデックスが使用され たかどうかチェックできます。これは、クエリが AUTO_INCREMENT イン デックスを伴う INSERT だったかどうかもチェックできます:

if (mysql_error(&mysql)[0] == 0 &&
    mysql_num_fields(result) == 0 &&
    mysql_insert_id(&mysql) != 0)
{
    used_id = mysql_insert_id(&mysql);
}

生成された最後の ID は接続毎にサーバ内で維持されています。他のクライアント によって変更はされません。他の AUTO_INCREMENT 項目を非マジック値 (すなわち、NULL でなく 0 でない値) で更新する場合でも、それは変更 されません。

また、他のテーブルにその ID を挿入しようとする場合、次で行なうことができます:

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

8.4.5.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

これは、あなたのシステム上では、コンパイル/リンク行の最後に、math ライブ ラリ (-lm) を含める必要があることを意味します。

8.4.6 Building Client Programs

If you compile MySQL clients that you've written yourself or that you obtain from a third party, they must be linked using the -lmysqlclient -lz option on the link command. You may also need to specify a -L option to tell the linker where to find the library. For example, if the library is installed in `/usr/local/mysql/lib', use -L/usr/local/mysql/lib -lmysqlclient -lz on the link command.

For clients that use MySQL header files, you may need to specify a -I option when you compile them (for example, -I/usr/local/mysql/include), so the compiler can find the header files.

8.4.7 スレッドクライアントを作る方法

クライアントは `ほとんど' スレッド安全です。一番大きな問題は `net.c' (ソケットから読み込みをするサブルーチンを含むファイル) が割 り込み安全でないことです。これは、サーバからの長い読み込みを中断できるよ うに、自身のアラームを持ちたいだろうという考慮で行なわれました。 If you install interrupt handlers for the SIGPIPE interrupt, the socket handling should be thread safe.

われわれの Web site で公開している古いバイナリ配布では、 標準クライアントライブラリはスレッドオプションでコンパイルされていません。 (the Windows binaries are by default compiled to be thread safe). Newer binary distributions should have both a normal and a thread-safe client library.

スレッド安全クライアント(MySQLサーバーとの通信時に、 他のスレッドがクライアントのスレッドに interrupt をかけたり、 タイムアウトをセットしたりする) を得るためには、-lmysys, -lstring, -ldbug ライブラリとサーバが使用する net_serv.o を使用しま す。

If you don't need interrupts or timeouts, you can just compile a thread safe client library (mysqlclient_r) and use this. 「8.4 MySQL C API」節参照. In this case you don't have to worry about the net_serv.o object file or the other MySQL libraries.

スレッドクライアントを使用する時、`thr_alarm.c' ルーチンを大いに使 用できます。mysys ライブラリからのルーチンを使用する場合、覚えて おかなければならないことは my_init() を最初に呼ぶことだけです!

mysql_real_connect() を除く全ての関数は現在スレッド安全です。スレッ ド安全クライアントライブラリをコンパイルし、それをスレッド安全なマナーで使 用するための方法を、次の注意で説明します。(この mysql_real_connect() についての注意は、実際には mysql_connect() にも有効です。しかし mysql_connect() は推奨 されませんので、とにかく mysql_real_connect() を使用すべきです。)

mysql_real_connect() をスレッド安全にするためには、クライアントを次の コマンドで再コンパイルする必要があります:

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

This will create a thread-safe client library libmysqlclient_r. --enable-thread-safe-client. This library is thread safe per connection. You can let two threads share the same connection as long as you do the following:

You may get some errors because of undefined symbols when linking your client with mysqlclient_r. In most cases this is because you haven't included the thread libraries on the link/compile line.

8.5 MySQL C++ APIs

Two APIs are available in the MySQL Contrib directory.

8.5.1 Borland C++

You can compile the MySQL Windows source with Borland C++ 5.02. (The Windows source includes only projects for Microsoft VC++, for Borland C++ you have to do the project files yourself).

One known problem with Borland C++ is that it uses a different structure alignment than VC++. This means that you will run into problems if you try to use the default libmysql.dll libraries (that was compiled with VC++) with Borland C++. You can do one of the following to avoid this problem.

8.6 MySQL Java Connectivity (JDBC)

There are 2 supported JDBC drivers for MySQL (the mm driver and the Reisin JDBC driver). You can find a copy of the mm driver at http://mmmysql.sourceforge.net/ or http://www.mysql.com/Downloads/Contrib/ and the Reisin driver at http://www.caucho.com/projects/jdbc-mysql/index.xtp For documentation consult any JDBC documentation and the driver's own documentation for MySQL-specific features.

8.7 MySQL Python APIs

The MySQL Contrib directory contains a Python interface written by Joseph Skinner.

You can also use the Python interface to iODBC to access a MySQL server. mxODBC

8.8 MySQL Tcl APIs

Tcl at binevolve. The Contrib directory contains a Tcl interface that is based on msqltcl 1.50.

8.9 MySQL Eiffel wrapper

The MySQL Contrib directory contains an Eiffel wrapper written by Michael Ravits.

You can also find this at: http://www.netpedia.net/hosting/newplayer/

8.10 MySQL Ruby API

以下のサイトに、Ruby の MySQL インターフェースがあります。

www.tmtm.org とみたまさひろ氏の Web ページ


Go to the first, previous, next, last section, table of contents.