SimSig timetable data converter

Instructions for use

Clive Feather

Version 2.28 or later

Introduction

The timetable data converter allows you to represent SimSig timetables in a text form which can be edited using any convenient text editor. It also allows the use of a "copy and modify" approach so that a schedule can be written once and then used for several trains, possibly with variations. It also handles timetable rules.

You can download it here (212kB).

Usage

The converter must be run from a Windows command-line prompt (also known as an "MS-DOS prompt" or "Command Prompt"). To convert a SimSig timetable file (say my_tt.wtt) to a text file (say my_tt.txt), enter the command:

ConvData -C my_tt.wtt my_tt.txt

(the -C can be omitted). To convert back, enter:

ConvData -c my_tt.txt my_tt.wtt

(the -c is now lowercase and is required).

In each case, any existing destination file is overwritten without warning. The converter does not pay attention to file suffixes, but SimSig requires the timetable to have the .wtt suffix and some text editors require a .txt suffix.

There are also various option flags. These are also placed between the command name and file names (either as one combined argument, separate arguments, or a mix) with a leading dash. Thus, for example, conversion to a timetable file with the i and r flags can be written as any of:

ConvData -cir my_tt.txt my_tt.wtt
ConvData -rci my_tt.txt my_tt.wtt
ConvData -c -r -i my_tt.txt my_tt.wtt
ConvData -r -c -i my_tt.txt my_tt.wtt
ConvData -rc -i my_tt.txt my_tt.wtt
ConvData -i -cr my_tt.txt my_tt.wtt

or indeed other arrangements. The available flags are:

To include rules in conversions, the R flag must be used. The name of the rules file is derived from the name of the timetable file by changing the final t to an r. So either of the commands:

ConvData -CR my_tt.wtt my_tt.txt
ConvData -cR my_tt.txt my_tt.wtt

will use the rules file my_tt.wtr (in the latter case the file will be overwritten without warning if it exists). In the unusual case that a different filename is required, it can be provided as an additional argument; thus the above commands can also be written:

ConvData -CR my_tt.wtt my_tt.txt my_tt.wtr
ConvData -cR my_tt.txt my_tt.wtt my_tt.wtr

A message will be printed when conversion is complete. To suppress this message, use the V flag.

Text file format

General

The text file consists of a number of blocks. A block can describe the overall timetable, a train type, a schedule used by several trains, a specific train, or a rule. A block begins with a name and then contains one or more key=value pairs, separated by semi-colons and ending with a full stop. For example:

    EMU365
        DES='Class 365 EMU';
        MXS=100; LEN=80; BRK=High; PWR=AC.

is a block called "EMU365" with five values.

Where a block describes a train or a schedule, it can also have a list of calling points. These come after the last value and before the full stop. The data for each calling point is in parentheses and, once again, consists of a name (actually an abbreviation) and a list of key=value pairs. The calling points can be separated by commas or semicolons, or just follow one another. For example:

    1D01
        ENP=ANYTOWN; ENT=10:23;
        MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=11:02; DEP=11:04; ENA=1H; PLT=2)
        (SEASIDE ARR=11:10; DEP=11:20).

The converter will determine the different types of block by examining the keys that appear within each block. The order of the keys in a block or calling point is not significant. However, the order of the calling points within a block is significant. Nearly all keys can be omitted, in which case a default value is used (unless stated specifically otherwise, the default is an empty string, the number 0, or the value "false" as appropriate). The converter will complain if there are insufficient keys to determine the type of the block.

When converting a timetable file to text, the converter is conservative - it always starts with the general information, then the train types, then the individual trains (and, if the R flag is specified, the rules follow this). If a timetable is converted to text and the resulting file converted back, the two timetables will be identical. However, text files have much more leeway than this; for example, train types may be freely mixed with individual train details and generic schedules, and rules can be placed with one or other of the associated trains. Thus converting text to a timetable and back again might not produce an identical file.

Keys tagged with a † (dagger) are not compatible with very old simulations (see the k and K flags above).

Syntax rules

