.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SQL::Eval 3"
.TH SQL::Eval 3 "2016-04-11" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SQL::Eval \- Base for deriving evaluation objects for SQL::Statement
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    require SQL::Statement;
\&    require SQL::Eval;
\&
\&    # Create an SQL statement; use a concrete subclass of
\&    # SQL::Statement
\&    my $stmt = MyStatement\->new("SELECT * FROM foo, bar",
\&                                SQL::Parser\->new(\*(AqAnsi\*(Aq));
\&
\&    # Get an eval object by calling open_tables; this
\&    # will call MyStatement::open_table
\&    my $eval = $stmt\->open_tables($data);
\&
\&    # Set parameter 0 to \*(AqVan Gogh\*(Aq
\&    $eval\->param(0, \*(AqVan Gogh\*(Aq);
\&    # Get parameter 2
\&    my $param = $eval\->param(2);
\&
\&    # Get the SQL::Eval::Table object referring the \*(Aqfoo\*(Aq table
\&    my $fooTable = $eval\->table(\*(Aqfoo\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements two classes that can be used for deriving
subclasses to evaluate SQL::Statement objects. The SQL::Eval object
can be thought as an abstract state engine for executing \s-1SQL\s0 queries
and the SQL::Eval::Table object is a table abstraction. It implements
methods for fetching or storing rows, retrieving column names and
numbers and so on.  See the \f(CW\*(C`test.pl\*(C'\fR script as an example for
implementing a subclass.
.PP
While reading on, keep in mind that these are abstract classes,
you *must* implement at least some of the methods described below.
In addition, you need not derive from SQL::Eval or SQL::Eval::Table,
you just need to implement the method interface.
.PP
All methods throw a Perl exception in case of errors.
.SS "Method interface of SQL::Eval"
.IX Subsection "Method interface of SQL::Eval"
.IP "new" 8
.IX Item "new"
Constructor; use it like this:
.Sp
.Vb 1
\&    $eval = SQL::Eval\->new(\e%attr);
.Ve
.Sp
Blesses the hash ref \e%attr into the SQL::Eval class (or a subclass).
.IP "param" 8
.IX Item "param"
Used for getting or setting input parameters, as in the \s-1SQL\s0 query
.Sp
.Vb 1
\&    INSERT INTO foo VALUES (?, ?);
.Ve
.Sp
Example:
.Sp
.Vb 2
\&    $eval\->param(0, $val);        # Set parameter 0
\&    $eval\->param(0);              # Get parameter 0
.Ve
.IP "params" 8
.IX Item "params"
Used for getting or setting the complete array of input
parameters. Example:
.Sp
.Vb 2
\&    $eval\->params($params);       # Set the array
\&    $eval\->params();              # Get the array
.Ve
.IP "table" 8
.IX Item "table"
Returns or sets a table object. Example:
.Sp
.Vb 2
\&    $eval\->table(\*(Aqfoo\*(Aq, $fooTable);  # Set the \*(Aqfoo\*(Aq table object
\&    $eval\->table(\*(Aqfoo\*(Aq);             # Return the \*(Aqfoo\*(Aq table object
.Ve
.IP "column" 8
.IX Item "column"
Return the value of a column with a given name; example:
.Sp
.Vb 3
\&    $col = $eval\->column(\*(Aqfoo\*(Aq, \*(Aqid\*(Aq);  # Return the \*(Aqid\*(Aq column of
\&                                        # the current row in the
\&                                        # \*(Aqfoo\*(Aq table
.Ve
.Sp
This is equivalent to and a shorthand for
.Sp
.Vb 1
\&    $col = $eval\->table(\*(Aqfoo\*(Aq)\->column(\*(Aqid\*(Aq);
.Ve
.IP "_gen_access_fastpath" 8
.IX Item "_gen_access_fastpath"
Return a subroutine reference for fast accessing columns for read-only
access. This routine simply returns the \f(CW\*(C`_gen_access_fastpath\*(C'\fR of the
referenced table.
.SS "Method interface of SQL::Eval::Table"
.IX Subsection "Method interface of SQL::Eval::Table"
.IP "new" 8
.IX Item "new"
Constructor; use it like this:
.Sp
.Vb 1
\&    $eval = SQL::Eval::Table\->new(\e%attr);
.Ve
.Sp
Blesses the hash ref \e%attr into the SQL::Eval::Table class (or a
subclass).
.Sp
The following attributes are used by \f(CW\*(C`SQL::Eval::Table\*(C'\fR:
.RS 8
.IP "col_names" 12
.IX Item "col_names"
Array reference containing the names of the columns in order they appear
in the table. This attribute \fBmust\fR be provided by the derived class.
.IP "col_nums" 12
.IX Item "col_nums"
Hash reference containing the column names as keys and the column
indexes as values. If this is omitted (does not exist), it will be
created from \f(CW\*(C`col_names\*(C'\fR.
.IP "capabilities" 12
.IX Item "capabilities"
Hash reference containing additional capabilities.
.IP "_gen_access_fastpath" 12
.IX Item "_gen_access_fastpath"
Return a subroutine reference for fast accessing columns for read-only
access. When the instantiated object doesn't provide own methods for
\&\f(CW\*(C`column\*(C'\fR and \f(CW\*(C`column_num\*(C'\fR a subroutine reference is returned which
directly access the internal data structures. For all other cases a
subroutine directly calling \f(CW\*(C`$self\->column($_[0])\*(C'\fR is returned.
.RE
.RS 8
.RE
.IP "row" 8
.IX Item "row"
Used to get the current row as an array ref. Do not confuse
getting the current row with the fetch_row method! In fact this
method is valid only after a successful \f(CW\*(C`$table\->fetchrow()\*(C'\fR.
Example:
.Sp
.Vb 1
\&    $row = $table\->row();
.Ve
.IP "column" 8
.IX Item "column"
Get the column with a given name in the current row. Valid only after
a successful \f(CW\*(C`$table\->fetchrow()\*(C'\fR. Example:
.Sp
.Vb 1
\&    $col = $table\->column($colName);
.Ve
.IP "column_num" 8
.IX Item "column_num"
Return the number of the given column name. Column numbers start with
0. Returns undef, if a column name is not defined, so that you can use
this for verifying column names. Example:
.Sp
.Vb 1
\&    $colNum = $table\->column_num($colNum);
.Ve
.IP "col_nums" 8
.IX Item "col_nums"
Returns an hash ref of column names with the column names as keys and
the column indexes as the values.
.IP "col_names" 8
.IX Item "col_names"
Returns an array ref of column names ordered by their index within the table.
.IP "capability" 8
.IX Item "capability"
Returns a boolean value whether the table has the specified capability
or not. This method might be overridden by derived classes, but ensure
that in that case the parent capability method is called when the
derived class does not handle the requested capability.
.Sp
The following capabilities are used (and requested) by SQL::Statement:
.RS 8
.IP "update_one_row" 12
.IX Item "update_one_row"
Defines whether the table is able to update one single row. This
capability is used for backward compatibility and might have
(depending on table implementation) several limitations. Please
carefully study the documentation of the table or ask the author of
the table, if this information is not provided.
.Sp
This capability is evaluated automatically on first request and must
not be handled by any derived classes.
.IP "update_specific_row" 12
.IX Item "update_specific_row"
Defines if the table is able to update one single row, but keeps the
original content of the row to update.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "update_current_row" 12
.IX Item "update_current_row"
Defines if the table is able to update the currently touched row. This
capability requires the capability of \f(CW\*(C`inplace_update\*(C'\fR.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "rowwise_update" 12
.IX Item "rowwise_update"
Defines if the table is able to do row-wise updates which means one
of \f(CW\*(C`update_one_row\*(C'\fR, \f(CW\*(C`update_specific_row\*(C'\fR or \f(CW\*(C`update_current_row\*(C'\fR.
The \f(CW\*(C`update_current_row\*(C'\fR is only evaluated if the table has the
\&\f(CW\*(C`inplace_update\*(C'\fR capability.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "inplace_update" 12
.IX Item "inplace_update"
Defines if an update of a row has side effects (capability is not
available) or can be done without harming any other currently running
task on the table.
.Sp
Example: The table storage is using a hash on the \f(CW\*(C`PRIMARY KEY\*(C'\fR of
the table. Real perl hashes do not care when an item is updated while
the hash is traversed using \f(CW\*(C`each\*(C'\fR. \f(CW\*(C`SDBM_File\*(C'\fR 1.06 has a bug,
which does not adjust the traversal pointer when an item is deleted.
.Sp
\&\f(CW\*(C`SQL::Statement::RAM::Table\*(C'\fR recognizes such situations and adjusts
the traversal pointer.
.Sp
This might not be possible for all implementations which can update
single rows.
.Sp
This capability could be provided by a derived class only.
.IP "delete_one_row" 12
.IX Item "delete_one_row"
Defines whether the table can delete one single row by it's content or
not.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "delete_current_row" 12
.IX Item "delete_current_row"
Defines whether a table can delete the current traversed row or
not. This capability requires the \f(CW\*(C`inplace_delete\*(C'\fR capability.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "rowwise_delete" 12
.IX Item "rowwise_delete"
Defines if any row-wise delete operation is provided by the
table. \f(CW\*(C`row\-wise\*(C'\fR delete capabilities are \f(CW\*(C`delete_one_row\*(C'\fR and
\&\f(CW\*(C`delete_current_row\*(C'\fR.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.IP "inplace_delete" 12
.IX Item "inplace_delete"
Defines if the deletion of a row has side effects (capability is not
available) or can be done without harming any other currently running
task on the table.
.Sp
This capability should be provided by a derived class only.
.IP "insert_new_row" 12
.IX Item "insert_new_row"
Defines if a table can easily insert a new row without need to seek
or truncate. This capability is provided by defining the table class
method \f(CW\*(C`insert_new_row\*(C'\fR.
.Sp
This capability is evaluated automatically on first request and must not
be handled by derived classes.
.RE
.RS 8
.Sp
If the capabilities \fIrowwise_update\fR and \fIinsert_new_row\fR are
provided, the table primitive \f(CW\*(C`push_row\*(C'\fR is not required anymore and
may be omitted.
.RE
.PP
The above methods are implemented by SQL::Eval::Table. The following
methods are not, so that they *must* be implemented by the
subclass. See the \f(CW\*(C`DBD::DBM::Table\*(C'\fR or \f(CW\*(C`DBD::CSV::Table\*(C'\fR for
example.
.IP "drop" 8
.IX Item "drop"
Drops the table. All resources allocated by the table must be released
after \f(CW\*(C`$table\-\*(C'\fRdrop($data)>.
.IP "fetch_row" 8
.IX Item "fetch_row"
Fetches the next row from the table. Returns \f(CW\*(C`undef\*(C'\fR, if the last
row was already fetched. The argument \f(CW$data\fR is for private use of
the subclass. Example:
.Sp
.Vb 1
\&    $row = $table\->fetch_row($data);
.Ve
.Sp
Note, that you may use
.Sp
.Vb 1
\&    $row = $table\->row();
.Ve
.Sp
for retrieving the same row again, until the next call of \f(CW\*(C`fetch_row\*(C'\fR.
.Sp
\&\f(CW\*(C`SQL::Statement\*(C'\fR requires that the last fetched row is available again
and again via \f(CW\*(C`$table\-\*(C'\fR\fIrow()\fR>.
.IP "push_row" 8
.IX Item "push_row"
As fetch_row except for storing rows. Example:
.Sp
.Vb 1
\&    $table\->push_row($data, $row);
.Ve
.IP "push_names" 8
.IX Item "push_names"
Used by the \fI\s-1CREATE TABLE\s0\fR statement to set the column names of the
new table. Receives an array ref of names. Example:
.Sp
.Vb 1
\&    $table\->push_names($data, $names);
.Ve
.IP "seek" 8
.IX Item "seek"
Similar to the seek method of a filehandle; used for setting the number
of the next row being written. Example:
.Sp
.Vb 1
\&    $table\->seek($data, $whence, $rowNum);
.Ve
.Sp
Actually the current implementation only uses \f(CW\*(C`seek($data, 0, 0)\*(C'\fR
(first row) and \f(CW\*(C`seek($data, 2, 0)\*(C'\fR (beyond last row, end of file).
.IP "truncate" 8
.IX Item "truncate"
Truncates a table after the current row. Example:
.Sp
.Vb 1
\&    $table\->truncate($data);
.Ve
.SH "INTERNALS"
.IX Header "INTERNALS"
The current implementation is quite simple: An SQL::Eval object is an
hash ref with only two attributes. The \f(CW\*(C`params\*(C'\fR attribute is an array
ref of parameters. The \f(CW\*(C`tables\*(C'\fR attribute is an hash ref of table
names (keys) and table objects (values).
.PP
SQL::Eval::Table instances are implemented as hash refs. Attributes
used are \f(CW\*(C`row\*(C'\fR (the array ref of the current row), \f(CW\*(C`col_nums\*(C'\fR (an
hash ref of column names as keys and column numbers as values) and
\&\f(CW\*(C`col_names\*(C'\fR, an array ref of column names with the column numbers as
indexes.
.SH "MULTITHREADING"
.IX Header "MULTITHREADING"
All methods are working with instance-local data only, thus the module
is reentrant and thread safe, if you either don't share handles between
threads or grant serialized use.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to \f(CW\*(C`bug\-sql\-statement at
rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL\-Statement>.  I
will be notified, and then you will automatically be notified of
progress on your bug as I make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 2
\&    perldoc SQL::Eval
\&    perldoc SQL::Statement
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL\-Statement>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/SQL\-Statement>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/s/SQL\-Statement>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/SQL\-Statement/>
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
Written by Jochen Wiedmann and currently maintained by Jens Rehsack.
.PP
This module is Copyright (C) 1998 by
.PP
.Vb 4
\&    Jochen Wiedmann
\&    Am Eisteich 9
\&    72555 Metzingen
\&    Germany
\&
\&    Email: joe@ispsoft.de
\&    Phone: +49 7123 14887
.Ve
.PP
and Copyright (C) 2009, 2016 by
.PP
.Vb 1
\&     Jens Rehsack < rehsackATcpan.org>
.Ve
.PP
All rights reserved.
.PP
You may distribute this module under the terms of either the \s-1GNU\s0
General Public License or the Artistic License, as specified in
the Perl \s-1README\s0 file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISQL::Statement\fR\|(3)