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 file ~~~~~~~~ The ptt file can contain the following records. (All records are optional, but if none present the file must still exist.) desc: ttfrom: ttto: stn: trn: uset: used: by: deffrom: defto: notrn: ruleset: 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. notrn is optional, but if specified declares the number of train definitions in the trn file, which speeds up the loading of the timetable. The use of the ruleset keyword is documented later in this document. stn file ~~~~~~~~ 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 x - dummy station 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. The x attribute suppresses the station from the list of those available for a journey. (ie it is used only for showing which station a train is headed under the 'towards' column. This is used extensively in the BR automatic extracts. trn file ~~~~~~~~ The format of a train record is as follows : :::+ ::+ [::...] (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 compulsory d: seat reservations recommended v: silver standard service e: snacks and sandwiches available =: Service runs on restricted dates. This must always be the last flag - details follow. If specified, the additional description (after a comma in the service flags field) is displayed in the result along side the depature station. In the case when '=' is specified as a flag, the following codes can used in the description : mmdd: Service runs after specified day (inclusive) =mmdd: Service runs on specified day Only one of each type may appear, but both of the first two may be present in the same train definiton line. When these flags are used, PsiTrain will process them and to determine if the service is valid for the current request ... and is the therefore preferable to a text only description. If the word "change" appears in the description field (ie as part of an instruction to change trains) this definition line is ignored when the user has elected to list direct services only. 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 special time of 9999 causes the station to be ignored when looking for a journey. (Used by the BR extracts, in conjunction with stations having the x attribute.) A train can call at up to 50 stations, including terminal ones. Constraints ~~~~~~~~~~~ Trains should be sorted in departure time order as the search routines depend on it. The exception to this is with mutually 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. (Indeed this is true for departure times too, with complex databases.) It may therefore be necessary to use rulesets, as documented below, or to split service definitions into multiple lines. (ie instead of : dep-time:stn1:time:stn2:arr-time:stn3 you may need to use : dep-time:stn1:time:stn2 time:stn2:arr-time:stn3 dep-time:stn1:arr-time:stn3 or a subset instead.) Rulesets ~~~~~~~~ In order to protect against some of the restrictions noted above, rulesets have been introduced. To activate a ruleset, use the ruleset keyword in the ptt file. Only one ruleset is included in the current release of PsiTrain. ruleset:1 When searching for earlier or later services, do not assume monotonically increasing departure or arrival times. This ruleset will cause PsiTrain to search through the whole trn definition file each time a use looks for an earlier or later service. Therefore only use when necessary.