File: README

package info (click to toggle)
msql-mysql-modules 1.2005-1
  • links: PTS
  • area: contrib
  • in suites: slink
  • size: 744 kB
  • ctags: 412
  • sloc: perl: 4,402; ansic: 1,753; makefile: 73
file content (281 lines) | stat: -rw-r--r-- 9,103 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
The code in this package is

Copyright (c) 1997 Jochen Wiedmann <joe@ispsoft.de>

some older parts, in particular the Msql::Statement and Mysql::Statement
modules are

Copyright (c) 1994-1997 Andreas K�nig <a.koenig@mind.de>

and may be used, copied and redistributed under the same terms as perl
(see the files README, Copying and Artistic in the perl distribution).


*EXPERIMENTAL SOFTWARE*
-----------------------

This package contains experimental software and should *not* be used
in a production environment. We are following the Linux convention and
treat the "even" releases (1.18xx as of this writing, perhaps 1.20xx,
1.22xx, ... in the future) as stable. Only bug or portability fixes
will go into these releases.

The "odd" releases (1.19xx as of this writing, perhaps 1.21xx, 1.23xx
in the future) will be used for testing new features or other serious
code changes.


Where to get it
---------------

The easiest way to find this package is within the CPAN. Go to your
next CPAN host into the directory modules/01modules.index.html and you
should find it in there. If you don't know what CPAN is, learn about
it at http://www.perl.com/CPAN/.


Prerequisites
-------------

mSQL is a database server and an API library written by David Hughes
<bambi@Hughes.com.au>. You get that library and the database engine
from

    http://Hughes.com.au

Please follow the links there.


    ###########################################################
    ###########################################################
    ##  						     ##
    ##          Both mSQL-1 and mSQL-2 are supported         ##
    ##            with both Msql.pm and DBD::mSQL.           ##
    ##  						     ##
    ###########################################################
    ###########################################################

MySQL is another database server and another API library written by
Michael 'Monty' Widenius. It was inspired by mSQL, but is not based
on it. You find it on

    http://www.mysql.com

binary versions as well as source versions.

To use the perl modules you definitely have to install the respective
database and the library first. From the perl side perl5.004 is required.


Installation
------------

See the INSTALL document.


What is in this package
-----------------------

M(y)sql.pm and DBD::mSQL(mysql) implement two different approaches to
communicate with an mSQL or mysql server. DBD::mSQL(mysql) is built
upon the DBI, the generic Perl Database Interface. It brings you an
identical interface to a broad variety of databases and is in this
regard comparable to ODBC. The advantage of the DBI approach is
portability and interoperability. M(y)sql.pm are the elder species.
They were written before DBI was available but inspired by an early
draft of the DBI specification. As they have been circulating longer
they are more mature and pretty stable. They're also more complete
than DBD::mSQL and DBD::mysql.

As of Msql-Mysql-modules 1.1815, we consider DBD::mSQL and DBD::mysql
superior over MsqlPerl and MysqlPerl: They are sufficiently stable
(there�s only one known problem in DBI itself and it's announced to
be fixed in DBI 0.91) and definitely faster. Anyways, you have to decide
on your own about the trade-offs.


What you achieve with Msql.pm and Mysql.pm
------------------------------------------

Msql.pm and Mysql.pm are an interface between the perl programming
language and the mSQL or mysql programming API that come with the
mSQL any mysql relational database management systems. All functions
provided by the respective programming API's are supported.

From perl you activate the interface with the statement

    use Msql;

	or

    use Mysql;

After that you can connect to multiple msql or mysql database servers
and send multiple queries to any of them via a simple object oriented
interface. Two types of objects are available: database handles and
statement handles. Perl returns a database handle to the Connect
method like so:

    $dbh = Msql->connect($hostname,$databasename);

	or

    $dbh = Mysql->connect($hostname,$databasename);

Once you have connected to a database, you get a statement handle
with:

    $sth = $dbh->query("select foo from bar");

You can open as many queries as you like simultaneously by selecting a
different scalar to hold the object:

    $another_sth = $dbh->query("select bar from foo");

The statement handle allows you to step through the virtual table
returned from the database with the FetchRow method:

    @row = $sth->fetchrow;