The following general syntax rules apply to the text files:

• A hash sign (#) starts a comment that lasts to the end of the line.
• Any string, including a number or a key, can be placed in either single or double quotes. The syntactic delimiters (equals, semi-colon, etc.) must not be quoted when performing their role, and must be quoted if they are part of a string.
• A quoted string ends at the first occurrence of the quote character that starts it.
• An unquoted string ends at the first space, tab, newline, parenthesis, comma, semicolon, full stop, or equals sign.
• A backslash (\) introduces an escape sequence. These do not end strings even if the character they represent would have done.
  • Backslash followed by newline is ignored, so it can be used to break long strings into several lines.
  • Backslash followed by itself, single or double quote, or a space represents that character.
  • Backslash followed by n represents an actual newline.
  • Backslash followed by X (in either case) and then two hexadecimal digits is a hexadecimal escape and represents the character with that code. Thus \x42 is another way of writing B (which has code 42).
• Except when using backslash followed by newline, a string - quoted or unquoted - must all be on a single line (the k flag overrides this rule).
• A string has the same meaning whether quoted or not and no matter how its characters are represented. Thus the five strings:

      "A B"
      'A B'
      'A\x20B'
      A\ B
      A\ \
  B

  all have the same meaning. This applies even to numbers and other special formats.

In general, white space (spaces, tabs, and new lines) can be added or omitted as you like without having any effect on the meaning. The exceptions are:

• White space is meaningful within a quoted string and ends an unquoted string.
• White space is needed between the name of a block and the first key.
• White space must not appear either side of the colon in a time expression or an ACT value at a calling point.

A number is a string of digits. Times and durations can be written either as hours and minutes with a colon, or as a number of minutes without a colon (if this is used where a time is expected, it will be read as that number of minutes past midnight). In both cases H may be used to indicate an extra half minute.

Times can also appear in the form hour:minute:second, such as 11:22:45. These will sometimes appear in data generated automatically by SimSig, but half-minute accuracy normally suffices.

Earlier versions of the converter had a T before times and an M before periods of time (e.g. T08:11 and M10H). This is no longer necessary, but these letters will still be accepted and ignored.

A "Boolean" value is one that is either true or false. A string beginning with T or Y (in either case) represents true; all other strings represent false.

General information block

There must be at least one general information block in the file. If there is more than one, the last one is used. (This allows two or more files to be concatenated and then converted.)

The block must have the name "SIMSIGT2". It has the following keys:

Example:

    SIMSIGT2
        STT=03:00; END=26:00;
        SIM=Didcot; NAM='Standard weekday';
        DES="A basic weekday timetable, \
containing the actual train\x0D\x0A\
service in 2003 plus some imaginary\x0D\x0A\
freight trains.".

Train type blocks

Train types appear in the timetable as an aid to creating new trains. Even though each train in a timetable has a type, changing the properties of the type won't change the trains of that type already created (this applies both in the converter - unless the UTT key is used for the train - and SimSig itself).

The name of the block is the name of the type. It has the following keys:

Example:

    EMU365
        DES='Class 365 EMU';
        MXS=100; LEN=80; BRK=High; PWR=AC.

Train schedule blocks

These blocks describe individual trains or generic schedules that can be used to describe several trains.

The name of the block is the train identifier or, for generic schedules, a name that can be used to refer to it (these latter names do not appear in the final SimSig timetable file). It has the following keys:

The data is then followed by a list of timing points, each in parentheses (if there is a CTT value, this can be omitted). The name of each timing point is the SimSig code for the location (this is often a TIPLOC code) and it has the following keys:

Example:

    1D01
        ENP=ANYTOWN; ENT=10:23;
        MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=11:02; DEP=11:02+2; ENA=1H; PLT=9A)
        (SEASIDE ARR=11:10; ACT= J:1D03, Next:1L42).

The name of a timing point may be prefixed with an asterisk (e.g. *HLPSTN). This indicates that the timing point was entered automatically by SimSig.

