.\" 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.  | 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 "WWWdb::DbSession 3"
.TH WWWdb::DbSession 3 "2003-04-15" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
WWWdb::DbSession \- DbSessions for WWWdb
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use WWWdb::DbSession;
.Ve
.PP
.Vb 7
\& $oDbSession     = DbSession->new($cDbDriver,
\&                                  $cDbName,
\&                                  $cUserName,
\&                                  $cPassword,
\&                                  [RaiseError => $],
\&                                  [PrintError => $],
\&                                  [AutoCommit => $]);
.Ve
.PP
.Vb 2
\& $oDbSession->SqlDo($cSQL_Statement,
\&                    [@lBindValues]);
.Ve
.PP
.Vb 2
\& $lResult = $oDbSession->SqlSelect($cSQL_Statement,
\&                                   [@lBindValues]);
.Ve
.PP
.Vb 1
\& $iMaxId = $oDbSessionGL->getMaxId($cNameOfIdField, $cTable);
.Ve
.PP
.Vb 3
\& $oDbSessionGL->TransactionLoop($iNrOfLoopsIfTransactionFails,
\&                                \e&pProcedureToCall,
\&                                [@lParamsForProcedure]);
.Ve
.PP
.Vb 4
\& $oDbSessionGL->TransactionLoop($iNrOfLoopsIfTransactionFails,
\&                                sub
\&                                {
\&                                   my $pDbHandle = shift;
.Ve
.PP
.Vb 4
\&                                   # db-actions
\&                                   ...
\&                                },
\&                                [@lParamsForProcedure]);
.Ve
.PP
.Vb 2
\& $oDbSessionGL->DateToDb(scalar(localtime()));
\& DbSession::Pg::DateToDb(undef, scalar(localtime()));
.Ve
.PP
.Vb 2
\& $oDbSessionGL->DateFromDb($cDateField);
\& DbSession::Pg::DateFromDb($cDateField);
.Ve
.PP
.Vb 2
\& $bAutoCommit = $oDbSession->getAutoCommit();
\& $oDbSession->setAutoCommit($bAutoCommit);
.Ve
.PP
.Vb 2
\& $bPrintError = $oDbSession->getPrintError();
\& $oDbSession->setPrintError($bPrintError);
.Ve
.PP
.Vb 2
\& $bRaiseError = $oDbSession->getRaiseError();
\& $oDbSession->setRaiseError($bRaiseError);
.Ve
.PP
.Vb 1
\& $cDataSource = $oDbSession->getDataSource();
.Ve
.PP
.Vb 1
\& $pDbHandle = $oDbSession->getDbHandle();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "The DbSession class"
.IX Header "The DbSession class"
Db-Session is another layer over the DBI\-Module. It gives some
easy-to-use functionality for db\-access.
.Sh "Note"
.IX Subsection "Note"
.RS 4
When a DbSession-object gets destroyed, the session will be
automatically finished.
.RE
.Sh "Class Methods"
.IX Subsection "Class Methods"
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 7
\& $oDbSession     = DbSession->new($cDatabaseType,
\&                                  $cDatabaseName,
\&                                  $cDatabaseUser,
\&                                  $cDatabasePassword,
\&                                  RaiseError       => $bRaiseError,
\&                                  PrintError       => $bPrintError,
\&                                  AutoCommit       => $bAutoCommit);
.Ve
.Sp
Create a new DbSession and connect to the database.
The following database-types are supported currently:
.Sp
.Vb 3
\& - PostgreSQL
\& - MySql
\& - Oracle
.Ve
.Sp
The attributes are passed to the internal DBI\-Object.
.IP "\fBError\fR" 4
.IX Item "Error"
.Vb 4
\& $oDbSession->Error($pHandle,
\&                    $cSQL_Statement,
\&                    $cBindValues,
\&                    $cDescription);
.Ve
.Sp
This function generates an error\-message, if a problem occured in the
last database statement. You will get the text and the number of the
database-error and the statement together with the data passed by
bind, which led to this error.
.Sp
Normally this method is only called internally.
.IP "\fBSqlDo\fR" 4
.IX Item "SqlDo"
.Vb 2
\& $oDbSession->SqlDo($cSQL_Statement,
\&                    [@lBindValues]);
.Ve
.Sp
SqlDo executes a non-select SQL-statement passed in \f(CW$cSQL_Statement\fR.
If you want to pass Parameters, then you can generate the statement by
example via sprintf, but you have to quote them by yourselve then.
.Sp
The second possibility (which is recommended and much easier)
is, to pass the parameters separately. The underlying \s-1DBI\s0
will care about quoting etc.
.Sp
Here are two examples which show the difference:
.Sp
.Vb 10
\& $oDbSession->SqlDo
\&     (sprintf("INSERT INTO customer
\&               (id_customer,
\&                name,
\&                last_change)
\&               VALUES
\&               (%d, '%s', '%s')",
\&              $iIdCustomer,
\&              $cCustomerName,
\&              $cLastChange));
.Ve
.Sp
Here you have to build your SQL-Statement by yourself and you
need to quote the fields correctly.
.Sp
.Vb 10
\& $oDbSession->SqlDo
\&     ("INSERT INTO customer
\&      (id_customer,
\&       name,
\&       last_change)
\&      VALUES
\&      (?, ?, ?)",
\&      $iIdCustomer,
\&      $cCustomerName,
\&      $cLastChange);
.Ve
.Sp
Here, you only have to pass the SQL-statement and the parameters
and ... thats it!
.Sp
If some database-error occurs, the procedure will throw a die-signal
with an error-message via the Error\-method.
.IP "\fBSqlSelect\fR" 4
.IX Item "SqlSelect"
.Vb 2
\& $lResult = $oDbSession->SqlSelect($cSQL_Statement,
\&                                   [@lBindValues]);
.Ve
.Sp
This statement is a special-form of the SqlDo\-statement. It prepares a
SELECT-statement passed in \f(CW$cSQL_Statement\fR, executes it and returns
the result in a array of arrays.
.Sp
To process the results the following loops may be helpful:
.Sp
.Vb 7
\& # loop through all records
\& foreach $pRecord (@$lResult)
\& {
\&    # loop through the fields
\&    foreach $cField (@$pRecord)
\&    {
\&       print "$cField, ";
.Ve
.Sp
.Vb 3
\&    }
\&    print "\en";
\& }
.Ve
.Sp
To access a value direcly you may use:
.Sp
.Vb 2
\& print "Second Record <@{$lResult->[1]}>\en";
\& print "Third Record, Second Field <$lResult->[2]->[1]>\en";
.Ve
.Sp
If some database-error occurs, the procedure will throw a die-signal
with an error-message via the Error\-method.
.IP "\fBTransactionLoop\fR" 4
.IX Item "TransactionLoop"
.Vb 3
\& $oDbSessionGL->TransactionLoop($iNrOfLoopsIfTransactionFails,
\&                                \e&pProcedureToCall,
\&                                [@lParamsForProcedure]);
.Ve
.Sp
or with a anonymous subroutine
.Sp
.Vb 4
\& $oDbSessionGL->TransactionLoop($iNrOfLoopsIfTransactionFails,
\&                                sub
\&                                {
\&                                   my $pDbHandle = shift;
.Ve
.Sp
.Vb 4
\&                                   # db-actions
\&                                   ...
\&                                },
\&                                [@lParamsForProcedure]);
.Ve
.Sp
This procedure disables (temporarily) the AutoComit
functionality. Then it runs the procedure given by
\&\e&pProcedureToCall. The first parameter for this procedure is a
pointer to the DbSession-object it belongs to. Then any other
parameters, defined by the user may follow.  If that procedure thows a
die or returns undef, the transaction is assumed to be failed. In this
case it will be returned up to \f(CW$iNrOfLoopsIfTransactionFails\fR times.
.Sp
If the db-error keeps happening, then this procedure throws a
die with the SQL\-errors.
.IP "\fBgetMaxId\fR" 4
.IX Item "getMaxId"
.Vb 1
\& $iMaxId = $oDbSessionGL->getMaxId($cNameOfIdField, $cTable);
.Ve
.Sp
Especially when you use databases, which do not support auto-increment
fields, or if you want to keep your portability, then this will help
you to generate id\e's for unique indexes in a simple way.
.Sp
Passing the name of the unique key-field in the variable
\&\f(CW$cNameOfIdField\fR and the database-table in \f(CW$cTable\fR, this procedure
selects the maximum value for this field, adds one and returns the
value.
.Sp
Please note that this is only a hack, because if two users use this
function at the same time, duplicate values may be generated. A better
way would be to have a own table for this index-fields and use them
like tickets in secure transactions.
.IP "\fB_Connect\fR" 4
.IX Item "_Connect"
This internal procedure creates a datasource-descriptor for the
database and connects to the database.
.Sp
This procedure is for internal use only.
.IP "\fB_Disconnect\fR" 4
.IX Item "_Disconnect"
This internal procedure commits all open transactions and disconnects
from the database.
.Sp
This procedure is for internal use only.
.IP "\fB[\s-1DATABASE\s0]::_CreateDataSource\fR" 4
.IX Item "[DATABASE]::_CreateDataSource"
This internal procedure generates the necessary DBI-datasource for
the specified database.
.Sp
This procedure is for internal use only.
.IP "\fB[\s-1DATABASE\s0]::DateToDb\fR" 4
.IX Item "[DATABASE]::DateToDb"
.Vb 1
\& $oDbSessionGL->DateToDb(scalar(localtime()));
.Ve
.Sp
or the specialized form for a database
.Sp
.Vb 1
\& DbSession::Pg::DateToDb(undef, scalar(localtime()));
.Ve
.Sp
Converts a date, given by the perl-localtime-function (b.e. Mon Mar 6
16:21:21 2000) to a date\-format, the database can understand.
.Sp
The following date-data-types are supported
.Sp
.Vb 7
\&         +------------+-----------+
\&         | Database   | Date-type |
\&         +------------+-----------+
\&         | PostgreSQL | datetime  |
\&         | Oracle     | timestamp |
\&         | MySql      | datetime  |
\&         +------------+-----------+
.Ve
.IP "\fB[\s-1DATABASE\s0]::DateFromDb\fR" 4
.IX Item "[DATABASE]::DateFromDb"
.Vb 1
\& $oDbSessionGL->DateFromDb($cDateField);
.Ve
.Sp
or the specialized form for a database
.Sp
.Vb 1
\& DbSession::Pg::DateFromDb($cDateField);
.Ve
.Sp
This function is the opposit to DateToDb. It converts a date-field
as delivered by the database to the same format,
the perl-localtime-function would give back.
.Sh "Class Attributes"
.IX Subsection "Class Attributes"
.IP "\fBAutoCommit\fR" 4
.IX Item "AutoCommit"
.Vb 2
\& $bAutoCommit = $oDbSession->getAutoCommit();
\& $oDbSession->setAutoCommit($bAutoCommit);
.Ve
.Sp
If a commit-statement should be issued automatically after
each SQL-statement then AutoCommit must be set to a true
value (which it is by default)
.IP "\fBPrintError\fR" 4
.IX Item "PrintError"
.Vb 2
\& $bPrintError = $oDbSession->getPrintError();
\& $oDbSession->setPrintError($bPrintError);
.Ve
.Sp
Reads or sets the DBI::PrintError flag.
.IP "\fBRaiseError\fR" 4
.IX Item "RaiseError"
.Vb 2
\& $bRaiseError = $oDbSession->getRaiseError();
\& $oDbSession->setRaiseError($bRaiseError);
.Ve
.Sp
Reads or sets the DBI::RaiseError flag.
.IP "\fBDataSource\fR" 4
.IX Item "DataSource"
.Vb 1
\& $cDataSource = $oDbSession->getDataSource();
.Ve
.Sp
Returns the name of the DBI::Datasource.
.IP "\fBDbHandle\fR" 4
.IX Item "DbHandle"
.Vb 1
\& $pDbHandle = $oDbSession->getDbHandle();
.Ve
.Sp
Returns the database-handle for the current connection.