
	Trainsimulator - Utility "TSUtil"



Version     : 3.3.06
Programdate : 13.07.2007

Instructions:

This utility was developed to simplify maintenance and modification of TS-routes. Therfore,
there are some, so called, 'Functions', which will be described in the following: 

INTRODUCTION:
All you need to use this utility is a working "Java-Runtime-Environment".

After the installation (see also: Installaion of ... in 'readme.txt') TSUtil can be used
immediately. TSUtil is always called as a 'Java-Application' from within a DOS-Window, regardless
of the function you like to use. Because there is no GUI, the activation of the functions are
a little bit 'tricky' and output (errors and messages) are directed to the window, but the
usage is quite effective.
If someone changes the standard-buffer-values of the DOS-Window (e.g. 400 lines) all messages
could easely be checked. Nevertheless it's better to have a LOG-File written, because this file
will contain additional informations.

IMPORTANT:
  If you enter some data, you should be aware of the case of letters. Although the program ist not
  sensitive to case in all circumstances, it is better to pay attention to case of all your input
  in order to avoid errors.

IMPORTANT:
  ALWAYS be sure that you have a backup of the files, before you are going to work with TSUtil.

VERY IMPORTANT:
  Since version 3, and if not stated otherwise, ALL function have been changed so that they only
  work on 'marked tiles'. So, tile-, world- or sound-files, which do NOT correspond to marked
  tiles are not processed, although they may exist in the appropriate directory. Perhaps you
  have to change the route with the Geometry-Extractor to mark all used tiles as populated.

BACKGROUND to the form of world-files:
  In order to change world-files, they must exists in the so-called UT-Form":
  World-files (.w) can take one of FOUR different file-fomats:
	- [UT] uncompressed Text - File (Unicode, Marker starts with: "SIMISA@@")
	- [CT] compressed Text - File (Unicode, Marker starts with: "SIMISA@F")
	- [UB] uncompressed Binary - File (ASCII, Marker starts with: "SIMISA@@")
	- [CB] compressed Binary - File (ASCII, Marker starts with: "SIMISA@F")
  Remark: My naming conventions are:
	'uncompressed text'-format is also called 'expanded' format
	'uncompressed binary'-format is also called 'reduced' or 'tokenized' format.
	Both formats can be additionally compressed using Z-Lib	algorithm.
  Trainsimulator(TS) provides a tool called "ffeditc_unicode", which can convert world-files between
  the different forms. One call converts:
	a) Option /u :	UT->UB; UB->UT; CT->UB; CB->UT
	b) Option /c :	UT->CB; UB->CT; CT->CB; CB->CT
  So, sometimes it is neccessary to convert a world-file more than once (Option /u) to reach UT-Form
  (CT->UB->UT). UT-Form is the ONLY version of a world-file, which can be modified with an editor.
  You can read the first 7 or 8 characters of a world-file, to distinguish between the 4 forms. Then you
  have to compare these characters with the marker-definition. First, you must read the file using binary-
  mode in order to check if the file is a binary file. Only if the read characters cannot be interpreted,
  you can read file-header again using unicode-mode. Reading of a binary file in unicode-mode will
  create a read-error, because invalid unicode-characters are recognized.

  The use of "ffeditc_unicode" is NOT error-free. A single conversion can make some objects invisible from
  special directions and make them unselectable, too. Route-Editor(RE) can convert all tiles to UT-Form
  without an error. Compareing the results of such conversions shows, that "ViewDbSphere" - entries have a
  much deeper structure and therefore longer recordlength when they are uncompressed with "ffeditc_unicode".
  In order to convert a world-file to UT-form without a error, it is necessary to use Route-Editor.

  To decompress or compress world-files without an error, you can ALSO use the 'DeComp'- or 'Comp'-Program
  of Martyn Griffin (recmp119.zip). These Programs are/were also implemented in Route-Riter, which can do
  the job, too.
  ATTENTION: These programs cannot handle world-files which use the CT-Form. In these cases you must use
	"ffeditc_unicode" or the Route-Editor.

  You also can compress/decompress/reduce/expand files with a program-module from Okrasa Ghia. This new
  module is also implemented in Route-Riter starting with version 6. The performance of any conversation
  is very good and a stand-alone version is also available(zipper/tk_utils). 
  ATTENTION: This module needs MS 'framework.net'-Environment

  Due to cooperation with Mike Simpson (Route-Riter), TSUtil-version 3.0.140 (and later) contains a
  program-module which decompresses/expands World-, Tile- or Shape-files, while reading. On the other side
  the module compresses/reduces data, while writing to a file. So, the precondition, that a function requires
  a decompressed/expanded file, is no longer valid.

  Remark: The track-/road-database always use a storage-mode, which can be directly read and modified.
END of background


A short help can be shown with the following command:
	C>java TSUtil ?

When calling TSUtil, 'Systemoptions' can be inserted. These options depend on the used runtime-environment
and may change from version to version. e.g. One of the options can increase the used heap-memory from
(default) 64MB to 256MB: "java -Xmx256m TSUtil ..." 

Before selecting a single function, GLOBAL OPTIONS can be inserted in the commandline. These options
can be specified in every case without error, although they are NOT USED in every function.
The later call-definitions of the functions show, which global option is recognized.
The following GLOBAL OPTIONS are valid:

 -l[<logfle>]	: With this global option, writing of a log-file can be activated. If the name of the
			log-file (<logfle>), which could/should be a fully specified filename, is ommitted or
			invalid, this log-file is named 'TSUtil.log' and will be created in the current
			working-directory.
			If this option is successfully specified, it will take absolute precedence and specififying
			a log-file-name at the end of a commandline has no impact. Functions, where a log-file
			MAY also be specified at the end of the commandline are marked with '+' in the lower
			functionlist.
 -k	: This global option enables the output of the messagekey to the log-file. Every message of this
		file is then preceeded by its messagekey, wrapped by curly brackets. 
 -e	: This global Option is used to suppress output of all 'Informations' and 'Warnings' both to
		the log-file as well as to the screen.
 -w	: This global Option is used to suppress output of all 'Informations' both to the log-file as
		well as to the screen.
 -m<id>	: Using this global option, it is possible to suppress single messages both to the log-file as
		well as	to the screen. <id> is the Key of the message, which should be supressed. This 
		key can be found in the current file "TSErrMsg_xx.properties". Global option '-m' can
		be specified more than once.
		ATTENTION: Message-keys are case-sensitive.
 -h[<path>]	: If, using a local option, filenames of track-objects are modified, the new filename is
			automatically extended and an accesspath is added, too. Normally, this accesspath
			is: '../../Routes/<route>/Shapes/'. If this global option '-h' is used, it is
			possible, to change this default accesspath to the specified path. This specified
			path may contain placeholder, which are resolved during check of option. These are:
				%0 - <current routename>
				%1 - "../../Routes/" (fix value)
			ATTENTION: This path-value MUST contain more than 8 characters or it is not accepted.
				('\\' counts ONE character, because it is replaced with '/'.)
			If this option is used without specifying an explicit path, the default-path is
			set to '<route>/', so that the directory 'global/shapes/<route>' is searched for
			additional track-objects.
			This option overwrites '-H' option, if already specified.
 -H	: If, using a local option, filenames of track-objects are modified, the new filename is automatically
		extended and an accesspath is added, too. Normally, this accesspath is:
		'../../Routes/<route>/Shapes/'. Using this option '-H', it is possible to suppresse this
		additional modification. If '-H' is used, an accesspath is no longer added.
		This option overwrites '-h' option, if already specified.
	Prior to Version 3.3.04 this option is the default-option, although it was not specified.


So, a call to TSUtil looks like this:
	java [<system-options>] TSUtil [<global-options>] <functionname> [<local-options>] ...


Hint: From now on, TSUtil is available as an jar-file, too. So, everyone can activate all the
	functions of this tool with the java 'jar-file-syntax'. Using this syntax, it is also
	possible to create ptf-files.  
	e.g: "javaw -jar [<system-options>] TSUtil.jar ..."
	     "java -jar [<system-options>] TSUtil.jar ..."


The following functions are available in this Version (Number of description follows in brackets):
+	- adjh   : Change global Height-Definition of a Route (16)
	- chgdb  : Change shape-/section-references in track-Database "*.tdb"/"*.rdb" (6)
+	- chkup  : Check a global 'tsection.dat'-File to be used as upgrade for an OLD one (15)
+	- clrdb  : Reorganization of databases (track/road) and resources (20)
	- cmkr   : Convert '.coo'-file to marker-file (4)
+	- cmp    : Reduce/Compress files (S,T,W) to binary format (17)
+	- cmpw   : Compress world-files using the "Comp"-program of Martyn Griffin (10)
+*	- cvrt   : Convert, adjust and correct a complete route-definition (5)
	- dcpy   : Compare file-dates and copy if newer (7)
	- filter : Verification and Correction of the Geometrie-Definition of a Route (9)
	- fmgr   : Compress/Decompress/Reduce/Expand of file(s)/filegroups (S,T,W) (24)
+*	- ichk   : Integrity-check of a route-definition (12)
+	- merge  : Merge a route-definition into another route (19)
+*	- move   : Shift complete route-definition to new longitude/lattitude (14)
+	- rendb  : Modify track-database "*.tdb"/"*.rdb" and delete gaps (13)
	- shftdyn: Shift dynamic definitions of local 'tsection.dat' to current position (22)
	- shift  : Shift/renumber block of global Shape/Section-definitions within 'tsection.dat' (8)
*	- tsconv : Convert ALL route-definitions of a TS-Instance according to 'cvrt' (11)
+	- unc    : Uncompress/expand files (S,T,W) (18)
	- version: Show/print internal ID-values of known TSUil-classes (23)
	- wcmp   : Compress world-files to binary format (ffeditc_unicode) (2)
	- wcmpo  : Compress world-files to binary format (only) (ffeditc_unicode) (3)
	- wunc   : Uncompress world-files (ffeditc_unicode) (1)
	- zusi   : Prepare a route-defintion for import into ZUSI-Trainsimulator (21)