This example shows the use of UTT; these two sets of blocks are equivalent:

    DMU
        DES='Generic DMU';
        MXS=75; LEN=60; BRK=High; PWR=Diesel.

    1F01
        ENP=ANYTOWN; ENT=10:23;
        TYP=DMU; UTT=2;
        (BEECITY ARR=11:02; DEP=11:02+2; ENA=1H; PLT=9A)
        (SEASIDE ARR=11:10; ACT= J:1G03, Next:1L42).

    1F02
        ENP=ANYTOWN; ENT=11:23;
        TYP=DMU; UTT=1; MXS=70;
        (BEECITY ARR=12:02; DEP=12:02+2; ENA=1H; PLT=9A)
        (SEASIDE ARR=12:10; ACT= J:1G05, Next:1L44).

    DMU
        DES='Generic DMU';
        MXS=75; LEN=60; BRK=High; PWR=Diesel.

    1F01
        ENP=ANYTOWN; ENT=10:23;
        TYP=DMU; MXS=75; LEN=120; BRK=High; PWR=Diesel;
        (BEECITY ARR=11:02; DEP=11:02+2; ENA=1H; PLT=9A)
        (SEASIDE ARR=11:10; ACT= J:1G03, Next:1L42).

    1F02
        ENP=ANYTOWN; ENT=11:23;
        TYP=DMU; MXS=70; LEN=60; BRK=High; PWR=Diesel;
        (BEECITY ARR=12:02; DEP=12:02+2; ENA=1H; PLT=9A)
        (SEASIDE ARR=12:10; ACT= J:1G05, Next:1L44).

Rules blocks

Rules are stored in a separate data file and provide relationships between trains.

The name of the block is the train that is being controlled by the rule. It has the following keys:

Example:

    1A01 RUL=MAAE:1A00; TIM=6H.
    1B01 RUL=NotIf:1B00.
    1C01 RUL=DAA:1C00; LOC=NOWHERE; TIM=3.

There is one special rule type: mutually exclusive schedules. The form of this rule type is:

    1B0?   RUL=MutExcl.
    1B11-? RUL=MutExcl:Shunters.

The train identity should include at least one question mark. There need not be a colon and following name; if there is, it will be ignored. The tag MutExcl can be written MX or MutuallyExclusive.

Conversion: the -i flag

If the -i flag is specified when converting files, then:

• When converting to a timetable file, the PWX, CSR, DLY, DLW, ETD, and DPD values will be ignored and replaced by the default value. Any timing points whose name begins with an asterisk will be omitted from the resulting timetable.
• When converting to a text file, the PWX, CSR, DLY, DLW, ETD, and DPD values, and any timing points whose name begins with an asterisk, will be included in the text file but placed after a # sign, so that they will be ignored when converting back even without the -i flag.

These items, of course, are those that aren't required in SimSig timetables.

Time expressions

The four possible times at calling points (ARR, DEP, ENA, and PTA) can each be time expressions. A time expression is a sequence of values added and subtracted from each other. As shown above, these can be numbers and times but, more usefully, they can be references to other times in the train's schedule. Such references are indicated by a code beginning with a percent sign.

The following codes have the same value throughout the schedule:

The following codes have a value that depends on the timing point they are being used with. They come in two parts.

So, for example, %A1 or %D@SEASIDE.

There are a few restrictions on references to the current location:

• %D0 and %S0 may not be used.
• %A0 may only be used in the DEP value.
• %E0 and %P0 may only be used in the ARR and DEP values.

(the same holds when the @place form is used to refer to the current location).

The equivalent entry time (EET) is used by the converter for setting the value of the %EN reference in the same way as the entry time (ENT), but does not appear in the SimSig timetable file. It is ignored if the timetable has an entry time.

The converter will object to invalid references, such as calling points before the start of the schedule or the use of %A or %S where the relevant calling point has PAS or SDO set to true.

