MSTS_Check (v2.

0b) (September 2018)

===========
Program Description
----------------------------
There are two separate parts to this program, Main Program and Report Management; the
latter is detailed below.

Main Program

Pressing <START> results in the standard Windows folder selection screen being displayed.

If the selected folder doesn't contain SOUND and TRAINS folders, it is reported as being invalid
and re-selection is
requested.
If a valid folder is selected, the user is asked to choose the group of SourceLists to be used for
displaying Suggested
Source/s for missing items. If the required Group is already selected, continue with selection of
the element to be
checked, otherwise click on an "empty" circle, then press <Cabviews>, <Sounds> or <FA / PV>,
depending on which
are to be checked. Pressing <QUIT> at any time will close the program.

NOTE : The SourceList Groups are : UK for UK-based stock, NA for North American-oriented
stock, User is for user-created SourceList files and None will result in the reports produced not
including Suggested Source/s entries. On the first run
after installation, 'None' will be selected. See Appendix A to these instructions for details
regarding creating and/or
amending SourceList files.

The parent of the selected root folder and the selected Group will be "remembered" the next
time the program is run.
These are held in the Registry key : HKEY_CURRENT_USER\Software\Ged's-
Utilities\MSTS_Check.

The selected root folder's TRAINSET folder is scanned. Depending on which check is selected, it
will a) check .eng files
only for the presence of a cabview file matching that shown in the cabview line, b) check .eng
and .wag files for the
presence of .sms files matching those shown in the Sound lines or c) check .eng and .wag files for
the presence of a shape
file matching that shown in the FreightAnim and PassengerCabinFile lines.

While the scanning is taking place, the current folder being processed is shown in the bottom
part of the display and the
<QUIT> button is replaced by <Cancel>; this allows the process to be cancelled, if required. If
the process is cancelled,
<Cabviews>, <Sounds> and <FA / PV> will not be available until <START> has been pressed to
select/re-select a root folder.
IMPORTANT NOTE : If <Cancel> is pressed while a scan is in progress, an incomplete report will
be produced.

Although MSTS won't be stopped by missing .ace or .wav files, this program checks for the
presence of each .ace and
.wav referenced by .cvf and .sms files respectively. Each missing file will be listed, showing the
actual line of
entry from the .cvf or .sms file together with the full specified path to that file. This information
may be useful when
investigating why certain images aren't shown in cabviews, or why certain sounds aren't heard.

Files may be aliased, or not; if a .wav file is not aliased, and is not present in the same folder as
the .sms file, the global
SOUND folder is checked. A number of .sms files have been found where the author intented to
use a .wav file from the
global SOUND folder, but entered it as an aliased path, like :-
..//..//KIHA31//SOUND//x_uncouple_auto1.wav In such
cases, MSTS is unable to find the file.

If no errors are detected, a screen similar to the following will be shown :

If errors are detected, the screen displayed will be like this:

The mentioned report will also be displayed.

More details of the reports are in Reports, below.

If it's desired to check more than one installation, it's NOT necessary to close and re-open the
program - press <START>
to select another. Similarly, after checking an installation, it's not necessary to close the program
to make amendments
or corrections to that installation - make the required changes, then select the appropriate
option (<CABVIEWS>, <SOUNDS> or <FA / PV>) to re-check. If a different installation is selected,
the appropriate SourceLists Group may be chosen.

The program makes absolutely no changes to any files in the MSTS/ORTS installation or Registry
entries.

Report Management
The Reports button will only be available after a valid MSTS/ORTS root folder has been
selected. Pressing <Reports> results in the left screen being displayed and selecting <Cabviews>,
<Sounds> or <FA / PV> displays a screen similar to that
on the right. If there are no reports for the selected category, an appropriate message will be
shown.

An existing report may be displayed (using the Windows default .txt file viewer) or deleted, by
pressing the appropriate
button. Only one report may be selected at any time, but using <Delete All> will delete all the
listed reports.
Pressing <BACK> will return to the previous screen to allow either the display or deletion of
another set of reports, or to
return to the initial MSTS_Check screen. Pressing <FINISH> will then return to the initial
MSTS_Check screen.

