All NetCharts applets support the use of the FILE keyword to retrieve parameter definitions or data values from one or more data files. The FILE keyword allows HTML authors and developers to separate the chart display parameters (usually defined in the HTML file) from the actual data values, which may be more easily stored in data files.
The following specific issues are addressed in this document:
The FILE keyword can be used to define any parameter, regardless of the number of items or attributes required by that parameter. That is, the FILE keyword can be used to define a single value parameter, such as Bar3DDepth, a single tuple of attributes, like the Grid Parameter, or a vector of individual or tuple values, like the Slices and LineSets parameters. The most common use of the FILE keyword is for defining a vector of data values in a comma delimited file.
The FILE keyword has the following syntax:
Parameter = FILE "url pathname";
The filename given can be any URL that is valid for the environment in which the chart is being executed. For example, in a browser, if the chart is downloaded from a Web server, then the URL can specify a relative pathname or a full HTTP pathname.
For example, the following parameter definitions specify a local file named barlabels.dat and another data file, named barset1.dat, located on a specific server:
BarLabels = FILE "barlabels.dat";
DataSets = ("My Data");
DataSet1 = FILE "http://mycompany.com/data/barset1.dat";
If a relative pathname is specified, as in the BarLabels parameter
above, then the DocumentBase will be used as the start of the relative
location.
Since the FILE keyword allows an arbitrary URL to be specified for the
"data file", it is possible to use the output from a CGI script
to define a specific parameter.
For example, the following parameter definition specifies a CGI
script, with appropriate input parameters, that will generate
a text file containing the desired data.
In this case, the
This capability allows Web developers to create scripts that simply
generate the necessary data, while leaving all NetCharts syntax in the
HTML file(s) that need that data. This eliminates the need to generate
the entire HTML file, just to insert a few data values in the chart
definition. (Naturally, we don't restrict you from doing that, if you
prefer. The FILE keyword is just another alternative.)
Regardless of how the data file is stored, accessed or generated,
it is automatically processed by the chart in order to define one
or more attributes, for one or more tuples. This processing is controlled
by a small number of attributes, defined in the FileFormat directive,
that specify the "delimiters" of the data. Each delimiter
specifies one or more characters that are used in the file to separate
the various data components.
The FileFormat directive has the following syntax:
Any number of FileFormat directives can be specified within a parameter
script, to control the processing of different data files. The attributes
remain in effect for all subsequent FILE keywords, until the next FileFormat
directive is defined.
For example, the following script uses two files with the default
format, followed by two other files with different
All of the FileFormat attributes are optional and if they are not
specified, or they are specified to be "null", then the previously
defined value or the default value will be used.
The delimiter strings can contain any number of characters. Each
character in the string may be used as a delimiter in the data file.
Generally, only one character is used per delimiter, although this is
not necessary. The delimiters are used as follows:
CGI Script Data Output
DataSet1 = FILE "/cgi-bin/genData?user=fred&dataset=barset1";
genData
script is executed, generating whatever data
is appropriate for the given CGI input parameters. NetCharts will
automatically invoke the script and process all results returned, using
them to define the given parameter.
FileFormat Directive
FileFormat = ("startDelim", "itemDelim", "endDelim",
"whiteSpace", "quoteChars", "commentChars");
startDelim and endDelim
values.
BarLabels = FILE "barlabels.dat";
BarActiveLabel = FILE "baractive.dat";
FileFormat = ("{", null, "}");
DataSet1 = FILE "dataset1.dat";
DataSet2 = FILE "dataset2.dat";
| Delimiter | Default | Usage | ||||||||||||||||||
startDelim
| "(" | Denotes the start of aiexample, the following script uses two files with the default
format, followed by two other files with different startDelim and endDelim
values.
BarLabels = FILE "barlabels.dat";
BarActiveLabel = FILE "baractive.dat";
FileFormat = ("{", null, "}");
DataSet1 = FILE "dataset1.dat";
DataSet2 = FILE "dataset2.dat";
All of the FileFormat attributes are optional and if they are not specified, or they are specified to be "null", then the previously defined value or the default value will be used. The delimiter strings can contain any number of characters. Each character in the string may be used as a delimiter in the data file. Generally, only one character is used per delimiter, although this is not necessary. The delimiters are used as follows:
|