So, for example, we can describe a train by giving each time in terms of the previous calling point:

    1D01
        ENP=ANYTOWN; ENT=10:23;
        MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=%EN+39; DEP=%A0+2; ENA=1H; PLT=9A)
        (NOWARE  DEP=%D1+3-%S1; PAS=T; PTA=0H)
        (SEASIDE ARR=%D@BEECITY+6+%P@NOWARE; ACT=Next:1L42).

In this schedule, the train arrives at Beecity 39 minutes after entering the simulation and departs 2 minutes later. It is allowed 3 minutes from arriving at Beecity to passing Noware, but the former is determined by taking the departure time and subtracting the time stopped (this is, after all, just an example of how to use this feature!). Finally, it takes 6 minutes to get from Beecity to Seaside, but we also add on the pathing allowance at Noware in determining the arrival time.

References can also have a second form using a colon, as in %p1:2. This means "if the reference before the colon is non-zero, use the value after the colon; otherwise use the value zero". So, for example, ARR=12:35+%P1:0H will add half a minute to the arrival time if the previous location had a pathing allowance, while ARR=12:35-%s1:0H will subtract half a minute if the previous location had SDO=T. The component to the right of the colon can be a reference itself, so ARR=12:35+%t1:%P2 or even ARR=12:35+%t1:%P2:1H area allowed (the latter adds 1.5 minutes if the previous location had TLS=T and the one before that had a non-zero pathing allowance). In this case, the component to the right of the colon is only checked for validity if the reference on the left is non-zero.

Conversion: the -r flag

If the -r flag is specified when converting timetable files to text, then the ARR and DEP values will be expressed using references according to the following rules:

• Arrival times will use %EN for the first calling point, and %D1 for all others. If the train does not have an entry time, an EET (equivalent entry time) value will be included in the timetable, using the departure time of the first calling point.
• Departure times will use %A0 unless there is no arrival time, or SDO or PAS is true, in which case the same rule applies as for arrival times.
• Offsets up to 99 and a half minutes will be expressed as a number of minutes if possible (that is, it is a multiple of half a minute), and as hours and minutes (and possibly seconds) otherwise.

If the -n flag is also specified, then %D@place will be used instead of %D1.

Using generic schedules

The convertor also allows you to write a schedule once - a generic schedule - and then adapt it to several trains. This is done by writing the generic schedule and then making the other trains refer to it.

Basic technique

For example, let's start with a simple schedule for a regular-interval service:

    DownRegular DTT=T;
        DES="Down regular-interval service";
        ENP=ANYTOWN; ENT=08:00;
        TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=%EN+39; DEP=%A0+2; PLT=9A)
        (NOWARE  DEP=%D@BEECITY+2; PAS=T; PTA=0H)
        (SEASIDE ARR=%D@BEECITY+6+%P@NOWARE; DEP=%A0+0H).

Note the DTT=T value. This indicates that this is a generic schedule and should not itself appear in the generated timetable file. Instead, we use this schedule in several trains:

    1R01 CTT=DownRegular; ENT=08:21.
    1R03 CTT=DownRegular; ENT=09:21.
    1R05 CTT=DownRegular; ENT=10:21.
    1R07 CTT=DownRegular; ENT=11:22H.

The CTT value tells the converter where to find the remaining details of the train. If we convert this to a timetable and then convert it back again, we will find the following (edited slightly for convenience):

1R01
  DES='Down regular-interval service';
  ENP=ANYTOWN; ENT=08:21;
  TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=09:00; DEP=09:02; PLT=9A)
  (NOWARE  DEP=09:04; PAS=T; PTA=0H)
  (SEASIDE ARR=09:08H; DEP=09:09).
1R03
  DES='Down regular-interval service';
  ENP=ANYTOWN; ENT=09:21;
  TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=10:00; DEP=10:02; PLT=9A)
  (NOWARE  DEP=10:04; PAS=T; PTA=0H)
  (SEASIDE ARR=10:08H; DEP=10:09).
1R05
  DES='Down regular-interval service';
  ENP=ANYTOWN; ENT=10:21;
  TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=11:00; DEP=11:02; PLT=9A)
  (NOWARE  DEP=11:04; PAS=T; PTA=0H)
  (SEASIDE ARR=11:08H; DEP=11:09).