* - These functions are the most important part of this tool.

If not stated otherwise, all functions store their result in a new directory which is named '\newroute'.
The structure of subdirectories of the complete route is retained and copied. All functions are designed
in a manner that a TDB-rebuild is no longer necessary.

Error-Messages of the processes are identified with "--->" so that they can be recognized easily.
Normally, this means, that the created data-files cannot be used, because they may contain errors, too.
But that is NOT mandatory and depends on the message.
Warnings and other messages are not specially marked.

Definitions of common terms:
  static representation
	A 'static representation' of a 'TrackObj' is a 'TrackObj'-Definition, which is defined as an
	object of type 'Static' in the world-files. Such an object furthermore contains all properties of
	a 'TrackObj'-definition and is also recorded in the trackdatabase. But it does NOT show an
	overheadwire, even if the route is electrified.
	Such a object is also called 'Hidewire-Object' (especially in messages) due to the name of the
	tool, which primarily created these objects.


1) Uncompress world-files
  The function "wunc" is used to convert ALL world-files to "uncompressed text" - form (UT-Form),
  that means the only form of a world-file, which can be changed using a 'normal' editor.
  In order to do this, 'wunc' creates a list of world-files and stores this list to an intermediate
  file. Then it checks the form of each world-files and converts them by generating one or more calls
  to "ffeditc_unicode".

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-m<id>] [{-e|-w}] wunc <dir>
  with:
	"dir" contains (fully defined) path to route-definition, where the world-files are located.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log wunc C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- All files in the 'newRoute/world'-directory should be copied to the directory 'world'
		of the route.

2) Compress world-files to binary format
  The function "wcmp" is used to convert ALL world-files to "compressed binary" - form (CB-Form),
  that means the form of a world-file, which optimizes load-time.
  In order to do this, 'wcmp' creates a list of world-files and stores this list to an intermediate
  file. Then it checks the form of each world-files and first converts them to UT-Form by generating
  one or more calls to "ffeditc_unicode". At least, an additional call to "ffeditc_unicode" is used
  to convert each file to CB-form.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] wcmp <dir>
  with:
	"dir" contains (fully defined) path to route-definition, where the world-files are located.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log wcmp C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- All files in the 'newRoute/world'-directory should be copied to the directory 'world'
		of the route.

3) Compress world-files to binary format (only)
  The function "wcmpo" is ALSO used to convert ALL world-files to "compressed binary" - form (CB-Form),
  that means the form of a world-file, which optimizes load-time.
  But unlike to function 'wcmp', this function ONLY converts world-files to CB-form, which already uses
  the UT-form. All other world-files are NOT changed.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] wcmpo <dir>
  with:
	"dir" contains (fully defined) path to route-definition, where the world-files are located.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log wcmpo C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- All files in the 'newRoute/world'-directory should be copied to the directory 'world'
		of the route.

4) Convert '.coo'-file to marker-file
  If someone uses a Map-Serie called "TOP50" (1:50000), it is possible to store coordinates to a file.
  This file gets the suffix ".coo".  This Function 'cmkr' can convert such a file to a marker-file
  of Trainsimulator.

  The call of this function looks as follows:
	C>java TSUtil [-m<id>] cmkr <file>
  with:
	"file" is the (fully defined) filename without suffix of the file, which contains
		Coordinate-Definitions using WGS84(decimal)-Format.
	Concerning the global options, compare to 'Introduction'

  z.B. : "java TSUtil cmkr C:\koord"
	This converts file Datei "C:\koord.coo" to marker-file "C:\koord.mkr".

  Note: Only markers of type "2" are used to generate marker-lines.

  Action(s) to use the results of the function:
	- Rename the result-file to the appropriate name and copy it to the route-directory.

5) Convert, adjust and correct a complete route-definition
  This function ('cvrt') is mainly used, to customise a route-definition to changes of the
  environment. This includes a replacement of the global 'tsection.dat' - file. Additionally
  other modifications like 'renumbering ID's of World-Objects' are handled by this function.

  If the globale 'tsection.dat' has been replaced and the route must be adjusted to this, the
  following reqirements have to be met to execute this function without an error:
	- The global 'tsection.dat'-file, which is originally used to build the route, has
		to be still available.
	- The global 'tsection.dat'-file, to which route-definition is adapted, is the actual
		one and is located in the 'global' directory.
  This function also recognizes changes like replacement of Shape-Definitions and adjusts all
  references automatically. But, in order to establish a non-ambigous assignment between 'old'
  and 'new' Shape-/Section-definitions, it is recommended that the sequence of Sub-Options
  (e.g. SectionIdx) WITHIN a definition do NOT change. If this is NOT possible (e.g. because
  of error-correction) an assignment can be established manually with the '-v' - option.

  This function modifies the 'populated' world-files as well as the track- and road-database and
  creates them again. A new local 'tsection.dat'-file is also build and stored in the 'newroute'-
  directory. So, it is no longer necessary to do a TDB-rebuild.  

  If there are NO changes between 'old' and 'new' global 'tsection.dat'-file, the '-b'-Option 
  can be ommitted. Then, replacement of shape- and section-definitions will not be done. All other
  function of 'cvrt' are still available. 

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] cvrt [-r] [-s] [{-c|-u}] [-k] [-v<no1>:<no2>]
		[-b<file>] [{-H|-h{1|2|3}[:<s1>:<s2>]}] [-m[<sl>:<s1>:[<s2>]]] [-z{1|2|3}[:<s1>:[<s2>]]] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"file" describes filename (and path) to old global "tsection.dat" -file. This file need not
		be named 'tsection.dat'.
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	If option "-r" is specified, renumbering of UID-Numbers in each world-file is activated.
		If this is not possible to individual files, because of errors, renumbering of this
		file is suppressed and a message is logged.
	If option "-s" is specified, it is aditionally checked, if all shape-files, which are 
		referenced from NEW global 'tsection.dat', are present.
	If option "-c" is used, all world files are written in the compressed format [CB].
		Normally, world-files are written in the same format as they were read. This option
		may be cleared with the '-u' -option.
	If option "-u" is used, all world files are written in the expanded format[UT]. Normally,
		world-files are written in the same format as they were read. This option may be
		cleared with the '-c' -option.
        Non-ambigous assignment between definitions from OLD and NEW 'tsection.dat' may not be
		possible. Using option '-v' someone can do this manually. 'no1' defines a
		shape-number of OLD 'tsection.dat' and 'no2' defines the number of the assigned
		shape-definition in NEW 'tsection.dat'. This assignment is only active, if no
		other (e.g. automatic) assignment was possible. Option '-v' can be specified
		more than once.
	Option "-k" enables the 'correction-mode' of world-files. If this mode is enabled,
		world-objects are checked using the following rules (additionally):
		+ A second specification of a definition-line does NOT invalidate the whole object.
			The second line is logged and ignored.
		+ A missing definition-line is added using default-values (if possible)
	Options "-h" and '-H' are used to change track-objects to their static representation or to
		suppress this conversion. This allows TS to suppress the overheadwire for these objects.
		(also compare to 'Hidewire')
		Normally, ALL such objects, which were reconverted from their static representation to normal
		'TrackObj's in order to check them, are converted back to their static representation.
		If option '-H' is specified, this conversion is suppressed, and the object-definition
		is written unchanged ('TrkObj'/'Dyntrack') to the world-file. If the filename of such
		an object was modified, this modification is lost and the original filename is used.
		Option '-h' must not be used, if option '-H' is specified. If '-H' is followed by some
		additional data, this data is skipped.
		Option '-H' implies option '-m' with no additional arguments in order to undo the
			potential modification of a filename.

		Option '-h' is used to specify, that additional 'TrkObj'-definitions need to be converted
		to their static representation. This option is followed by a number (1,2,3), which
		is compared to the 'StaticdetailLevel'-property of the 'Trackobj'-definition and select
		if an object should be converted to its static representation. Then, and ONLY then,
		modification of the current filename of the object is possible. In this case, the filename
		of the 'TrackObj' is checked, if it starts with the specified string and if so, this part of
		the filename is replaced with the second string.
		Option '-h' may be specified up to 3 times. If '-h' is used, '-H' cannot be used, too.
		Example: '-h1:A:Xt' - All trackobjects, which are defined with a 'StaticDetailLevel'
			of 1, are changed to 'Static'-objects. If the filename starts with 'A', this
			'A' is replaced with 'Xt'. (A1t10mstrt.s -> Xt1t10mstrt.s)
		Attention: If modification of filename is active, the original filename is added to
			the world-object using keyword 'TreeTexture'. This keyword is ignored from TS
			within static objects and is only used to undo the modification.
	Option '-m' may be used to modify the filenames of Track-/Road-objects. So, the appearance of a
		trackobject may change. Unlike option '-h', Option '-m' do NOT convert a track-object to a
		static object.
		If option '-m' is used WITHOUT following values, ALL modifications of filenames are rolled
		back. Normally a modification is active and restored when a world-file is written.
		If option '-m' is followed by a number, this number is compared to the 'StaticdetailLevel'-
		property of the 'Trackobj'-definition and selects, if the filename should be modified. Value
		'0' and values between '4' and '9' (incl.) are valid here. However, modification of the
		filename only occurs, if, additionally, filename starts with the string specified as "s1".
 		In this case, this part of the filename is replaced with the second string ("s2"). If the
		second string ("s2") is NOT present an empty string is used instead.
		Option '-m' may be specified more than once, even if it uses the same 'StaticdetailLevel'.
		Attention: If 'StaticdetailLevel' matches, a potential previous modification is cleared
			before it is tried to modify the filename again. So, if NO "s1"-string matches TOO,
			a previous modification is lost.
		Example: '-m4:A:Xt' - (compare to option '-h')
		Attention: If modification of filename done, the original filename is added to the
			world-object using keyword 'TreeTexture'. This keyword is ignored from TS
			within track-objects and is only used to undo the modification.
	Option "-z" is used to change STATIC OBJECTS, which ARE static representations of a 'TrackObj'-Entry
		but cannot be identified as such an object, to a new 'TrackObj'-definition (compare to '-h-Option').
		The following number(1,2,3) specifies the 'StaticDetailLevel', which will be applied to the
		created object. This is independent from the current Level. 
		In order to deceide, if an object has to be converted, the filename of the static object is 
		compared to ALL shape-names, which are defined in the current global 'tsection.dat'.
		If it matches, the static object is converted to the corresponding 'TrackObj' and all missing
		definition-lines are added.
		If specified within the option (value "s1"), the filename of the static object is modified BEFORE
		'tsection.dat' is searched. If "s1" is present, the filename is checked, if it starts with this string
		(no respect to case of letters) and if so, this part of the filename is replaced with the second
		string. If the second string ("s2") is NOT present an empty string is used instead.

		Option '-z' may be specified more than once.
		Example: '-z1:Xt:A' - Filenames of ALL static objects are checked, if they start with 'Xt'. If NOT,
			this option is not applied and the static object may remain unchanged (depending on other
			options). If it matches, filename is (locally) changed and 'Xt' is replaced by 'A'. Then,
			current global 'tsection.dat' is searched, if a corresponding shape-definition exists.
			If such a definition is found, the static object is converted to the 'TrackObj'-definition
			and gets a 'StaticDetailLevel' of 1. (Xt1t10mstrt.s -> At1t10mstrt.s)
		Attention: If modification of filename is active and the static object is converted, the original
			filename is also stored, so that it can be used if this object is recoverted to a
			'Hidewire'-object (option '-H' NOT present).
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log cvrt -bC:\tsection.dat C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.

