.\" 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 "ESQL 3"
.TH ESQL 3 "2001-06-05" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
AxKit::XSP::ESQL \- An Extended SQL taglib for AxKit eXtensible Server Pages
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Add the esql: namespace to your \s-1XSP\s0 \f(CW\*(C`<xsp:page\*(C'\fR> tag:
.PP
.Vb 5
\&    <xsp:page
\&         language="Perl"
\&         xmlns:xsp="http://apache.org/xsp/core/v1"
\&         xmlns:esql="http://apache.org/xsp/SQL/v2"
\&    >
.Ve
.PP
And add this taglib to AxKit (via httpd.conf or .htaccess):
.PP
.Vb 1
\&    AxAddXSPTaglib AxKit::XSP::ESQL
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This tag library provides extensive support for executing \s-1SQL\s0 statements
from within \s-1XSP\s0. This tag library is the same as the Cocoon \s-1ESQL\s0 taglib.
.SH "TAG REFERENCE"
.IX Header "TAG REFERENCE"
Note that below we use the esql: prefix as a convention, however you can
use whatever prefix you like provided it is mapped to the appropriate
namespace.
.ie n .Sh """<esql:connection"">"
.el .Sh "\f(CW<esql:connection\fP>"
.IX Subsection "<esql:connection>"
.Vb 1
\&  parent: none
.Ve
.PP
This is the required 'wrapper' element that declares your connection.
.ie n .Sh """<esql:driver"">"
.el .Sh "\f(CW<esql:driver\fP>"
.IX Subsection "<esql:driver>"
.Vb 1
\&  parent: <esql:connection>
.Ve
.PP
The contents of this element define the \s-1DBI\s0 driver to be used. For
example, Pg, Sybase, Oracle.
.PP
You can also add an optional attribute: \fBtransactions='no'\fR to the
driver element, to indicate that this driver does not support
transactions (or just that you don't want to use transactions).
.ie n .Sh """<esql:dburl"">"
.el .Sh "\f(CW<esql:dburl\fP>"
.IX Subsection "<esql:dburl>"
.Vb 1
\&  parent: <esql:connection>
.Ve
.PP
The name of this tag is a hang-over from the Cocoon (Java) version. In
the AxKit version this is simply anything that goes after the driver in
the connection string. So for PostgreSQL you might have in here 
\&\f(CW\*(C`dbname=axkit\*(C'\fR, to connect to the \*(L"axkit\*(R" database. The full connect 
string is constructed as follows:
.PP
.Vb 1
\&  "dbi:$driver" . ($dburl ? ":$dburl" : "")
.Ve
.PP
See your \s-1DBD\s0 driver documentation for more details on what is valid for
the connection string.
.ie n .Sh """<esql:username"">"
.el .Sh "\f(CW<esql:username\fP>"
.IX Subsection "<esql:username>"
.Vb 1
\&  parent: <esql:connection>
.Ve
.PP
The username to connect to the database with.
.ie n .Sh """<esql:password"">"
.el .Sh "\f(CW<esql:password\fP>"
.IX Subsection "<esql:password>"
.Vb 1
\&  parent: <esql:connection>
.Ve
.PP
The password to use to connect to the database.
.ie n .Sh """<esql:execute\-query"">"
.el .Sh "\f(CW<esql:execute\-query\fP>"
.IX Subsection "<esql:execute-query>"
.Vb 1
\&  parent: <esql:connection>
.Ve
.PP
This tag is a 'wrapper' tag around queries. You may have as many queries
as you like within a single \f(CW\*(C`<esql:connection\*(C'\fR> tag.
.ie n .Sh """<esql:skip\-rows"">"
.el .Sh "\f(CW<esql:skip\-rows\fP>"
.IX Subsection "<esql:skip-rows>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The contents of this tag (which may be an <xsp:expr>) define a number of
rows to skip forward in the result set.
.ie n .Sh """<esql:max\-rows"">"
.el .Sh "\f(CW<esql:max\-rows\fP>"
.IX Subsection "<esql:max-rows>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The maximum number of rows to return.
.ie n .Sh """<esql:query"">"
.el .Sh "\f(CW<esql:query\fP>"
.IX Subsection "<esql:query>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The contents of this tag define the query to be executed.
.ie n .Sh """<esql:parameter"">"
.el .Sh "\f(CW<esql:parameter\fP>"
.IX Subsection "<esql:parameter>"
.Vb 1
\&  parent: <esql:query>
.Ve
.PP
This tag can be put in your \s-1SQL\s0 query everywhere you might put a ? in
your \s-1SQL\s0 in \s-1DBI\s0. \s-1ESQL\s0 is intelligent enough to create a cached statement
when you do this, and only execute your code when necessary. You
put an expression (or another taglib) within the parameter tag (see
the example below).
.ie n .Sh """<esql:results"">"
.el .Sh "\f(CW<esql:results\fP>"
.IX Subsection "<esql:results>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The contents of this tag are \*(L"executed\*(R" whenever the query returns some
results.
.ie n .Sh """<esql:row\-results"">"
.el .Sh "\f(CW<esql:row\-results\fP>"
.IX Subsection "<esql:row-results>"
.Vb 1
\&  parent: <esql:results>
.Ve
.PP
The contents of this tag are \*(L"executed\*(R" for each row of the results
.ie n .Sh """<esql:get\-columns"">"
.el .Sh "\f(CW<esql:get\-columns\fP>"
.IX Subsection "<esql:get-columns>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
This tag gets all of the columns in the current row, and outputs them
as \f(CW\*(C`<column_name\*(C'\fR>\f(CW\*(C`value</column_name\*(C'\fR>. If you specify an attribute
\&\f(CW\*(C`tag\-case="upper"\*(C'\fR, all columns are upper case. Alternatively, \*(L"lower\*(R"
gives you all tags in lower case. An ancestor attribute is also allowed,
see \*(L"Nested Results\*(R" below for more details.
.Sh "get\-*"
.IX Subsection "get-*"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
These are:
.PP
.Vb 8
\&  get-column
\&  get-string
\&  get-boolean
\&  get-double
\&  get-float
\&  get-int
\&  get-long
\&  get-short
.Ve
.PP
(and more below)
.PP
Each of these takes either an attribute column=\*(L"name\*(R", or a child tag,
\&\f(CW\*(C`<esql:column\*(C'\fR> which gives the column name. Alternatively either the
attribute or child element can be an integer (starting at 1) specifying
the column number.
.PP
Also allowed is an ancestor attribute, which is an integer (default 0),
which indicates how far up the nested results you go. See Nested Results
below.
.ie n .Sh """<esql:get\-date""\fP>, \f(CW""<esql:get\-time""\fP>, \f(CW""<esql:get\-timestamp"">"
.el .Sh "\f(CW<esql:get\-date\fP>, \f(CW<esql:get\-time\fP>, \f(CW<esql:get\-timestamp\fP>"
.IX Subsection "<esql:get-date>, <esql:get-time>, <esql:get-timestamp>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
These tags are the same as get\-* above, except they also take a 
\&\f(CW\*(C`format="..."\*(C'\fR attribute, which contains a strftime formatting string.
.ie n .Sh """<esql:get\-xml"">"
.el .Sh "\f(CW<esql:get\-xml\fP>"
.IX Subsection "<esql:get-xml>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
Again the same as get\-* above. This tag assumes the contents of the
column are valid \s-1XML\s0, and appends that \s-1XML\s0 into the result tree.
.ie n .Sh """<esql:get\-row\-position"">"
.el .Sh "\f(CW<esql:get\-row\-position\fP>"
.IX Subsection "<esql:get-row-position>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
Gets the current row number. Optional \f(CW\*(C`ancestor\*(C'\fR attribute.
.ie n .Sh """<esql:get\-column\-name"">"
.el .Sh "\f(CW<esql:get\-column\-name\fP>"
.IX Subsection "<esql:get-column-name>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
Gets the column name indicated by the numbered column in the 
\&\f(CW\*(C`column="..."\*(C'\fR attribute, or the child \f(CW\*(C`<esql:column\*(C'\fR> element. The
attribute/child can actually be a string (name), but then what is
the point of that?
.ie n .Sh """<esql:get\-column\-label"">"
.el .Sh "\f(CW<esql:get\-column\-label\fP>"
.IX Subsection "<esql:get-column-label>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
Gets the label of the column. This is a hang-over from the Cocoon java
implementation where sadly nobody seems to know what label is compared
with name. In this case, get-column-name is always lower case, whereas
get-column-label is returned in the case that the \s-1DBD\s0 driver returns it
as.
.ie n .Sh """<esql:get\-column\-type\-name"">"
.el .Sh "\f(CW<esql:get\-column\-type\-name\fP>"
.IX Subsection "<esql:get-column-type-name>"
.Vb 1
\&  parent: <esql:row-results>
.Ve
.PP
Returns the \s-1TYPE_NAME\s0 of the column indicated as other get\-* elements.
See the \s-1DBI\s0 docs for more details.
.ie n .Sh """<esql:no\-results"">"
.el .Sh "\f(CW<esql:no\-results\fP>"
.IX Subsection "<esql:no-results>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The contents of this element are executed when the \s-1SQL\s0 returned no rows.
.ie n .Sh """<esql:update\-results"">"
.el .Sh "\f(CW<esql:update\-results\fP>"
.IX Subsection "<esql:update-results>"
.Vb 1
\&  parent: <esql:execute-query>
.Ve
.PP
The contents of this element are executed when the \s-1SQL\s0 was an update
statement. The number of rows updated are in the \f(CW$rv\fR variable.
.SH "Nested Results"
.IX Header "Nested Results"
With the \s-1ESQL\s0 taglib it is quite possible to do nested results. This is
a way to emulate outer joins, or just better organise things. See below
for an example of this.
.PP
When using nested results, you can use the ancestor attribute on any of
the get\-* elements to get results from higher up the ancestry of results.
.SH "Errors"
.IX Header "Errors"
Unlike the original Cocoon version of this taglib, we let you handle
errors however you choose to, using the exception taglib. If an error
occurs, \s-1ESQL\s0 will throw an exception. If you don't capture this exception
it will propogate up to the core of AxKit, and either give a 500 internal
server error, or execute the AxErrorStylesheet if one is defined. See
AxKit.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 42
\&  <esql:connection>
\&  <esql:driver>Pg</esql:driver>
\&  <esql:dburl>dbname=axkit</esql:dburl>
\&  <esql:username>postgres</esql:username>
\&  <esql:password></esql:password>
\&  <esql:execute-query>
\&    <esql:query>
\&      select id,name from department_table where foo = 
\&      <esql:parameter><xsp:expr>4 + 5</xsp:expr></esql:parameter>
\&    </esql:query>
\&    <esql:results>
\&      <header>header info</header>
\&      <esql:row-results>
\&        <department>
\&          <id><esql:get-int column="id"/></id>
\&          <name><esql:get-string column="name"/></name>
\&          <esql:connection>
\&            <esql:driver>org.postgresql.Driver</esql:driver>
\&            <esql:dburl>jdbc:postgresql://localhost/test</esql:dburl>
\&            <esql:username>test</esql:username>
\&            <esql:password>test</esql:password>
\&            <esql:execute-query>
\&              <esql:query>select name from user_table where department_id = <esql:parameter type="int"><esql:get-int ancestor="1" column="id"/></esql:parameter></esql:query>
\&              <esql:results>
\&                <esql:row-results>
\&                  <user><esql:get-string column="name"/></user>
\&                </esql:row-results>
\&              </esql:results>
\&              <esql:no-results>
\&                <user>No employees</user>
\&              </esql:no-results>
\&            </esql:execute-query>
\&          </esql:connection>
\&        </department>
\&      </esql:row-results>
\&      <footer>footer info</footer>
\&    </esql:results>
\&    <esql:no-results>
\&      <department>No departments</department>
\&    </esql:no-results>
\&  </esql:execute-query>
\&  </esql:connection>
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Matt Sergeant, matt@axkit.com. Original Cocoon taglib by Donald Ball
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2001 AxKit.com Ltd. You may use this module under the same
terms as AxKit itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
AxKit, \s-1DBI\s0, Apache::AxKit::Language::XSP, the AxKit.org pages at
http://axkit.org/