1R07
  DES='Down regular-interval service';
  ENP=ANYTOWN; ENT=11:22H;
  TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=12:01H; DEP=12:03H; PLT=9A)
  (NOWARE  DEP=12:05H; PAS=T; PTA=0H)
  (SEASIDE ARR=12:10; DEP=12:10H).

Note how the ENT time in the generic schedule has been ignored in favour of that in the specific trains, and how the use of references in the schedule means that the times are all adjusted appropriately. We will see how to introduce further variation into a schedule later.

The generic schedule can be a train in its own right as well; we do this by not setting the DTT value to true. For example, we could produce the same timetable as before by writing:

    1R01
        DES="Down regular-interval service";
        ENP=ANYTOWN; ENT=08:21;
        TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=%EN+39; DEP=%A0+2; PLT=9A)
        (NOWARE  DEP=%D@BEECITY+2; PAS=T; PTA=0H)
        (SEASIDE ARR=%D@BEECITY+6+%P@NOWARE; DEP=%A0+0H).
    1R03 CTT=1R01; ENT=09:21.
    1R05 CTT=1R01; ENT=10:21.
    1R07 CTT=1R01; ENT=11:22H.

Which approach to use is entirely a matter of taste and convenience for the timetable author.

Overriding properties

Any of the items in the generic schedule can be overridden simply by providing the new value in the specific train schedule. For example, the following makes train 1R09 longer and turns 1R13 into an EMU.

    # Using same definition of DownRegular as before:
    1R01 CTT=DownRegular; ENT=08:21.
    1R03 CTT=DownRegular; ENT=09:21.
    1R05 CTT=DownRegular; ENT=10:21.
    1R07 CTT=DownRegular; ENT=11:22H.
    1R09 CTT=DownRegular; ENT=12:21; LEN=160.
    1R11 CTT=DownRegular; ENT=13:21.
    1R13 CTT=DownRegular; ENT=14:21; TYP=EMU365; PWR=AC.

In actual fact, the different ENT times are just an example of this: the ENT=08:00 in the generic schedule isn't used at all. If we omitted the ENT value from one train, that one would be given an entry time of 08:00.

Overriding calling points

Calling points can also be overridden in the same way. For example, we can make one train set-down only at Noware:

    1R15 CTT=DownRegular; ENT=15:21;
        (NOWARE  DEP=%D@BEECITY+2; SDO=T)
    .

producing the schedule

1R15
  DES='Down regular-interval service';
  ENP=ANYTOWN; ENT=15:21;
  TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=16:00; DEP=16:02; PLT=9A)
  (NOWARE  DEP=16:04; SDO=2)
  (SEASIDE ARR=16:08; DEP=11:08H).

Note that the calling point is completely replaced - for example, the pathing allowance is not copied. Several calling points may be overridden; if so, they can be specified in any order.

Where the changes to a calling point are fairly small (e.g. changing the pathing allowance) it may be better to use substitutions, which are described below. Which approach to use is entirely a matter of taste and convenience.

Adding and removing calling points

The technique of modifying calling points can also be used to add and remove them. If a calling point has no keys associated with it at all, it is a placeholder and will not appear in the final timetable. However, it exists for all other purposes - for example, references like %D3 include placeholders when counting back to the correct timing point. Placeholders are useful in two ways:

• A placeholder can be overridden to include a calling point in one schedule but not the rest.
• A calling point can be omitted from a schedule by overriding it with a placeholder.

For example:

    DownBranch DTT=T;
        DES="Down branch service";
        ENP=ANYTOWN; ENT=08:00;
        TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (RIVERTN  DEP=%EN+5)
        (BASEMNT  DEP=%D@RIVERTN+5)
        (CLIFFE)
        (HILLTOP  DEP=%D@BASEMNT+10)
    .
    2B01 CTT=DownBranch; ENT=08:00.
    2B03 CTT=DownBranch; ENT=09:00; (BASEMNT).
    2B05 CTT=DownBranch; ENT=10:00; (CLIFFE DEP=%D@RIVERTN+9).
    2B07 CTT=DownBranch; ENT=11:00.

