PsiTrain File Formats

If you are interested in building your own
timetable databases this information in this
document will be useful to you.  If you think
that the database will be useful to others,
please email the files to myself at
mike@boink.demon.co.uk and I'll put it on the
Web server at http://www.boink.demon.co.uk/

A support application, PsiTrnEd, is provided to
assist in the creation, maintenance and validation
of databases. To keep PsiTrain memory usge down,
and speed up, little validation is done - errors
in the data do indeed produce unpredicable results.

(Note that PsiTrain can't load a database if
you're curently editing a database file using the
text editor though PsiTrnEd itself can be loaded.)


Filenames

If there are to be many contributions the naming
convention of files will be important.

I propose the following (plus the appropriate
extension for each file in the database :

  Xccayyr or Xaaayyr

where :
 X is the transport type
  (t-train, b-bus, a-air, f-ferry ...)
 cc is a company code, for that providing the service
  (eg br-british rail (or see TOCs below), ep-Eurostar,
   gc-Great Central Railway, and with a different
   transport type, bm-British Midland, ba-British
   Airways, va-Virgin Atlantic etc)
 a or aaa is an area code, if necessary (eg country+county/state)
   or a timetable number.
 yyr release year and sequence number for this
   timetable.

Valid X,cc and aaa types will be found on the
website and new ones can be registered by sending
an email to me.

In the UK, railway train operating companies have
two chatacter codes as documented below :

AR - Anglias Railways
CA - Cardiff Railway Co
CH - Chiltern Railway Co
CT - Central Trains
EP - Eurostar (UK)
GE - Great Eastern
GR - Great North Eastern
GW - Great Western
GX - Gatwick Express
IL - Island Line
LS - LTS Rail
ME - Merseyrail Electrics
ML - Midland Main Line
NL - North London Railways
NW - North Western Trains
RE - Regional Railways North East
SC - Connex South Central
SE - Connex South East
SR - ScotRail
SW - South West Trains
TL - Thameslink
TT - Thames Trains
WC - Virgin West Coast
WN - West Anglia Great Northern Railway
WR - West Coast Railway Co
WW - South Wales & West Railway
XC - Virgin Cross Country

(The example databases just have descriptive
filenames and do not follow this convention.)


Overview

Each database has three text files :
  .ptt - top level information
  .stn - stations
  .trn - trains

All are simple textfiles to enable and encourage
anyone to create a database.  I may enhance
PsiTrnEd to compile the data at a later date to
improve performance.

In general, records are colon delimited fields.
As PsiTrain is a type 3 application it will
display all .ppt files found in the \ptt
directories on any disk.  This allows static
databases to be put on flash, for instance, whilst
those databases you are working on are located on
RAM.

In general, lines can be up to 128 chars in length.

In each of the files, comments may be added by
commencing the line with 'REM' or '#'.


ptt

The ptt file can contain the following records.
(All records are optional, but if none present
the file must still exist.)

  desc:<description>
  ttfrom:<ddmmyyyy>
  ttto:<ddmmyyyy>
  stn:<stn file location and filename>
  trn:<trn file location and filename>
  uset:<useful information title>
  used:<useful information detail lines>
  by:<Transportation type>
  deffrom:<default from station>
  defto:<default to station>

The desc record defines the title of the database,
which is displayed when the database is loaded.

ttfrom and ttto define the range of days for which
this timetable is valid.  PsiTrain will not permit
queries to be made outside this range, though, of
course the ptt file can be edited to ignore
dates altogether.

The stn and trn records permit the database files
to be located on another disk or directory. If not
specified it is assumed that they are in the same
location with the same filename as the ptt file
(with the appropriate extension).

Useful information screens (as many as you like)
are defined by specifying title and detail lines.
Up to 8 lines are displayed per page.  Specifying
a title starts a new page.

The default transportation type is "Train" though
this can be overridden using a "by" definition.
This is only used when displaying the result. This
can be up to 16 chars.

deffrom and defto provide defaults for this
timetable.  These can be overridden by use defined
defaults from within PsiTrain. Each is the number
of the station required.  ie The line number of
the station in the station definition line.

stn


station[:services]

This is simply a list of stations, one station per
line, optionally followed by a list of services
at that station:

  u - Underground
  s - Shipping
  a - Airport Link
  h - Hovercraft and similar

The line number is used in the trn file,
and it should be noted new strations should always
be added at the end of the file (or be prepared to
make other changes too).  If a station is inserted
into the middle of the stn file, it will affect the
line number of all subsequent stations. (The line
number is used in the trn file).

Note that there is now a sort facility in the
editor.  The best approach to insert a station
is to add it at the end of the station definition
file, then use the editor sort options.  See the
help file for more info.

Station names may be up to 30 chars long, and the
number of stations is limited only by memory.


trn

The format of a train record is as follows :

<train id>:<running/service flags[,addition desc]:+
 <station>:<arr/dep time>:+
 <station>:<arr/dep time>:+
 [<station>:<arr/dep time>:...]

(The + character in a field indicates continuation
both in this document and in PsiTrain. Leading
spaces in any line are removed, which may aid
readability. The / character can be used for
continuation in the same manner.  Note, however,
that the use of continuation should only be used
to circumvent to line length limitations, as
continuation has a detrimental effect on
performance.)

The train id can be up to 8 chars long, and is
displayed in the result.

Running/service flags can be include any of the
following :
  1-7: runs on this day of the week, mon to sun
  w: runs mon-fri
  f: first class accomodation available
  r: first class restaurant service available
  b: buffet service available (hot + cold)
  t: trolley service available
  s: seat reservations possible
  c: seat reservations compuslory
  d: seat reservations recommedned
  v: silver standard service
  e: snacks and sandwiches available

If specified, the additional description (after a
comma in the service flags field) is displayed in
the result along side the depature station.

The stations are specified as the line number from
the station file. Either a single Departure or
Arrival time can be specified in the format hhmm
(or hhcmm).  PsiTrain decides which it is. Both
can be specified, separated separated by a comma.
The optional "c" can be any single character and
is not used in any processing, but is displayed in
the result.  For instance request stops are denoted
by the letter "x" on UK timetables.

A train can call at up to 50 stations, including
terminal ones.

Trains should be sorted in departure time order as
the search routines depend on it. The exception
to this is with mutualy exclusive days.
ie Mon-Fri, Sat, and Sun can be kept apart, and
may improve readability.  However do not
separate Friday-only services from the weekday
ones, for instance.

Note that if the arrival times are not sorted
(quite possible) the next/previous functions, when
acting on an arrival time search, may be
compromised. This risk is taken to optimise
search times, and may be removed in a future
release if it proves to be a problem.