Detail
--------
General
----------
The required lines in a .eng or .wag file are those, not within Comment or Description
statements, containing 'Cabview', 'Sound', 'FreightAmin' or 'PassengerCabinFile'. All checks are
case-insensitive.

Cabviews (.cvf)
--------------------
The "cabview" line is read; if the cvf file is aliased, the path is followed and if not, the CABVIEW
folder within the loco's
folder is checked for the existence of the specified cvf file. Wherever the .cvf file is located, the
presence of each
referenced .ace file, aliased or not, is verified. The line containing each missing .ace file is shown
on the report,
together with its line number and full path. If a folder is missing, it will be shown together with a
Suggested Source, if
available. If the .cvf file is not in the indicated location, it is considered to be missing and details
are included in the report.

Sounds (.sms)
-------------------
A similar procedure is carried out for checking for the presence of matching .sms files and
their .wav files. In addition,
if a .sms file is not aliased and is not in the stock's SOUND folder, the global SOUND folder is
checked. Similarly, if a
.wav file is is not aliased and not present in the same folder as the .sms file, the global SOUND
folder is checked.
Missing .wav files are shown similarly to missing .ace files, as described under Cabviews (.cvf)
If the .sms file is not in the indicated position, or any of the .wav files cannot be found in their
specified locations, a
report will be created.

Freight Animations / Passenger Views (.s)

--------------------------------------------------------
If a vehicle contains FreightAnim and/or PassengerCabinFile lines, and a specified shape (.s) file
cannot be found
(aliased or not), details are included on a report.

General Checking
------------------------
.eng and .wag files may use any of the following to link to an aliased .cvf or .sms
file : ..//..//, ../../, and ..\\ ..\\.
Whichever is used, the program will treat them correctly to link to an aliased file.
Similarly, ../, ..// , and ..\\ may be
used for Freight Animations and Passenger Views. Note that, although ..\ is the standard
Windows path separator, MSTS doesn't recognise it, and if found in an alias path, will be
reported as an error.
If any of the selected lines contains an incorrect, or missing, extension - eg .cfv instead of .cvf, or
the dot is missing
before the extension they will be shown on the report and not processed.

Missing WagonShape files

Legitimate .eng / .wag files are identified by having the shape file specified in the WagonShape
line, present in the
same folder as the eng file. Any without a matching shape file are reported and ignored
regarding further checks.
Within a session (ie after <START> has been pressed and before it is pressed again, or <QUIT> is
pressed), missing
WagonShape files will be reported only once, as follows :
(i) If <Cabviews> is pressed first, WagonShape files missing for .eng files will be reported
(ii) If <Sounds> or <FA/ PV> is pressed first, Wagonshape files missing for .eng and .wag files will
be reported.
(iii) If <Sounds> or <FA/ PV> is pressed after <Cabviews>, only WagonShape files missing for .wag
files will be reported.
(vi) If <Cabviews> is pressed after <Sounds> or <FA/PV>, no missing WagonShape files will be
reported.
Subsequent re-pressing of any button will result in no missing WagonShape files being reported,
but this does not mean
that none are missing. It is recommended that, after correcting reported errors, either <START>
must be re-pressed, or
the program restarted.

Reports
-----------
Separate reports are created for missing cabviews, sounds and freight animations/passenger
views. Each report uses
an optional SourceList file (see Appendix A) to show the possible source/s for any missing files.
The report files are
named cvfReport*.txt, smsReport*.txt and faReport*.txt respectively, where * is a number; they
will be saved in a folder named MSTS_Check_Reports, stored within the selected MSTS/ORTS
root folder.

Each run of the same type will create a new report file. If a report is created, it will be displayed
on the screen when
the run completes. If no missing files are detected, no report will be produced, but a message
will be shown on-screen.