producing the schedules

2B01
    DES="Down branch service";
    ENP=ANYTOWN; ENT=08:00;
    TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
    (RIVERTN  DEP=08:05)
    (BASEMNT  DEP=08:10)
    (HILLTOP  DEP=08:20)
.
2B03
    DES="Down branch service";
    ENP=ANYTOWN; ENT=09:00;
    TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
    (RIVERTN  DEP=09:05)
    (HILLTOP  DEP=09:20)
.
2B05
    DES="Down branch service";
    ENP=ANYTOWN; ENT=10:00;
    TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
    (RIVERTN  DEP=10:05)
    (BASEMNT  DEP=10:10)
    (CLIFFE   DEP=10:14)
    (HILLTOP  DEP=10:20)
.
2B07
    DES="Down branch service";
    ENP=ANYTOWN; ENT=11:00;
    TYP=D210; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
    (RIVERTN  DEP=11:05)
    (BASEMNT  DEP=11:10)
    (HILLTOP  DEP=11:20)
.

These techniques can be useful, but care should be taken: a placeholder does not have arrival or departure times and so has no %A or similar references (but does have %i etc., so constructions like %i1:%A1 work).

Chaining

A schedule that refers to another, using CTT, can in turn refer be referred to by other schedules. This process is called chaining and can be carried out to any number of levels. The schedule that lists the calling points of a train is called the core schedule of that train and lies at the end of the chain. The basic rule is that each property of the train is taken from the first schedule in the chain that mentions it. The list of calling points is taken from the core schedule but, for each calling point, the first schedule in the chain that mentions it defines its properties (and whether or not it is a placeholder).

For example, the following file defines a general Up train, then creates DMU and EMU versions, and finally builds a timetable:

    UpRegular DTT=T;
        DES="Up regular-interval service";
        ENP=SEASIDE;
        (NOWARE  PAS=T;         DEP=%EN+4; PTA=1)
        (BEECITY ARR=%EN+6+%P1; DEP=%A0+2; PLT=7)
        (ANYTOWN ARR=%D1+40;    DEP=%A0+5).
    UpDMU CTT=UpRegular; DTT=T; TYP=D210;   MXS=90; LEN=80; BRK=Med; PWR=Diesel.
    UpEMU CTT=UpRegular; DTT=T; TYP=EMU317; MXS=90; LEN=80; BRK=Med; PWR=AC.
    1R02 CTT=UpEMU; ENT=08:40.
    1R04 CTT=UpEMU; ENT=09:40.
    1R06 CTT=UpDMU; ENT=10:40.
    1R08 CTT=UpEMU; ENT=11:40; LEN=160.
    1R10 CTT=UpDMU; ENT=12:40.
    1R12 CTT=1R08;  ENT=13:40; MXS=85.

Note how 1R08 has a different length and 1R12 is in turn chained from 1R08 (meaning that the full chain is 1R12-1R08-UpEMU-UpRegular).

Substitutions

Sometimes a set of trains run at very similar timings but not identical ones - for example, they may have different pathing allowances or may use a different platform at one station. It would also be nice to be able to include the time of a train in its description without having to give the full description. Both of these, and more, can be done using substitutions. A substitution is indicated by $character$. It is defined as a property of a schedule and then used in values.

