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 and an optional icon file can also be included : .pic - icons All data files are simple text files to enable and encourage anyone to create a database. 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 255 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: show: 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. The show record permits a message to be displayed to the user when the timetable is loaded. (Can be used to display the name of the timetable author, for instance, if the timetable is being shared.) 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. Predefined attributes are as follows : u: Underground s: Shipping a: Airport Link i: tourist information h: Hovercraft and similar c: Rental cars available l: Hotel x: dummy station Additional icons can be added using any unused letters between "a" and "v" - see notes in the description of train service definitions below. 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. Predefined Running/service flags are as follows : 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 g: Tourist train i: Intercity service j: Interrail service e: snacks and sandwiches available l: Sleeper -: Dummy flag =: Service runs on restricted dates. This must always be the last flag - details follow. You may add your own icons if you wish, or replace existing unused ones. There are two ways (the second method is recommended over the first) : 1. The letters a-u correspond to positions in the icon file (icons.pic.) You will see the predefined entries above. The first row of icons are for train services, and the second for station attributes. Icons are 15x15 pixels. Guides to the corners of the icon are just above and below the drawable areas. This file may be amended to change or add icons. 2. You may distribute your own icons with timetables, by including an optional copy of icons.pic, amended appropriately, and renamed to have the same base name as the timetable files (still with the pic extension.) This file is held in the ptt directory along with the other timetable components. This file will then entirely replace the default icons for the selected timetable, and it is therefore important to start with a copy of the default file and retain all icons which are still required. The hyphen flag may be used as a filler character. For example, to highlight missing days in a schedule. (eg 12-4567 for journies every day except Wednesday.) 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 : yyyymmdd: Service runs after specified day (inclusive) =yyyymmdd: 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 definition line. 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 where possible. An exception is when using 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, as trains do overtake each other) 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 (sorted in departure time order, as this ensure all journies are covered.) 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. ruleset:1 When searching 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. Multiple rulesets may be specified (eg ruleset:12)