varlena ere: XML/HTML Tags


Overview

Requirements

Examples

How It Works

Design Structure

Tags

Design a Report

Variables

Built-in Arguments

Debugging

Using CSV files

Tricks

Copyright

Reports Home

The barebones outline of an ere template file looks like this. Special ere tags are in bold. Information to be entered by the report developer is in italics. All tags require a matching end tag, with the exception of the <VAR .... /VAR> tag which is a single entity.

Some optional elements are shown here and are listed as optional in the detailed explanations below. Also see the details below for information regarding <table> and <area> tags.


<HTML>
<HEAD>
...
   <ReportDefinition>
      <ReportName> reportname </ReportName>
      <Var name=variablename value=variablevalue/Var>
      <DataStreamDef name=datastreamname dbname=:dbname: port=:port: user=:user: >
         <SQL>
            SQL statement
         </SQL>
         <TargetList>
            comma separated target list
         </TargetList>
         <BreakList>
            comma separated break column list
         </BreakList>
      </DataStreamDef>
   </ReportDefinition>
   ...
</HEAD>
<BODY>
   ...
   <table|area name=areaname break=breakname checkbreak=yes|no maxrepeat=n >
      ....
   </table|area>
   ...
</BODY>
</HTML>

<ReportDefinition>
The <ReportDefinition> tag encloses the details of the specifications for the report, its DataStream(s) and variables. It is required.
<ReportName>
The name of the report is specified between the <ReportName> tags. The report name is usually the same as the file name, but is not required to be so. The name is used for error messages files and to create output file names. Because the name is used to create file names, it should only contain identifyer friendly characters. This tag is required.
<Var>
<Var> is used to define and assign variables for use in the report or the SQL statement. Variables defined using <Var> may have their values based on command line arguments.

See the Variable Section for more details on command line, declared and column variables.

<DataStreamDef>
A DataStream is a query or queries that produce one flow of rows and columns from the database. You may have more than one DataStream per report, however, the breaks of the DataStreams must be syncronized or the queries must be completely disjoint. You may also have multiple SQL statements in a single DataStream; the last one must be a SELECT.

The <DataStreamDef> tag encloses the <SQL>, <TargetList>, and the <BreakList> tags described below.

A DataStream attributes are as follows.

name=datastreamname
The name of the DataStream should be unique within the report. You will use this name to associate repeating areas with the datastream.

The csv feature is deprecated.
The datastream name is used for internal reference as well as a "default" variable containing the name of the csv file created by the datastream, if one exists. The variable with the same name as the datastream can then be used to create a link from the report output to the csv file.

dbname=database, host=host, port=port, user=user, password=password
These are the database connection options. If they are not set, then the default database connection will be used. The default connection is based on the environment variables PGDATABASE, PGPORT, PGUSER and PGPASSWORD which may be set in the environment in which ere is running.

By setting these options you can enable ere to be run by another process, for example a web server, and still control the database connection used. These options also enable you to use datastreams from multiple databases in your report.

These options may be set explicitly in the report or by using variables passed in on the command line. For example if you invoke ere with the database connection variables on the command line:

	ere.pl myreport dbname=mydb port=12345
Then they could be used in a DataStream definition like this:
	<DataStreamDef name=primary dbname=:dbname: port=:port: >

The csv feature is deprecated.
csv=t
Indicates that the DataStream query can produce a csv file. The file is only produced if requested at runtime by using the argument do_csv=yes on the command line.

<TargetList>
The target list is a comma separated list of the column names produced by the DataStream. These names may be used as column variables and embedded in the HTML portion of the report bracketed by underscores: _columnname_. When the report is run, the values are expanded from the query values.
<BreakList>
The <BreakList> is a comma separated list of elements from your <TargetList> that describe the hierarchy of your report. You must sort your query according to your <BreakList>. <BreakList> elements may then be used in repeating <TABLE> or <area> sections that delineate the contents of each level of the report. If there are no breaks in your report, you must specify "detail" as your break list. This will ensure row by row break needed for most tabular reports.
<SQL>
The <SQL> tag brackets one or more SQL statements. If there are more than SQL statements in an <SQL> section, the last one must be a SELECT statement. The elements in the <TargetList> and <BreakList> described above pertain only to the ultimate query.

Leading statements, such as CREATE TEMP TABLE, are useful for preparing the data for the report.

<Area>
An <AREA> tag outlines the HTML to be repeated as rows are fetched. An <AREA> has a name, an associated DataStream and a break for that DataStream. It may have multiple DataStreams as a quoted space separated list, if and only if the break is on the same column in all the named DataStreams.

Each of the attributes of an <AREA> tag may also be inserted into a <TABLE> tag. If you have a header row in your table, you probably prefer to use an area.

	<TABLE name=detail_area datastream=query break=detail >
	   <TR>
	      <TD> _datacol_ </TD><TD> _nextcol_ </TD> <TD>_lastcol_ </TD>
	   </TR>
	</TABLE>

	Alternatively:

	<TABLE>
	   <TR>
	      <TH> Data Column </TH><TH> Next Column </TH> <TH>Last Column </TH>
	   </TR>
	   <AREA name=detail_area datastream=query break=detail >
	   <TR>
	   	<TD> _datacol_ </TD><TD> _nextcol_ </TD> <TD>_lastcol_ </TD>
	   </TR>
	   </AREA>
	</TABLE>
	
	

Attributes of an <Area> tag are as follows:

name=areaname
The area name must be unique within a report. It is used as an internal identifier.

datastream=datastreamname
The datastream name designates that datastream which will drive this area. If more than one datastream is to drive the area, you may have a quoted comma separated list of datastream names. If you have more than one datastream associated with an area, the break columns must be syncronized.

break=breakcolumn
The break column indicates which column from the possible break columns from the datastream pertain to this area. "detail" must be specified if a row by row break is wanted. "NONE" as a break will indicate that there will be only a single repetition for the area or table. If you want more than one break column surrounding an area, use two area structures:

	   <AREA name=detail_nextcol datastream=query break=nextcol >
	   <AREA name=detail_lastcol datastream=query break=lastcol >
	   <TR>
	   	<TD> _datacol_ </TD><TD> _nextcol_ </TD> <TD>_lastcol_ </TD>
	   </TR>
	   </AREA>
	   </AREA>
	

checkbreak=yes
Checkbreak indicates that a new row should be fetched and verified to match the break for this area. Usually rows are fetched after an area has completed. This is used with sibling areas with multiple (areas at the same hierarchical level with the same parent area) to produce multiple columns. Sibling areas usually have different DataStreams.

maxrepeat=n
Max repeat indicates that the maximum number of times to repeat this area is n. This is used to syncronize sibling areas and for areas repeating left to right.

<Include>
An <INCLUDE> tag enables you to avoid repetition between reports and to be more consistent with your HTML styles. The included file is inserted at parse time, but is not parsed. The included file may contain variables or column references, but nothing from the Report Definition and may not contain repeating areas or tables.

file=/fullpath/filename
The file to be included must be a full path name. You may use arguments from the command line in the file name. If you are using rerun then the directory path to your reports is passed in automatically. That can be used as a variable in the path name. Or you can create your own variable as necessary to be more flexible with the complete path name.

	<INCLUDE file=:rptdir:/std_headers.html>
	

Copyright 2003 through 2009 A. Elein Mustain, Varlena, LLC