Author: Jerry Grochow

# JMRI: Understanding the Data Management

A Work-In-Progress

since 4.23.3

Note: The PanelPro main menu is being changed. See Loading and Storing Your Work for details. The menu references below are for the new menu structure with the old menu paths in braces.

- Elements by Category
- Category/Alpha Index

This page includes information intended for advanced users of JMRI. Basic information on commands to load and store your work is available here. The additional information containted on the current page is not necessary for ordinary, day-to-day use of JMRI but may be of interest to those who want to understand in more detail when, how, and where JMRI stores the data you and the system create and update.

As you work with JMRI, you will create and update many different items within its various applications and tools. You may also develop and run "scripts" (external programs) that will do that as well. JMRI will update some of these at certain points during train operation. Although JMRI tries to hide lots of technical details from you, some model railroaders want to know how things work: what data is created when you take various actions, when it gets updated by the JMRI programs, and also whether it gets saved once you quit JMRI and come back at another time. This page provides a reference guide to all JMRI data, how it gets created and updated, when it gets saved (some doesn't!), and, for more advanced users, where it gets stored.

We want to stress that this is additional technical detail. You should not need to know this for normal operation of the programs. If you find that you do, perhaps there's something going wrong, and before reading this page you should ask for help on the JmriUsers group or elsewhere.

The Elements by Category table columns show the following information:

Category: The tables below categorize the different types of JMRI data to make this information easier to present and hopefully to understand. These categories are shown in the column labelled "Category":

- Layout Elements: all the things that describe my layout and how it works, such as turnouts, tracks, pictures there of, blocks, signals, etc.). All this information is entered in PanelPro.
- Roster Information: roster entries for each of your engines and other DCC controlled accessories, pictures of engines, the roster itself, and related information. Roster information is entered in DecoderPro.
- Operations Elements: data related to operating your railroad (manually or with some degree of automation) such as warrants, paths, and dozens of other things. Operational elements are entered in various "Tools" listed in PanelPro including "Dispatacher...".
- System Preferences: all the things you enter under Preferences, either in DecoderPro or PanelPro.

Creates/Stores:When it comes to saving what you input and/or what JMRI does with that input, there are multiple different situations, shown in the table column "Creates/Stores". There is data that is:

- User created, user stored (e.g. turnout table entries, layout panels, connections, start-up preferences)
- User created, automatically stored (e.g. size and position of windows, roster entries when change made to the roster table)
- Automatically created, user stored (e.g. Logix from LRoute)
- Automatically created, automatically stored (e.g. default profile)
- Automatically created, not stored! (e.g. turnout status)

The key to successful operation with JMRI is understanding which is which. And that is what the tables below will show you.

Save Command:Unfortunately, there is no single command to save all user created or modified data. It is important to recognize when and where you have to take some action to make sure your work is there the next time you come back to it. As the table shows in the column labelled "Save Command", these are the places where a command to "save" or "store" will save and store some portion of your work:

1. Preferences: "Save"
2. Panel editors: File ⇒ Store ALL table content and panels... {Old: File ⇒ Store Panels...} or use the PanelPro main menu item File ⇒ Store ALL table content and panels... {Old: Panels ⇒ Store Panels...}
3. Tables (also Fast Clock): File ⇒ Store ⇒
   (a) Store Only table content (No Panels)... {Old: Store configuration} or
   (b) Store ALL table content and panels... {Old: Store configuration and panels}
4. Roster entry: (a) automatic (b) File ⇒ Save or "Save to Roster" (c) "Write" to Decoder
5. Images/Icons: "Save Image Index"
6. Scripts: "Store..." (on Script Entry window)

These commands are identified in the tables by these numbers.

Where Stored: Data stored on disk by JMRI is separated into a number of files and directories. The typical user shouldn't have to deal with these, but for those who are interested, see the help page on Profile File Structure.

## JMRI Elements by Category

This index cross-references JMRI data by Category: Layout Element, Operations Element, Roster Element, Preferences, and Other. The column Creates/Saves uses abbreviations for the situations listed above, e.g. "UC/US" means "User Created/ User Stored." The Store Command uses the numbers above for the different commands.

Click a heading to sort the list up or down by that column.

