Starting DataVision
You can run DataVision from either your favorite window manager or the
command line. If you start DataVision from the command line, you may run a
report without ever opening the DataVision GUI screens. In either case, you
will have to supply a database password if one is required for access to
the database.
When you start DataVision without specifying an existing report XML
file, a new, empty report will be opened.
Launching DataVision
To start DataVision and create a new report, launch the file
datavision.sh (Unix) or datavision.bat (Windows)
by single- or double-clicking its icon (whichever is appropriate for your
window manager). An empty report design window will appear and a database
connection dialog box will open. See Connecting to the Database for
help filling out that dialog box.
To open an existing DataVision file or files, drag them on top of the
datavision.sh icon.
Running DataVision from the Command Line
To start DataVision from the command line, run the either script
datavision.sh (Unix) or batch file datavision.bat
(Windows). It sets the Java class path and runs DataVision, passing all
command line arguments to the application.
Usage
datavision.sh
[-c file | -d file
| -f file | -h file
| -l file | -x file | -w]
[-s delim_char]
[-r parameter_value_xml_file]
[-n | -p db_password |
-e data_file]
[-a data_file_sep_char]
[-g lang_code]
[-i region_code]
[-q]
[xml_file...]
The first group of options tell DataVision to run the XML report file(s)
without opening the report design GUI. Each option character represents a
layout engine:
- -cfile
- character-delimited file; default
delimiter character is a comma; use the -s option to specify a
different character
- -dfile
- DocBook
- -ffile
- PDF
- -hfile
- HTML
- -lfile
- LaTeX2e
- -w
- Swing
- -xfile
- XML
If you specify a layout engine you must also specify at least one XML file.
The output file name for each report is either the optional file
argument or, if that is not used, the name is created by replacing the
xml_file file name's extension with one appropriate for the
specified layout engine. The Swing layout engine doesn't produce an output
file. See Layout Engines for more
information about the output produced by each layout engine. Note
that specifying an output file name along with multiple report XML files
makes no sense because each report will be output to the same file name.
This is most likely not what you want.
The -s option lets you specify a separator character for the
character-delimited file layout engine. The default delimiter character is
a comma. You may have to quote or escape your separator on the command
line, especially if it is a space, tab, or other character that is special
to the shell.
The -p, -n, and -e options determine what kind of
data source DataVision will use. These three options are mutually
exclusive. The -p option lets you specify the database connection
password; the report XML file must specify a database. The -n option
tells DataVision to use the database defined in the report XML file, but
that a password is either unnecessary or it is the empty string. Finally,
the -e option tells DataVision to read data from a
character-separated file. The default separator character is defined in the
report XML, but may be overridden by using the -a option.
If you specify a non-Swing layout engine you must specify a data source
by using one of the -p, -n, or -e options. When you
use the Swing layout engine and do not specify either of these options,
DataVision will use its standard database password dialog box to ask you
for the password.
If you do not specify a layout engine and do not specify the -p,
-n, or -e option, you will be asked for the database password
when the report is opened for editing.
If there are parameters in your report and you are running a ``headless''
report (you specified a layout engine; the design window will not open),
then you need to specify the values of the parameters that appear in the
report. To do this, you create a small XML file and specify the parameter
values inside it. Pass this file on the command line using the -r
option. See Parameter Value XML Files.
For an example file, see parameters.xml in the
examples directory.
If you are opening a new report for editing in the GUI (no XML file was
specified on the command line), a database connection dialog box will
appear before the report design window opens. See Connecting to the Database for
information about the database connection dialog.
The -g and -i options let you override your system's default
language and region. This affects the selection of the application's
display strings such as menu items and dialog box prompts. Each option's
value is a two letter code. lang_code is a two-letter language
code (for example, ``en'' for English, ``fr'' for French).
region_code is a two-letter region or country code; examples
include ``US'' for the United States and ``FR'' for France. Both values are
case-insensitive.
Normally, database table and column names are quoted when necessary (when
the case of the name does not match the case the JDBC driver uses when it
performs a query). Using the -q flag turns off this quoting, except
for names that contain spaces which are always quoted.
Examples
Create a new report and start editing it:
datavision.sh
Open an existing report and start editing it:
datavision.sh report_file.xml
Open an existing report that requires no password, run it and generate
the LaTeX file report_file.tex:
datavision.sh -l -n report_file.xml
Open an existing report that asks for parameter values but requires no
password, run it and generate the LaTeX file my_output.tex:
datavision.sh -l my_output.tex -r parameters.xml -n report_file.xml
Open an existing report that requires the password ``fred'', run it and
generate the comma-separated file output.csv:
datavision.sh -c output.csv -p fred report_file.xml
Open an existing report that requires the password ``fred'', run it and
generate the tab-separated file report_file.tab:
datavision.sh -c -s " " -p fred report_file.xml
(There should be a tab character between the double quotes.)
Open an existing report that reads data from the file data.csv
and outputs it to PDF. The comma separator character defined in the report
XML file will be used.
datavision.sh -f -e data.csv report_file.xml
Font Display Problems
Report Output If you don't see the font you expect in report output,
make sure the layout engine you are using supports that font. In the
sections Available Layout Engines and
Supported Features, the layouts
and their available fonts or formatting options are discussed.
DataVision GUI Many languages uses non-Latin characters. For
example, Bulgarian uses Cyrillic characters. If these characters do not
display properly, you may need to upgrade your version of Java. Tony Tomov
(tomovtony@yahoo.com), our Bulgarian translator, did not see Cyrillic
characters properly until he upgraded to Java 1.3. When he upgraded to Java
1.4, he noticed that Cyrillic support had improved.
Font Error Messages
On Mac OS X, after upgrading to Java 1.4.1 via the Apple software update
tool I have started seeing the same error message every time I launch
DataVision (the long lines have been broken up):
2003-06-11 17:09:10.864 java[4080] Font GB18030Bitmap: in
_readBasicMetricsForSize, claims 0 max advance but is fixed-pitch.
2003-06-11 17:09:10.942 java[4080] Warning: Font LucidaSans-TypewriterBold
claims fixed-pitch with 0 max advance!
These error messages appear harmless.
On some Linux systems (for example, Red Hat 7.x), when you
start DataVision a whole slew of identical error messages are generated
that look something like this:
Font specified in font.properties not found
[--symbol-medium-r-normal--*-%d-*-*-p-*-adobe-fontspecific]
These error messages are harmless. There is at least one way to get rid of
them: edit the file $JAVA_HOME/jre/lib/font.properties and
replace all occurrences of ``-adobe-'' with ``-urw''. Note that you may
need to be root to edit this file.
Tom Van Overbeke (tom.van.overbeke@pandora.be) describes another way to get
rid of the messages: ``I checked all the fonts.dir available on my system,
there were a dozen of them. then I grepped through all of them to check for
"standard symbols l", and i found the entry in the file
/usr/share/fonts/default/Type1/fonts.dir. The entry was:
s050000l.pfb -URW-Standard Symbols
L-medium-r-normal--0-0-0-0-p-0-urw-fontspecific
``and I changed it to:
s050000l.pfb -URW-Standard Symbols
L-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
``Then I quit X, stopped and restarted xfs and restarted X, and it
worked.''