6) Change shape-/section-references in track-Database "*.tdb"/"*.rdb"
  With this function it is possible to adapt the Track Database to a change of the global file
  "tsection.dat". This function is meaningful if the rebuild of the Track Database
  (in accordance with 'Advanced option ') does not succeed. An adjustment of further files is
  not made.
  This function analyzes the specified Track Database, modifies all references on Shapes and sections
  due to the indicated new benchmark figures and provides a copy with the ending "tbd$"/"rdb$" in
  the original directory.  

  The call of this function looks as follows:
	C>java TSUtil chgdb <file> [<shn> <scn> [<sha> <sca>]]
  with:
	"file" is the file name (with path) of the Track Database (tdb/rdb)
        "sha" is the up-to-date used benchmark figure for Shapes (Default=263)
        "sca" is the up-to-date used benchmark figure for sections (Default=376)
        "shn" is that benchmark figure for shapes (Default=5000), which can be used again,
        "scn" is that benchmark figure for sections (Default=5500), which can be used again,

  e.g. ProTrain 1: "java TSUtil chgdb
	C:\TRSim\routes\ProTrain_Rheintal\ProTrain_Rheintal.tdb 40000 40000"

  NOTE: This function works -contrary to 5) - on pure sentence basis. With this fact, it is
	possible that, depending upon indication of the values "sha", "sca", "shn" and "scn",
	the maximum record length of the Track Database increases (e.g. Section number with
	six digits instead of with 3 digits).  
        Since the maximally USABLE record length of the Track Database is not known, this is
	a reason for a possible error.

  Action(s) to use the results of the function:
	- Delete file *.tdb and rename file *.tdb$ to *.tdb. OR
	- Delete file *.rdb and rename file *.rdb$ to *.rdb.

7) Compare file-dates and copy if newer
  A call of the function "dcpy" compares the file/directory structure based on directory 1
  file for file with the structure based on directory 2. Each file/directory from the
  structure 1, which is not present in the structure 2 or has a newer date, is copied to
  the appropriate place of the structure based on directory 3. Intermediate directories,
  which are missing, are provided automatically.  

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] dcpy [-a] [-o] <dir1> <dir2> <dir3>
  with:
	"dir1" is the file path on the original route
	"dir2" is the file path on the route to be compared to
	"dir3" is the file path on the target-route
	If the option "-a" is specified, also the files with ending "bk" are considered.
		In the other case these files are checked nor copied neither.
	Option '-o' is used to restrict copy of files. If this option is active each file of
		structure 1 is ONLY copied to structure 3 if it is both present in structure 2 AND
		contains a newer date.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log dcpy C:\TRSim\routes\ProTrain_Rheintal
			C:\TRSimV\routes\ProTrain_Rheintal C:\TRSimN\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- The directory-tree, which starts at directory <dir3> contains the copied files.

8) Shift/renumber block of global Shape/Section-definitions within 'tsection.dat'
  The function "SHIFT" shifts ShapeId and/or Section-ID ranges in the indicated GLOBAL "tsection.dat"
  and provides a copy under a new name, which is formed by appending '$' to the old name.  
  
  Only the Id's and the references on this Id's are changed as the shift value is added. A new assortment
  of the entries does not take place. In order NOT to shift a range (Shapes OR Sections), '0' has to be
  specified as the shift value. The values of the borders are irrelevant in this case, however, they must
  be entered correctly.
  The shift value can be both positive and negative.  The ranges - and both source and target area concerns
  - must lie within the defined borders (0, maxShape/maxSection).

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] shift <file> <shl> <shh> <shd> <scl> <sch> <scd>
  with:
	"file" is the file name (with path) of the global "tsection.dat" file
	"shl" is the lower limit of the ShapeId range (inclusive)
	"shh"is the upper border of the ShapeId range (exclusive)
	"shd" is the shift value for the ShapeId's
	"scl" is the lower limit of the SectionId range (inclusive)
	"sch" is the upper border of the SectionId range (exclusive)
	"scd" is the shift value for the SectionId's
	Concerning the global options, compare to 'Introduction'

  z.B.: "java TSUtil -lC:\Logdat.log shift C:\TRSim\Routes\tsection.dat 0 400 2000 0 400 2000"
  	Here the definitions between 0 and 400 are shifted to the place 2000. 

  RESTRICTION:  This function may not run correctly when the words "TrackSections", "TrackShapes",
	"TrackSection" und "TrackShape" occur within a COMMENT.  Such a comment must be removed from
	the global "tsection.dat" before using this option.  After the shift it can be added again.

  Action(s) to use the results of the function:
	- Sort all entries of the resulting file due to the section- or shape-indices. The you can use
		this file as new 'tsection.dat' (global). Perhaps you must adjust the defined routes to
		this file with the 'cvrt'-function. 

9) Verification and Correction of the Geometrie-Definition of a Route
  Function 'filter' checkes every marked tile-definition for completeness. If it does NOT contain
  tile-data (.t-file), it is unmarked as 'populated'. If option '-w' is additionaly specified, the tile
  is also unmarked, if a connected world-definition is not present.
  Both Tile- and LO_Tile-Definions are checked.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] filter [-w] <dir>
  with:
	"dir" contains (fully defined) path to route-definition, where the world-files are located.
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Option '-w' involves world-files into the verification. A marked tile-definition, which
		do not contain a connected world-file is unmarked as 'populated' 
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log filter C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Delete the directory 'TD' of the route and replace it with the 'TD'-directory	from 'newRoute'.

10) Compress world-files using the "Comp"-program of Martyn Griffin
  The function "cmpw" is used to convert world-files to compressed format (CB-Type). Unlike to the
  other compress-functions(2)(3), this function uses the 'Comp'-Program of Martyn Griffin to process
  the files. This program is available in the Internet (e.g. 'train-sim.com') and is called 'recmp119'. 
  The 'Comp'-program does NOT contain errors like 'ffeditc_unicode', so that world-files are
  error-free converted to the CB-Format.
  In order to be able to activate this program by TSUtil, it MUST be installed to folder 'utils/comp'
  of the TS-Instance.

  World-files, which are available in UB-form are converted to UT-Form using 'ffeditc_unicode' before
  calling the 'Comp'-Program. Already compressed files (CB-Form, CT-Form) are NOT changed.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] cmpw <dir>
  with:
	"dir" contains (fully defined) path to route-definition, where the world-files are located.
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log cmpw C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- All files in the 'newRoute/world'-directory should be copied to the directory 'world'
		of the route.

11) Convert ALL route-definitions of a TS-Instance according to 'cvrt'
  By the function "tsconv" ALL route definitions of an TS instance are adapted to a new global
  "tsection.dat" definition. The individual route definitions are overwritten with the changes.
  Thereby for each Route-Definition of the TS instance the action "Converting the Route-definition
  with the function 'cvrt'" is released.  
  
  The original "tsection.dat", by which outgoing ALL Routes are to be adapted to the new version,
  must be copied to the directory "Routes" of the TS instance. If a Route-Definition, which can
  be modified uses another "tsection.dat", alternatively for this Route-Definition the applicable
  "tsection.dat" can be copied under the name "$tsection.dat" to the private Route-Directory.  
  This is then preferred to the general definition (in ' Routes ')

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] tsconv [-s] [-u] [-v<nr1>:<nr2>] <dir>
  with:
	"dir" is the file path on the TS instance
	If option "-s" is specified, it is aditionally checked, if all shape-files, which are 
		referenced from NEW global 'tsection.dat', are present.
	If Option "-u" is used, the world files are always written in the 'UT'-format. Normally,
		world-files are written in the same format as they were read.
        Non-ambigous assignment between definitions from OLD and NEW 'tsection.dat' may not be
		possible. Using option '-v' someone can do this manually. 'no1' defines a
		shape-number of OLD 'tsection.dat' and 'no2' defines the number of the assigned
		shape-definition in NEW 'tsection.dat'. This assignment is only active, if no
		other (e.g. automatic) assignment was possible. Option '-v' can be specified
		more than once.
	Concerning the global options, compare to 'Introduction'

  e.g. : "java TSUtil -lC:\Logdat.log tsconv C:\TRSim\"

  Action(s) to use the results of the function:
	There are NO actions needed. Files are replaced directly by the 'tsconv'-function.

