view release on metacpan or  search on metacpan

dbixchart.html  view on Meta::CPAN

<li>POINTGRAPH( * | column-list )
<li>BARCHART( * | column-list )
<li>HISTOGRAM( * | column-list )
<li>BOXCHART( * | column-list )
<li>PIECHART( * | column-list )
<li>GANTTCHART( * | column-list )
<li>QUADTREE( * | column-list )
<li>IMAGE
</ul>
<p>
<code>
&lt;select-stmt&gt; := <i>any valid SELECT statement, including any grouping, ordering,
or other qualifiers</i><p>
chart-prop-expr := <i>&lt;property&gt; &lt;</i> = | IN <i>&gt; &lt;literal-list&gt;</i></b><p>
literal-list := &lt;<i>?</i> | <i>literal</i> [, literal-list ]&gt;<p>
</code>
(<i>Note: support for using returned columns of a charted query to specify
chart property values is planned for a future release.</i>)<p>

When <b>IMAGEMAP</b> is included in the column list, text
is generated for either
<ul>
<li>an HTML client-side imagemap
<li>a Perl compatible array of hashrefs of value and coordinate attributes
</ul>
Various <i>&lt;properties&gt;</i>s from the WHERE clause provide
base URL or scripting tags to be associated with the imagemap.
See <a href="#imagemaps">IMAGEMAPS</a> below for details.<p>
When any of the various <code>$sth->fetch()</code> operations is applied to the SELECT statement:
<ul>
<li>For PNG, JPEG, or GIF formats, images are returned as VARBINARY objects
representing the binary image data.
<li>Imagemaps are returned as VARCHAR objects containing the HTML imagemap text.
</ul><p>
<b>General Restrictions:</b><br>
<ul>
<li>ordering of wedges and bars in pie and barcharts is determined by the order the rows are
returned by the associated SELECT statement.<br>
<li>Ordering of plot points in line, area, and point graphs with numeric and temporal domains is
ascending left to right on the X-axis, ascending bottom to top on Y-axis. Graphs with symbolic
domains are plotted in the order they are INSERT'd.<br>
<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.<br>
<li>Support for JPEG images on Windows platforms with ActiveState Perl requires installing
the Tk::JPEG PPM from ActiveState.
<li>Support for GIF image formats requires a compatible version of the GD
modules (pre 1.20).
<li>Composite images can only be constructed from compatible chart types:
<ul>
<li>piecharts, Gantt charts, quadtrees, and 3-axis barcharts/histograms must be used alone (i.e., a single graph composite).
<li>histograms are only compatible with other histograms
<li>3-d barcharts are only compatible with other 3-d barcharts
<li>all other types are compatible with one another
</ul>
<li>The domain types for the individual graphs in a composite image
must be compatible, i.e., numeric with numeric, temporal with temporal, and
symbolic with symbolic.
<li>Named derived table queries cause the specified name to be used to identify the
associated plot in any legend
generated for the composite image. If no name is given for a derived table query,
the default name "PLOTn", where n is the sequence number of the query in the image,
will be used.
</ul>
</li><p>
</ul>
<p>

<a name="colormap"></a>
<h3>Colormaps</h3>
The colors used to render the various image elments can be adjusted by the
application by modifying the predefined COLORMAP table. The COLORMAP table
is predefined as follows:
<pre>
CREATE TABLE CHART.COLORMAP (
	Name VARCHAR(30),	-- name of color
	RedValue INTEGER,	-- value of red component
	GreenValue INTEGER,	-- value of green component
	BlueValue INTEGER,	-- value of blue component
);
</pre>
The color component values must be specified between 0 and 255.
<p>
Refer to DBD::Chart for the predefined values in the COLORMAP table.
<p>
For example, to define a new color:
<pre>
$dbh-&gt;do('INSERT INTO COLORMAP VALUES('chartreuse', 230, 179, 180);
</pre>
To modify an existing color:
<pre>
$dbh-&gt;do("UPDATE COLORMAP SET REDVALUE=100 WHERE NAME='marine'");
</pre>
To fetch the current values of an existing color:
<pre>
$sth = $dbh-&gt;prepare("SELECT * FROM COLORMAP NAME='marine'");
$sth-&gt;execute;
$row = $sth-&gt;fetchrow_arrayref;
</pre>
Finally, a generic parameterized statement can be used to define colors at runtime:
<pre>
$sth = $dbh-&gt;prepare("INSERT INTO COLORMAP VALUES(?, ?, ?, ?)");
$sth-&gt;execute('marine', 127, 127, 255);
</pre>
Note that using non-alphanumeric characters in color names may cause parsing
problems, so stick to alphanumerics, e.g., 'red3'.
<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 DBI, or any underlying DBI driver,
will be flagged in err and errstr with whatever info is returned.
<p>

<a name="diags"></a>
<h3>Diagnostics</h3><p>

DBI provides the <code>trace()</code> function to enable various levels