A list of missing .ace (cabviews) and .wav (sounds) files within a stock folder is shown, based on
their entries in the
.cvf or .sms files respectively.
It should be noted that a large number of .sms files specify .wav files which are stored in the
global SOUND folder (eg x_couple_chain1.wav), but have an aliased address, eg
"..//..//GP38//sound//uncouple_auto1.wav". MSTS will NOT
find these sounds, therefore this program reports them as 'missing'. If the .sms file line was
"uncouple_auto1.wav",
it would work correctly.
For cabviews, there only appears to be one .ace file which is regularly entered incorrectly; this is
coal.ace (in the
FuelCoal entry for steam locos). This is the converse of the above in that it's often shown as non-
aliased when it should
be aliased, eg "..//..//SCOTSMAN//Cabview//coal.ace". Again, MSTS won't find the non-aliased
version, UNLESS it's in
the same folder as the .cvf file.
Also for cabviews, the CabviewWindowFile entries in .cvf files are ignored as they often refer to
non-existent files.

If a file or path name contains illegal characters, it will be reported and no processing will be
performed on it. Illegal
characters are defined as being the standard Windows list, together with a single back-slash [ \ ],
and a space, if the
file/path name is not enclosed in double-quotes. The standard Windows list comprises : " < >
| * ? and any control character (ASCII 0-31).

Some details shown in a report are dependent on the chosen SourceList Group.

This document also contains Appendix B, which details my interpretation of how aliasing works.

Limitations
---------------
1. Some locos use .cvf or .sms files named the same as a default file (eg. gp38) but point to a
different cabview folder.
If the latter folder is present there is no problem, but if it isn't, there's no way to determine the
actual cabview required;
these cases may be covered by additional entries in the appropriate SourceList. If a "Suggested
Source" cannot be
determined, it is shown as "Unknown".
2. The "Suggested Source/s" (if present) are just that. If one of those doesn't work, the stock's
readme must be consulted
to ascertain its actual requirements.
3. Use of most of the "Suggested Source/s" entries will entail an element of file/folder editing,
be it renaming or
aliasing/re-aliasing.
4. As a new report is created each time the program is run, it is recommended that the Report
Management facility is
used to remove any obsolete or unwanted files.

Installation
----------------
The program may be installed wherever the user wishes, but it's recommended to keep clear of
the "protected folders"
for Vista and later. The default location is C:\MSTS_Check v2.0. The installation folder will also
contain the supplied
SourceList files, which the user may remove, or update using any text editor, like NotePad - see
Appendix A.

Uninstallation
-------------------
Use the Control Panel or Start Menu option. If report files have not been previously deleted, it
will be necessary to
manually delete the installation folder.

Thanks, Acknowledgements & Legal Bits

-------------------------------------------------------
Thanks to David (Shawmut), Bob (scampispeedway), David (dforrest), Gerry (R. H. Steele), Bob
Latimer, Alec (rufuskins), Jonathan (Jonathan David), Roderic (RIGFindlay) and Charles (cstagg)
for their suggestions, comments and help in testing
this, and previous versions of this program.

The icon used is a renamed version of Webalys-Kameleon.pics-Chessboard.ico, which may be

freely used for
non-commercial purposes and is available from : http://www.iconarchive.com/

THIS PROGRAM will be uploaded to UKTS, trainsim.com, TSSH and elvastower.com. It may be
uploaded to any other
site, without seeking my permission. The source code may be made available on receipt of a PM
to any of the Forums
listed below, but I reserve the right to refuse the request without giving a reason. Modified
versions of the program
may be uploaded to any site, without my permission, on condition that it is renamed and
contains this readme file.
Contact via PM on FORUMS : UKTS & TSSH - slipperman12; trainsim.com & elvastower -
slipperman

Sept. 2018 (v2.0b) (Minor bug fixed in missing .sms routine)

