NAME
DBIx::YAWM - (Yet Annother Wrapper Module) Provides a simplified interface to DBI
This module provides annother layer of abstraction for talking to databases via DBI. YAWM.pm can theoretically talk to any database which has a DBD:: driver, however it's only been tested against MySQL, Sybase and Oracle. This module provides support for querying and inserting records (but not updating yet).
I guess the value of this module is that it provides a central place where all the SELECT's and INSERT's in your code occur, leaving only the SQL to keep track of in your main program. This handier than you would think.
To Do:
write test scripts
New (constructor)
Notes
This is the object contructor. Upon object creation, this will connect to the specified database. So if you want to connect to more than one database, you would use more than one object. Be sure to use Destroy on the object to disconnect from the datbaase. In all other methods, if the method failes, an error is written to $Object->{errstr}, but becuase we don't have an object if this method fails, we write the error to $DBIx::YAWM:errstr.
Synopsis
$Object = DBIx::YAWM::new([options]) || die $DBIx::YAWM::errstr, "\n";Required Options
- DBType
-
This is the type of database you are connecting to. Specifically, this is the name of the DBD driver for that database. For example "Oracle" for DBD::Oracle, and "Sybase" for DBD::Sybase.
- Server
-
This is the name of the database you are trying to connect to. What this is exactly is slightly dependant on the DBType. For instance, Oracle expects the hostname of the server containing the database. However, Sybase uses an interfaces file which handles hostname resolution, so Sybase expects the alias from the interfaces file here.
- User
-
This is the username to connect to the target database
- Pass
-
This is the password associated with User
- SID
-
This is only required when connecting to DBType=>"Oracle". This is the oracle SID, or the name of the database.
Additional Options
- Debug
-
Setting this option to a nonzero value causes debug messages to be printed
Query
Notes
This method handles querying the database. Data is returned as a reference to an array of anonymous hashes. Each nested hash represents a record returned from the query, and contains field value pairs for each selected field. So it looks like this:
\@data = (
{ 'field' => $value, 'field2' => $value2, etc ... },
{ 'field' => $value, 'field2' => $value2, etc ... }
);Upon failure, the undef value is returned, and an error is written to $Object->{errstr}
Synopsis
$data = $Object->Query([options]) || die $Object->{errstr}, "\n";Required Options
- Select
-
This is an array refrence to a list of field names to select. You may find it convinient to buid the array reference inline with the function call like this: Select => ["field1", "field2", "field3"]
- From
-
The name of the table, view or object to select from.
Additional Options
- Where
-
The 'where clause' of your SQL query.
Insert
Notes
Insert a record into the given table of the database
Synopsis
$Object->Insert([options]) || die $Object->{errstr}, "\n";Required Options
- Into
-
The name of the table or view to insert data into
- Insert
-
The data you wish to insert. This should be a hash reference containing field/value pairs. You may find that it is helpfull to build the hash reference inline with the function call like so:
Insert => { 'field1' => $value1, 'field2' => $value2 } - NoQuote
-
This is an ugly hack. Some databases have funny rules about quoting certain values (such as integers). By default, YAWM quotes all values with the quote charachter defined by the DBD driver for the database. You can specify a hash reference here, each key in the hash is a field name, the value for the key is ignored. If a field is defined in the hash reference, it's value won't be quoted in the SQL, here's an example:
$obj->Insert( Into => "Stuff", Insert => { 'integer' => 23, 'string' => "the integer won't be quoted" }, NoQuote => { 'integer' => 1 } );
like I said it's an ugly hack. What would be better of course, would be to pull a table description first, and then to match the datatype, and quoting rules. I'd bet that the DBD drivers may do something like this already ... but this a "Yet Annother *" module and in keeping in with that spirit ... ;-)
Login
This logs into the database. This method is called internally by the DBTools::New method. This is not intended for public use.
Do
Synopsis
Prepare and execute an arbitrary SQL statement. Return undef if error, else return whatever comes back from dbi->execute.
Options
- SQL
-
the SQL statement to be prepared and executed
Update
head2 Synopsis
changes data in a preexisting record
$Object->Update([options]) || die $Object->{errstr}, "\n";
Options
- Table
-
name of table which contains record(s) matching 'Where' to update with 'Fields'
- Where
-
where clause that identifies which record(s) to update in 'Table'
- Fields
-
a hash reference containing data to be changed in the matching record(s). Each key is a field name each value is the data for the corresponding key.
Author:
Andrew N. Hicox <ahicox@hicox.com>
http://www.hicox.com