.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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.  \*(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-
.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 "RoPkg::DBObject 3pm"
.TH RoPkg::DBObject 3pm "2006-06-09" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
.Vb 1
\& RoPkg::DBObject \- General pourpose database object.
.Ve
.SH "VERSION"
.IX Header "VERSION"
0.1.4
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class can be used as a base class for objects who
holds all their information in a database. The class
provides the base methods to add/delete/update/select the
object to/from a database. 
.PP
RoPkg::DBObject inherits RoPkg::Object .
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package RoPkg::Person;
.Ve
.PP
.Vb 2
\& use strict;
\& use warnings;
.Ve
.PP
.Vb 2
\& use RoPkg::DBObject;
\& use RoPkg::Exceptions;
.Ve
.PP
.Vb 1
\& use vars qw($VERSION @ISA);
.Ve
.PP
.Vb 1
\& @ISA=qw(RoPkg::DBObject);
.Ve
.PP
.Vb 5
\& my $methods = {
\&   id => '\-',
\&   Name => '\-',
\&   Addr => '\-',
\& };
.Ve
.PP
.Vb 3
\& sub new {
\&   my ($class, %opt) = @_;
\&   my $self;
.Ve
.PP
.Vb 2
\&   $opt{methods} = $methods;
\&   $self = $class\->SUPER::new(%opt);
.Ve
.PP
.Vb 2
\&   return $self;
\& }
.Ve
.PP
.Vb 2
\& sub AddToDB {
\&   my ($self) = @_;
.Ve
.PP
.Vb 2
\&   OutsideClass\->throw('Called from outside class')
\&     if ( !$self or ref($self) ne $CLASS);
.Ve
.PP
.Vb 2
\&   return $self\->SQL_Insert();
\& }
.Ve
.PP
.Vb 1
\& 1;
.Ve
.PP
.Vb 1
\& tester.pl
.Ve
.PP
.Vb 2
\& use warnings;
\& use strict;
.Ve
.PP
.Vb 2
\& use RoPkg::Person;
\& use RoPkg::DB;
.Ve
.PP
.Vb 2
\& sub main {
\&   my ($p, $db);
.Ve
.PP
.Vb 3
\&   $db = new RoPkg::DB();
\&   $db\->add('dsn...', 'user', 'pass', 'dbc');
\&   $p = new RoPkg::Person(dbo => $db, dbo_method => 'db_dbc');
.Ve
.PP
.Vb 5
\&   $p\->id(1);
\&   $p\->Name('John Doe');
\&   $p\->Addr('home');
\&   $p\->AddToDB();
\& }
.Ve
.PP
.Vb 1
\& main();
.Ve
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.Sh "new($hashref)"
.IX Subsection "new($hashref)"
Constructor of the class. At this moment \fInew()\fR accepts 3 parameters:
.IP "*) dbo" 3
.IX Item "*) dbo"
.PD 0
.IP "*) dbo_method" 3
.IX Item "*) dbo_method"
.IP "*) quote_char" 3
.IX Item "*) quote_char"
.PD
.PP
\&\fBdbo\fR and \fBdbo_method\fR \fBmust\fR be given to the constructor.
\&\fBquote_char\fR is optional. \fIdbo\fR is the database object (a 
instance of RoPkg::DB)and \fIdbo_method\fR dbo_method is the 
name of the method used to have access to the database handle.
\&\fBquote_char\fR is the char used internally by \s-1DBI\s0 to quote
the table names, field names and so on. Default, the quote_char
is empty (no quotation). If you are using PostgreSQL and
you have upcase chars in table and fields names use
quote_char => q{"} .
.PP
Exceptions:
.PP
RoPkg::DBObject uses the exceptions provided by RoPkg::Exceptions.
\&\fInew()\fR throws the following exceptions:
.IP "*) Param::Mising" 2
.IX Item "*) Param::Mising"
.PD 0
.IP "*) Param::Wrong" 2
.IX Item "*) Param::Wrong"
.PD
.PP
Param::Missing is raised when \fIdbo\fR or \fIdbo_method\fR parameters
have not been specified in the parameters list.
.PP
Param::Wrong is raised when \fIdbo\fR or \fIdbo_method\fR parameters
are not defined (or empty).
.Sh "dbo($dbo)"
.IX Subsection "dbo($dbo)"
get/set method. If \f(CW$dbo\fR is present (and defined), the internal
\&\f(CW$dbo\fR object will be replaced with the new one. If \f(CW$dbo\fR is not
present, the method acts as a get method, and will return the
database object. The method will raise OutsideClass exception
if is called outside the class instance.
.Sh "dbo_method($dbo_method)"
.IX Subsection "dbo_method($dbo_method)"
get/set method. If \f(CW$dbo_method\fR is present (and defined), the
internal \f(CW$dbo_method\fR value will be replaced with the one
specified by \f(CW$dbo_method\fR parameter. Otherwise, the get
behaviour will be selected, and the method will return
the current value of \f(CW$dbo_method\fR. The method will raise
OutsideClass exception if is called outside the class
instance.
.Sh "\fIdbh()\fP"
.IX Subsection "dbh()"
Returns the \s-1DBI\s0 object used by this object.
.SH "SQL METHODS"
.IX Header "SQL METHODS"
The following methods are responsable for all operations
involving the database. All methods use SQL::Abstract
to generate sql queries to ensure portability of the queries.
.PP
The data that will be added/deleted to the database, is taken
from the methods provided by \fI$methods\fR . 
.Sh "\fISQL_Insert()\fP"
.IX Subsection "SQL_Insert()"
add the current object to the database. Returns the value
of \s-1DBI\-\s0>execute.
.Sh "SQL_Update(@fields)"
.IX Subsection "SQL_Update(@fields)"
update the data from database. The fields array hold all the
field names who will uniquely identify the object in the
database (usually the id of the object).
.Sh "SQL_Delete(@fields)"
.IX Subsection "SQL_Delete(@fields)"
update the data from database. The fields array hold all the
field names who will uniquely identify the object in the
database (usually the id of the object).
.Sh "SQL_Select(@fields)"
.IX Subsection "SQL_Select(@fields)"
searches into the database for the object and initialize
the current object with the values found.  The fields array
hold all the field names who will uniquely identify the 
object in the database (usually the id of the object).
This method is special. It will look only at the first
record who meet the requirements (in sql '\s-1LIMIT\s0 1'). Also,
if no records are found DB::NoResults exception is raised.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
RoPkg::Object require perl 5.008 or later and the following modules:
.IP "SQL::Abstract" 3
.IX Item "SQL::Abstract"
.PD 0
.IP "RoPkg::Object" 3
.IX Item "RoPkg::Object"
.IP "RoPkg::Exceptions" 3
.IX Item "RoPkg::Exceptions"
.PD
.SH "PERL CRITIC"
.IX Header "PERL CRITIC"
The code is perl critic level 2 compliant and almost level 1 compliant
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
This module comes with his own tests. To run the tests unpack the source,
and use 'make test' command.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
This module does not use any configuration files or environment
variables. The dependencies however can use them. Please read
the man page of each dependency to be sure.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
Do not install this version on the same machine with Simba <= 0.7.1
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
None known to the author
.SH "AUTHOR"
.IX Header "AUTHOR"
Subredu Manuel <diablo@iasi.roedu.net>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (C) 2005 Subredu Manuel.  All Rights Reserved.
This module is free software; you can redistribute it 
and/or modify it under the same terms as Perl itself.
The \s-1LICENSE\s0 file contains the full text of the license.