G. Saunders
APPENDIX A - SourceList Files
===========================
General
These files are optional, but if present, MUST be in the same folder as the program.
If the file is empty, it is treated the same as if it was missing. If a SourceList file for a particular
category is not present, or
is empty, the equivalent report will not show the several "Key" lines near to the top, or the
"Suggested Source/s".

Separate files are used for cabviews, sounds and freight animations. Different groups of files are
supplied for UK and
North American oriented installations; the appropriate Group to be used is user-selectable. The
user may optionally
select "None", which will not show "Suggested Source/s" on any reports produced, or "User" to
employ any user-created
SourceList files.

As supplied, the lines in the SourceList files are (mainly) in alphanumerical order, but that isn't
essential. They are easier
to maintain if that order is retained, but the user can add new lines wherever they wish, as long
as there are no blank
lines between 'block' of data. The items which are out of order are those using a unique part of
the path to identify their source.

They are plain txt files and may be updated by the user as required (see below) - the order of
entries is not critical, but
are supplied in alphanumerical order to ease maintenance.

Creating/Amending a SourceList File

These are normal text (.txt) files and their names MUST be the Group followed by "-SourceList-"
followed by "Cabviews", "Sounds" or "FAs", for example "User-SourceList-Sounds.txt" (As is
standard in Windows, case is unimportant).

Each line of entry in a SourceList file comprises two values separated by a comma. The first may
be a file name of the
appropriate type (.cvf, .sms or .s) or a unique string of characters, probably from a file's path, to
be searched for. The
second will be one or more suggested sources for that file.

First Value
This may be a file name (of the appropriate type), eg gp9.cvf. It is only the file name and must
not include any other part
of its path (ie folder/s).
Where commonly used file names are used (eg sd402eng.sms), but are accessed via a specific
path, the first value may be
a uniquely identifiable part of that path (eg. \567_Turbo\). If used in this way, the file name and
type must not be used.
NOTE : Even though the path separators within MSTS files may be \\, \, // or /, if used in entries
in these files, the Windows
standard of \ MUST be used.
The user is completely at liberty to choose their own 'unique' part of a path as it is only to be
used on their installation/s.

Second Value
This should either be the UKTS file ID number (if applicable) or the actual name of the file to be
downloaded. One or more
options will be indicated by / between file names/file IDs. Where a combination of files must
be installed, + will be shown
between two or more file names/file IDs.

Appendix B - Aliasing in MSTS (and Open Rails)

==========================================
The following is my understanding of how aliasing works, based on extensive testing for
MSTS_Check. It should not be taken as the definitive guide on the subject and if I've got
anything radically wrong, please let me know, and I'd be
pleased to make the appropriate corrections.

May I offer my thanks to David (dforrest) for clarifying my understanding, particularly regarding
Freight Animation
aliasing, but also sorting out a few other niggles I had. I have made some modifications to this
document since it was
first published (21 February 2017).

This is more correctly known as Relative Addressing and has been an integral part of MSTS since
the early days.

I have seen many tutorials and Forum posts on how to do it for cabviews and sounds, but I've
never seen any
explanations of what ..//..// etc., mean. The purpose of this article is to clarify how it works, for
MSTS, although the general principles apply to Windows in general.

