Substitution table functions

There are a number of built-in script functions that can be used to retrieve or modify values in substitution tables. Substitution tables are to some extent similar to maps, see Map functions.

A substitution table contains several entries (rows), and each entry contains two or more columns. The first column is the key, which is a unique identifier for each entry. The remaining columns contain the values for the entry (value 0, value 1,..., value N).

Example 44

Substitution table.

The substitution table below contains two entries. Each entry contains two values

//!CodePage UTF8! //!multicolumn! //key value 0 value 1 agatha christie 1890 alfred hitchcock 1899

 

Creating a substitution table

You can create a substitution table as a table resource in any resource set in your Project. Each entry must contain two or more columns, where the first column is the key (a unique identifier for the entry) and the remaining columns contain the values for the entry.

You can use space or tab as delimiter for the columns. Note that keys and values must be within double quotes (“) if they contain spaces.

Referencing a substitution table

When you use a substitution  table script function, you must specify the path to the substitution table to work with. If you create the substitution table as a table resource, the substitution table file will be exported and deployed to:

../data/tables/<filename>

Example 45

Using the Subst function.

In this example, the substitution table author.tbl is created as a table resource. The script function Subst is used to retrieve the first value of the substitution table entry with the key agatha.

Subst("../data/tables/author.tbl", "agatha");

 

Removing substitution tables from memory after use

A substitution table is kept in memory until the script function EraseSubst is called for that table. This means StreamServer performance will be affected if several tables are created in a job, and if the tables are never removed from memory during the job using the EraseSubst function.

For example, if you use variables in the table names, you must make sure there are a limited number of tables in the memory. In this case you must call EraseSubst for each table after it is used.

Substitution table functions

The table below contains a short description of each script function. For information about syntax, examples, etc., see the full description of each script function.

Function name	Description
AddSubst	Adds a value to the specified value column of the specified substitution table entry.
ClearSubst	Clears the contents of the specified substitution table, but does not remove the actual table from memory.
DelSubstKey	Deletes the specified entry from the specified substitution table.
DumpSubst	Dumps the names of all open substitution tables to a file on disk.
EraseSubst	Removes the specified substitution table from memory.
GetSubst	Returns the value from the specified value column in the specified substitution table entry.
GetSubstColCount	Returns the number of columns in the specified entry in the specified substitution table.
GetSubstKey	Returns a key from a substitution table.
GetSubstKeyCount	Returns the number of entries in a substitution table.
ReadSubst	Re-reads a substitution table from disk.
SetSubst	Assigns a value to an entry in a substitution table.
Subst	Returns the first value (value column 0) in the specified substitution table entry.
SubstArr	Looks up a key in a substitution table, and creates an array containing the entry values.
WriteSubst	Writes a substitution table to a specified path.