12) Integrity-check of a route-definition
  With the Function("ichk") the internal integrity of a Route-Definition is checked. It is checked,
  whether the global and local 'tsection.dat' - file are syntactically correct and whether the
  references between track-/road-database and world-files are correct.  
  
  It is also checked if duplicate UiD identifications are used and whether it is possible to change these,
  if necessary. However, NO changes in the Route definition are made!  
  
  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] ichk [{-s|-S}] [-k] [-z{1|2|3}[:<s1>:[<s2>]]] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	If option "-s" is specified, it is checked, if all shape-files, which are referenced from
		global 'tsection.dat', are present. If this option is specified as "-S", it is
		aditionally checked if all shape-definitions, which are referenced from a
		world-file, are present. All texture-files, which are used from within these
		shape-files have to exist, too. If not, a message is logged but no action is taken.
	Option "-k" switches the check-mode of world-files. If this option is enabled,
		object-definitions are checked using the same rules as if the 'correction-mode'
		(compare to function 'cvrt'(5)) is enabled.
	Option "-z" is used to change STATIC OBJECTS, which ARE static representations of a 'TrackObj'-Entry
		but cannot be identified as such an object, to a new 'TrackObj'-definition (compare to 'cvrt').
		The following number(1,2,3) specifies the 'StaticDetailLevel', which will be applied to the
		created object. This is independent from the current Level. 
		In order to deceide, if an object has to be converted, the filename of the static object is 
		compared to ALL shape-names, which are defined in the current global 'tsection.dat'.
		If it matches, the static object is converted to the corresponding 'TrackObj' and all missing
		definition-lines are added.
		If specified within the option (value "s1"), the filename of the static object is modified BEFORE
		'tsection.dat' is searched. If "s1" is present, the filename is checked, if it starts with this string
		(no respect to case of letters) and if so, this part of the filename is replaced with the second
		string. If the second string ("s2") is NOT present an empty string is used instead.

		Option '-z' may be specified more than once.
		Attention: All modification are made BEFORE the integrity of the object is checked.
		Example: '-z1:Xt:A' - Filenames of ALL static objects are checked, if they start with 'Xt'. If NOT,
			this option is not applied and the static object may remain unchanged (depending on other
			options). If it matches, filename is (locally) changed and 'Xt' is replaced by 'A'. Then,
			current global 'tsection.dat' is searched, if a corresponding shape-definition exists.
			If such a definition is found, the static object is converted to the 'TrackObj'-definition
			and gets a 'StaticDetailLevel' of 1. (Xt1t10mstrt.s -> At1t10mstrt.s)
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log ichk C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	This funcion does NOT create any new file (except LOG).