or
    %hash = $sth->fetchhash;

You can access all metadata that mSQL and mysql supply for a given
table. To find out the number of rows or the number of fields returned
by a query you simply say:

    $numrows = $sth->numrows;
    $numfields = $sth->numfields;

To find out the size in bytes for the field with the offset 0 (the
first field of a query), you say:

    $length = $sth->length->[0];

The list of the names for each column is returned by

    @list => $sth->name;

As for other metadata available, consult the manpages that come with
MsqlPerl and Mysqlperl and study the examples in the file t/akmisc.t,
which is the extensive testscript to test your installation, but is
heavily commented, so you may use it as a tutorial.


Installing The Adaptor
----------------------

Unpack in any directory anywhere on your filesystem and run

    perl Makefile.PL
    make
    make test

The latter will give you some instructions if msqld or mysqld are not
running or if a database "test" is not available. Rest assured, that
no existing data in this database will be overwritten.

If the tests finish with `ok', give it a try to

    make install

If anything fails, check the documentation of the ExtUtils::MakeMaker
module. Especially if you're facing problems with dynamic loading, set
the environment variable PERL_DL_DEBUG to some value greater 0 to get
some more information from the DynaLoader.


Documentation
-------------

Documentation is available in pod format within the files Msql.pm and
Mysql.pm. During installation this should be turned into a manpage. Try
'man Msql' or 'man Mysql', and if this doesn't work on your system, try
'perldoc Msql' or 'perldoc Mysql'.

The tutorial that may be helpful for you is in the file t/akmisc.t.
This file is the test program for this package and illustrates all basic
operations that are available.


pmsql, pmysql and dbimon
------------------------

This package comes with some small standalone programs, pmsql, pmysql
and dbimon, being used with Msql, Mysql and the DBI drivers, respectively.
They are lightweight shells for your interactive communication needs
with your mSQL or mysql server(s). Try 'man pmsql', 'man pmysql' or
'man dbimon' to get at the documentation embedded in the program. If that
doesn't work, try 'perldoc pmsql' or 'perldoc pmysql'.

The programs are similar to both the msql (mysql) monitor and the relshow
(mysqlshow) program. The main advantage over those is that if you
have Term::ReadKey and Term::ReadLine::Perl installed on your system,
you have access to a readline clone, entirely written in perl with
command line editor, a basic completion and history, and you get the
output of any select query piped into your favorite pager program.


Mailing lists
-------------

Several mailing lists are devoted to the support of this package or
parts of it. 

  - The most preferable is

      msql-mysql-modules@tcx.se

    (This is the only one where the current maintainer is listening.)
    It's an open list, for subscribing just send a mail with the
    words

	subscribe msql-mysql-modules

		or

	subscribe msql-mysql-modules-digest

    to mdomo@tcx.se. (The latter will guarantee that you receive only
    one email per day.) A mailing list archive is in preparation.

  - MsqlPerl- and MysqlPerl related topics are best sent to

      msqlperl@franz.ww.tu-berlin.de.

    Note that this mailing list really is for MsqlPerl and MysqlPerl
    only and not for DBI specific topics, besides perhaps installation
    of the Msql-Mysql-modules. An archive of this list is available
    at

      http://franz.ww.tu-berlin.de/msqlperl

    Please search this archive first before posting a new question.
    The mailing list is open: You can post questions without being
    subscribed. If you want to subscribe, send a mail with the word
    "subscribe" in the first line of the body to

      msqlperl-request@franz.ww.tu-berlin.de

    This list is leaving out, as the machine franz.ww.tu-berlin.de
    will be switched off in the near future.

  - DBI users will prefer the DBI related mailing lists

     dbi-users@fugue.com
     dbi-announce@fugue.com

   these are closed mailing lists: You must subscribe before posting
   here. You can subscribe at

     http://www.fugue.com/dbi

   where you also find archives of these mailing lists.

Announcements of new versions of major importance will usually be made
on comp.lang.perl.announce. Smaller updates will be announced on the
mailing lists.



Andreas K�nig <koenig@kulturbox.de>
Jochen Wiedmann <joe@ispsoft.de>