Home Tutorials A Guide to Checking and Fixing an MSTS .REF file

A Guide to Checking and Fixing an MSTS .REF file

by Yuri Sos

"Quick Fix" Link

If you're in a hurry, click here for quickest fix of 95% of errors.

Introduction

TsUtils, designed by Carl-Heinz Rive, is like having a Swiss Army knife within the Route_Riter Swiss Army knife. The very comprehensive Integrity-Check ("ichk") report has a section that reports any errors within the route's REF file.

This tutorial walks you through correcting the .REF file using both Route Riter and TsUtils. It is recommended that you install or upgrade to Route_Riter 7.0.43 or higher to make best use of the REF File Editor.

Executive Summary

Initially run Route Riter's REF file editor, then TsUtils "ichk" option.

Table of Contents


 

Getting Started

Read Understanding the TsUtils Integrity-Check Report File: the Getting Started section shows you how to generate the report we are going to use.

Once you've generated the report, scroll past the thousands of Missing Shapes messages until you come to the .REF file section. If there's no error, you will get a one-line message that the .REF file has been loaded and checked - like this.

Commonly, though TsUtils will return a variety of errors. We propose to run through these errors and give you hints on their correction.
 

Error Correction Part 1: The Most Common Error - The Missing Bracket

Typically and most commonly, the errors that are found within the REF file are related to missing brackets and missing or erroneous parameters. You need to find and correct this error as shapes referenced below the missing bracket cannot be accessed in Route Editor. The missing bracket also masks errors further down the REF file.

Let's look at an example - here's a typical REF file report:

If you look at the report, you can see that there is a keyword error: this is usually the giveaway for a missing bracket: note that the number AFTER the keyword STATIC points to the line number in the REF file.

Let's open the REF file in ConTEXT, turn on line numbering (Options | Environment Options | Editor [x] Line Numbers) and jump to the line number in question (Ctrl-G):

It's immediately very clear that the problem with the keyword Static is that the shape reference immediately above is lacking a closing bracket. This is why the ref file is not examined below this error and may account for the subsequent EOF error.

There are two ways to correct this error:

  1. Insert the closing bracket at line 2655, save the REF file and run the ichk again: this certainly works but option #2 below is better because it corrects a few things at the same time.
     
  2. The preferred method to correct bracket errors is to use Route_Riter's REF File Editor. In fact, it's probably preferable to run this option as a matter of course before TsUtils' "ichk" report. Route developers should run this option to ensure that they have access to all the shapes they think they have: dropping a bracket is so easy to do. The method demonstrated here fixes bracket errors, "names-with-spaces-not-enclosed-in-quotes" errors and removes duplicate shape references.

    Open Route_Riter.

    1. Select your route (arrow #1).
    2. Click on "Confirm Route" (arrow #2).
    3. Click on the route's REF file (arrow #3).
    4. Click on the REF File Editor button (arrow #4).

    5. Route_Riter will then check all the shapes in the Shapes folder and compare them to the REF file. The REF file is then presented in an Excel-like spreadsheet format. It doesn't display the four standard items - DYNTRACK, PLATFORM, SIDING, CARSPAWNER: Route_Riter will add these definitions to the top of any REF file automatically on saving. Route_Riter also saves the original REF file as a backup in case you've made an error.

      The quick-fix method is to

      1. click "Delete Duplicates" (arrow #1); Route_Riter will ask you to confirm (some route developers have the same shape file in two separate classes for ease of use);
      2. re-index .REF file (arrow #2); then
      3. click "Save New REF" (arrow #3).

This has taken care of over 95% of REF file errors. TsUtils will now help you to correct any REF file errors that are left.

Error Correction Part 2: some of the rest!

Section Incomplete - I'm still looking for more examples to demonstrate repair techniques - email me if you have one of interest

Back to the REF file we looked at before - now we have an error on line 4747 (beyond where the bracket error was - note that this error only appeared after we corrected the bracket error).

Here's the area in ConTEXT.

Remove the invalid "ALIGN" line and after tunning "ichk" again, all errors in this section are cleared - thus the REF file is now correct.

Here's another example: this one mentioned in a recent post on train-sim.com.

Once again the relevant "ichk" .REF file report:

Now let's run it through Route Riter's REF file editor; the editor's fixed just about everything - see below - this is why I suggest that you run the REF file Editor before you do anything else:

Now open ConTEXT and scroll to the line number: I've moved the "wrong" Platform reference up to the correct one for this screenshot so that you can see the error. A blank filename line had been inserted.

Delete this faulty "Platform" reference and that's got rid of all the errors.

Not all the errors are exactly the same as demonstrated above, but I hope you can see the methodolgy and structure to correcting these errors.

Error Correction Part 3: A Shape Is Listed In The REF File That Is Not In The Shapes Folder

This one is self-evident: there's no matching shape in the SHAPES directory. Either place the shape's files (.S, .SD into Shapes folder, .ACE(s) into Textures folder) or delete the entry using the Ref File Editor.

This one appears a little trickier at first glance, but it isn't. As there's no filename in the error message it means there is a static shape definition with no shape specified or a blank shape specified, ie the REF File definition will have either omitted the Filename line altogether or have a line such as Filename ( "" ) .

Repair by the following method:

  1. In Route File Editor, click on Delete duplicates, then click on Filename column header (arrow #1 below) to sort the REF file entries.
  2. The top static entry/entries will contain a blank for filename (arrow #2).
  3. Select row by clicking on index number. Click Delete Row (arrow#3). Click Re-index REF File. Click Save New REF file.

Fine-tuning your REF file (mainly for route developers)

I hope you've found this tutorial of benefit.

Enjoy.

10-17 Aug 2007, 20 Aug 2007