Category | Data Types | Where Created | Creates/Stores | Store Command | Where Stored |
--- | --- | --- | --- | --- | --- | ---
Layout Elements | LE Panels, Track Connections, Block Assignments, Signal Placement | Layout Editor | UC/US | 2, 3(b) | "[user named].xml" files where specified (default is the User Files Location directory) | ✔
Layout Elements | Sensor, Turnout, Block, Light | Table for specific element type | UC/US | 2, 3(a), 3(b) | "[user named].xml" files where specified (default is the User Files Location directory) | ✔
Layout Elements | Icons, Images, Image Index | Icon Editor, Image Index Editor | UC/US | 5 | Image/icon files where specified (default is the User Files Location directory). Image index in catalogTrees.xml in the Preferences locaiton. |
Layout Elements | Blocks | Block Table | UC/US | 2, 3(a), 3(b) | "[user named].xml" files where specified (default is the User Files Location directory) | ✔
Operations Elements | Throttles | ?? | UC/US |  |  |
Operations Elements | Consisting | ?? | UC/US |  |  |
Operations Elements | Block Contents (Value) | ?? | UC/US followed by AS | User enters first Block Value, then JMRI updates automatically. | blockvalues.xml in Preferences location | ✔
Operations Elements | Sensor Status, Turnout Status, Block (Occupancy) Status | Table for specific element type | AC/NS | Status data is not saved when JMRI is closed. | NA | ✔
Operations Elements | Occupancy Block (OBlock) | OBlock Table | UC/US | 2, 3(a), 3(b) | "[user named].xml" files where specified (default is the User Files Location directory) | ✔
Operations Elements | OBlock, Portal, OPath | Circuit Builder | AC/US | 2, 3(a), 3(b) | "[user named].xml" files where specified (default is the User Files Location directory) | ✔
Operations Elements | Scripts | Script Entry window or external editor | UC/US | 6 | Scripts are stored in ".py" or ".js" files where specified by user (default: Script Location) | ✔
Operations Elements | Speedometer |  | UC/US | Tools->Speedometer, Hit "Save as default" | In ?? in Preferences location. NOTE: Sensor names are saved and reappear when JMRI reopens even though they may not be defined at that point. You must then load a panel or otherwise define the sensors. |
Operations Elements | Timetable data |  | UC/US | Tools->Timetable, Hit "Save" | In timetable/TimeTableData.xml in Preferences location |
Operations Elements | CTC data |  | UC/US | 2, 3(a), 3(b) | Included in the tables and panels xml data file |
Operations Elements | Dispatcher |  | UC/US | ? | In dispatcheroptions.xml in Preferences location |
Operations Elements | Dispatcher trains |  | UC/US | ? | In dispatcheroptions.xml in Preferences location |
Operations Elements | OperationsPro data | Operations Pro (Operations menu) | UC/AS | Appropriate file saved when changes made | In six files in operations/ in User Files location | ✔
Other | Window size/location |  | UC/AS | Saved when window is moved or resized | Saved in the user-interface.xml file in the Profile location. |
Other | Backup panels | Whenever panels or tables are stored | AC/AS | NA | In backupPanels/ in Profile location | ✔
Roster Info | Roster Entry Info | Changing info on main Roster page | UC/AS | 4(a) | Individual files in subdirectory "roster" in Roster Files Location | ✔
Roster Info | Roster Entry (full) | "Save" Roster Entry | UC/US | 4(b) | Individual files in subdirectory "roster" in Roster Files Location | ✔
Roster Info | Decoder CVs | "Write" Roster Entry | UC/US | 4(c) | Individual files in subdirectory "roster" in Roster Files Location | ✔
Roster Info | Roster Group | DecoderPro Settings-> options for Roster Group | UC/AS | 4(a) | roster.xml Roster Files Location | ✔
Roster Info | Consisting | Select "Consist" tab on individual roster entry | UC/US |  | Individual decoder files in Roster Files Location |
Roster Info | Consisting | Direct Entry to Consisting window | UC/NS | ?? | Not saved. |
System Preferences | Config Profiles | Select Config Profiles in Preferences window under Edit pulldown | UC/US | 1 | In subdirectories under Config File locaiton. | ✔
System Preferences | Connections, Defaults, File Locations, Start Up Actions, etc. | Select different items in Preferences window under Edit pulldown | UC/US | 1 | In several different files in the Settings Location. | ✔
MORE | MORE |  |  | 1, 2, 3(a), 3(b), 4(a), 4(b), 4(c), 5, 6? |  |

[Go to top of page]

## Category/Alphabetic Index

This index cross-references hardware and products by the categories under which they appear on this page. Click on a category to go to that category on this page. Click on a hardware item to go to the JMRI Help page for that product or family. The sidebar provides an alphabetic list.

Layout elements: Describe the physical layout

- Layout Editor (LE) Panel
- Control Panel Editor (CPE) Panel
- Block
- Turnout
- Sensor
- Light
- MORE

Roster information: Specify engine and other DCC controlled components

- Roster main page
- Roster entry
- Roster group

Operations elements: Additional information about the physical layout used for operational control of the railroad

- Block
- OBlock
- OPath
- Portal
- Route
- LRoute
- Warrant
- Script
- Memory Variable
- MORE

System preferences: Information used by JMRI to customize look, feel, and operation of the JMRI system

- Connection
- Start-up
- MORE

Other:

- Window size/position
- Script
- MORE

[Go to top of page]