For example, let's take the previous UpRegular service and allow some flexibility:

    UpRegular DTT=T;
        DES="Up $@$ regular-interval service";
        ENP=SEASIDE;
        $P$=7;
        (NOWARE  PAS=T;         DEP=%EN+4; PTA=$N$)
        (BEECITY ARR=%EN+6+%P1; DEP=%A0+2; PLT=$P$)
        (ANYTOWN ARR=%D1+40;    DEP=%A0+5).
    UpDMU CTT=UpRegular; DTT=T; $N$=1H; TYP=D210;   MXS=90; LEN=80; BRK=Med; PWR=Diesel.
    UpEMU CTT=UpRegular; DTT=T; $N$=1;  TYP=EMU317; MXS=90; LEN=80; BRK=Med; PWR=AC.
    1R02 CTT=UpEMU; ENT=08:40; $@$=0820.
    1R04 CTT=UpEMU; ENT=09:40; $@$=0920.
    1R06 CTT=UpDMU; ENT=10:40; $@$=1020.
    1R08 CTT=UpEMU; ENT=11:40; $@$=1120; $P$=1C.
    1R10 CTT=UpEMU; ENT=12:40; $@$=1220; $N$=3.

This example uses three substitutions:

• $P$ is the platform number at Beecity. A value of 7 is specified as part of UpRegular, so this is used by all trains except 1R08.
• $N$ is the pathing allowance at Noware. No value is specified as part of UpRegular, but each of UpEMU and UpDMU have their own values. Train 1R10 overrides this value.
• $@$ is the time to appear in the description. No value is specified in any of the generic schedules, so one has to be provided for each train.

Note how the normal rules for chaining apply, so the value for $N$ specified by train 1R10 overrides that in UpEMU (which, in turn, would override a value specified in UpRegular if one was).

There are a few special rules that apply to substitutions and which should be taken into account.

• Substitutions do not have a default. So any substitution used in a train must have a definition somewhere in the chain. In particular, this means that if a core schedule uses a substitution and does not define it, all schedules referring to that one must define the substitution somewhere (it also means that the core schedule must have DTT=T).
• Substitutions are not expanded in the definition of a substitution. So, given $A$="X$B$X"; $B$=Z;, the value of $A$ is not XZX. This does, however, mean it is possible to get a dollar sign into a string by defining and using a substitution like $$$=$;.
• Substitutions can only appear:
  • in string values - the substitution can have any value;
  • in time expressions - the substitution must be a simple time and not an expression using + and -, but it can be a reference such as %D@SEASIDE;
  • as the train ID in an ACT value (for example, ACT=Join:$T$).
  They can't be used for Boolean values (like PAS), numbers (like MXS), codes (like BRK), the entry time (ENT), in the action part of ACT values, or in rule blocks.
• Case is significant in substitution names, so $A$ and $a$ are different substitutions.
• More generally, any character can be used as the central character of the substitution name. So all of the following are valid substitutions:
  

  $7$       $<$
  $\ $      $"$
  $\x0A$    $\xCC$

  
  though of course care will be needed in quoting some of them. However, $+$ and $-$ cannot be used in time expressions for technical reasons.

Future versions of the converter may introduce other kinds of substitution, all of which will begin with a dollar sign.

Reference times and relative times

There is another way to adjust the times on schedules when referring to them in other trains. This technique is best used with existing schedules that have been written using specific times, rather than those constructed from scratch using the %D and %A references. This technique involves the use of reference times. There are two different ways this can be done.

1. Write the initial schedule using simple times and then define other trains using an offset in the RFT value for each train. For example:
   

       1D01
           DES="Metropolis to Zedville service";
           ENP=ANYTOWN; ENT=10:23;
           MXS=90; LEN=80; BRK=Med; PWR=Diesel;
           (BEECITY ARR=11:02; DEP=11:02+2; ENA=1H; PLT=9A)
           (SEASIDE ARR=11:10; DEP=11:15).
       1D03 CTT=1D01; RFT=1:05.

   
   This will produce a train 1D03 which has all times exactly 1 hour 5 minutes later than 1D01.
2. Write the initial schedule using times based on a "reference" time, which is specified in the RFT value for the generic timetable, then define other trains using the equivalent time in their own RFT value. For example, using the time that the train is due at Zedville as the reference time:
   

       1D01
           DES="Metropolis to Zedville service";
           RFT=11:30;  # Arrival time at Zedville
           ENP=ANYTOWN; ENT=10:23;
           MXS=90; LEN=80; BRK=Med; PWR=Diesel;
           (BEECITY ARR=11:02; DEP=11:02+2; ENA=1H; PLT=9A)
           (SEASIDE ARR=11:10; DEP=11:15).
       1D03 CTT=1D01; RFT=12:35.

   
   This will produce the same timetable as in the previous method.