13) Modify track-database "*.tdb"/"*.rdb" and delete gaps
  After manual delete of (defective) Track-Nodes from track-/road-database *.tdb/*.rdb, this function
  ('rendb') can repair references and dependencies within the databases. All Nodes are
  'shifted together' and references are updated. It is checked, if there are invalid references
  which cannot be reestablished. These references are logged and replaced by '0'.
  TrItem-Definitions are renumbered, too. All gaps are deleted. If specified, TrItem-Definitions,
  which are no longer referenced from world-files or Track-Nodes, are also deleted. All references
  are updated.

  Both databases are fully checked logically. But, if option '-o' is specified, world-files are not
  loaded and it is not possible to check dependencies to these files. So, in this case error-messages
  concerning these problems, can be ignored.
  This function ALSO newly create the *.tit and *.rit databases. This is only possible without
  errors, if these databases are manually changed in the same way as the corresponding
  *.tdb/*.rdb-files.

  ATTENTION: All changed files are created in the '\newroute'-directory. Before replacing the
	original files with these new files, it is recommended to check if there are NO unresolved
	references. Perhaps some definitions may deleted by mistake. Logfile can be used to do this.
 
  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] rendb [{-c|-u}] [-o] [-a] [-w[ -m]] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Option "-o" is used to ONLY reorganize the TrackDB-Area of the databases.
		In this case, NO modifications (neither changes nor deletions) must exist in the
		TrItem-Area of the databases.
	If LOCAL Option "-w" is specified, databases will be newly created in every case. This is
		also done, if logical check of database fails because of errors.
	If Option "-a" is specified, all Tritem-Definitions, which are NO LONGER REFERENCED,
		are deleted. So, these Items need not to be deleted explicitly from
		database-files (*.tdb,*.rdb,*.tit,*.rit). This option does not work, if '-o'
		is specified.
	Option '-m' marks UID-entries in the database, which contain errors.
		If, due to option '-w', the new version of the database is still created, all values,
		which contain errors are copied unchanged. If option '-m' is specified, such
		UID-values are replaced by '?'. The option'-m' must be specified AFTER option '-w'.
	If option "-c" is used, all world files are written in the compressed format [CB].
		Normally, world-files are written in the same format as they were read. This option
		may be cleared with the '-u' -option. This option is ignored, if '-o' is active.
	If option "-u" is used, all world files are written in the expanded format[UT]. Normally,
		world-files are written in the same format as they were read. This option may be
		cleared with the '-c' -option. This option is ignored, if '-o' is active.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log rendb C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.
	- if option '-o' is NOT specified:
	 + Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	 + If the 'activities'-directory within directory 'newRoute' is present, delete directory
		'activities' of the route and replace it with this directory.
	 + If the 'paths'-directory within directory 'newRoute' is present, delete directory
		'paths' of the route and replace it with this directory.
	 + If the 'services'-directory within directory 'newRoute' is present, delete directory
		'services' of the route and replace it with this directory.
	 + If the 'traffic'-directory within directory 'newRoute' is present, delete directory
		'traffic' of the route and replace it with this directory.


14) Shift complete route-definition to new longitude/lattitude
  This function ('move') shifts a Route-Definition a certain, definable number of Route squares in X
  and/or Z-direction.  All definitions (tile-files, world-files, TD definitions...) are adapted
  accordingly and again provided. The new files are written to the directory '/new route ', which
  is created in the Route-Definition.  
  To the exact proceeding also compare to the later fictous example.
  TSUtil computes the maximum edge-length of the used tiles. The number of squares, the route is to
  be moved, must be divisible through this number so that no overlapping will occur during move.

  During moveing a consolidation of the quad-tree-structure is made.  All tiles, which are not
  'populated', are summarized if possible.  Beside the files of the Route-Definition, also ALL files
  of the Activities are shifted and adapted, since they contain references on the Route definition, too.  
  
  NOTE: Only the Tiles are shifted, which are marked 'populated' in the route-geometry-extractor. All
	other tiles are not processed. This also concerns the assigned world- and tile- files. If
	necessary thereby a correction of the Route has to be done using route-geometry-extractor.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] move [-c] [-p] <dir> <dx> <dz>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	"dx" is the number of Tiles, which the route is to be shifted in X-direction. The value
		must be a multiple of the greatest used Tile-edge-length.
	"dz" is the number of Tiles, which the route is to be shifted in Z-direction. The value
		must be a multiple of the greatest used Tile-edge-length.
	If the option "-c" is provided, the tile-files (*.t) are written using the 'reduced format' in
		any case. Normally, tile-files are rewritten in the same format as they are read.
	The option "- p" causes that beside the Tile-files (*.t) and the Tile-data-files (*_ y.raw,
		*_ f.raw) also the buffer files (*_e.raw, *_ n.raw) are copied under the appropriate
		change of name. Thus the TS does not have to build them again.  
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log move C:\TRSim\routes\ProTrain_Rheintal -5120 -496"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- Delete the directory 'TD' of the route and replace it with the 'TD'-directory from 'newRoute'.
	- Delete the directory 'tiles' of the route and replace it with the 'tiles'-directory
		from 'newRoute'.
	- Delete the directory 'LO_tiles' of the route and replace it with the 'LO_tiles'-directory
		from 'newRoute'.
	- If the 'activities'-directory within directory 'newRoute' is present, delete directory
		'activities' of the route and replace it with this directory.
	- If the 'paths'-directory within directory 'newRoute' is present, delete directory
		'paths' of the route and replace it with this directory.
	- If the 'services'-directory within directory 'newRoute' is present, delete directory
		'services' of the route and replace it with this directory.
	- If the 'traffic'-directory within directory 'newRoute' is present, delete directory
		'traffic' of the route and replace it with this directory.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.

15) Check a global 'tsection.dat'-File to be used as upgrade for an OLD one
  Function 'chkup' can check the compatibility between two versions of an global 'tsection.dat'-file.
  An NEW version is compatible to a OLD one, if all track- and road-definitions of the OLD file are
  also defined in the NEW version. 'defined' does not mean that they are exactly the same. Even
  ID-values can have changed. 'defined' only says, that TSUtil can establish a connection between
  old and new definition.
  The OLD version of 'section.dat' is given during call of this function, while the new version
  must exits as 'tsection.dat' in the SAME directory as the old one. So, someone can initiate
  a simple syntax-check of a 'tsection.dat'-file by specifying the new version as the old one.  

  This function also recognizes changes like replacement of Shape-Definitions and adjusts all
  references automatically. But, in order to establish a non-ambigous assignment between 'old'
  and 'new' Shape-/Section-definitions, it is recommended that the sequence of Sub-Options
  (e.g. SectionIdx) WITHIN a definition do NOT change. If this is NOT possible (e.g. because
  of error-correction) an assignment can be established manually with the '-v' - option.

  This 'chkup'-function does NOT do any corrections.

  Note: This function is part of the route-conversion according to function 'cvrt'. So, it is a
	sort of pre-stage for route-conversion in order to check 'tsection-dat'-file.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] chkup [-v<nr1>:<nr2>] <file>
  with:
	"file" is the file-name (fully defined) of an OLD Version of a "tsection.dat"-file
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
        Non-ambigous assignment between definitions from OLD and NEW 'tsection.dat' may not be
		possible. Using option '-v' someone can do this manually. 'no1' defines a
		shape-number of OLD 'tsection.dat' and 'no2' defines the number of the assigned
		shape-definition in NEW 'tsection.dat'. This assignment is only active, if no
		other (e.g. automatic) assignment was possible. Option '-v' can be specified
		more than once.
	Concerning the global options, compare to 'Introduction'

  e.g. '$tsection.dat': "java TSUtil -lC:\Logdat.log chkup -v99:99 C:\TRSim\global\$tsection.dat"

  Action(s) to use the results of the function:
	This funcion does NOT create any new file (except LOG).

16) Change global Height-Definition of a Route
  Function 'adjh' can RAISE or LOWER a WHOLE route-definition, by changing height-values of the
  route-definition. A fix, specified value, which can be negative, is added to ALL height-values
  of the route. This concerns object-definitions in world-files as well as tile-definitions.
 
  All files (*.t,*.w,...) are rewritten in the same format, as they were read. Where required,
  the tile-files can be converted to the 'reduced format' by specifying the '-c' option.
  Remark: *.t-files are NOT compressed (UB-format)

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] adjh [-c] <dir> <dh>
  with:
	"dir" contains (fully defined) path to route-definition
	"dh" is the difference value(float), which is to be added to all height-values
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	If the option "-c" is provided, the tile-files (*.t) are written using the 'reduced format' in
		any case. Normally, tile-files are rewritten in the same format as they were read.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log adjh C:\TRSim\routes\ProTrain_Rheintal 15.5"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- Delete the directory 'tiles' of the route and replace it with the 'tiles'-directory
		from 'newRoute'.
	- Delete the directory 'LO_tiles' of the route and replace it with the 'LO_tiles'-directory
		from 'newRoute'.
	- If the 'paths'-directory within directory 'newRoute' is present, delete directory
		'paths' of the route and replace it with this directory.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.

17) Reduce/Compress files (S,T,W) to binary format
  Using function 'cmp', someone can reduce and/or compress all sorts of files (S,T,W).

  This function copies ALL .s/.t/.w-files in the appropriate directory to 'newroute' and changes file-format
  from 'uncompressed text' (UT) to 'uncompressed binary' (UB). Using option '-c', the new file will
  compress to 'compressed binary'-format (CB) with the ZLib-algorithm.
  Tile-Files cannot be compressed. They only use the tokenized UB-format.

  'cmp'-function CANNOT handle input-formats other than 'UT'-format.
  You only can process one type of file with one call to the 'cmp'-function.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] cmp {-s|-t|-T|-w} [-c] [-x] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Option '-s' selects the Shape-files from 'Shapes'-directory. All *.s-files of this 
		directory are reduced and/or compressed and copied to directory 'newRoute/Shapes'.
	Option '-t' selects the Tile-files from 'Tiles'-directory. All *.t-files of this 
		directory are reduced and copied to directory 'newRoute/Tiles'.
		Option '-c' cannot be specified in this case.
	Option '-T' selects the LO_Tile-files from 'LO_Tiles'-directory. All *.t-files of this 
		directory are reduced and copied to directory 'newRoute/LO_Tiles'.
		Option '-c' cannot be specified in this case.
	Option '-w' selects the World-files from 'World'-directory. All *.w-files of this 
		directory are reduced and/or compressed and copied to directory 'newRoute/World'.
	If option '-c' is specified, source files are not only reduced to tokenized format ('UB')
		but also compressed to 'compressed binary'-format (CB). No additional tool is needed.
	If option '-x' is specified a FULL copy of the source-directory is made. ALL files, which
		are not processed (due to file-type), are simply copied to the target-directory.
		Attention: Sub-directories are NEITHER processed NOR copied.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log cmp -w -c C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- if option '-x' is specified: Delete the appropriate directory of the route and replace it
		with the directory from 'newRoute'.
	- Else: All files in the appropriate 'newRoute'-directory should be copied to the directory
		of the route.

18) Uncompress/expand files (S,T,W)
  Using function 'unc', someone can decompress and/or expand all sorts of files (S,T,W).

  This function copies ALL .s/.t/.w-files in the appropriate directory to 'newroute' and changes file-format
  to 'uncompressed text' (UT). The current file-format of each file is automaticly detected and the
  appropriate actions are taken. e.g.: If the file already uses UT-format, the file is only copied to
  the destination directory. 

  You only can process one type of file with one call to the 'cmp'-function.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] unc {-s|-t|-T|-w} [-x] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Option '-s' selects the Shape-files from 'Shapes'-directory. All *.s-files of this 
		directory are decompressed and/or expanded and copied to directory 'newRoute/Shapes'.
	Option '-t' selects the Tile-files from 'Tiles'-directory. All *.t-files of this 
		directory are expanded and copied to directory 'newRoute/Tiles'.
	Option '-T' selects the LO_Tile-files from 'LO_Tiles'-directory. All *.t-files of this 
		directory are expanded and copied to directory 'newRoute/LO_Tiles'.
	Option '-w' selects the World-files from 'World'-directory. All *.w-files of this 
		directory are decompressed and/or expanded and copied to directory 'newRoute/World'.
	If option '-x' is specified a FULL copy of the source-directory is made. ALL files, which
		are not processed (due to file-type), are simply copied to the target-directory.
		Attention: Sub-directories are NEITHER processed NOR copied.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log unc -w C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- if option '-x' is specified: Delete the appropriate directory of the route and replace it
		with the directory from 'newRoute'.
	- Else: All files in the appropriate 'newRoute'-directory should be copied to the directory
		of the route.

19) Merge a route-definition into another route
  This function ('merge') creates a common route from two Route-Definitions. It merges another route into
  a basis-route. In order to get no errors, the following conditions/considerations have to be met:

	- Both routes must not contain a common tile-definition.
		If a common tile-definition still exists, it is ignored from merge-route and not used.
		This may lead to inconsistencies of the databases (*.tdb,*.rdb,...) and will raise
		appropriate error-messages.
		This concerns to LO-Tile-Definitions, too.
	- The basis-value for dynamic tracks has to be the same and must correspond to the current
	   global 'tsection.dat'-file.

  While merging, Shape-, Texture-, Terrtex- and Sound(sms/wav)-files, which are necessary for the common route
  and which are not defined in the basis-route, are copied. This is a critical process, because the basic-route
  may contain other shapes/textures with the same name. These files are NOT copied to the 'newroute'-directory.
  Signal-definitions are also merged. However, if a signal-name already exists in the target-route, the
  definition is NOT transfered. So, there may be problems in signalling, if this occurs.

  Note: The created route-definition should be checked using the TSUtil-'ichk' function. So, possible
		problems with the new route may be detected.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] merge [-p] [-h{1|2|3}] <dir1> <dir2>
  with:
	"dir1" contains (fully defined) path to route-definition (basis)
	"dir2" contains (fully defined) path to route-definition which should be merged
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	The option "- p" causes that, beside the Tile-files (*.t) and the Tile-data-files (*_y.raw,
		*_f.raw), the buffer files (*_e.raw, *_n.raw) are copied/processed, too. So, the
		TS does	not have to build them again.
		The buffer-files of the 'LO_Tile'_definitions are copied in any case, even if this
		option is not specified. (TS-Bug)
	Option "-h" is used to modify 'StaticDetailLevel' of the merged trackobjects. So, these objects
		('TrackObj','DynTrack') can be handled by 'TSUtil-cvrt' or 'Hidewire' seperate from the
		other trackobjects.
		If this option is active, 'StaticDetailLevel' of the merged trackobjects, whose original
		'StaticDetailLevel' equals '0', is set to the specified value.
		(The sequence of world-objects within a world-file is adjusted, too.)
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log merge C:\TRSim\routes\ProTrain_Rheintal C:\TRSim\routes\XXX"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- Delete the directory 'TD' of the route and replace it with the 'TD'-directory from 'newRoute'.
	- Delete the directory 'tiles' of the route and replace it with the 'tiles'-directory
		from 'newRoute'.
	- Delete the directory 'LO_tiles' of the route and replace it with the 'LO_tiles'-directory
		from 'newRoute'.
	- If the 'paths'-directory within directory 'newRoute' is present, delete directory
		'paths' of the route and replace it with this directory.
	- All files in the 'newRoute/shapes'-directory should be copied to the directory 'Shapes'
		of the route.
	- All files in the 'newRoute/textures'-directory should be copied to the directory 'Textures'
		of the route. (incl. sub-directories)
	- All files in the 'newRoute/terrtex'-directory should be copied to the directory 'Terrtex'
		of the route. (incl. sub-directories)
	- All files in the 'newRoute/sound'-directory should be copied to the directory 'Sound'
		of the route.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.


20) Reorganization of databases (track/road) and resources
  Function ('clrdb') analyzes track- and road-database and deletes all definition-chains (TrEndNode -
  TrVectorNode/TrJunctionNode - TrEndNode), which are no longer used. A definition-chain of nodes is
  no more used, if there are NO valid references from world- or sound-objects to this chain. This
  situation may exist, if world-objects or total world-files have been deleted.

  Additionally, ALL TrItem-Definitions, which are no longer used by the objects and by the node-part
  of the databases are deleted, too.
  All world- and sound-files, which are still used, are copied to the target-directory in the
  'newRoute'-tree. So, it is easily possible to delete the other, unused files.

  All Activity-, Path-, Service- and Traffic-files are checked, if they contain an invalid reference.
  If they are still valid, they are copied to the appropriate target-folder. The dependings between
  the single parts of activity-files are also checked. So, an activity-act is only valid (and copied),
  if all components, on which it depends (path, service,...) are valid, too.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] clrdb [-t[ -p]] [-w] <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	The specification of option "- t" causes the copy of all Tile- (*.t) and Tile-data-files (*_y.raw,
		*_f.raw), which are still populated, to the appropriate target-directory ('newRoute/Tiles',
		'newRoute/LO_Tiles'). This enables the consolidation of Tile-definitions, by simply replacing
		directories.
	The option "- p" causes that, beside the Tile-files and the Tile-data-files, the buffer files
		(*_e.raw, *_n.raw) are copied, too. So, the TS does not have to build them again. This option
		does nothing, if '-t' is NOT specified.
	The option '-w' initiates generation of missing world-files. A new empty 'dummy-world-file' is added to
		all Quad-Definitions of Tiles, which do NOT already contain a valid world-file.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log clrdb C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- If the 'activities'-directory within directory 'newRoute' is present, delete directory
		'activities' of the route and replace it with this directory.
	- If the 'paths'-directory within directory 'newRoute' is present, delete directory
		'paths' of the route and replace it with this directory.
	- If the 'services'-directory within directory 'newRoute' is present, delete directory
		'services' of the route and replace it with this directory.
	- If the 'traffic'-directory within directory 'newRoute' is present, delete directory
		'traffic' of the route and replace it with this directory.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.
	- if option '-t' is specified: Delete the directory 'tiles' of the route and replace it with
		the 'tiles'-directory from 'newRoute'.
	- if option '-t' is specified: Delete the directory 'LO_tiles' of the route and replace it with
		the 'LO_tiles'-directory from 'newRoute'.

21) Prepare a route-defintion for import into ZUSI-Trainsimulator.
  Using function 'zusi', route-data may be provided in a special form. Internal data of the route is written
  to files using standarized xml-format. In order to get correct files, route-definition should not contain
  errors. So, log-file should be checked, before using the provided data.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] zusi <dir>
  with:
	"dir" contains (fully defined) path to route-definition
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log zusi C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Files out of directory 'newRoute' may be used for german simulator 'ZuSi'.

22) Shift dynamic definitions of local 'tsection.dat' to current position
  Function 'shftdyn' is used to shift the range of dynamic track-definitions to the correct position.
  This position is clearly defined by the current global 'tsection.dat'. This function modifies the
  'populated' world-files as well as the track- and road-database. The result is stored in a new directory
  which is named '\newroute'. The structure of subdirectories is retained and copied. A new local
  'tsection.dat'-file is also build and stored in this directory. So, it is no longer necessary to do
  a TDB-rebuild.

  The position of this range of dynamic definitions is given by the arguments 'sha' (shapes) and
  'sca' (sections). If these values are ommitted a default-value is assumed. However, the actual values
  must equal the start-indices, which can be found in local 'tsection.dat'. The length of this range is
  also given by this file. This range can - in contrast to function 'cvrt' - overlap with the current global
  'tsection.dat'.

  In order to assign all specified arguments correctly, an exact sequence of values is needed. So, it may
  be necessary to specify a placeholder '+', if the real value is ommitted.

  ATTENTION: Even if '-w'-Option is active, not ALL missing 'Dyntrack'-objects may be created. There may be a lack
		of informations in the trackdatabase, which inhibits the creation of single objects.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] shftdyn [{-c|-u}] [-w] <dir> [{<sha>|+} [<sca>]]
  with:
	"dir" contains (fully defined) path to route-definition
	"sha" specifies the ID-Bias, where dynamic paths can be found. If this value is not present,
		a default-value of '263' is assumed. This default-value is also used, if the placeholder
		'+' is specified. This may be necessary, if other following values will be given.
	"sca" specifies the ID-Bias, where dynamic sections can be found. If this value is not present,
		a default-value of '376' is assumed.
	Option "-w" is used to enable automatic creation of missing 'DynTrack'-objects. If this option
		is active, a missing 'DynTrack'-object of a world-file is created using informations of the
		trackdatabase. So, all paths/sections are shifted even though NO (valid) 'DynTrack'-Object
		may exist (due to error(s)). After execution of this function, all created 'DynTrack'-objects
		should be edited with the RE in order to recalculate the new values derived from tdb-file. 
	If option "-c" is used, all world files are written in the compressed format [CB].
		Normally, world-files are written in the same format as they were read. This option
		may be cleared with the '-u' -option.
	If option "-u" is used, all world files are written in the expanded format[UT]. Normally,
		world-files are written in the same format as they were read. This option may be
		cleared with the '-c' -option.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log shftdyn C:\TRSim\routes\ProTrain_Rheintal"

  Action(s) to use the results of the function:
	- Delete the directory 'world' of the route and replace it with the 'world'-directory
		from 'newRoute'.
	- Move all files from the 'newRoute'-directory to the route-directory and replace them.

23) Show/print internal ID-values of known TSUil-classes
  Function "version" is used to display or log the identifications of all Java-Classes used by TSUtil.
  Therefore it is possible to verify if the current installation is up-to-date.
  
  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] version
  with:
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	Concerning the global options, compare to 'Introduction'

  e.g. : "java TSUtil -lC:\Logdat.log version"

  Action(s) to use the results of the function:
	This funcion does NOT create any new file (except LOG).

24) Compress/Decompress/Reduce/Expand of file(s)/filegroups (S,T,W)
  Function 'fmgr' is used to convert file(s) or group of files of different types of data (S,T,W) to
  target-fileformat (CB,UB,UT), which can be also specified.
  Source- and target-directory are included in function-call, so that this function is independent from any route.
  Source- and target-directory can specify the same directory. Then all selected files are overwritten without
  inquiry. (The real destination is a temporary file, which is later copied to the selected destination-directory.) 

  Option '-m' specifies a charactermask, which is used to select file(s) from within source-directory. This mask
  is interpreted as a 'regular expression' and therefore all properties of such an expression are available to
  select files. It is NOT a file-mask, as MS uses in several commands. (e.g. copy)
  More information about 'regular expressions' can be found in Annex B of this document. There you will also
  find a (not complete) list of placeholder, which ca be used in a 'regular expression'.
  If option '-m' (and option '-n') is NOT used, current selection-charactermask is loaded from Configurationfile
  ('TSErrMsg...') and depends on type of datafile. Normally ALL appropriate files are selected.
    (Shape('FleMgrMS'): '.+\.s' Tile('FleMgrMT'): '.+\.t' World('FleMgrMW'): '.+\.w')
  Using option '-n' a file-mask may be specified. This mask uses 'windows'-style to build a file-selection-mask.
  Because it is converted to a regular expression, ONLY '?' and '*' are supported as wildcard-character.

  This function uses NO external tool and is based on the conversion-algorithm of Martyn Griffin.
  It automaticly detects the current file-format of each file and takes the appropriate actions. e.g.: If the file
  already uses the target-format, the file is only copied to the destination directory. 

  ATTENTION: This function is NOT very fast and effective. While reading, all files are converted record by record
	to 'UT'-format before, while writing, they are again converted to the specified target-format.

  You only can process one type of file with one call to the 'file'-function.

  The call of this function looks as follows:
	C>java TSUtil [-l[<logfle>]] [-k] [-m<id>] [{-e|-w}] fmgr {-c|-e|-r} {-s|-t|-w} [{-m<msk>|-n<fmsk>}]
		[-o] <dir1> <dir2>
  with:
	"dir1" contains (fully defined) path to source-directory of files
	"dir2" contains (fully defined) path to target-directory of files
	"msk" specifies a 'selection-pattern' (regular expression) for file-selection. Only one of the options
		'-m' or '-n' should be used. If one of these options is specified more than once, the LAST one
		is active. If neither option is used, aLL files, which do are from correct filetype (due to
		options '-s','-t' or '-w'), are processed.
	"fmsk" specifies a 'selection-pattern' in 'windows'-style for file-selection. Only one of the options
		'-n' or '-m' should be used. If one of these options is specified more than once, the LAST one
		is active. If neither option is used, aLL files, which do are from correct filetype (due to
		options '-s','-t' or '-w'), are processed.
		ATTENTION: Beside character '?' and '*' no OTHER wildcards are supported within selection-mask.
	"logfle" is (optional) the name of the log-file, which will get error- and other messages
	If Option '-c' (compressed) is specified, target-fileformat is set to 'compressed binary' (CB). This
		Option is NOT allowed, if 'Tiles' are selected (Option -t is also used)
	If Option '-e' (expanded) is specified, target-fileformat is set to 'uncompressed text' (UT).
	If Option '-r' (reduced) is specified, target-fileformat is set to 'uncompressed binary' (UB).
	Option '-s' selects type of files to process. Only 'Shape-Files' are converted. All other type of files
		are rejected.
	Option '-t' selects type of files to process. Only 'Tiles' are converted. All other type of files
		are rejected.
	Option '-w' selects type of files to process. Only 'World-Files' are converted. All other type of files
		are rejected.
	If Option '-o' is active, missing subdirectories of target-directory are automatically created. If not, call
		to file-function terminates with an error, if such a condition is found.
	Concerning the global options, compare to 'Introduction'

  e.g. ProTrain 1: "java TSUtil -lC:\Logdat.log fmgr -e -w -o C:\TRSim\routes\ProTrain_Rheintal\world
                        C:\temp\world"

  Action(s) to use the results of the function:
	All files are created in the correct directory. NO additional action is needed.






FICTIOUS EXAMPLE (Function 'cvrt'):
In the following example it is presumed, that Trainsimulator is installed in directory "C:\TrSim".
There is also a route-definition called "Usa3", which has to be adapted at a new 'tsection.dat' in
order to implement extensions. The global file 'tsection.dat', which is still valid for this route-
definition, can be found in the directory "C:\TrSim\global". A new global 'tsection.dat' is provided
in the directory "C:\TrSim\new". This file contains extended definitions, which are to be used in
the route-definition.  

Further it is to be accepted, that the execution of commands do NOT produce errors. The examination
of the log-file is not shown, too.

a) Create a Backup of the Route

b) Open a DOS-Window
	Presumption: The new Window opens to directory "C:\"

c) Expand/Decompress all world-files (obsolete)

d) Copy and secure the actual,working 'tsection.dat'
	C>md C:\TrSim\old
	C>copy C:\TrSim\global\tsection.dat C:\TrSim\old

e) Activation of NEW 'tsection.dat' (please overwrite)
	C>copy C:\TrSim\new\tsection.dat C:\TrSim\global

f) Delete target-directory, if present
	C>deltree C:\TrSim\Routes\Usa3\newRoute

g) Conversion of Route-Definition
	C>java TSUtil -lTSUtil.log cvrt -bC:/TrSim/old/tsection.dat -c C:/TrSim/Routes/Usa3

h) Delete original directories/files from route-definition
	C>deltree C:\TrSim\Routes\Usa3\world

i) Activation of newly created files (please overwrite)
	C>xcopy C:\TrSim\Routes\Usa3\newRoute\*.* C:\TrSim\Routes\Usa3 /s

j) Optional delete of files after copy
	C>deltree C:\TrSim\Routes\Usa3\newRoute

k) Close window again
	C>exit


FICTIOUS EXAMPLE (Function 'move'):
In the following example it is presumed, that Trainsimulator is installed in directory "C:\TrSim".
There is also a route-definition called "Usa3", which has to be shifted to Europe. So, the route
is to be shifted 5120 tiles east(X-direction). The position according to Z-direction should NOT
be modified.

Further it is to be accepted, that the execution of commands do NOT produce errors. The examination
of the log-file is not shown, too.


a) Create a Backup of the Route

b) Expand Tile-Files (*.t)
	Use 'Route-Riter' to expand all *.t-files both in directory 'C:/TrSim/Routes/Usa3/Tiles'
	as well as in directory 'C:/TrSim/Routes/Usa3/LO_Tiles', if present.

c) Open a DOS-Window
	Presumption: The new Window opens to directory "C:\"

d) Delete target-directory, if present
	C>deltree C:\TrSim\Routes\Usa3\newRoute

e) Shift Route-Definition to Europe
	C>java TSUtil -lTSUtil.log move C:/TrSim/Routes/Usa3 5120 0

f) Delete of original directories/files from route-definition
	C>deltree C:\TrSim\Routes\Usa3\TD
	C>deltree C:\TrSim\Routes\Usa3\world
	C>deltree C:\TrSim\Routes\Usa3\Tiles
	C>deltree C:\TrSim\Routes\Usa3\LO_Tiles		(if present)
	C>deltree C:\TrSim\Routes\Usa3\Activities
	C>deltree C:\TrSim\Routes\Usa3\Paths
	C>deltree C:\TrSim\Routes\Usa3\Services
	C>deltree C:\TrSim\Routes\Usa3\Traffic

g) Activation of newly created files (please overwrite)
	C>xcopy C:\TrSim\Routes\Usa3\newRoute\*.* C:\TrSim\Routes\Usa3 /s

h) Optional delete of files after copy
	C>deltree C:\TrSim\Routes\Usa3\newRoute

i) Reduce all Tile-files (*.t) again
        (obsolete, if '-c' option is used in step e) or if the files were already reduced)
	Use 'Route-Riter' to compress all *.t-files both in directory 'C:/TrSim/Routes/Usa3/Tiles'
	as well as in directory 'C:/TrSim/Routes/Usa3/LO_Tiles', if present.

j) Reduce/Compress all world-files again (optional, you can also use 'Route-Riter')
	C>java TSUtil -lTSUtil.log cmp -w -c C:/TrSim/Routes/Usa3

k) Activation of newly created files (please overwrite)
	C>xcopy C:\TrSim\Routes\Usa3\newRoute\World\*.* C:\TrSim\Routes\Usa3\World

l) Optional delete of files after copy
	C>deltree C:\TrSim\Routes\Usa3\newRoute

m) Close window again
	C>exit


HISTORIE:
30.07.2003 - V2.0 Release for use
01.08.2003 - V2.0 Extended Check of plausibility
05.08.2003 - V2.0 Minor error-corrections and optimizations (Logging)
17.08.2003 - V2.1 New function 'shift'
25.08.2003 - V2.1 Support of 'identical section - definitions'
05.09.2003 - V2.1 Correction of errors(upper/lower case)
22.09.2003 - V2.2 Implementation of several new options and function 'cmpw'
30.10.2003 - V2.3 New function 'tsconv'
19.01.2004 - V2.3 Support of blank in Route-Names, error-corrections
21.01.2004 - V2.3 additional options, optimizations
23.01.2004 - V2.4 New function 'ichk'
00.00.0000 - V2.5 New function 'rendb'
16.02.2004 - V2.6 Redesign of execution (read - check - (write))
07.04.2004 - V3.0 New fully referenced data-modell, check of tile-Definitions
		    check of quad-tree, new function 'move', new function 'chkup'
13.04.2004 - V3.0 Error-correction, exact version-identification
11.05.2004 - V3.0 Additional arguments (cvrt,...), intern: local 'tsection.dat' changed
18.05.2004 - V3.0 Error-corrections and optimizations
21.05.2004 - V3.0 Implementation of error-correction in 'rendb' - function
27.05.2004 - V3.0 New function 'adjh' (not available for download)
01.07.2004 - V3.0 Error-corrections and extended check within function 'ichk'
15.07.2004 - V3.0 First, not fully translated, english version
09.08.2004 - V3.0 Error-corrections, Second english version (not fully translated, too)
12.08.2004 - V3.0 Error-corrections, Third english version (Translation almost completed)
19.08.2004 - V3.0 Error-corrections, Fully translated english version
13.09.2004 - V3.0 Error-corrections, Support of multiple signal-script-files
31.10.2004 - V3.0 Error-corrections, Extended check of local 'tsection.dat'
15.11.2004 - V3.0 Error-corrections (not available for download)
20.11.2004 - V3.0 New function 'cmp', new function 'unc', minor error-corrections,
		    new global option, changes in documentation
26.11.2004 - V3.0 New function 'filt', enhanced Error-Messages
05.12.2004 - V3.0 Function 'filt'->'filter', Error-corrections, 'ichk' checks Activities
07.12.2004 - V3.0 Error-corrections
28.12.2004 - V3.0 Error-corrections, Implementation of new file-Interface to some functions
		    (version is NOT available for download)
16.01.2005 - V3.1 Error-corrections, new function 'merge', advanced file-interfaces
27.01.2005 - V3.1 Error-corrections
06.02.2005 - V3.2 Error-corrections, support of tiles with edge-length>1, new function 'clrdb'
		    extended documentation
10.02.2005 - V3.2 Error-corrections
12.02.2005 - V3.2 Error-corrections
17.02.2005 - V3.2 Error-corrections
22.02.2005 - V3.2 Error-corrections, extended support of local options
22.03.2005 - V3.2 Error-corrections, extended 'Merge'-funktion (Signaldefinition)
31.03.2005 - V3.2 Error-corrections
29.04.2005 - V3.2 Error-corrections
27.05.2005 - V3.2 Error-corrections, new "Correction-mode" for world-definitions
22.06.2005 - V3.2 Error-corrections, optimizations within various class-definitions
28.07.2005 - V3.2 Error-corrections, new function 'shftdyn', optimizations
26.08.2005 - V3.2 Error-corrections, enhancement of function 'shftdyn'
10.09.2005 - V3.2 Error-corrections
15.09.2005 - V3.2 Error-corrections, new options for function 'rendb', new function 'version'
02.11.2005 - V3.2 Error-corrections, new support of some undocumented keywords
22.11.2005 - V3.2 Error-corrections
06.12.2005 - V3.2 Error-corrections, new function 'fmgr', internal optimisations
31.12.2005 - V3.2 Error-corrections; fixing for enhancement to version 3.3
		    (version is NOT available for download)
04.09.2006 - V3.3.00 Error-corrections; support of 'Hidewire' or 'Dynatrax' - modifications
		    creation of static representations of trackobjects;
		    optimization of internal procedures; changed activation of LOG-file; 
		    extended check of 'path'-, 'service'- and 'traffic'-files;
		    new function 'zusi'; enhanced fault-tolerance;
19.09.2006 - V3.3.01 Error-corrections within documentation and messages
29.01.2007 - V3.3.04 Error-corrections; enhancement within identification of 'Hidewire'-Objects (-z);
		    internal redesign of java-objects for easy implementation of new functions and performance;
		    additional extension of filenames with an accesspath;
28.03.2007 - V3.3.05 Error-corrections; internal standardizations(Queue); Enhancement of file-manager(fmgr);
		     Fault-tolerance for File-IDs of files;
11.04.2007 - V3.3.06 Error-corrections (specially: I/O-buffering for TS-files)
13.07.2007 - V3.3.06 Error-corrections






ATTENTION:

- This Software was provided and tested on my own PC. I'm not and i cannot be held responsible for
	damages to Hard- and Software, which may occur.
- Development of this program proceeds. This includes the correction of errors, which normally cannot
	be avoided. So, the latest version of this program should be downloaded from:
	'carloshr.privat.t-online.de'  or (alias) 'www.carloshr.homepage.t-online.de'


Credits:

Many thanks to 'Don Quichotte' for his unresting test of new functions. Many thanks also for helpful suggestions
  of new TSUtil-functions and improvement of existing functions
I also like to thank Mike Simpson for integrating this software into Route-Riter and for his great work on testing
  the TSUtil-functions


CopyRight:
----------

This utility is Freeware and my be spread and copied as long as the contents of this ZIP-file is not
changed. All other changes require the consent of the author.
If this software is used to create, modifiy or check payware-routes, the usage of this utiltiy must be mentioned
in the credits/instruction-file of this route. Otherwise the usage of TSUtil is NOT permitted. 

Contact:
	carlosHR@t-online.de


======================================================================================================================

A)Annex: Properties of 'Correction-Mode'
	 -------------------------------

ATTENTION: This description is pimarily designed for experts, who will know and understand all features of TSUtil
	and who also understand the fundamentals of electronic data-processing.

If 'correction-mode' is active and if they are missed, some definition-lines are automaticly added to an
object-definition using default-values. These default-values are either created following a fix rule or read from
the property-file.
The following definitions are used:

Object-type !	Keyword		   !	Y   !	Key	  !	Rule
------------------------------------------------------------------------------------------------------------ 
TrackObj	Elevation		3	TSUidX03	-
TrackObj	VDbId			25	-		fix value '4294967294'
TrackObj	StaticDetailLevel	26	-		current level is inserted
DynTrack	Elevation		3	TSUidX13	-
DynTrack	VDbId			25	-		fix value '4294967295'
DynTrack	StaticDetailLevel	26	-		current level is inserted
Signal		VDbId			25	-		fix value '4294967295'
Signal		StaticDetailLevel	26	-		current level is inserted
Static		StaticDetailLevel	26	-		current level is inserted
Forest		ScaleRange		2	TSUidX42	-
Forest		Area			3	TSUidX43	-
Forest		Population		4	TSUidX44	-
Forest		TreeSize		5	TSUidX45	-
Forest		VDbId			25	-		fix value '4294967295'
Forest		StaticDetailLevel	26	-		current level is inserted
Platform	VDbId			25	-		fix value '4294967295'
Siding		VDbId			25	-		fix value '4294967295'
Gantry		VDbId			25	-		fix value '4294967295'
Speedpost	Speed_Text_Size		3	TSUidX83	-
Speedpost	VDbId			25	-		fix value '4294967295'
CarSpawner	CarFrequency		1	TSUidX91	-
CarSpawner	CarAvSpeed		2	TSUidX92	-
CarSpawner	VDbId			25	-		fix value '4294967295'
LevelCr 	Crashprobability	2	TSUidXA2	-
LevelCr 	LevelCrTiming		4	TSUidXA4	-
LevelCr		VDbId			25	-		fix value '4294967295'
Hazard		VDbId			25	-		fix value '4294967295'
Transfer	VDbId			25	-		fix value '4294967295'
Transfer	StaticDetailLevel	26	-		current level is inserted
CollideObject	VDbId			25	-		fix value '4294967295'
Telepole	VDbId			25	-		fix value '4294967295'
Pickup		VDbId			25	-		fix value '4294967295'

(Remark: Y refers to bit-number of Y-mask (see below))


If the upper table specifies a key, this key is used to read the default-value from the property-file
(TSErrMsg???.properties) The read data is - surrrounded by additionally blanks - used as the argument of the
new definition-line.
Normally, fix values are defined in the property-file using these keys. On the other side, user can
modify the file and change the values. Then, he can also use some placeholders, which are dynamically replaced,
when writing the (new) definition-line to the output-file:
- ID '%0' will be replaced by the current file-name of the object ("" if not available)
- ID '%1' will be replaced by the current UiD-value
- ID '%2' will be replaced by the current Y-value (compare to table)


Additionally 'online-configuration' of TSUtil can control if a default-definition is added to output.
'Online-configuration' uses hidden global options to dynamically control the behaviour of TSUtil. So, the
option '$D' is used to decide, if a default-definition is added.  
Option '$D' looks like this:
	-$Dxxxx:yyyyyyyy	(Attention: 'D', not 'd')
Both 'xxxx' and 'yyyyyyyy' define a  hexadecimal mask, which exactly holds 4 respectively 8 hex-digits.
All bits of these masks are numbered from right to left, starting with '0'. So, X-mask contains 16 (15..0) and
Y-mask 32 (31..0) bits.

The bits of X-Mask are assigned to the following object-types:
 0 - TrackObj
 1 - DynTrack
 2 - Signal
 3 - Static
 4 - Forest
 5 - Platform
 6 - Siding
 7 - Gantry
 8 - Speedpost
 9 - CarSpawner
10 - LevelCr
11 - Hazard
12 - Transfer
13 - CollideObject
14 - Telepole
15 - Pickup

In order to apply Y-mask to an object-type-definition, the assigned bit has to be set. So, 'FFFF' can be used to
apply Y-mask to all object-types, while '0000' will show NO impact to any definition.

The bits of Y-mask are assigned as follows:
0..15 - depends on object-type.
16 - TrItemId
17 - CollideFlags
18 - Collidefunction
19 - FileName
20 - StaticFlags
21 - Position
22 - QDirection
23 - Matrix3x3
24 - MaxVisDistance
25 - VDbId
26 - StaticdetailLevel
27 - SignalSubObj
28 - SignalUnits
29 - NoDirLight
30 -
31 -

All assignments can be seen in the upper table, too. (Y-Bit)
Y-mask specifies, which definition-line should NOT be created. In order to suppress creation of a definition-line
of a special type, the corresponding bit has to be set to '0' (reset). Therefore all UNUSED bits of Y-mask should
be set to '1'.

Examples:
 -$DFFFF:FBFFFFFF - A definition-line 'StaticdetailLevel' is not created for ALL object-types.
 -$D0001:F9FFFFFF - Definition-lines 'StaticdetailLevel' and 'VDbId' are NOT created for TrackObj-definitions.
 -$DFFFF:00000000 - NO definition-lines are created which contain default-definitions.
			(All other properties of 'correction-mode' are still active.)


B)Annex: Definition of 'regular expressions'
	 -----------------------------------

A 'regular expression' is used to check if a given characterstring matches this expression. So it is
possible to select a subset of strings from a set of strings (e.g. filenames).

A 'regular expression' consists of characters WITH and WITHOUT 'special meaning'. A character WITHOUT
'special meaning' represents the character itself. Characters without 'special meaning' have to occur in a
string, which should be checked, in the same sequence. Then this expression matches the given string.
Sometimes, no attention is paid to case of charactes, but this depends on the compare-method. All
'regular expressions', which are used in TSUtil, do NOT pay attention to case of characters. 

The impact of the most important characters WITH 'special meaning' is now described. It differs from character
to character or from charactergroup to charactergroup. 

Char	Meaning
 .	This character is a placeholder, which matches ANY single character.
	  It has NO 'special meaning' within a characterlist. (as defined below)
 \	If another character with 'special meaning' follows this character, the 'special meaning' of this
	  following character is suppressed and it is used as the character itself. In the other case a
	  charactergroup (characterclass) is defined, which itself has a'special meaning'. Some of these groups
	  are listed here.
	  If \ is followed by a character, which DO NOT define a charactergroup, this expression is erroneous.
	  The following character may be  \ , which defines " \ WITHOUT 'special meaning' ".
 ?	The PREVIOUS character must be used ONCE or NOT AT ALL.
 *	The PREVIOUS character must be used ZERO or MORE TIMES.
 +	The PREVIOUS character must be used ONE or MORE TIMES.
 (n)	The PREVIOUS character must be used EXACTLY n TIMES (n is a number).
 (n,)	The PREVIOUS character must be used AT LEAST n TIMES (n is a number).
 (n,m)	The PREVIOUS character must be used AT LEAST n but NOT MORE than m TIMES (n,m are numbers).
 [	Start of a characterlist
 ]	End of a characterlist e.g.: [0123] - This defines digit 0 to 3: ONE of these digits must occur
	  This character only has a 'special meaning', if a characterlist is active. (after [ )
 -	(1) Specifies a range of characters within a characterlist e.g.: [A-Z] - All letters betweeen A and Z
	(2) NO 'special meaning' outside a characterlist.
 ^	(1) Negates the meaning of the characters within a characterlist. e.g. [^04] - All characters but NOT 0 and 4
	(2) Start of a characterstring. (next specification refers to the FIRST character of the string)
 |	The previous OR the following character has to occur in the string to be checked.
 \d	Any digit. (= [0-9])
 \D	Any character, which do NOT form a digit. (= [^0-9])
 \w	Any characer used to build a word (digits and letters). (= [a-zA-Z0-9])
 \W	Any character, which is NOT used to build a word. (= [^\w])
 \t	The tab-character
 \n	The 'newline'-character
 \r	The 'carriage-return'-character
 \f	The 'form-feed'-character
 \s	Any whitespace-character (blank, newline, formfeed, ...)
 \S	Any character, which is NOT a whitespace-character
 \xhh	The character with the hexadecimal value 'hh'
 \uhhhh	The unicode-character with the hexadecimal value 'hhhh'

These are only part of the characters, which have a 'special meaning'. In order to get a complete list you should
refer to literture.

Examples of 'regular expressions':
 '...\.\d' - three characters follwed by a dot and a digit
 '.(8)\.[01](3)' - exactly eight characters folowed by a dot and exactly three digits 0 or 1
 '.(8)[.][01](3)' - same meaning as last expression (Dot has no 'special meaning' inside a charcterlist)
 '.+\*.' - one to n characters followed by a asterisk and another character.
 '.+\(x\)' - one to n characters (any character) followed by '(x)'.


C)Annex: Short description of Meta-Language
	 ----------------------------------

The Meta-Language, which is used in this documentation to specify commands, is as follows: 

  - Placeholder, that means 'names' which represent a string or a number or ... (e.g. filename), are enclosed with
	angle brackets. e.g.: <xx> - xx is a placeholder-variable
  - Optional elements, which can be placeholder,... too, are surrounded with square brakets.
	e.g.:	[H] - the letter H is optional
		[<name>] - the placeholder 'name' is optional
  - A selective element is a list of elements of which ONE element is requested. Such a list is surrounded with
	curly brackets and the single elements are divided by '|'.
	e.g..: {A|B|C} - letter A or letter B or letter C is requested/possible.
  - All other elements/characters are written in the same form as they are requested. But someone should be aware
	of the case of the letters. This ALSO applies to 'blank'-characters.
  - Optional and selective elements may be nested. However selective elements may be optional but not vice versa.
	(e.g. because: {[X]|Y|Z} = [{X|Y|Z}] but {X[E]|Y|Z})

Example:  The Meta-Text
	"Txt <name> [{I|O}] [ext]"
 with "'name' is placeholder for 'C:\boot.txt'" expands as follows(exactly):
	"Txt C:\boot.txt  "
	"Txt C:\boot.txt I "
	"Txt C:\boot.txt O "
	"Txt C:\boot.txt  ext"
	"Txt C:\boot.txt I ext"
	"Txt C:\boot.txt O ext"
It is not a task of Meta-Languages to define, which of these lines should be selected. This depends on the context of
 the definition.

