<html>
<head>
<title>DBD::Chart 0.20 - Perl DBI Driver abstraction for rendering charts and graphs</title>
<META NAME="keywords" CONTENT="Chart, graph, chart, Perl, perl, DBD, DBI, PNG, GD">
<META NAME="description" CONTENT="DBD::Chart Reference and User Guide.">
<META NAME="author" CONTENT="By Dean Arnold"></head>
<body>
<h2>NAME</h2><p>
<h3>
DBD::Chart - Perl DBI Driver interface For Rendering Charts and Graphs</h3><p>
<ul>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<li><a href="#version">VERSION</a>
<li><a href="#history">CHANGE HISTORY</a>
<li><a href="#behavior">DRIVER-SPECIFIC BEHAVIOR</a>
<ul>
<li><a href="#dsn">DATA-SOURCE NAME</a>
<li><a href="#types">DATA TYPES</a>
<li><a href="#parmsql">SQL DIALECT</a>
<li><a href="#errors">ERROR HANDLING</a>
<li><a href="#diags">DIAGNOSTICS</a>
<li><a href="#specattr">DRIVER-SPECIFIC ATTRIBUTES</a>
<li><a href="#funcs">DRIVER-SPECIFIC FUNCTIONS</a>
</ul>
<li><a href="#conform">PREREQUISITES AND CONFORMANCE</a>
<li><a href="#bugs">KNOWN BUGS</a>
<li><a href="#todo">TO DO List</a>
<li><a href="#acks">ACKNOWLEDGEMENTS</a>
<li><a href="#refs">REFERENCES</a>
<li><a href="#copy">COPYRIGHT</a>
</ul>
<p>
<a name="synopsis"></a>
<h2>SYNOPSIS</h2><p>
<pre>
use DBI;
my $dbh = DBI->connect('dbi:Chart:');
or die "Cannot connect\n";
#
# example: create a pie chart
#
$dbh->do('CREATE TABLE pie (region CHAR(20), sales FLOAT)');
$sth = $dbh->prepare('INSERT INTO pie VALUES( ?, ?)');
$sth->execute('East', 2756.34);
$sth->execute('Southeast', 3456.78);
$sth->execute('Midwest', 1234.56);
$sth->execute('Southwest', 4569.78);
$sth->execute('Northwest', 33456.78);
$rsth = $dbh->prepare('SELECT PIECHART FROM pie ' .
'WHERE WIDTH=400 AND HEIGHT=400 AND ' .
'TITLE = \'Sales By Region\' AND COLOR=(red, green, blue, lyellow, lpurple)');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="simppie.png" alt="Simple Pie Chart"></center><p>
<pre>
#
# multi-range 3-D bar chart
#
$dbh->do('CREATE TABLE bars (quarter SMALLINT, East FLOAT, '.
'Southeast FLOAT, Midwest FLOAT, Southwest FLOAT, Northwest FLOAT)');
$sth = $dbh->prepare('INSERT INTO bars VALUES(?, ?, ?, ?, ?, ?)');
$sth->execute(1, -2756.34, 3456.78, 1234.56, -4569.78, 33456.78);
$sth->execute(2, 2756.34, 3456.78, 1234.56, 4569.78, 33456.78);
$sth->execute(3, 2756.34, 3456.78, -1234.56, 4569.78, 33456.78);
$sth->execute(4, 2756.34, -3456.78, 1234.56, 4569.78, 33456.78);
$rsth = $dbh->prepare('SELECT BARCHART FROM bars ' .
'WHERE WIDTH=600 AND HEIGHT=400 AND X-AXIS=\'Quarter\' AND ' .
' Y-AXIS=\'Revenue\' AND TITLE = \'Quarterly Revenue By Region\' AND ' .
'3-D=1 AND SHOWVALUES=1 AND COLOR=(red, green, blue, yellow, dbrown)');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="multibar.png" alt="Bar Chart"></center><p>
<pre>
#
# scatter graph
#
$dbh->do('CREATE CHART line (Month SMALLINT, sales FLOAT)');
$sth = $dbh->prepare('INSERT INTO line VALUES( ?, ?)');
$sth->execute(1, 2756.34);
$sth->execute(2, 3456.78);
$sth->execute(3, 1234.56);
$sth->execute(4, undef);
$sth->execute(5, 33456.78);
$sth->execute(6, 908.57);
$sth->execute(7, 756.34);
$sth->execute(8, 3456.78);
$sth->execute(9, 12349.56);
$sth->execute(10, 4569.78);
$sth->execute(11, 13456.78);
$sth->execute(12, 90.57);
$rsth = $dbh->prepare('SELECT POINTGRAPH FROM line ' .
'WHERE WIDTH=500 AND HEIGHT=300 AND X-AXIS=\'Sales\' AND ' .
'TITLE = \'Sales By Region\' AND COLOR=black AND SHOWGRID=0 AND ' .
'SHAPE=filldiamond AND SHOWVALUES=1');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="simppts.png" alt="Scatter Graph"></center><p>
<pre>
#
# multi-range line w/ points
#
$dbh->do('DROP CHART line');
$dbh->do('CREATE CHART line (Month SMALLINT, East FLOAT, ' .
'Southeast float, Midwest float, Southwest float, Northwest float)');
$sth = $dbh->prepare('INSERT INTO line VALUES( ?, ?, ?, ?, ?, ?)');
$sth->execute(1, 2756.34, 3456.90, 1234.99, 1005.34, 2876.34);
$sth->execute(2, 3456.78, undef, 4321.25, 9001.34, 997.68);
$sth->execute(3, 1234.56, 7783.20, 5321.11, 3333.33, 876.10);
$sth->execute(4, 4569.78, 4326.3, -7895.44, 4444.44, 12345.29);
$sth->execute(5, 33456.78, 12094.5, 6666.66, 3322.11, 9090.90);
$sth->execute(6, 908.57, -2367.4, 3399.55, 5555.55, 887.3);
$sth->execute(7, 756.34, 1111.11, 2222.22, 8888.88, 9456.3);
$sth->execute(8, undef, 7783.20, 5321.11, 3333.33, 876.10);
$sth->execute(9, 12349.56, 12094.5, 6666.66, 3322.11, 9090.90);
$sth->execute(10, 4569.78,3456.99, 4321.25, 9001.34, 997.68);
$sth->execute(11, 13456.78, 2367.4, 3399.55, 5555.55, 887.3);
$sth->execute(12, 90.57,3456.90, 1234.99, undef, 2876.34);
$rsth = $dbh->prepare('SELECT LINEGRAPH FROM line ' .
'WHERE WIDTH=400 AND HEIGHT=400 AND X-AXIS=\'Month\' AND '.
'Y-AXIS=\'Sales\' AND TITLE = \'Monthly Sales By Region\' AND ' .
'COLOR=(red, green, blue, yellow, lbrown) AND ' .
'SHOWPOINTS=1 AND SHOWGRID=1 AND ' .
'SHAPE=(fillcircle, fillsquare, filldiamond, horizcross, diagcross)');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="multlpt.png" alt="Multiline Graph"></center><p>
<pre>
$dbh->do('CREATE CHART line (Month SMALLINT, East FLOAT, ' .
'Southeast float, Midwest float, Southwest float, Northwest float)');
$sth = $dbh->prepare('INSERT INTO line VALUES( ?, ?, ?, ?, ?, ?)');
@month = (1,2,3,4,5,6,7,8,9,10,11,12);
@east = ( 2756.34, 3456.90, 1234.99, 1005.34, 2876.34, 3456.78, undef,
4321.25, 9001.34, 997.68, 1234.56, 7783.20);
@seast = ( 5321.11, 3333.33, 876.10, 4569.78, 4326.3, -7895.44, 4444.44,
12345.29, 3456.78, 12094.5, 6666.66, 3322.11);
@midwest = ( 9090.90, 908.57, -2367.4, 3399.55, 5555.55, 887.3, 756.34,
1111.11, 2222.22, 8888.88, 9456.3, undef);
@swest = ( 7783.20, 5321.11, 3333.33, 876.10, 12349.56, 12094.5, 6666.66,
3322.11, 9090.90, 4569.78, 3456.99, 4321.25);
@nwest = ( 9001.34, 997.68, 13456.78, 2367.4, 3399.55, 5555.55, 887.3,
90.57, 3456.90, 1234.99, undef, 2876.34);
$sth->func(1, \@month, chart_bind_param_array);
$sth->func(2, \@east, chart_bind_param_array);
$sth->func(3, \@seast, chart_bind_param_array);
$sth->func(4, \@midwest, chart_bind_param_array);
$sth->func(5, \@swest, chart_bind_param_array);
$sth->func(6, \@nwest, chart_bind_param_array);
%stsary = ();
$sth->func(\%stsary, chart_bind_param_status);
$sth->execute;
$rsth = $dbh->prepare('SELECT AREAGRAPH FROM line ' .
'WHERE WIDTH=400 AND HEIGHT=400 AND X-AXIS=\'Month\' AND ' .
'Y-AXIS=\'Sales\' AND TITLE = \'Monthly Sales By Region\' AND ' .
'COLOR=(red, green, blue, yellow, lbrown) AND ' .
'SHOWPOINTS=1 AND SHOWGRID=1 AND ' .
'SHAPE=(fillcircle, fillsquare, filldiamond, horizcross, diagcross)');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="multarea.png" alt="Area Graph"></center><p>
<pre>
#
# log-log line graph
#
$dbh->do('CREATE CHART line (Month FLOAT, sales FLOAT)');
$sth = $dbh->prepare('INSERT INTO line VALUES( ?, ?)');
for ($i = -3; $i < 13; $i++) {
$sth->execute(5**$i, exp($i));
}
$rsth = $dbh->prepare('SELECT LINEGRAPH FROM line ' .
'WHERE WIDTH=450 AND HEIGHT=450 AND X-AXIS=\'5**X\' AND Y-AXIS=\'e**X\' AND '
'Y-LOG=1 AND X-LOG=1 AND SHOWVALUES=0 AND ' .
'TITLE = \'Sample Log-Log Linegraph\' AND ' .
'COLOR=lred AND SHOWGRID=1 AND SHOWPOINTS=1');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="simpylog.png" alt="Log-Log Graph"></center><p>
<pre>
#
# simple candle graph
#
$dbh->do('CREATE CHART candle (Day DATE, low FLOAT, high FLOAT)');
$sth = $dbh->prepare('INSERT INTO candle VALUES( ?, ?, ?)');
$sth->execute('2000-05-11', 27.34, 29.50);
$sth->execute('2000-05-12', 24.67, 28.50);
$sth->execute('2000-05-13', 22.34, 26.50);
$sth->execute('2000-05-14', 17.34, 20.50);
$sth->execute('2000-05-15', 17.34, 19.50);
$sth->execute('2000-05-18', 17.34, 21.50);
$sth->execute('2000-05-19', 18.34, 25.50);
$sth->execute('2000-05-20', 27.34, 39.50);
$sth->execute('2000-05-21', 30.34, 34.50);
$sth->execute('2000-05-22', 33.34, 37.50);
$sth->execute('2000-05-25', 32.34, 36.50);
$sth->execute('2000-05-26', 30.34, 32.50);
$sth->execute('2000-05-27', 28.34, 33.50);
$sth->execute('2000-05-28', 30.34, 38.50);
$sth->execute('2000-05-29', 27.34, 35.50);
$sth->execute('2000-06-01', 28.34, 34.50);
$sth->execute('2000-06-02', 25.34, 30.50);
$sth->execute('2000-06-03', 23.34, 28.50);
$sth->execute('2000-06-04', 20.34, 26.50);
$rsth = $dbh->prepare('SELECT CANDLESTICK FROM candle ' .
'WHERE WIDTH=400 AND HEIGHT=400 AND X-AXIS=\'Date\' AND ' .
'Y-AXIS=\'Price\' AND TITLE = \'Daily Price Range\' AND ' .
'COLOR=red AND SHOWGRID=1 AND ' .
'SHAPE=filldiamond AND SHOWPOINTS=1');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="simpcndl.png" alt="Candlestick Graph"></center><p>
<pre>
#
# use same data to render linegraph with symbolic domain
#
$rsth = $dbh->prepare('SELECT LINEGRAPH FROM candle ' .
'WHERE WIDTH=400 AND HEIGHT=400 AND X-AXIS=\'Date\' AND ' .
'Y-AXIS=\'Price\' AND TITLE = \'Daily Price Range\' AND ' .
'COLOR=(red, blue) AND SHOWGRID=1 AND ' .
'SHAPE=(filldiamond, fillsquare) AND SHOWPOINTS=1');
$rsth->execute;
$rsth->bind_col(1, \$buf);
$rsth->fetch;
</pre><p>
produces the image<p><center>
<img src="simpsymb.png" alt="Non-numeric Graph"></center><p>
<a name="description"></a>
<h2>DESCRIPTION</h2><p>
DBI driver abstraction for rendering pie charts, bar charts, line, point, area, and
candlestick graphs. (See <b>DBI(3)</b> for details).<br>
<b>BE ADVISED:</b> This is <b>ALPHA</B> software, and subject to change at the
whim of the author(s). <p>
Why DBD::Chart ? Basically, the idea is to make chart rendering easy for us database
geeks...and maybe for other folks, as well. Being able to render a chart from a
rowset by simply binding output column buffers as input parameter buffers for a
simple INSERT, then just SELECT'ing to get the image, seemed like a nice
abstraction.<p>
BTW: This driver is 100% pure Perl.<p>
<p>
<a name="version"></a>
<h2>CURRENT VERSION</h2><p>
<a href="http://home.earthlink.net/~darnold/dbdchart/dbdchart020.zip">Release 0.20</a>
<a name="history"></a>
<h2>CHANGE HISTORY</h2><p>
Release 0.20:<p>
<ul>
<li>added support for 3-D bar and pie charts (via GD::Graph3d)
<li>added logarithmic line/point graph support
<li>added area graphs
<li>added candlestick charts (e.g., for daily trading range charts)
<li>added support for non-numeric domain values
<li>packaged for CPAN
</ul><p>
Release 0.10:<p>
<ul>
<li>Coded; first alpha release
</ul><p>
<a name="behavior"></a>
<h2>DRIVER-SPECIFIC BEHAVIOR</h2><p>
<a name="dsn"></a>
<h3>DATA-SOURCE NAME</h3><p>
The dsn string passed to <code>DBI->connect()</code> is simply <code>'dbi:Chart:'</code>.
No username or password is required.<p>
<a name="types"></a>
<h3>DATA TYPES</h3><p>
Range (i.e., Y-axis) values must be defined as numbers.
INTEGER, FLOAT, SMALLINT, TINYINT, and DECIMAL are all
acceptable number types. Domain (i.e., X-axis) values may be either numeric
or non-numeric (including CHAR, VARCHAR, DATE, TIME, TIMESTAMP, etc.).
A non-numeric (i.e., "symbolic") domain will result in a uniformly distributed
mapping of values to the X-axis. For pie and barcharts, and candlestick graphs,
all domain types are treated as symbolic; for all other graph types,
a numeric domain will be mapped using the actual (scaled) numeric values.
<a name="datetime"></a>
<h3>Date, Time, and Timestamp TypeS</h3><p>
Obviously, handling these data types is important for temporal graphs. For now,
however, we just treat them as symbolic values, the same as CHAR or VARCHAR.<p>
<a name="parmsql"></a>
<h3>SQL DIALECT</h3><p>
DBD::Chart uses a small subset of SQL to create, populate, render, and discard
chart data:<p>
<ul>
<li><code><b>CREATE { TABLE | CHART } <i>chartname</i> ( <i><domain-definitions></i> )</b></code><p>
Creates a chart object that can be populated with datapoints and subsequently rendered.
<code><b><i><domain-definitions></i></b></code> is a list of column definitions
which must follow these rules:<p>
<b>For pie charts:</b>
<ol>
<li>no more than 2 columns should be defined; extra columns will be ignored when the chart is rendered.
<li>the 1st column contains the text of label applied to the associated wedge of the pie.
<li>the 2nd column must be numeric and defines the domain values to be plotted.
</ol><p>
<b>For bar charts:</b>
<ol>
<li>at least 2 columns must be defined
<li>the 1st column contains the text label printed along the X axis for each bar
(if only a single domain column is defined) or group of bars (if more than 1 domain column is defined).
<li>the remaining columns must be numeric. When more than 1 domain column is defined, the column
values are plotted in groups by the associated label, i.e., all domains for each row are plotted
in a group.
</ol><p>
<b>For line, area, or point graphs:</b>
<ol>
<li>at least 2 columns must be defined.
<li>the 1st column defines the X-axis values for each row to be plotted (i.e., the "domain"),
which may be of any type. Note that non-numeric domain types are handled symbolicly, as
<a href="#types">described above</a>.
<li>each additional column is used as a Y-axis value for a distinct plot line or point-set within
the rendered image (i.e., multiple ranges may be plotted against a single domain in a single graph).
<li>Y-axis values may be NULL, in which case the corresponding (X, Y) plot point will be omitted from the
associated line or pointset.
<li>numeric domain datasets do not need to be INSERT'ed in order; the charting engine will automatically
sort the domain values into ascending order. Non-numeric domains will be plotted in the same order
as they are INSERT'd.
</ol><p>
<b>For candlestick graphs:</b>
<ol>
<li>at least 3 columns must be defined.
<li>the 1st column defines the X-axis values for each candlestick to be plotted,
which may be of any type.
<li>the 2nd column must be numeric, and is used as the minimum (bottom) value of the candlestick.
<li>the 3rd column must be numeric, and is used as the maximum (top) value of the candlestick.
<li>multiple sets of candlesticks can be plotted in the same graph by defining additional
(minimum, maximum) columns.
</ol><p>
Column qualifers (e.g., NOT NULL, CASESPECIFIC, etc.) are not supported.</li><p>
<li><code><b>DROP { TABLE | CHART }<i>chartname</i></b></code><p>
Discards the specified chart context information. Any open statement handles which attempt
to manipulate the chart after it has been dropped will return errors.</li><p>
<li><code><b>INSERT INTO <i>chartname</i> VALUES ( <i><? | NULL | literal></i> [, ...] )</b></code><p>
Populates the chart with the specified data. A value must be provided for each column defined
in the chart (i.e., no defaults are used.).</li><p>
<li><code><b>SELECT <i><chart-type></i><br>
FROM <i><chartname | subquery></i> [, ...]<br>
WHERE <i><qualifier = literal> | <qualifier = valuelist></i> [AND ...]</b></code><p>
Renders an image containing the specified chart(s), using the qualifers to control how the image
is rendered. Valid <i><chart-type></i> values are<p>
<ul>
<li><b>PIECHART</b> - generates a piechart; each wedge is represented as a percentage of the sum of all the
domain values. Negative domain values result in an error.
<li><b>BARCHART</b> - generates a barchart; each bar is represented as a percentage of the largest value
in the domain. Negative values are supported.
<li><b>LINEGRAPH</b> - generates a linegraph
<li><b>AREAGRAPH</b> - generates an areagraph (i.e., the area between plotline and X-axis is filled
with the plot color).
<li><b>POINTGRAPH</b> - generates a pointgraph (i.e., scatter-graph)
<li><b>CANDLESTICK</b> - generates a candlestick graph
<!-- <li>IMAGE - used only when derived tables are specified; permits layering of
different graph types in a single image. -->
</ul><p>
The following qualifiers are allowed:<p>
<ul>
<li><b>WIDTH</b> - sets the image width in pixels; single value only
<!-- , cannot be used within a derived table query -->
<li><b>HEIGHT</b> - sets the image height in pixels; single value only
<!-- , cannot be used within a derived table query -->
<li><b>SHOWGRID</b> - when set to 1, causes the background grid of all charts/graphs except
piecharts to be displayed. single value only, valid values are 0 and 1.
<li><b>COLOR</b> - sets the color of chart elements; may be multivalued, in which case each wedge(piechart),
bar(barchart), line(linegraph), area(areagraph), pointset(scattergraph), or candlestick-set uses the next
color in the list. The colorlist wraps if more range valuesets are defined than
colors. Valid color values are <code>white, lgray, gray, dgray, black, lblue, blue, dblue, gold, lyellow,
yellow, dyellow, lgreen, green. dgreen, lred, red, dred, lpurple,
purple, dpurple, lorange, orange, pink, dpink, marine, cyan, lbrown, dbrown.</code>
<li><b>SHAPE</b> - sets the shape of points for line, area, point, or candlestick graphs; may be multivalued.
Valid values are <code>fillsquare, opensquare, horizcross, diagcross, filldiamond, opendiamond,
fillcircle, opencircle.</code>
<li><b>SHOWPOINTS</b> - for line, area, and candlestick graphs, determines whether datapoints are explicitly
rendered; single value only. Ignored for pie and bar charts, and pointgraphs. Valid values are 0 and 1.
<li><b>SHOWVALUES</b> - for barcharts, line, area, point, and candlestick graphs, determines whether the
datapoint values are displayed; single value only, valid values are 0 and 1, ignored for pie charts.
When set to 1, the (X,Y) values are displayed just above the plotted datapoint for line, area, and point graphs;
for candlesticks, the minimum and maximum Y values are plotted just above and below each candlestick.
<li><b>X-LOG</b> - causes values along the X-AXIS to be plotted in log<sub>10</sub> form;
for line, area, point, and candlestick graphs.
<li><b>Y-LOG</b> - causes values along the Y-AXIS to be plotted in log<sub>10</sub> form;
for line, area, point, and candlestick graphs.
<li><b>X-AXIS</b> - sets the label string on the X-AXIS of line, area, point, and candlestick graphs.
<li><b>Y-AXIS</b> - sets the label string on the Y-AXIS.
<li><b>TITLE</b> - sets the title string of the graph.
<li><b>3-D</b> - sets the 3-D effect on either pie or bar charts.
</ul>
<b>Restrictions:</b><br>
<ul>
<!-- <li>Only a single level of derived tables is allowed. -->
<li>no expressions (e.g., X + Y) or functions (e.g., AVG(X)) are allowed.
<li>ordering of wedges and bars in pie and barcharts is determined by the order the rows are
INSERTed.
<li>Ordering of plot points in line, area, and point graphs with numeric domains is ascending left to
right on the X-axis, ascending bottom to top on Y-axis. Graphs with non-numeric domains are plotted
in the order they are INSERT'd.
<li>Due to a current misalignment problem in the GD::Graph3d::bar3d module, the alignment of text when
setting SHOWVALUES=1 for 3-D barcharts may be less than appealing.
<li>When generating area graphs with multiple range valuesets (i.e., more the 1 set of Y values),
the order in which the range valuesets are plotted is column 2, column 3,...column N.
This order may cause some ranges to be completely obscured by the areagraph of a succeding range. You'll
need to experiment with the order of your range valuesets to get the best view.
</ul>
</li><p>
<li><code><b>DELETE FROM <i>chartname</i><br>
[ WHERE <i><domain-name></i> <i><operator></i> <i><? | literal></i>]</b></code><p>
Removes one (or more) data points from the chart. Valid <i><operator></i>s are
<, <=, =, >, >=, <>.
E.g., this could be used to render realtime
scrolling linegraphs where old values are rolled off the left of the graph, and new values are appended
on the right.<br>
<b>NOTE:</b>Deleting from a barchart, then inserting new rows, will cause new
rows to be displayed at the right end of the chart. Use UPDATE if you want to
modified the bar values, but maintain the original display order.
</li><p>
<li><code><b>UPDATE <i>chartname</i><br>
SET <i><domain-name></i> = <i><? | literal></i><br>
[ WHERE <i><domain-value></i> <i><operator></i> <i><? | literal></i>]</b></code><p>
Replaces the point with the specified value with a new point value.
Valid <i><operator></i>s are <, <=, =, >, >=, <>.
E.g., this could be used with
a bar chart to refresh the bar values in realtime (e.g., monitor User's CPU usage).</li>
</ul><p>
<a name="errors"></a>
<h3>ERROR HANDLING</h3><p>
Any errors generated from improper SQL usage are flagged with an error value of -1, and
appropriate text in the errstr. Errors emanating from the GD::Graph or DBD::Chart::Plot
modules will be flagged in err and errstr with whatever info is returned by those modules.
<p>
<a name="diags"></a>
<h3>DIAGNOSTICS</h3><p>
DBI provides the <code>trace()</code> function to enable various levels
of trace information. DBD::Chart currently doesn't add any traces to this.
<p>
<a name="specattr"></a>
<h3> DRIVER-SPECIFIC ATTRIBUTES</h3><p>
<ul>
<li>chart_noverify - when set to 1 during connect(), verification of data values with target
columns is bypassed (to provide some performance improvement).
</ul><p>
<a name="funcs"></a>
<h3> DRIVER-SPECIFIC FUNCTIONS</h3><p>
The following functions are provided to optimize data movement:<br>
<b><i>Note:</b>generalized versions of these functions are currently
under consideration for addition to the DBI specification.</i><p>
<ul>
<li><code>$sth->chart_bind_param_array($paramnum, \@paramary [\%attr | $typespec])</code><p>
binds an array of parameters to the statement; the entire array of parameters will be
consumed when the statement is executed.<p>
<li><code>$sth->chart_bind_param_status(\@stsary | \%stshash)</code><p>
binds an array or hash to receive parameter status information when parameter array binding has been
used on the statement. If the array version is used, then status for every supplied parameter
tuple is returned; if a hash is used, then only the status of unsuccessful parameter tuples is reported,
using the ordinal tuple number as the hashkey.<p>
</ul>
<i><b>Note:</b> array binding of output values is not supported, since
SELECT only returns a single value at a time, namely, the chart image.</i><p>
<a name="conform"></a>
<h2>PREREQUISITES AND CONFORMANCE</h2><p>
DBD::Chart requires the following (versions are recommended
only, cuz they're the version I built with...if you're feeling
frisky, you can try older or newer versions.): <p>
<ul>
<li>Perl version 5.006
<li>DBI module 1.14.
<li>GD module 1.32
<li>GD::Graph module X.XX
<li>GD::Graph3d module 0.55
<li>GD::TextUtil module X.XX
<li>DBD::Chart::Plot module 0.10 (included in release package)
</ul>
Be advised that the GD modules require the following libraries:<p>
<ul>
<li> <a href="http://www.boutell.com/gd/">libgd</a>
<li> <a href="http://www.libpng.org/pub/png">libpng</a>
<li> <a href="http://www.info-zip.org/pub/infozip/zlib/">zlib</a>
</ul><p>
The following DBI functions are not supported:
<pre>
DBI->data_sources()
$dbh->prepare_cached()
$sth->table_info()
$dbh->tables()
$dbh->type_info_all()
$dbh->type_info()
</pre>
<p>
<a name="bugs"></a>
<h2>KNOWN BUGS</h2><p>
<table border=1><tr>
<th align=center>Bug Number</th>
<th align=center>Report<br>Date</th>
<th align=center>Release<br>Reported in</th>
<th align=center>Description</th>
<th align=center>Status</th>
<th align=center>Fix<br>Release</th>
</tr></table>
<a name="todo"></a>
<h2>TO DO List</h2><p>
<ul>
<li>Support derived tables to layer graphs in an image
<li> (X, Y, Z) (i.e., true 3 dimension) barcharts
<li>surfacemaps ?
<li>placeholders in SELECT predicate expressions
<li> <i>Any suggestions?</i>
</ul>
<p>
<a name="acks"></a>
<h2>ACKNOWLEDGEMENTS</h2><p>
<a name="refs"></a>
<h2>REFERENCES</h2><p>
<ul>
<li><a href="http://www.symbolstone.org/technology/perl/DBI/">Official DBI Site</a>
<li><a href="http://www.cpan.org">CPAN</a>
<li><a href="http://www.perl.com">Perl.com</a>
<li><a href="http://www.activestate.com">ActiveState</a> (for Perl software for Windows)
</ul>
<h2>AUTHOR</h2><p>
<a href="mailto:darnold@earthlink.net">Dean Arnold</a><p>
<a name="copy"></a>
<h2>COPYRIGHT</h2><p>
Copyright (c) 2001, Dean Arnold, USA<br>
Affiliations:<br>
<ul>
<!-- <li><a href="http://www.baseline-consulting.com">Baseline Consulting</a>,<br> -->
<li><a href="http://www.mylines.com">MyLines.com</a>,<br>
<li><a href="http://home.earthlink.net/~darnold">Homepage</a>
</ul><p>
Permission is granted to use this software according to the terms of the
<a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</a>.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.<p>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.<p>
Please note that this license prohibits the incorporation of the source
code of this product in publicly distributed, but proprietary products (e.g., something
you're trying to sell, as opposed to selling support for). However, proprietary products
may invoke DBD::Chart.<p>
I'm offering the software <b>AS IS</b>, and <b>ACCEPT NO
LIABILITY FOR ANY ERRORS OR OMMISSIONS IN, OR LOSSES INCURRED AS A
RESULT OF USING DBD::Chart.</B><p>
I reserve the right to provide support for this software
to individual sites under a separate (possibly fee-based)
agreement.<p>
<center><i>Last updated March 12, 2001</i>
</body></html>