Author: Daniel Bergqvist
Keywords: jmri LogixNG reference tables

# LogixNG Reference - Chapter 11

## LogixNG Tables

LogixNG Tables are two dimensional data structures, like a spreadsheet.

Example:

| A | B | C | D
--- | --- | --- | --- | ---
1 |  | West yard | East yard | North yard
2 |  | Left entrance of the yard
3 | Leftmost turnout | IT101 | IT201 | IT301
4 | Left turnout | IT103 | IT203 | IT303
5 |  | Right entrance of the yard
6 | Rightmost turnout | IT112 | IT212 | IT312
7 | Right turnout | IT114 | IT214 | IT314

A table can be used to create a lookup table. It's accessed by either its system name or its user name, followed by a left square bracket, the name of the row, a comma, the name of the column, and a right square bracket.

Instead of the names of the row and column, it's also possible to use the row number or the column number. The row and column numbers start at 0 with the row names in column 0 and the column names in row 0. The first data cell is 1,1. In spreadsheet terms, this is B2.

Note that spreadsheet software, like Excel and LibreOffice Calc, has cell <column letter><row number> while references in JMRI has table[row,column]. Example: Cell B3 is table[2,1], since B3 is row 2 and column 1.

To avoid confusion, use the row and column names.

Example from the table above. These examples assume that IM3 has the value 'West yard', IM4 has the value 'Rightmost turnout' and IM5 has the value 'IQT22'.

Cell | Value | Note
IQT22[0,1] | West yard | Cell B1 has the name of column B
IQT22[2,0] | Leftmost turnout | Cell A3 has the name of row 2
Yard table[2,0] | Leftmost turnout | The user name of the table can be used to access the table
IQT22[3,2] | IT203 | Cell C4 has the value 'IT203'
IQT22[Left turnout,North yard] | IT303 | Column 'North yard' and row 'Left turnout' has the cell D4 with the value 'IT303'
Yard table[Left turnout,North yard] | IT303 | Column 'North yard' and row 'Left turnout' has the cell D4 with the value 'IT303'
IQT22[Leftmost turnout,{IM3}] | IT101 | IM3 is in curly brackets and have the value 'West yard' so this points to cell B3
IQT22[{IM4},East yard] | IT212 | IM4 is in curly brackets and have the value 'Rightmost turnout' so this points to cell C6
IQT22[{IM4},{IM3}] | IT112 | Column {IM3} and row {IM4} points to cell B6
{IM5}[{IM4},{IM3}] | IT112 | Even the table name can be accessed indirectly

Note that a Memory can point to a table. For example, if the memory IM7 has the value '{Yard table[{IM3},Leftmost turnout]}', LogixNG will look at IM7, and find that it's value is in curly brackets. It will then resolve the value inside these curly brackets, which is 'Yard table[{IM3},Leftmost turnout]'. It will then resolve the value of IM3 which has the value 'West yard'. It will then get the table cell 'Yard table[West yard,Leftmost turnout]' which is cell B3 with the value 'IT101'.

The tables are created using a spreadsheet program and then exported as a TAB delimited CSV file. PanelPro Tools ⇒ Tables ⇒ LogixNG ⇒ LogixNG Tables is used to load the table into JMRI memory. See LogixNG Tables Table for details. The table is not stored in the PanelPro data file. When the data file is loaded, a reference to the table will be used to load the CSV file into memory. The CSV file should be located in the user files location along with the PanelPro data file.

### Using comments in the table

It's useful to be able to add comments in the table, especially for large tables. Therefore LogixNG has a simple way to add comments to tables. If the header of a row or column is empty, LogixNG treats that row or column as a comment. So if you want to add a comment on a row, leave the first column on that row empty. And if you want to add a comment on a column, leave the first row on that column empty. If the first cell on a row or column is empty, the action "Table: For each" will skip that row or column entirely.

### The CSV File

The CSV files LogixNG uses must be separated with tab, not comma. In OpenOffice Calc, select {Tab} as the field delimiter.

You must not use single or double quotes in the CSV table. OpenOffice Calc uses different single quote characters at the beginning of a word and at the end of a word, and if you store a csv file with these, you might end up with non readable characters in the CSV file. OpenOffice Calc also writes non readable characters for double qoute characters to the CSV file.

Also, don't use backspace in the CSV file. It might later be supported to quote other characters so it's reserved fornow.

If a name has the characters comma, left or righ square bracket or left or right curly brackets, these characters must be escaped by preceding them with a backslash. Examples: \, \[ \] \{ \} \\

If a reference contains a backslash, it will take some more time to evaluate it than if it doesn't contain any backslash. So if it's possible to not use these special characters in references or names of beans, it's recommended.

### Table Actions

There are two LogixNG actions for working with tables

##### Table: For each

This is used to look at the rows for a column or the columns for a row.

The contents of a series of cells will be placed in a local variable. As each cell is processed, the action will be performed.

To create the action, select the Table: For each type from the Common category.

Select the table, row or column, and then the row name or column name. The name selection will change based on the table and row/column selections. Enter the name of a local variable. The table, row and column names can also refer to local variables or references.

After the action has been created, add another action to the new A1 do handle the current cell item.

##### Listen on beans - Table

Since the items in the table, such as turnouts and sensors, are accessed using references, when their state changes, there is no notification of the event. See Chapter 7 for details about the issue.

Rather than creating a Listen on beans list entry for each item, the Listen on beans - table action can simplify creating the listeners.

To create the action, select the Listen on beans - Table type from the Other category.

Select the table, row or column, and then the row name or column name. The name selection will change based on the table and row/column selections. Select the type of item. The supported types are Light, Memory, Sensor and Turnout.

## Tables - working with templates

The sample shown on the home page is an example of a template. A module is created that implements the locking logic. It can be used for any turnout that can be locked by a sensor.

The data for the template comes from a table. The table identifies the sensor that is used to request that a turnout be toggled, the sensor that can used to lock the turnout and the name of the turnout.

See Chapter 10 - Modules for details about modules.

The module is supplied the row name for the turnout. The row name is used to find the lock sensor. If the sensor is not active, the row name is used to find the turnout and set its state to toggle.

To invoke the module, a ConditionalNG sets the module's variable with a row name and calls the module.

Return to the Reference TOC