In both cases it is still possible to use substitutions and to override particular values, just as before. It is also possible to use the various percent-references within the core schedule. However, the latter requires care and it is important to understand exactly how the various aspects interrelate.

The RFT value for a train - determined using the normal rules for finding a value in a chain of schedules - is called its train reference time and can be used in time expressions by writing %RT. The RFT value for the core schedule - that is, the one found in the block actually containing all the calling points - is called its core reference time and can be used in time expressions by writing %RC. The difference between the two (%RT-%RC) is called the schedule offset. (Note that if RFT isn't used in any part of the chain then the schedule offset is zero and all of the following can be ignored.)

The schedule offset is applied to the entry time (ENT) and to calling point arrival and departure times (ARR and DEP), but not to anything else (e.g. pathing allowance). Each of the times is categorised as relative or absolute; the schedule offset is added to relative times but not absolute times.

• If the entry time or time expression begins with the letter U (in either case) the time is absolute.
• If a time expression contains any of the references %EN, %RT, %RC, %A, or %D, the time is absolute; however, for a reference with a colon in it, this only applies to the part after the last colon.
• If a time expression contains a substitution and that value is prefixed with U (e.g. U12:34H), the time is absolute.
• Otherwise the time is relative and the schedule offset is applied to it. For clarity:
  • The entry time is relative if it does not begin with U.
  • The arrival and departure times are relative if they don't begin with U, don't use substitutions that begin with U, and don't use the references %A and %D.

For example:

RelativeDemo DTT=T;
        DES="Metropolis to Zedville service";
        RFT=13:30;  # Arrival time at Zedville
        ENP=ANYTOWN; ENT=10:23;
        TYP=DMU; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
        (BEECITY ARR=11:02; DEP=11:02+2)
        (SEASIDE ARR=%D1+6; DEP=%A0+5)
        (DEEPORT ARR=U$D$;  DEP=$E$+10).
    1E41 CTT=RelativeDemo; RFT=09:30;             $D$=07:40; $E$= 11:40.
    1E42 CTT=RelativeDemo; RFT=10:30;             $D$=09:45; $E$=U09:40.
    1E43 CTT=RelativeDemo; RFT=10:40; ENT= 10:24; $D$=09:50; $E$=U09:45.
    1E44 CTT=RelativeDemo; RFT=10:50; ENT=U08:20; $D$=09:58; $E$=U10:00.

will produce the timetables:

1E41
  DES='Metropolis to Zedville service';
  ENP=ANYTOWN; ENT=06:23;
  TYP=DMU; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=07:02; DEP=07:04)
  (SEASIDE ARR=07:10; DEP=07:15)
  (DEEPORT ARR=07:40; DEP=07:50).
1E42
  DES='Metropolis to Zedville service';
  ENP=ANYTOWN; ENT=07:23;
  TYP=DMU; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=08:02; DEP=08:04)
  (SEASIDE ARR=08:10; DEP=08:15)
  (DEEPORT ARR=09:45; DEP=09:50).
1E43
  DES='Metropolis to Zedville service';
  ENP=ANYTOWN; ENT=07:34;
  TYP=DMU; MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=08:12; DEP=08:14)
  (SEASIDE ARR=08:20; DEP=08:25)
  (DEEPORT ARR=09:50; DEP=09:55).
1E44
  DES='Metropolis to Zedville service';
  ENP=ANYTOWN; ENT=08:20;
  TYP=DMU;
  MXS=90; LEN=80; BRK=Med; PWR=Diesel;
  (BEECITY ARR=08:22; DEP=08:24)
  (SEASIDE ARR=08:30; DEP=08:35)
  (DEEPORT ARR=09:58; DEP=10:10).

Back to the SimSig index. Back to the Rail index. Back to Clive's home page.