Before going any further, MSTS appears to use a selection of path separators - /, // and \\ but
treats them all in the same way. This document only uses the double forward-slash (..//)
because MSTS doesn't accept the Windows standard -
single back-slash (\), although, strangely, it uses them in error messages.

Cabviews and sounds are very similar, but there is one difference between them, so they will be
taken separately.

In the examples shown below, and MSTS as a whole, the quotes ("") surrounding an entry are
not essential if there are
no spaces within it, but it has almost become an "industry standard" that they are used for all
entries. MSTS doesn't complain.

Cabviews
The entry in a .eng file may be : Cabview ( gp38.cvf )
This means that file gp38.cvf is expected to be in the Cabview folder in the same folder as the
.eng file.

Alternatively, it might look like this : Cabview ( "..//..//Dash9//Cabview//Dash9.cvf" )

In this case, the cabview is aliased to that of the default Dash 9 locomotive (in the same
TRAINSET folder).
NOTE : This entry is only an example; it won't work in practice because the individual .ace files in
the Dash9's Cabview folder aren't aliased.

Or, it might look like this : CabView ( "..//..//Common.Cab//Tanker//Tanker.cvf" ) where, the

cabview file is expected
to be in folder Tanker, which is in folder Common.Cab, which is in the TRAINSET folder.

Within a cabview (.cvf) file, there will be many entries specifying texture (.ace) files. The same
system is used to locate these files. If it's shown like this : CabViewFile ( class50cableft.ace ),
the .ace file is expected to be in the same folder as
the .cvf file itself, or, if not there, in the loco's CABVIEW folder, if different.
An alternative is this : CabViewFile ( ..//..//Scotsman//CabView//scothudleft.ace ), in which case
the specified file will
be looked for in the Scotsman's cabview folder.

If a .ace file is not in the loco's Cabview folder, its entry in the .cvf file must alias to its actual
location.

Sounds
An entry may look like this : Sound ( "d9eng.sms" ) which means that file d9eng.sms is expected
to be in the Sound
folder, within the folder containing the .eng file. If it's not in that folder, or that folder is missing,
MSTS looks in the
"global" SOUND folder (found in the root (Train Simulator) folder). This often, but not
exclusively, applies to wagons
and coaches (.wag files), which don't normally have their own SOUND folders. An example :
Sound ( "GenFreightWag2.sms" )
Alternatively, an entry like this : Sound ( "..//..//common.sound//2cyl_generic//2c-140b-
eng01.sms" ) indicates that the .sms file is in the 2cyl_generic folder which is within the
common.sound folder.

In a .sms file, there will be several "calls" to sound (.wav) files, like : StartLoop ( 1 File
( "c50_power_cruise3.wav" -1 ) which shows that the required file is expected to be in either the
same folder as the .sms file, or if not, in the "global"
SOUND folder. If it looks like this : File ( "..//..//Dash9//Sound//x_d9_sand.wav" -1 ), the file is
expected to be in the
Sound folder of the Dash9 loco.

if a .wav file is not in the same folder as its calling .sms file and not in the global SOUND folder,
its entry in the .sms file must alias to its actual location.

Freight Animations / Passenger Views

An entry may look like this : FreightAnim ( crew_20.s 1 1 ) or FreightAnim
( "..//common.crew//LIB_1//N2.s" 0.1 0.1 ).
The first is not aliased, so the shape file (crew_20.s) is expected to be in the same folder as the
.eng file. In the second example, the shape file is expected to be in the common.crew folder
which is in the current folder's parent folder.

How it works
Relative addressing
Each ..// (or MSTS variation) moves into the folder one level above the current location, which I'll
call the 'default' level.

For .cvf (Cabview) and .sms (Sound) files, the 'default' level is the CABVIEW and SOUNDS folder
respectively; for Freight Animations and Passenger Views, it is the loco/wag folder.
In the above examples, Loco1's eng file has an entry : Sound
( "..//..//common.sound//locoID//locoeng.sms" ). ..//..// means move up two folder levels - the
first level is folder Loco1 and the second is TRAINSET. The system is then
instructed to look for folder common.sound within that second level folder and then to folder
locoID within
common.sound in which file locoeng.sms is expected to be found.

.ace files (Cabview textures)

The 'default' level is ALWAYS the current loco's CABVIEW folder. Any unaliased .ace files are
expected to be in that
folder, wherever the .cvf file is located.

.wav files (Sounds)

The 'default' level is the folder containing the .sms file. Any unaliased .wav files are expected to
be in either the folder
containing the .sms file, or, if not there, in the global SOUND folder (in the MSTS root folder,
which, by default, is Train Simulator).

.s (Freight Animation / Passenger View) files

The 'default' level is the folder containing the .eng/.wag file.