Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Mysql.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mysql 3"
.TH Mysql 3 "2002-10-01" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Msql / Mysql \- Perl interfaces to the mSQL and mysql databases
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Msql;
.Ve
.PP
.Vb 2
\&  $dbh = Msql->connect($host);
\&  $dbh = Msql->connect($host, $database);
.Ve
.PP
.Vb 1
\&      or
.Ve
.PP
.Vb 1
\&  use Mysql;
.Ve
.PP
.Vb 2
\&  $dbh = Mysql->connect(undef, $database, $user, $password);
\&  $dbh = Mysql->connect($host, $database, $user, $password);
.Ve
.PP
.Vb 1
\&      or
.Ve
.PP
.Vb 2
\&  $dbh = Msql1->connect($host);
\&  $dbh = Msql1->connect($host, $database);
.Ve
.PP
.Vb 1
\&  $dbh->selectdb($database);
.Ve
.PP
.Vb 2
\&  @arr = $dbh->listdbs;
\&  @arr = $dbh->listtables;
.Ve
.PP
.Vb 3
\&  $quoted_string = $dbh->quote($unquoted_string);
\&  $error_message = $dbh->errmsg;
\&  $error_number = $dbh->errno;   # MySQL only
.Ve
.PP
.Vb 2
\&  $sth = $dbh->listfields($table);
\&  $sth = $dbh->query($sql_statement);
.Ve
.PP
.Vb 4
\&  @arr = $sth->fetchrow;        # Array context
\&  $firstcol = $sth->fetchrow;   # Scalar context
\&  @arr = $sth->fetchcol($col_number);
\&  %hash = $sth->fetchhash;
.Ve
.PP
.Vb 1
\&  $sth->dataseek($row_number);
.Ve
.PP
.Vb 1
\&  $sth->as_string;
.Ve
.PP
.Vb 3
\&  @indices = $sth->listindices                   # only in mSQL 2.0
\&  @arr = $dbh->listindex($table,$index)          # only in mSQL 2.0
\&  ($step,$value) = $dbh->getsequenceinfo($table) # only in mSQL 2.0
.Ve
.PP
.Vb 3
\&  $rc = $dbh->shutdown();
\&  $rc = $dbh->createdb($database);
\&  $rc = $dbh->dropdb($database);
.Ve
.SH "OBSOLETE SOFTWARE"
.IX Header "OBSOLETE SOFTWARE"
As of Msql-Mysql-modules 1.19_10 M(y)sqlPerl is no longer a separate module.
Instead it is emulated using the \s-1DBI\s0 drivers. You are strongly encouraged
to implement new code with \s-1DBI\s0 directly. See \*(L"\s-1COMPATIBILITY\s0 \s-1NOTES\s0\*(R"
below.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package is designed as close as possible to its C \s-1API\s0
counterpart. The manual that comes with mSQL or MySQL describes most things
you need. Due to popular demand it was decided though, that this interface
does not use StudlyCaps (see below).
.PP
As of March 1998, the Msql and Mysql modules are obsoleted by the
\&\s-1DBI\s0 drivers DBD::mSQL and DBD::mysql, respectively. You are strongly
encouraged to implement new code with the \s-1DBI\s0 drivers. In fact,
Msql and Mysql are currently implemented as emulations on top of
the \s-1DBI\s0 drivers.
.PP
Internally you are dealing with the two classes \f(CW\*(C`Msql\*(C'\fR and
\&\f(CW\*(C`Msql::Statement\*(C'\fR or \f(CW\*(C`Mysql\*(C'\fR and \f(CW\*(C`Mysql::Statement\*(C'\fR, respectively.
You will never see the latter, because you reach
it through a statement handle returned by a query or a listfields
statement. The only class you name explicitly is Msql or Mysql. They
offer you the connect command:
.PP
.Vb 2
\&  $dbh = Msql->connect($host);
\&  $dbh = Msql->connect($host, $database);
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 2
\&  $dbh = Mysql->connect($host, undef, $user, $password);
\&  $dbh = Mysql->connect($host, $database, $user, $password);
.Ve
.PP
.Vb 1
\&    or
.Ve
.PP
.Vb 2
\&  $dbh = Msql1->connect($host);
\&  $dbh = Msql1->connect($host, $database);
.Ve
.PP
This connects you with the desired host/database. With no argument or
with an empty string as the first argument it connects to the \s-1UNIX\s0
socket, which has a much better performance than
the \s-1TCP\s0 counterpart. A database name as the second argument selects
the chosen database within the connection. The return value is a
database handle if the connect succeeds, otherwise the return value is
undef.
.PP
You will need this handle to gain further access to the database.
.PP
.Vb 1
\&   $dbh->selectdb($database);
.Ve
.PP
If you have not chosen a database with the \f(CW\*(C`connect\*(C'\fR command, or if
you want to change the connection to a different database using a
database handle you have got from a previous \f(CW\*(C`connect\*(C'\fR, then use
selectdb.
.PP
.Vb 2
\&  $sth = $dbh->listfields($table);
\&  $sth = $dbh->query($sql_statement);
.Ve
.PP
These two work rather similar as descibed in the mSQL or MySQL manual. They
return a statement handle which lets you further explore what the
server has to tell you. On error the return value is undef. The object
returned by listfields will not know about the size of the table, so a
\&\fInumrows()\fR on it will return the string \*(L"N/A\*(R";
.PP
.Vb 2
\&  @arr = $dbh->listdbs();
\&  @arr = $dbh->listtables;
.Ve
.PP
An array is returned that contains the requested names without any
further information.
.PP
.Vb 1
\&  @arr = $sth->fetchrow;
.Ve
.PP
returns an array of the values of the next row fetched from the
server. Be carefull with context here! In scalar context the method
behaves different than expected and returns the first column:
.PP
.Vb 1
\&  $firstcol = $sth->fetchrow; # Scalar context!
.Ve
.PP
Similar does
.PP
.Vb 1
\&  %hash = $sth->fetchhash;
.Ve
.PP
return a complete hash. The keys in this hash are the column names of
the table, the values are the table values. Be aware, that when you
have a table with two identical column names, you will not be able to
use this method without trashing one column. In such a case, you
should use the fetchrow method.
.PP
.Vb 1
\&  @arr = $sth->fetchcol($colnum);
.Ve
.PP
returns an array of the values of each row for column \f(CW$colnum\fR.  Note that
this reads the entire table and leaves the row offset at the end of the
table; be sure to use \f(CW$sth\fR\->\fIdataseek()\fR to reset it if you want to
re-examine the table.
.PP
.Vb 1
\&  $sth->dataseek($row_number);
.Ve
.PP
lets you specify a certain offset of the data associated with the
statement handle. The next fetchrow will then return the appropriate
row (first row being 0).
.Sh "No close statement"
.IX Subsection "No close statement"
Whenever the scalar that holds a database or statement handle loses
its value, Msql chooses the appropriate action (frees the result or
closes the database connection). So if you want to free the result or
close the connection, choose to do one of the following:
.IP "undef the handle" 4
.IX Item "undef the handle"
.PD 0
.IP "use the handle for another purpose" 4
.IX Item "use the handle for another purpose"
.IP "let the handle run out of scope" 4
.IX Item "let the handle run out of scope"
.IP "exit the program." 4
.IX Item "exit the program."
.PD
.Sh "Error messages"
.IX Subsection "Error messages"
Both drivers, Msql and Mysql implement a method \->\fIerrmsg()\fR, which
returns a textual error message. Mysql additionally supports a method
\&\->errno returning the corresponding error number.
.PP
Usually you do fetch error messages with
.PP
.Vb 1
\&    $errmsg = $dbh->errmsg();
.Ve
.PP
In situations where a \f(CW$dbh\fR is not available (for example when
\&\fIconnect()\fR failed) you may instead do a
.PP
.Vb 5
\&    $errmsg = Msql->errmsg();
\&        or
\&    $errmsg = Mysql->errmsg();
\&        or
\&    $errmsg = Msql1->errmsg();
.Ve
.ie n .Sh "The ""\-w"" switch"
.el .Sh "The \f(CW\-w\fP switch"
.IX Subsection "The -w switch"
With Msql and Mysql the \f(CW\*(C`\-w\*(C'\fR switch is your friend! If you call your perl
program with the \f(CW\*(C`\-w\*(C'\fR switch you get the warnings from \->errmsg on
\&\s-1STDERR\s0. This is a handy method to get the error messages from the msql
server without coding it into your program.
.PP
If you want to know in greater detail what's going on, set the
environment variables that are described in David's manual. David's
debugging aid is excellent, there's nothing to be added.
.PP
By default errors are printed as warnings. You can suppress this
behaviour by using the PrintError attribute of the respective handles:
.PP
.Vb 1
\&    $dbh->{'dbh'}->{'PrintError'} = 0;
.Ve
.ie n .Sh "\->quote($str [, $length])"
.el .Sh "\->quote($str [, \f(CW$length\fP])"
.IX Subsection "->quote($str [, $length])"
returns the argument enclosed in single ticks ('') with any special
character escaped according to the needs of the \s-1API\s0.
.PP
For mSQL this means, any single tick within the string is escaped with
a backslash and backslashes are doubled. Currently (as of msql\-1.0.16)
the \s-1API\s0 does not allow to insert \s-1NUL\s0's (\s-1ASCII\s0 0) into tables. The quote
method does not fix this deficiency.
.PP
MySQL allows \s-1NUL\s0's or any other kind of binary data in strings. Thus
the quote method will additionally escape \s-1NUL\s0's as \e0.
.PP
If you pass undefined values to the quote method, it returns the
string \f(CW\*(C`NULL\*(C'\fR.
.PP
If a second parameter is passed to \f(CW\*(C`quote\*(C'\fR, the result is truncated
to that many characters.
.Sh "\s-1NULL\s0 fields"
.IX Subsection "NULL fields"
\&\s-1NULL\s0 fields in tables are returned to perl as undefined values.
.Sh "Metadata"
.IX Subsection "Metadata"
Now lets reconsider the above methods with regard to metadata.
.Sh "Database Handle"
.IX Subsection "Database Handle"
As said above you get a database handle with the \fIconnect()\fR method.
The database handle knows about the socket, the host, and the database
it is connected to.
.PP
You get at the three values with the methods
.PP
.Vb 3
\&  $scalar = $dbh->sock;
\&  $scalar = $dbh->host;
\&  $scalar = $dbh->database;
.Ve
.PP
Mysql additionally supports
.PP
.Vb 2
\&  $scalar = $dbh->user;
\&  $scalar = $dbh->sockfd;
.Ve
.PP
where the latter is the file descriptor of the socket used by the
database connection. This is the same as \f(CW$dbh\fR\->sock for mSQL.
.Sh "Statement Handle"
.IX Subsection "Statement Handle"
Two constructor methods return a statement handle:
.PP
.Vb 2
\&  $sth = $dbh->listfields($table);
\&  $sth = $dbh->query($sql_statement);
.Ve
.PP
$sth knows about all metadata that are provided by the \s-1API:\s0
.PP
.Vb 2
\&  $scalar = $sth->numrows;    
\&  $scalar = $sth->numfields;
.Ve
.PP
.Vb 18
\&  @arr  = $sth->table;       the names of the tables of each column
\&  @arr  = $sth->name;        the names of the columns
\&  @arr  = $sth->type;        the type of each column, defined in msql.h
\&                             and accessible via Msql::CHAR_TYPE,
\&                             &Msql::INT_TYPE, &Msql::REAL_TYPE or
\&                             &Mysql::FIELD_TYPE_STRING,
\&                             &Mysql::FIELD_TYPE_LONG, ...
\&  @arr  = $sth->isnotnull;   array of boolean
\&  @arr  = $sth->isprikey;    array of boolean
\&  @arr  = $sth->isnum;       array of boolean
\&  @arr  = $sth->length;      array of the possibble maximum length of each
\&                             field in bytes
\&  @arr  = $sth->maxlength;   array of the actual maximum length of each field
\&                             in bytes. Be careful when using this attribute
\&                             under MsqlPerl: The server doesn't offer this
\&                             attribute, thus it is calculated by fetching
\&                             all rows. This might take a long time and you
\&                             might need to call $sth->dataseek.
.Ve
.PP
Mysql additionally supports
.PP
.Vb 4
\&  $scalar  = $sth->affectedrows  number of rows in database affected by query
\&  $scalar  = $sth->insertid      the unique id given to a auto_increment field.
\&  $string  = $sth->info()        more info from some queries (ALTER TABLE...)
\&  $arrref  = $sth->isblob;       array of boolean
.Ve
.PP
The array methods (table, name, type, is_not_null, is_pri_key, length,
affected_rows, is_num and blob) return an array in array context and
an array reference (see perlref and perlldsc for details) when
called in a scalar context. The scalar context is useful, if you need
only the name of one column, e.g.
.PP
.Vb 1
\&    $name_of_third_column = $sth->name->[2]
.Ve
.PP
which is equivalent to
.PP
.Vb 2
\&    @all_column_names = $sth->name;
\&    $name_of_third_column = $all_column_names[2];
.Ve
.Sh "New in mSQL 2.0"
.IX Subsection "New in mSQL 2.0"
The \fIquery()\fR function in the \s-1API\s0 returns the number of rows affected by
a query. To cite the mSQL \s-1API\s0 manual, this means...
.PP
.Vb 4
\&  If the return code is greater than 0, not only does it imply
\&  success, it also indicates the number of rows "touched" by the query
\&  (i.e. the number of rows returned by a SELECT, the number of rows
\&  modified by an update, or the number of rows removed by a delete).
.Ve
.PP
As we are returning a statement handle on selects, we can easily check
the number of rows returned. For non-selects we behave just the same
as mSQL\-2.
.PP
To find all indices associated with a table you can call the
\&\f(CW\*(C`listindices()\*(C'\fR method on a statement handle. To find out the columns
included in an index, you can call the \f(CW\*(C`listindex($table,$index)\*(C'\fR
method on a database handle.
.PP
There are a few new column types in mSQL 2. You can access their
numeric value with these functions defined in the Msql package:
\&\s-1IDENT_TYPE\s0, \s-1NULL_TYPE\s0, \s-1TEXT_TYPE\s0, \s-1DATE_TYPE\s0, \s-1UINT_TYPE\s0, \s-1MONEY_TYPE\s0,
\&\s-1TIME_TYPE\s0, \s-1IDX_TYPE\s0, \s-1SYSVAR_TYPE\s0.
.PP
You cannot talk to a 1.0 server with a 2.0 client.
.PP
You cannot link to a 1.0 library \fIand\fR to a 2.0 library \fIat the same
time\fR. So you may want to build two different Msql modules at a time,
one for 1.0, another for 2.0, and load whichever you need. Check out
what the \f(CW\*(C`\-I\*(C'\fR switch in perl is for.
.PP
Everything else seems to remain backwards compatible.
.Sh "@EXPORT"
.IX Subsection "@EXPORT"
For historical reasons the constants \s-1CHAR_TYPE\s0, \s-1INT_TYPE\s0, and
\&\s-1REAL_TYPE\s0 are in \f(CW@EXPORT\fR instead of \f(CW@EXPORT_OK\fR. This means, that you
always have them imported into your namespace. I consider it a bug,
but not such a serious one, that I intend to break old programs by
moving them into \s-1EXPORT_OK\s0.
.Sh "Displaying whole tables in one go"
.IX Subsection "Displaying whole tables in one go"
A handy method to show the complete contents of a statement handle is
the as_string method. This works similar to the msql monitor with a
few exceptions:
.IP "the width of a column" 2
.IX Item "the width of a column"
is calculated by examining the width of all entries in that column
.IP "control characters" 2
.IX Item "control characters"
are mapped into their backslashed octal representation
.IP "backslashes" 2
.IX Item "backslashes"
are doubled (\f(CW\*(C`\e\e instead of \e\*(C'\fR)
.IP "numeric values" 2
.IX Item "numeric values"
are adjusted right (both integer and floating point values)
.PP
The differences are illustrated by the following table:
.PP
Input to msql (a real carriage return here replaced with ^M):
.PP
.Vb 4
\&    CREATE TABLE demo (
\&      first_field CHAR(10),
\&      second_field INT
\&    ) \eg
.Ve
.PP
.Vb 5
\&    INSERT INTO demo VALUES ('new
\&    line',2)\eg
\&    INSERT INTO demo VALUES ('back\e\eslash',1)\eg
\&    INSERT INTO demo VALUES ('cr^Mcrnl
\&    nl',3)\eg
.Ve
.PP
Output of msql:
.PP
.Vb 9
\&     +-------------+--------------+
\&     | first_field | second_field |
\&     +-------------+--------------+
\&     | new
\&    line    | 2            |
\&     | back\eslash  | 1            |
\&    crnlr
\&    nl  | 3            |
\&     +-------------+--------------+
.Ve
.PP
Output of pmsql:
.PP
.Vb 7
\&    +----------------+------------+
\&    |first_field     |second_field|
\&    +----------------+------------+
\&    |new\e012line     |           2|
\&    |back\e\eslash     |           1|
\&    |cr\e015crnl\e012nl|           3|
\&    +----------------+------------+
.Ve
.Sh "Version information"
.IX Subsection "Version information"
The version of Msql and Mysql is always stored in \f(CW$Msql::VERSION\fR or
\&\f(CW$Mysql::VERSION\fR as it is perl standard.
.PP
The mSQL \s-1API\s0 implements methods to access some internal configuration
parameters: gethostinfo, getserverinfo, and getprotoinfo.  All three
are available both as class methods or via a database handle. But
under no circumstances they are associated with a database handle. All
three return global variables that reflect the \fBlast\fR \fIconnect()\fR
command within the current program. This means, that all three return
empty strings or zero \fIbefore\fR the first call to \fIconnect()\fR.
.PP
This situation is better with MySQL: The methods are valid only
in connection with a database handle.
.Sh "Administration"
.IX Subsection "Administration"
shutdown, createdb, dropdb, reloadacls are all accessible via a
database handle and implement the corresponding methods to what
msqladmin does.
.PP
The mSQL and MySQL engines do not permit that these commands are invoked by
users without sufficient privileges. So please make sure
to check the return and error code when you issue one of them.
.PP
.Vb 3
\&    $rc = $dbh->shutdown();
\&    $rc = $dbh->createdb($database);
\&    $rc = $dbh->dropdb($database);
.Ve
.PP
It should be noted that database deletion is \fInot prompted for\fR in
any way. Nor is it undo-able from within Perl.
.PP
.Vb 1
\&    B<Once you issue the dropdb() method, the database will be gone!>
.Ve
.PP
These methods should be used at your own risk.
.Sh "StudlyCaps"
.IX Subsection "StudlyCaps"
Real Perl Programmers (C) usually don't like to type \fIListTables\fR but
prefer \fIlist_tables\fR or \fIlisttables\fR. The mSQL \s-1API\s0 uses StudlyCaps
everywhere and so did early versions of MsqlPerl. Beginning with
\&\f(CW$VERSION\fR 1.06 all methods are internally in lowercase, but may be
written however you please. Case is ignored and you may use the
underline to improve readability.
.PP
The price for using different method names is neglectible. Any method
name you use that can be transformed into a known one, will only be
defined once within a program and will remain an alias until the
program terminates. So feel free to run fetch_row or connecT or
ListDBs as in your old programs. These, of course, will continue to
work.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
mSQL is a database server and an \s-1API\s0 library written by David
Hughes. To use the adaptor you definitely have to install these first.
.PP
MySQL is a libmysqlclient.a library written by Michael Widenius
This was originally inspired by MySQL.
.SH "COMPATIBILITY NOTES"
.IX Header "COMPATIBILITY NOTES"
M(y)sql used to be a separate module written in C. This is no longer
the case, instead the old modules are emulated by their corresponding
\&\s-1DBI\s0 drivers. I did my best to remove any incompatibilities, but the
following problems are known to remain:
.IP "Static methods" 4
.IX Item "Static methods"
For whatever reason, mSQL implements some functions independent from
the respective database connection that really depend on it. This
made it possible to implement
.Sp
.Vb 1
\&    Msql->errmsg
.Ve
.Sp
or
.Sp
.Vb 1
\&    Msql->getserverinfo
.Ve
.Sp
as static methods. This is no longer the case, it never was for
MysqlPerl. Instead you have to use
.Sp
.Vb 1
\&    $dbh->errmsg
.Ve
.Sp
or
.Sp
.Vb 1
\&    $dbh->getserverinfo
.Ve
.IP "$M(Y)SQL::QUIET" 4
.IX Item "$M(Y)SQL::QUIET"
This variable used to turn off the printing of error messages. Unfortunately
\&\s-1DBI\s0 uses a completely different mechanism for that: The \f(CW\*(C`PrintError\*(C'\fR
attribute of the database and/or statement handles. We try to emulate
the old behaviour by setting the \f(CW\*(C`PrintError\*(C'\fR attribute to the current
value of $M(Y)SQL::QUIET when a handle is created, that is when
M(y)sql\->connect or \f(CW$dbh\fR\->\fIquery()\fR are called.
.Sp
You can overwrite this by using something like
.Sp
.Vb 1
\&    $dbh->{'dbh'}->{'PrintError'} = 1;
.Ve
.Sp
or
.Sp
.Vb 1
\&    $sth->{'PrintError'} = 0;
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Andreas Koenig \f(CW\*(C`koenig@franz.ww.TU\-Berlin.DE\*(C'\fR wrote the original
MsqlPerl. Jochen Wiedmann \f(CW\*(C`joe@ispsoft.de\*(C'\fR wrote the M(y)sqlPerl
emulation using \s-1DBI\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Alligator Descartes wrote a database driver for Tim Bunce's \s-1DBI\s0. I
recommend anybody to carefully watch the development of this module
(\f(CW\*(C`DBD::mSQL\*(C'\fR). Msql is a simple, stable, and fast module, and it will
be supported for a long time. But it's a dead end. I expect in the
medium term, that the \s-1DBI\s0 efforts result in a richer module family
with better support and more functionality. Alligator maintains an
interesting page on the \s-1DBI\s0 development:
.PP
.Vb 1
\&    http://www.symbolstone.org/technology/perl/DBI
.Ve