home *** CD-ROM | disk | FTP | other *** search
/ Game Killer / Game_Killer.bin / 709.FSDECODE.TXT < prev    next >
Text File  |  1993-02-04  |  44KB  |  827 lines

  1.  
  2.                                    FSDECODE
  3.                     DECODER FOR MICROSOFT FLIGHT SIMULATOR
  4.                                   DATA FILES
  5.  
  6.    Version Beta 2;  Release date: 4 February 1993
  7.  
  8.    Updates:
  9.    ∙ Link table increased to 240 entries
  10.    ∙ Added the scale factor in register 'S'
  11.    ∙ Added ASCII text to dump fields
  12.    ∙ Added quotes (") to dump and string fields
  13.    ∙ Added the undefined record procedure
  14.    ∙ Added the absolute and relative link directives (#@, #$)
  15.    ∙ Added the "mark routine" and the "call marked" directives (#M, #N)
  16.    ∙ Updated SD-DEF.DES
  17.    ∙ Added SCN.DES
  18.    ∙ Documented the #S directive and the ERRORLEVEL return codes.
  19.  
  20.    Version Beta 1;  Release date: 8 December 1992
  21.  
  22.                                   -----------
  23.                               FSDECODE REFERENCE
  24.                                   -----------
  25.  
  26.  
  27.    WHAT FSDECODE DOES
  28.  
  29.    FSDECODE reads a Flight Simulator data file (.SC1, .SCN, .DY1, .DYN, .DEM,
  30. .MOD...), chops it in fields each containing a single value and outputs a field
  31. contents description to an ASCII text file.  To do that, FSDECODE, which has
  32. almost no specific knowlegde about FS data file structures, uses a description
  33. file (thereafter called ".DES file") which tells the program how long each data
  34. field is, what it contains and how it has to be formatted in the output.  By
  35. default, FSDECODE selects a description file according to the input file exten-
  36. sion, but a specific description file can be indicated.
  37.  
  38.    HOW INSTALL FSDECODE
  39.  
  40.    Copy the program file (FSDECODE.EXE) and all the .DES files to the same
  41. directory. This directory can be the Flight Simulator directory or a different
  42. one.
  43.  
  44.    HOW TO RUN FSDECODE
  45.  
  46.    The syntax for FSDECODE command line is:
  47.  
  48. FSDECODE InputFileName OutpuFileName [/FfromOffset] [/TtoOffset]
  49.    [/DdescrFileName] [/WoutputWidth] [/U] [/X[o][x][t]]
  50.  
  51. where:
  52. <InputFileName> is the name of the data file to be read
  53. <OutputFIleName> is the name of the ASCII file to be created.
  54. These 2 arguments are required.
  55.  
  56. <fromOffset> is the input file offset from where to start (either a decimal or
  57.    an hex number; the latter in the format 0x.... es.: 1024 = 0x400)
  58. <toOffset> is the input file offset at where to stop (either a decimal or an
  59.    hex number)
  60. <descrFileName> is the name of the description file to use
  61. <outputWidth> is the maximum line width for the output file
  62. /U forces the program to unconditionally scan the input file from <fromOffset>
  63.    and not from the beginning
  64. /Xo or /Xx or /Xt exclude one of the three output columns (offset, hex and
  65.    text, see below); they can be combined up to /Xoxt
  66. These 6 arguments are optional, and can appear in any order but AFTER the two
  67.    file names.
  68.  
  69. Defaults:
  70. <fromOffset> defaults to 0
  71. <toOffset> defaults to the file end
  72. <descrFileName> defaults to a file name equal to the input file extension, and
  73.    a .DES extension
  74. <outputWidth> defaults to 132, legal values are in the range 80-197; values
  75.    lower than 80 are converted to 80 and values greater than 197 are converted
  76.    to 197.
  77.  
  78.   If a fromOffset parameter greater than 0 is given, the input file is scanned
  79. from the beginning to set possible link points and to follow the record struc-
  80. ture (see below), however no output is generated until the <fromOffset> point
  81. is reached; when the <toOffset> point is reached, the program ends.
  82.   If, however, the /U option is used, scanning begins directly from
  83. <fromOffset>; this can exclude some of the cross-check possibilities and has to
  84. be used only when the user is sure that <fromOffset> is exactly the initial
  85. point of a record.
  86.   If <toOffset> is equal to or lower than <fromOffset>, the program ends with
  87. an error message.
  88.  
  89.   All file names can include a full drive:\path\ indication.
  90.  
  91.   The description file (both default or given by the user) is looked for in the
  92. current directory; if it is not found, it is looked for in the directory where
  93. FSDECODE itself resides.  This permits to automatically use, for each input
  94. file kind, specialized .DES files for data files in different directories,
  95. resorting to a generic .DES file for that type if none is found.
  96.   If no suitable .DES file is found, the program aborts with an error message.
  97.  
  98.   During the run, FSDECODE displays the current input file offset and, at the
  99. end, the offset of the last accessed field and record; these are not neces-
  100. sarily the last DECODED field or record, if they fall beyond the <toOfset>
  101. limit.
  102.  
  103.   By pressing the ESC key while the program is running, the user can interrupt
  104. the program at any moment.
  105.  
  106.   ERRORLEVEL RETURN CODE
  107.  
  108.   If run in a batch file, FSDECODE returns the following ERRORLEVEL codes:
  109.  
  110.   0       success
  111.   1       invalid or missing parameter(s)
  112.   2       I/O error
  113.   3       other errors (out of memory, description file syntax...)
  114.  
  115.   MEMORY CONSIDERATION
  116.  
  117.   The input file is read a field at a time, and then input file size is not an
  118. issue. The description file, however, is kept in memory in its entirety and
  119. cannot be longer than ca. 53 kB. If there is not enough memory to hold the des-
  120. cription file, the program aborts with an error message.
  121.   Given that FSDECODE uses the small memory model, the program can run in about
  122. 100 kB of memory, but there is nothing you can do if you hit the small memory
  123. limit other than trying to simplify the description file, no matter how many MB
  124. of extended/expanded memory you have.
  125.   Each description file line takes 7+strlen(caption) bytes of memory.
  126.  
  127.   OUTPUT FILE LAYOUT
  128.  
  129.   Output files are organized in three columns:
  130.   1) at the left margin, the current file offset as a 6-digit hex number
  131.   2) at position 8, hex dump of the field values (hex column)
  132.   3) at position 62, field descriptions and values (text column)
  133.  
  134.   If any column is excluded with /X option, the column at its right takes over
  135. its width.
  136.  
  137.   Many fields can fit in a line and is the description file which tells
  138. FSDECODE when to start a new output line.  One blank space is automatically
  139. inserted before any hex dump and field description.
  140.   If the hex dump or the field description do not fit in the remaining portion
  141. of their columns, a new output line is generated; if they are longer than the
  142. corresponding column width, they are truncated.
  143.  
  144.   Hex dumps are always in hex, but all the digits of a field are given in the
  145. 'right' order (MSB first) and not in the Intel format (LSB first) actually used
  146. in the files. Some kinds of field (primarily geographic coordinates) generate a
  147. formatted hex dump (see below for details).  Field description format is almost
  148. entirely dictated by the description file.
  149.  
  150.   When the decoding is over, a record count list is appended, detailing the
  151. occurrences of each record found at least once in the input file and the total
  152. occurrences of undefined records.
  153.  
  154.   NOTE:  please be aware that output files generated by FSDECODE can be HUGE, a
  155. reasonable guess being about 20 times the length of the input file.
  156.  
  157.  
  158.                                  ------------
  159.                            LINK POINTS AND REGISTERS
  160.                                  ------------
  161.  
  162.   LINK POINTS
  163.  
  164.   The program maintains a table of up to 64 link points.  Link points are set
  165. by specific instructions in .DES files.  If the program is unable to correctly
  166. parse a point of the input file, it dumps an unformatted hex listing up to next
  167. link point.  If the next link point is more than 2 kB after the current point,
  168. FSDECODE assumes to have lost syncronism with the input file, dumps 1024 bytes
  169. in hex and aborts.
  170.  
  171.   The link table is updated (and elapsed link points are removed) every time a
  172. link is inserted and at each new record.
  173.  
  174.   REGISTERS
  175.  
  176.   The program maintains a set of 27 registers.  Registers can be set and
  177. checked with appropriate directives; checks can trigger jump to other descrip-
  178. tion lines.  All registers are signed long values (32 bits) and all register
  179. assignments are casted to (signed long).
  180.   Registers are addressed with a single character name from '@' to 'Z'.
  181.  
  182.   The following registers are somewhat special:
  183.  
  184. '@': this is actually a sort of pseudo-register; when read, it yields the next
  185.    link value, when set it inserts the given value into the link table; as the
  186.    link table is kept in ascending order, a new value can occupy any position
  187.    and is not necessarily the value returned when the register is read back.
  188.  
  189. 'Q': holds the file offset of the record being decoded and is internally used
  190.    to compute relative offset addresses (see below); it can be read and writ-
  191.    ten, but it is overwritten every time the program enters a new record.
  192.  
  193. 'R': holds the code of the current record; it can be read and written, but it
  194.    is overwritten every time the program enters a new record.
  195.  
  196. 'S': holds the current scale factor for FS delta coordinates and is internally
  197.    used to convert delta coordinates to actual FS coordinates.  It is not set
  198.    by the program, but it is left to the user to be sure that the .DES file
  199.    sets it when required.
  200.  
  201. 'V': holds the current field value; it can be read and written, but it is over-
  202.    written every time a new field is read.  If the current field is shorter
  203.    than 32 bits, the value is 0-extended for unsigned fields and sign-extended
  204.    for signed fields.  Strings and hex dump fields do not affect this register.
  205.  
  206. 'W': holds the file offset of the current field; it can be read and written,
  207.    but it is overwritten at each .DES line execution.
  208.  
  209.    Registers X, Y, Z are not reserved by the program, but are consistently used
  210. in the supplied .DES files to store the current East, North, Alt. coordinates
  211. of the current object or plane position. It is recommended that this practice
  212. will be observed.
  213.  
  214.    Other registers can be freely read and set with .DES instructions.
  215.  
  216.  
  217.                                  ------------
  218.                           DESCRIPTION FILE REFERENCE
  219.                                  ------------
  220.  
  221.    GENERAL STRUCTURE
  222.  
  223.    Description files are ASCII text files which tell FSDECODE how to interpret
  224. the input file and how to format the output.  .DES files are made of lines,
  225. each describing a field (i.e. a single value).
  226.    .DES lines are made of three columns:
  227.    1) a number: the length in bytes of the field
  228.    2) one or two characters: field value type and optional command
  229.    3) caption (a text string, optional): what to print before and/or after the
  230. field value output.
  231.    Columns can be separed by any combination of blanks (spaces and/or tabs) and
  232. do not need to be actually drawn up in column. However, the first column MUST
  233. begin at the first line character and the caption column CANNOT contain blanks
  234. (but see below).
  235.    Line length is limited to a maximum of 197 characters.
  236.    For example, the follwing .DES line:
  237.  
  238.    2        I    file_length:_
  239.  
  240.    tells FSDECODE that the next field is 2 bytes long, its value has to be
  241. printed as an I(nteger) number and the string "file length: " has to be
  242. prepended at the field value (underscore characters will be replaced by
  243. spaces).
  244.  
  245.    Given that many FS data files (as, for instance, .SC1, .DY1, .DEM) are made
  246. of records, each characterized by an initial byte code and each with its own
  247. structure and meaning, FSDECODE description files are also built around the
  248. record concept:
  249.    a record line states for which record code the following description is
  250. intended, and subsequent lines describes the various record fields.
  251.    Lines pertaining to the many fields of a record have to appear in the same
  252. order in which the fields appear in the record, one for each field, but des-
  253. criptions for the different record codes can appear in any order within the
  254. description file; however it is recommended to keep them sorted by record code.
  255.    If some lines appear in the description file before the first record line,
  256. they are intended to describe a file header and are executed to decode the
  257. input file initial portion, until the first record line is met.
  258.    See also section "NOTES" for details on record selection.
  259.  
  260.    COMMENTS
  261.  
  262.    Lines starting with a semicolon (;) are considered comment lines and are
  263. entirely disregarded.
  264.    Any text after the caption, separated by at least one blank, is considered a
  265. comment and is entirely disregarded.
  266.    Comments do not occupy memory.
  267.  
  268.    FIELD CAPTIONS
  269.  
  270.    The caption contains a descriptive text which is output with the field
  271. value.  Within captions, 3 characters have a special meaning:
  272.  
  273. '#': if a caption starts with a pound sign, a new output line is generated;
  274.    otherwise output for the current field will follow output for the previous
  275.    field in the same line, if it fits. If the symbol occurs in other positions
  276.    it is printed normally (but see below the note about the 'E' field type).
  277.  
  278. '|': if a pipe symbol appears anywhere in the caption, the field value is
  279.    inserted at this point of the caption; if no pipe symbol occur, the caption
  280.    is output entirely before the field value.
  281.  
  282. '_': all undescore symbols are replaced by space characters.  Always remember
  283.    to add to captions the required leading or trailing underscores to separate
  284.    caption text from field value.  Captions stop at the first space or tab
  285.    character they contain.
  286.  
  287.    FIELD VALUE TYPES
  288.  
  289.    Field value type tells FSDECODE how to interpret the field and how to print
  290. its value in the text column.
  291.    As a general rule, upper case types are unsigned, lower case types are
  292. signed; if this distinction does not apply (as for non-numeric fields, like
  293. strings), case makes no difference.
  294.    The following table lists the field types supported by FSDECODE Beta 2. For
  295. each type, the supported field lengths, a pattern of hex output and of text
  296. output as well as a description are given.
  297.  
  298. ┌──────┬───┬───────────┬──────────────┬──────────────────────────────┐
  299. │ type │len│ hex dump  │ value output │         description          │
  300. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  301. │ B/b  │ 1 │ hh        │ bbbbbbbb     │ binary number                │
  302. │      │ 2 │ hhhh      │ 2x bbbbbbbb  │                              │
  303. │      │ 3 │ hhhhhh    │ 3x bbbbbbbb  │                              │
  304. │      │ 4 │ hhhhhhhh  │ 4x bbbbbbbb  │                              │
  305. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  306. │  C   │ 2 │ hhhh      │ ddddd        │ int. FS coord   (-0xC000)    │
  307. │      │ 4 │ hhhh.hhhh │ ddddd.dddd   │ fract. FS coord (-0xC000)    │
  308. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  309. │  c   │ 2 │ hhhh      │ +dddddd      │ delta FS co., scale factor 8 │
  310. │      │   │           │ +dddd.d      │     "    , scale factor 6-7  │
  311. │      │   │           │ +ddd.dd      │     "    , scale factor 2-5  │
  312. │      │   │           │ +d.dddd      │     "    , scale factor 0-1  │
  313. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  314. │ D/d  │any│ hh hh hh..│ "ASCII text" │ hex dump                     │
  315. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  316. │ E/e  │1-4│as for b/B │ see below    │ enumeration (see below)      │
  317. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  318. │  G   │ 1 │ hh        │ ddd.dd°      │ degrees (0 - 360)            │
  319. │      │ 2 │ hhhh      │ ddd.dd°      │    "                         │
  320. │  g   │ 1 │ hh        │ +ddd.dd°     │ signed degrees (-180 - +180) │
  321. │      │ 2 │ hhhh      │ +ddd.dd°     │    "                         │
  322. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  323. │  I   │ 1 │ hh        │ ***          │ decimal integer              │
  324. │      │ 2 │ hhhh      │ ***          │    "                         │
  325. │      │ 4 │ hhhhhhhh  │ ***          │    "                         │
  326. │  i   │ 1 │ hh        │ +***         │ signed decimal integer       │
  327. │      │ 2 │ hhhh      │ +***         │    "                         │
  328. │      │ 4 │ hhhhhhhh  │ +***         │    "                         │
  329. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  330. │  J   │ 2 │ hh.hh     │ ddd.dd       │ decimal with 1 fract. byte   │
  331. │      │ 4 │ hhhhhh.hh │ ddddd.dd     │                              │
  332. │  j   │ 2 │ hh.hh     │ +ddd.dd      │sign. dec. with 1 fract. byte │
  333. │      │ 4 │ hhhhhh.hh │ +ddddd.dd    │                              │
  334. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  335. │  K   │ 4 │ hhhh.hhhh │ ddddd.dddd   │ decimal with 2 fract. bytes  │
  336. │  k   │ 4 │ hhhh.hhhh │ +ddddd.dddd  │sign. dec. with 2 fract. bytes│
  337. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  338. │ O/o  │1-4│as for b/B │ "off"/"on"   │ on / off switch:             │
  339. │      │   │           │              │ "off" printed if LSB == 0    │
  340. │      │   │           │              │ "on"  otherwise              │
  341. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  342. │ S/s  │any│hh hh hh.. │ "ASCII text" │ textual string               │
  343. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  344. │ X/x  │ 1 │ hh        │ hh           │ hex number                   │
  345. │      │ 2 │ hhhh      │ hhhh         │                              │
  346. │      │ 3 │ hhhhhh    │ hhhhhh       │                              │
  347. │      │ 4 │ hhhhhhhh  │ hhhhhhhh     │                              │
  348. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  349. │ Y/y  │ 2 │ hh.hh     │ hh.hh        │ hex number with 1 fract. byte│
  350. │      │ 4 │ hhhhhh.hh │ hhhhhh.hh    │                              │
  351. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  352. │ X/x  │ 4 │ hhhh.hhhh │ hhhh.hhhh    │hex number with 2 fract. bytes│
  353. ├──────┼───┼───────────┼──────────────┼──────────────────────────────┤
  354. │ '-'  │1-4│as for b/B │ none         │ empty value                  │
  355. ├──────┼───┴───────────┴──────────────┴──────────────────────────────┤
  356. │  #   │   Command directive; see next section                       │
  357. └──────┴─────────────────────────────────────────────────────────────┘
  358.  
  359.   Symbols:
  360.  
  361.   'b', 'd', 'h' stand for one binary, decimal or hex digit resp.
  362.   '+' stands for a sign character (either '+' or '-')
  363.   '***' stands for the amount of decimal digits necessary for expressing the
  364. number (output is left justified; other field outputs are right justified).
  365.  
  366.   Notes:
  367.  
  368. 'C': the field value is corrected by the -0xC000 base shift after hex output.
  369.    2-byte 'C' fields are aligned with int FSu decimal point (<< 16) after value
  370.    output.  These modifications show up in the 'V' register also.
  371.  
  372. 'c': the field value is corrected by the current value of register 'S' (scale
  373.    factor) after hex output, so that the field is aligned with int FSu decimal
  374.    point and is ready to be added to current reference coordinate to calculate
  375.    resulting point.  These modifications show up in the 'V' register also.
  376.    Text output has a variable number of decimal digits to make it to fit in 7
  377.    characters.
  378.  
  379. 'E': enumerations provide a way to convert coded values to text labels.  They
  380.    are intended for fields that can assume a small number of consecutive
  381.    values.  For enumerations, the caption column must have a precise structure:
  382.  
  383.    "[pre_label]|text_for_value_0#text_for_value_1#....[|post_label]"
  384.  
  385.    the program prints in the text column the text corresponding to the field
  386.    value, with the optional pre_ and post_labels before and after.  Note that
  387.    the final '|' is required only if the post_label is present, but the first
  388.    '|' is ALWAYS required.  If the field value is greater than the number of
  389.    supplied texts, a 2-digit hex number is printed.  Only the LSB of the field
  390.    is tested and printed, whatever the declared length of the field.
  391.  
  392. 'G': for degree fields, value output is converted in degrees, calculating
  393.    10000h (for 2-byte fields) or 100h (for 1-byte fields) = 360°. This calcula-
  394.    tion does not affect the V register which keeps its value. For 1-byte
  395.    fields, however, after value output, V is shifted 1 byte to the left to keep
  396.    the value aligned with 2-byte fields.  Value outputs have a final '°'.
  397.  
  398. 'D': strings are output in text chunks up to 16 bytes long, each surrounded by
  399.    a pair of quotes ("); control characters are replaced by the '^' symbol; new
  400.    output lines are generated until the field length is exhausted.  If the
  401.    field length is not known in advance, a length of -1 can be declared and the
  402.    file will be hex-dumped up to next link point.
  403.  
  404. 'S': strings are output in text chunks up to 16 bytes long, each surrounded by
  405.    a pair of quotes ("); control characters are replaced by the '^' symbol; new
  406.    output lines are generated until the field length is exhausted.  If the
  407.    field length is not known in advance, a length of -1 can be declared and
  408.    text will be output up to the next NULL character included.
  409.  
  410. '-': no value output. Hex dump is generated, but value output is not. Used to
  411.    read a field while deferring value output if it requires special manipula-
  412.    tions or avoiding it when caption text is enough.
  413.  
  414.    String and hex dump fields can have any length between 1 and 32677.  Other
  415. fields can be only 1 to 4 bytes long; if the declared field length is greater,
  416. the program stops with an error during description file check.
  417.    If a field length unsupported for that field type is declared, hex output
  418. will be usually correct, but no text output will be generated.  No messages are
  419. issued by the program.
  420.  
  421.    FIELD COMMANDS
  422.  
  423.    To the field type character, another character can be added addressing one
  424. of the internal registers.  If the character is upper case ('@' or 'A'-'Z') the
  425. corresponding register is set to the current field value; if it is lower case
  426. ('$' or 'a'-'z') the current value is added to the register (algebraically
  427. added, if the field was declared as signed).  Any other command will be simply
  428. ignored.  Commands do not affect hex or text output in any way.
  429.  
  430.    The following commands require some comments:
  431.  
  432.    Link points:
  433.  
  434.    '@': the field value is declared as an absolute link point; the field value
  435. is considered an absolute file offset and inserted into the link point table as
  436. it is.
  437.  
  438.    '$': the field value is declared as a relative link point; the field value
  439. is added to the current record offset and inserted into the link point table.
  440.  
  441.    Record line
  442.  
  443.    'R': declares the line as a record line; for record lines, field length
  444. column does not indicate the length of the field, but the code of the record; a
  445. record code field is always considered 1 byte long.  The R register is set to
  446. the field value and the value is output according to the field type.  NOTE:
  447. Record codes lesser than -1 or greater than 255 are ignored.  See also ".DES
  448. execution flow" in section "NOTES" below.
  449.  
  450.    Undefined record procedure
  451.  
  452.    A record line with a code of -1 marks a special record procedure wich will
  453. be invoked to process undefined records, overriding the default procedure (dump
  454. to next link point) built in the program.
  455.  
  456.    No field loading
  457.  
  458.    '-': outputs the current field value (V register) without loading it from
  459. the file; it is used to output a field value (usually previously read with a '-
  460. ' field type) that has been manipulated through directives (see below).  Value
  461. is formatted according to field type.  No hex output is generated.
  462.  
  463.  
  464.    COMMAND DIRECTIVES
  465.  
  466.    A line with a '#' field type is not considered a field description but a
  467. directive for the program.  Directives tell FSDECODE to perform certain
  468. actions.  They permit a rudimentary form of programmed file parsing.
  469.    Directives are recognized by the command character.  As a general rule,
  470. directive case is irrelevant.
  471.    Within directives, field length column and caption column have special mean-
  472. ing.
  473.  
  474.    The following table lists directive supported by FSDECODE Beta 2.  For each,
  475. the meanings of various columns and a description are given.
  476.  
  477. ┌─────┬───────────────┬─────────────┬─────────────────────────────────┐
  478. │ dir │ field length  │  caption    │         description             │
  479. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  480. │ #D  │ line offset   │ arithmetic  │ count Down on reg:              │
  481. │     │               │ expression  │ decrement reg and jump to       │
  482. │     │               │             │ [line offset] if reg > value    │
  483. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  484. │ #U  │ line offset   │ arithmetic  │ count Up on reg:                │
  485. │     │               │ expression  │ increment reg and jump to       │
  486. │     │               │             │ [line offset] if reg < value    │
  487. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  488. │ #I  │ line offset   │ boolean     │ jump If:                        │
  489. │     │               │ expression  │ jump to [line offset] if        │
  490. │     │               │             │ [expression] is true            │
  491. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  492. │ #J  │ line offset   │ (standard)  │ Jump:                           │
  493. │     │               │             │ jump to [line offset]           │
  494. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  495. │ #C  │ line offset   │ (standard)  │ Call subroutine:                │
  496. │     │               │             │ store current description line  │
  497. │     │               │             │ and jump to [line offset]       │
  498. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  499. │ #E  │ (ignored)     │ (standard)  │ End subroutine:                 │
  500. │     │               │             │ go back to the calling point    │
  501. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  502. │ #M  │ line offset   │ (standard)  │ mark a subroutine for later     │
  503. │     │               │             │ execution                       │
  504. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  505. │ #N  │ (ignored)     │ (standard)  │ call marked subroutine          │
  506. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  507. │ #S  │ bytes         │ (standard)  │ skip the given amount of bytes  │
  508. │     │               │             │ in the input file               │
  509. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  510. │ #R  │ (ignored)     │ arithmetic  │ Register operation              │
  511. │     │               │ expression  │                                 │
  512. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  513. │ #F  │ (ignored)     │ description │ execute description File:       │
  514. │     │               │ file name   │ load and execute [filename]     │
  515. │     │               │             │ (must include path and .ext)    │
  516. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  517. │ #H  │ (ignored)     │ heading     │ Heading:                        │
  518. │     │               │             │ output [heading] at hex column  │
  519. │     │               │             │ in a line of its own            │
  520. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  521. │ #T  │ (ignored)     │ text        │ Text:                           │
  522. │     │               │             │ output [text] at value column   │
  523. │     │               │             │ (same spec. char. as captions)  │
  524. ╞═════╪═══════════════╪═════════════╪═════════════════════════════════╡
  525. │ #@  │ line offset   │ (ignored)   │ link procedure to current value │
  526. │     │               │             │ intended a file offset          │
  527. ├─────┼───────────────┼─────────────┼─────────────────────────────────┤
  528. │ #$  │ line offset   │ (ignored)   │ link procedure to current value │
  529. │     │               │             │ intended as an offset from the  │
  530. │     │               │             │ current file offset             │
  531. └─────┴───────────────┴─────────────┴─────────────────────────────────┘
  532.  
  533.   Notes:
  534.  
  535.   [line offset] is a signed short integer which gives the target line offset
  536. relatively to the current line; comment lines are not counted.  Even when the
  537. field is ignored, it MUST contain a number.
  538.   Line offsets can be substituted with label references (see below).
  539.  
  540.   [arithmetic expression] is in the form "R?VALUE", where:
  541.   ∙ 'R' can be any register name ('@'-'Z')
  542.   ∙ '?' can be any of the following operators: + - * / % & | = which are equi-
  543. valent to the following C operators:
  544.           +              +=
  545.           -              -=
  546.           *              *=
  547.           /              /=   (integral division)
  548.           %              %=   (modulus)
  549.           &              &=   (bitwise AND)
  550.           |              |=   (bitwise OR)
  551.           =              =
  552.   The operator is not checked for #D and #U directives, but it MUST be there.
  553.   ∙ 'VALUE' can be a signed long integer (decimal or "0x...." hex) or a
  554. register name ('@'-'Z').
  555.  
  556.   [boolean expression] is in the form "R?VALUE", where:
  557.   ∙ 'R' can be any register name ('@'-'Z')
  558.   ∙ '?' can be any of the following operators: > < = ! (greater than, lesser
  559. than, equal, not equal).  Other operators are considered as '!'.
  560.   ∙ 'VALUE' can be a signed long integer (decimal or "0x...." hex) or a
  561. register name ('@'-'Z').
  562.  
  563.   '#D', '#U': implement a sort of "do...while" counted loop.  They are intended
  564. to be used at the end ("while") of repeating part to conditionally branch to
  565. the initial point ("do").  The lines between "do" and "while" are always
  566. executed at least 1 time.
  567.  
  568.   '#C': execution continues with the called subroutine; FSDECODE returns to the
  569. calling point only when an '#E' directive is executed.  There is no limit,
  570. memory availability excepted, to multiple subroutine nesting.
  571.  
  572.   '#E': returns execution to the calling point, either from a subroutine or
  573. from a nested .DES file.  Upon returning from a nested .DES, memory occupied by
  574. the called .DES is freed and its record definitions are lost.  If executed when
  575. no subroutine and no nested .DES is being called, it stops the program.
  576.  
  577.   'M': marks the routine targeted by the line offset (or label reference) for
  578. later execution through the 'N' directive.
  579.  
  580.   'N': calls a routine previously marked by the last 'M' directive.  It is a
  581. normal subroutine call, with returns only when an 'E' directive is found.  If
  582. no routine has been 'M'arked, the directive is ignored.
  583.   The directive pair 'M' - 'N' is used to select among several specific
  584. routines according to contingent conditions and to call the selected routine at
  585. a later point without the need to repeat the tests or keep memory of the
  586. previous conditions.
  587.  
  588.   '#F': execution continues with the given .DES file.  The file is looked for
  589. in the current directory and then in the FSDECODE directory, as for any .DES
  590. file; if it is not found, the program aborts with an error.  File name cannot
  591. include an underscore character ('_') because it would be replaced by a space.
  592.   FSDECODE returns to the calling point and frees the memory occupied by the
  593. called file only when an '#E' directive is executed.
  594.   Record definitions and labels are local to the called file and do not inter-
  595. fere with the records and labels defined in the caller.
  596.   Registers, undefined record procedure, marked procedure and link point proce-
  597. dures, however, are global and the called file shares the register with the
  598. caller or inherits the procedures if they have been set by the caller.
  599.   There is no limit, memory availability excepted, to multiple file nesting.
  600.  
  601.   '#H': generates an output line containing only the given text aligned with
  602. output hex column.  Text cannot contain spaces, which can be indicated by the
  603. '_' special character.  New line text prefix ('#') and field value place holder
  604. ('|') are printed as regular characters.  This directive is ignored if text
  605. output has been suppressed with the /Xt option.
  606.   This directive is used to insert titles or separators in the output.
  607.  
  608.   '#T': outputs the given text at the current output value position.  Text can-
  609. not contain spaces, which can be indicated by the '_' special character. New
  610. line text prefix ('#') is observed and field value place holder ('|') is
  611. printed as a regular characters.  This directive is ignored if text output has
  612. been suppressed with the /Xt option.
  613.   This directive is used to insert a caption that cannot be easily inserted in
  614. the caption column.
  615.  
  616.   '#@': links the procedure targeted by the line offset (or the label
  617. reference) to the current field value, intended as a file offset; when decoding
  618. arrives at this file offset the procedure is executed.  The procedure has to be
  619. closed by an #E directive, as for any subroutine call.
  620.   This directive is useful for inserting headings at given file offsets or for
  621. derouting execution during file sections with a particular structure.
  622.  
  623.   '#$': it similar to the previous directive, but the current field value is
  624. considered a delta from the current record offset, i.e.: the current field
  625. value is added to the current record offset, the result is considered a file
  626. offset and is linked to the targeted procedure.
  627.  
  628.   Any other directive will be simply ignored.
  629.  
  630.   Note that directives #C, #E, #J, #M, #N, #S can have a standard caption which
  631. will be output into the text column in the usual way.
  632.  
  633.   Refer to the supplied .DES files and to the "NOTES" section below for exam-
  634. ples and tips of using directives.
  635.  
  636.   LABELS
  637.  
  638.   Lines starting with a colon (':') are considered labels definitions and mark
  639. the following line.  Only the first 8 characters (':' excluded) are sig-
  640. nificant; labels are case-sensitive and may contain any caracter from '!'
  641. (ASCII 33) to '■' ('ASCII' 254).  Each .DES file can contain up to ca 3,000
  642. different labels.
  643.   A label can be referenced in directives, substituting the line offset with
  644. the label preceded by a '>'.  Again, see the supplied .DES for examples.
  645.   Labels do not count as lines and do not occupy .DES memory.
  646.  
  647.  
  648.                                  ------------
  649.                                      NOTES
  650.                                  ------------
  651.  
  652.   .DES EXECUTION FLOW and RECORD SELECTON MECHANISM
  653.  
  654.   If a .DES file does not contain record lines (like, for instance, MOD.DES),
  655. it is executed linearly from the first line onward, of course taking into
  656. account possible flow control directives like #J, #C, etc, until:
  657.   a) the input file is finished OR
  658.   b) the .DES file is finished OR
  659.   c) a #E directive is met which is not within a subroutine or #F call.
  660.  
  661.   If however it does contain record definitions, its execution is linear until
  662. the first record line is met.  At this point, FSDECODE assumes to have entered
  663. an input file section made of records, and the .DES file is no more executed
  664. sequentially but somewhat asynchronously: a record code is read from the input
  665. file and the routine associated with this code is retrieved and executed.  If
  666. the code has no associated routine, the undefined record mechanism is trig-
  667. gered.
  668.   When the routine is finished (i.e. when FSDECODE arrives at another record
  669. line), another record code is read from the input file and the selection
  670. process is repeated.
  671.  
  672.   In 'C' terms, the record definition block of a .DES file can be described as
  673. a big "switch" within which each record line is a "case" (and at the same time
  674. it "break"s the previous "case") and the undefined record proc (either built-in
  675. or DES-defined) is the "default"; the entire "switch" is enclosed in a
  676. "while(TRUE)" block.
  677.  
  678.   Thee is no way to stop this process and revert to plain sequential execution;
  679. if an input file portion is known to have a non-record structure, its address
  680. (either hard-coded in the .DES or derived from the file contents) can be
  681. inserted in the link point table and associated with an appropriate decoding
  682. subroutine through the #@ or #$ directives: when the decoding arrives at that
  683. file address, the associated routine will be triggered and the special section
  684. properly decoded.  After that, upon returning from the subroutine, the asyn-
  685. chronous record selection process resumes.
  686.  
  687.   Note that a .DES containing record definitions will never stop or, if called
  688. from antother .DES, will never return to the caller, until one the following
  689. condition is satisfied:
  690.   a) the input file is finished
  691.   c) one of record definition, thought to mark the end of the file, purposely
  692. contains an '#E', in which case execution of the .DES will stop after the first
  693. occurrence of this record in the input file.
  694.   Condition b) (end of .DES) is no more possible, because record selection is
  695. repeated until there are records to decode.
  696.  
  697.   NOTE ON THE '#E' DIRECTIVE AND CALLS
  698.  
  699.   .DES files that do not contain record definitions can, or even should, safely
  700. end with an '#E' directive.  If the file is called from another .DES with the
  701. '#F' directive, execution will return to the caller when the '#E' directive is
  702. reached; if there is no '#E', FSDECODE cannot anymore tell how to parse the
  703. file and usually aborts with an error.
  704.   .DES files that contain record definitions, however, cannot simply end with
  705. an '#E', because it will necessarily appear at the end of record definition and
  706. will cause FSDECODE to stop whenever a record of that kind is parsed.  The same
  707. apply to the code of a subroutine: if it follows a record definition, it will
  708. be executed whenever a record of that kind is parsed.  The solution is to group
  709. all subroutines, each terminated by its own '#E', at the beginning of the file
  710. and to add before them a #J directive jumping over all of them.
  711.  
  712.   '-' NULL FIELD TYPE AND '-' NULL FIELD COMMAND
  713.  
  714.   It is important to distinguish between these two instructions:
  715.   '-c' (where 'c' can be any field command, even empty) reads a field (of given
  716. length) and outputs its hex value but does not perform any text output.  The
  717. field value is stored in the 'V' register, as with any field read-in.  It prac-
  718. tically tells FSDECODE that there is no need for a value output because the
  719. caption is enough or that there is no simple way to output the field value and
  720. that the next .DES instructions will take care of it.  It can be associated
  721. with any field command.
  722.   't-' (where 't' can be any field type) does not read anything from the input
  723. file nor output any hex value, but outputs in the text column whatever value
  724. happens to be in the 'V' register, formatted according to the accompanying
  725. field length and type.  Practically, it tells FSDECODE that a suitable field
  726. value has been built in the 'V' register and that it can output this value in a
  727. standard format.  It can be associated with any field type but there has to be
  728. one, because the field command is always the second character.
  729.   It is also important to properly pair, when required, the null field type and
  730. the null field command, each in its .DES line, avoiding having two read-in for
  731. a single field (which would put the .DES out of synchronism with the input
  732. file) or no read-in at all.  Even more care has to be put when one of the two
  733. instructions is a sub-routine; for example:
  734.   a) when an instruction reads a field with the null field type and then calls
  735. a sub-routine, practically 'passing' to it the value in the 'V' register, the
  736. called sub-routine must not read the field again;
  737.   b) when a sub-routine is supposed to read the fields it works on, the caller
  738. must not read them in advance.
  739.   The most delicate points are sub-routines which can be executed asynchron-
  740. ously, like the undefined record procedure, procedures associated with link
  741. points and any 'marked' procedure: the .DES programmer has to be sure that
  742. these sub-routines will be executed with the right alignment with the input
  743. file.
  744.  
  745.  
  746.                                  ------------
  747.                                    FILE LIST
  748.                                  ------------
  749.  
  750.   The package contains the following files:
  751.  
  752. FSDECODE.EXE   the program
  753. FSDECODE.TXT   this documentation file
  754.  
  755. Sample .DES files:
  756.  
  757. DEM.DES        for .DEM files
  758. DY1.DES        for .DY1 files
  759. MOD.DES        for .MOD files
  760. SC1.DES        for .SC1 files
  761. SC-DEF.DES     for the default scenery F1 or other sceneries with the same
  762.                structure (as Mallard's *.SCN)
  763. SCN.DES        tentative .DES file for alternate sceneries (subLogic's *.SCN)
  764. STATRECS.DES   .DES containing static scenery record definitions, used by
  765.                SC1.DES, SC-DEF.DES and SCN.DES and callable by any .DES dealing
  766.                with static scenery.
  767.  
  768.   Notes on supplied .DES:
  769.  
  770.   SCN.DEF: scenery sections of *.SCN files are not contiguous but, when a sec-
  771. tion ends, the file is padded to the next kilobyte boundary, where the next
  772. section begins; also, at sector 116 (offset 59,392) there is a special section
  773. containing some of the items found in the header of F1.  While the supplied
  774. SCN.DES makes no attempt to deal properly with this special section, it tries
  775. to reduce the problems posed by the padding garbage with a custom undefined
  776. record procedure, which outputs an hex dump up to the next kB boundary and then
  777. resume record decoding.  This way, assuming that all real record types are
  778. properly defined, no significant portion is lost, but the initial part of each
  779. pad can be misleadingly decoded as scenery records, if it happens to follow the
  780. structure of some of the known records; therefore, records before the message
  781. "Undefined record, dumping to next kB boundary" back to the last END (79h) or
  782. RET (19h) record have to be discarded, potentially.
  783.  
  784.   STATRECS.DES:  this .DES includes all records of which I know at least the
  785. length.  Some records (like the runway record, 50h) have a simplified descrip-
  786. tion and no attempt as been made to analyze building records (code 53h); only
  787. some FS variables are converted to plain labels.  Detailed description of all
  788. known records can be found in the file FSSTRUCT.TXT, available on request.
  789.  
  790.  
  791.                                  ------------
  792.                         COPYRIGHT NOTICE AND DISCLAIMER
  793.                                  ------------
  794.  
  795.   FSDECODE is distributed to encourage research and knowledge acquisition on
  796. the Flight Simulator environment. It is intended as KnowledgeWare: it is free,
  797. but anyone is invited to let me know discoveries obtained with it.  I
  798. explicitly renounce to any copyright I may have on it.
  799.  
  800.   The FS4/ASD community as a whole has spent way too much time decoding this
  801. information in order to generate useful utilities.  It would be nice if the
  802. original authors chose to publish an "official" documentation of FS data files.
  803. However, FSDECODE is not distributed with an eye towards enabling anyone to rob
  804. the original authors of any rightful profits and should be used only for the
  805. common good of the FS4 community and to encourage availability and sales of FS4
  806. and related products and utilities.
  807.  
  808.   Flight Simulator is a registered trademark of SubLOGIC Corp.
  809.   Microsoft Flight Simulator is copyright of Microsoft Corp. and Bruce A.
  810. Artwick.
  811.   Aircraft and Scenery Designer is copyright of Microsoft Corp. and The Bruce
  812. Artwick Organization.
  813.  
  814.   FSDECODE has been realized by:
  815.  
  816.           Maurizio M. Gavioli - BoGaRT sas.
  817.           via Mino 1
  818.           50122 FIRENZE
  819.           ITALY
  820.  
  821.          CompuServe: 100021,2335
  822.          InterNet:   "Maurizio M. Gavioli" <VINCIGLI@idg.fi.cnr.it>
  823.  
  824.  
  825.   Last, but not least: I want to thank Dan Samuel, Andrew Tuline and Steve Tur-
  826. ley for their suggestions and friendly support.
  827.