Data source format

When you assign a data source to the main timeline or a movie clip's timeline using the Generator Environment Variable button, you can format data sources in two ways: Name/Value and Column Name/Value. The main difference between the two formats is the number of values a variable can have. Name/Value variables can have only one value per variable; Column Name/Value variables can have multiple values.

The Column Name/Value format is suited for multiple values and is required when you want to provide multiple sets (or records) of data to a command that takes multiple sets (Plot, Replicate, Scrolling List, Ticker, List, Chart, and so on)


 
Name/Value

The first line of this format must be as follows:

Name, Value 

These column names are required. Each row is a separate line within the file; column values are separated by commas. Under the Name column, specify the variable names. Under the Value column, specify the variable values. Each variable can be assigned only one value. Quotation marks ("") enclosing the values are optional as long as the value does not contain any embedded commas. Generally, it's a good idea to enclose values within quotation marks to make sure they are fully encapsulated and treated as a single value.

Name, Value
Var1, "Value1"
Var2, "Value2"
Var3, "Value3"


 
Column Name/Value

This format requires that the first row of data specify the variable names and the following rows specify the values, as in the following example. Quotation marks ("") enclosing the values are optional as long as the value does not contain any embedded commas. Generally, it's a good idea to enclose values within quotation marks to make sure they are fully encapsulated and treated as a single value.

Var1, Var2, Var3
"Value1", "Value2", "Value3"
"Value1a", "Value2a", "Value3a"

An SQL query statement creates a table more easily in this format than in the Name/Value format.


 
Using special characters in data sources

Generator reserves some characters for special uses within a data source. To insert reserved characters into a text string, you must use an escape character sequence beginning with a backslash (\). Use escape character sequences to format values in any type of data source. These modifications ensure that values are correctly displayed in the final generated output.

Line break indicates that the current row of data has ended. Use the character sequence \r\n. Here's an example that inserts a line break within a value:
"The first line.\r\nThe second line."
Quotation mark (") indicates the beginning or end of a text string. Quotation marks must be used in pairs. Use the character sequence \". Here's an example:
"He said - \"Yes, this will work.\""
Comma (,) indicates that the current column of data has ended. A comma is not treated as a delimiter if it appears within a pair of quotation marks but instead is parsed as a literal comma. Here's an example:
"A quoted comma, however, is a literal comma."
Backslash (\) treats the next character as an escaped character. Use the character sequence \\ to indicate a literal backslash. Here's an example that inserts a backslash within a value:
"Use a \\ in the directory path."

If values are obtained from databases or from HTTP or FTP requests, modification of the original data may not be necessary before passing the final values to Generator. Test these types of data sources thoroughly to determine whether modification is warranted. Several third-party Web application development tools, such as Microsoft Active Server Pages (ASP), Allaire ColdFusion, or any CGI-based scripting or programming environment, can be used to retrieve and modify the data before returning the formatted data source as output to Generator.

Here is an example of how to set a variable value containing special characters:

name, value
var1, hello, world
var2, "hello, world"
var3, "\"hello, world\""

When these variables are referenced, the following values will be returned:

var1 = hello
var2 = hello, world
var3 = "hello, world"


 
Specifying color in data sources

When you specify a color in a data source, specify its value in one of the following ways: a Web-safe color name (for example, black), a Web hexadecimal value (for example, #3434aa), or a regular hexadecimal value (for example, 0x232356).


 
How Generator parses data sources

When Generator parses a data source entry in the Data Source parameter field or dialog box, it checks the first character to see if it is a pound sign (#). A pound sign directs Generator to treat the remainder of the entry as a native data source. If a pound sign is not present, Generator treats the entry as a reference from which to retrieve an external data source (for example, a path to a text file, an HTTP/FTP URL, an fgjdbc:// database URL, and so on).

In most cases, the Generator object or command governs how a data source must be formatted. With the exception of data sources specified with the Generator Environment Variable button, all Generator objects and commands that accept their own data source parse that data source in Column Name/Value format. When parsing a data source in Column Name/Value format, Generator expects all variables to be defined in the first row of the data source. Subsequent rows of the data source contain values for those variables—one set of values per line, terminated with a line break. Values are provided in the order in which they are declared in the first line. If you don't provide a value for any variable in the original declaration, include a comma to indicate an empty value for that variable and to signal Generator to move to the next variable declaration in the list.

Data sources specified for a main timeline or a movie clip's timeline using the Generator Environment Variable button can be in either Column Name or Name/Value format. However, the format must be specified to ensure that the data source is correctly parsed. Regardless of the format selected, data sources specified with the Generator Environment Variable button are restricted to a single value per variable (much like Windows or UNIX system environment variables). You can declare as many variables as you like, but each variable can have only one value. As Generator parses the data source line by line, it allocates memory for the variables encountered. If a variable is encountered more than once, the second occurrence is treated as a redefinition of the variable's value, so the older value is replaced by the newer value.

When the Name/Value button is selected in the Generator Environment Variable dialog box, Generator requires that the first row of the data source contain the string "Name, Value" (the string is not case-sensitive). If "Name, Value" is not found in the first row, Generator cannot read the data source and an error is written to the Output window or log files. If "Name, Value" is found in the first row, Generator parses the data source using the first entry of each row as the variable name and the second entry as the value for that variable. Each row of the data source is read until no more lines are found.

When the Column Name/Value button is selected in the Generator Environment Variable dialog box, Generator uses the Column Name/Value method to read the data source. This setting is useful when you need to establish environment variables for a timeline using a database query. SQL SELECT queries return data in the Column Name/Value format easily. However, it is important to remember that the single value per variable restriction still applies; data sources with multiple rows result in a redefinition of the environment variables until the last line is reached. For this reason, restrict data sources in Column Name/Value format to a single row when using them with the Generator Environment Variable button.