FS-Interrogate 
(Version: 1.07  Build: 0020)

TOC Purpose Users of this tool Installation Project Saving your work Variables Exclude Areas Interrogate Options Interrogate Field Description Setting values 3-Scan Locator Export Registry History (be sure to check the latest changes)

Please note that this screenshot is not current.

Purpose/Credit
Some years ago Adam Szofran released a (freeware) product called FSIPC (Flight Simulator Inter Process Communication). Basically this product (a DLL installed into you MSFS's modules-folder) lets external (3rd party) programs communicate with MSFS, making it possible to read and set values within Flight Simulator (through a 8 Kb buffer that hold various variables). FSIPC was build for FS95/98 and the release of FS2K has caused some problems since the variables are no longer "placed" where they used to be. 

To my knowledge (at the time I started to develop this tool) I thought that the difference between FS95/98 and FS2K was the location of the variables within the 8 KB buffer, however this was not the case. But thanks to Pete Dowson's FSUIPC you can still use that (now non existent) 8 KB buffer (FSUIPC is doing all the magic so the data still appear to be contained within one continuous buffer). I would like to thank Pete Dowson who has suggested most of the improvements since version 1.00 (he really kept me busy <G>), but the net result is vastly improved product. I would also like to thank Chris Brett for his suggestions regarding the export-feature.

FS-Interrogate lets you browse the data supplied by FS98/2K. Hence it can help you locate variables and you can see the how the "changes" made in FS98/2K will be reflected in "the buffer". Pete Dowson had made a great "contribution" by updating FSUIPC.FSI (bundled with this version) that contains most (if not all) variables.

Since version 1.94 of FSUIPC and version 3.96 of WideFS "the buffer" has been extended to 16 KB giving access to a lot of new (FS2K only) variables. FS-Interrogate (version 1.04 and up) lets you access this "upper buffer", but this requires at least version 1.94 of FSUIPC (and version 3.96 of WideFS). Also the improvements to FSUIPC/WideFS means you can now (without problems) run FS-Interrogate on an external PC that communicate with MSFS through FSUIPC/WideFS.

Users of this tool
This tool IS NOT meant for "the average simmer". Not because its hard to use, but because the "average simmer" will have no use for it. So if you are not a 3rd party developer - nor plan to become one (freeware, shareware - whatever) this tool it not for you. If you on the other hand are a developer to whom FSIPC (and/or FSUIPC) are 2nd nature, this tool will probably not be useful either - since it won't provide you any knowledge you didn't previously have.

So who will find this tool useful (beside myself <G>). Well I am not new to writing programs (since it has been my job for +12 years) however I had not previously been writing add-ons for MSFS (other than Adventures, Scenery and repaints of Planes). Also I did learn C++ (some +6 years ago), but Delphi ended up being my preferred development-platform, hence I have never been too keen on diving into the SDK's that MS has released (anyone out there who have "an edge" as how-to write gauges and/or modules for MSFS in Delphi ? please mail me). The: "location", "type" and "use of" the variables accessible through FSIPC/ FSUIPC are not 2nd nature to me, and I had to learn "where to find them" and "how to use them" and for this purpose FS-Interrogate will be useful. 

Peter Dowson has released a SDK for FSUIPC which contains all the functions you need to to make it possible for your software to communicate with FSxx (through FSUIPC/WideFS). This SDK contains all the source that you need whether you are a C, Visual Basic or Delphi (like myself) -programmer. This SDK can be downloaded from this address: http://www.schiratti.com/dowson.html.

Installation
Simply install (extract) the "FSInterrogate.EXE" into a folder (of your own choice) from where it can be executed. This program doesn't require any additional files, other than a working FS98/FS2K. Since FS98/FS2K in it self does not offer any communication (with external programs) facilities you need also to install either FSIPC.DLL (also called FS6IPC) or FSUIPC.DLL (if you are a FS2K user) into your FSxx/Modules folder. FSUIPC can be downloaded from this address: http://www.schiratti.com/dowson.html (FSIPC/FS6IPC can be downloaded from several sites e.g. http://www.flightsim.com).

Thanks to Peter Dowson I can now bundle a "sample" file called FSUIPC.FSI that contains all known variables that can be manipulated through FSUIPC (and WideFS).

Be sure to install the latest versions of FSUIPC/WideFS to have support for the upper 8 KB buffer...

Project
FS-Interrogate works with one "project" at the time. So when you start FS-Interrogate most menus will be disabled until you either load up a project (the file "FSUIPC.FSI" is supplied with the program) or you can choose "New Project" in the file-menu. When you have an active project, the status-bar (bottom of the main-form) will show you the "platform" of the project, and if you have loaded a project (or saved a new project, so that a file is attached) the title-bar of the main-form will indicate the name of the file. The "Recent files" in the File-menu is currently not functioning.

When you choose "New-Project" you will be asked to chose a platform and enter a description. These are only meant as informative data (they don't carry any operational purpose). The platform can either be: "FS95", "FS98", "FS2K" or "Unknown", and these are meant to describe which platform you are "interrogating". The description lets you supply a description for the project (feel free to write away if you feel the need <G>)

In addition to the data mentioned above a Project consists of variables and exclude areas these are found in the Maintenance-menu (also in the Maintenance-menu you will find the Project info item that will let you change the description of the project and see the number of variables/exclude areas that are in the current project).

Saving you work
Whenever you close a window be sure to choose "Ok" if you have made any changes. Choosing "Cancel" will simply close the windows and thereby discarding the changes that you might have made. Also be sure to choose "Save Project" or "Save Project As..." in the main form, otherwise the changes you have made will not be written to the file (the file will only be updated by these 2 options), hence you changes will not be available next time you load the file. When the program sees that you have (potentially) made any changes it will warn you before you close a window.

Variables

For each variable you will have to enter the following informations:

• Address: The address (expressed as a 4 digit Hex-number). Actually the address is the offset within the 16 KB buffer, hence valid values are between $0000 and $4000 (currently its still possible to enter values up to $FFFF). Since version 1.04 you can add several variables to the same location (this wasn't posible in the first public released version). As you enter new variables they are not sorted however exiting this window (remember to use the OK-button) and enter again the data will be re-sorted.

• Field Name: This is meant for a "short description" of the variable. When exporting data from FS-Interrogate you will also be able to export af field called [VARNAME]. This field is derived from Field Name however it removes those chars that are not accepted by most programming platforms (eg. spaces, %, &, / and so on).

• Var-Type: New variable types have been introduced and the following are available: UNKNOWN, BYTE, WORD, LONGWORD, SHORTINT, SMALLINT, LONGINT and FLOAT64.Other than Byte, various development platforms might treat these variables different, hence I will explain how they works in Delphi. BYTE is 1 byte unsigned, WORD is 2 byte unsigned, LONGWORD is 4 byte unsigned, SHORTINT is 1 byte signed, SMALLINT is 2 byte signed, LONGINT is 4 byte signed, and FLOAT64 is a 8 byte floating point value. Choosing "Unknown" indicate that you have not yet determined the variable but the interrogate-function will treat it as a SmallInt. As a "golden rule" whenever in doubt you should choose "Unknown" since other valued indicate that you KNOW what the type is (this also goes for: Factor-Type, Read/Write and Category).

• Var-Base: Since version 1.04 you can state whether variables are to be show as either Decimal- or HEX values.

• Expression: Previous version had a Factor-type and a Factor, this didn't however give room for those tricky expressions. Since version 1.04 you have been able to enter an expression in stead - for instance like "(# * 360) / 65535" (the #-sign is being replaced by the value read from MSFS

• Read/Write: This is used to indicate whether the value in the buffer is: "Read Only", "Read/Write" or "Write only". If you are not sure you should choose "Unknown"

• Category: This (currently) serves no function other than describing the category of the variable.

• Usage: The Field-Name is only mentioned as a "short description" of the variable. If you want to write more info about the variable (for instance how to use it / possible values and their meaning) then use the "Usage".

Exlude Areas

Interrogate Options

Interrogate
Below you'll see an example of the Interrogate-window (when you first enter this window you won't see the values before you click any of the buttons below). In the lower right corner you'll see a Close button. If/when you have made any changes to the "known" variables (described later) the Close button will be replace by a Ok and Cancel button (you'll have to use the Ok Button if you want to keep the changes that you have made).

The current version is not 100% like this screen shot.

Basically the window consist of 2 "areas": above you'll see a grid showing various data for each variable and below you'll see the controls that lets you interact with FSxx. For each "known" variable you'll see the "address" and the "Field Name". If the variable is not known (you'll have to choose either "Only Interrogate unknown fields" or "Interrogate the entire buffer" in the "Interrogate Options Window") then there is no "Field Name" to show and since FS-Interrogate doesn't know the type for the variable it has to "guess" its type (unknown variables are treated as SmallInt - 2 byte signed).

Versions prior to 1.04 the interrogate screen showed all values (in all cells) however this tended to clutter the screen. Now values for (know variables) are only showed in the cell for which the variable type has be identified. If the variable is not specified (or the type is Unknown) all cell values are show. Likewise if a variable has been identified as a HEX variable the value is shown as a HEX number (prefixed with "$"). 

In the lower right corner you choose how to see Signed/Unsigned. Choosing Signed/Unsigned will show the variables according the their specifications. Choosing either Signed or Unsigned will either show the variables as Signed or Unsigned no matter how the variable is specified. The last option is called Show All and it functions just like Signed/Unsigned however it shows the value in all cells (even if the type is specified).

Just below sign-setting you'll find the base-setting. Normally you will leave this value at DEC/HEX, which means that variables are shown according to their specifications. Changing this into DEC or HEX will either show all variables as DECimal- or HEX values - no matter how the variables are specified.

The 5th of the green/red columns will show the "Factored" values. That is values calculated based on the Expression. This means that once the variable has been read FS-Interrogate will calculate the factored value (by using the Expression set up for that variable). For instance at $0270 you will find the variable for the FrateRate. If FS-Interrogate reads the value 1638 it will show the factored value as 20.00427 (frames/sec.) since the expression is "#/32768" (hence "32768 / 1638 = 20.00427"). FS-Interrogate lets you read the values into 2 difference buffers (Buffer-1 shown is as green and Buffer-2 shown as red). The last (right-most) column lets you display the difference between the Factored (calculated) values. This difference can be shown as either "As Factor", "As %" or "As Value". If you check "Auto Calc", the difference-value will be calculated each time either of the Buffers are re-read.

Watch out when looking at the various columns, since data will "overlap". For instance at $0350 you'll find the NAV1 Freq. This is a 2 byte variable so when you look at the "Long" values (4 Bytes) then you will see the 2 bytes "belonging to "NAV1 Freq" but you will also see the "next 2 bytes" that cover 2 bytes at $0352 where NAV2 Freq. is located. Also this "faulty reading" will appear when looking at the data just prior to the location where actual data is placed.

Clicking Read Buffer1 or Read Buffer2 will "Interrogate" (once) FSxx and show the values for these buffers. If you want to keep updating either of the two buffers you can put a checkmark in the "Continuous" box (you will not be able to use continuous scan for both buffers at the same time). If none of the rows are selected (either of the "methods") will Interrogate FSxx for all values, however if rows are selected only values for those rows will be read. To select a row you click the "gray button" to the left of a row. Several rows can be selected at once using SHIFT and/or CTRL (this shouldn't come as a surprise <G>). To "un-select" rows simply click elsewhere in the grid (e.g. in the "Field Name" column).

Field Description

Setting Values

3 Scan Locater

For instance if you want to find the location of the variable used for the lights you would first click the 3-Scan locater (in the Interrogate window) and when the window appear (as seen above) you would then click the 1st Scan button in order to perform the first scan. During this 1st scan the data is actually read into a 3rd buffer that is not used for other purposes (and therefore won't be visible). Then you would go into FSxx and flip one of the light switches and then go back to FS-Interrogate in order to perform the 2nd scan (by clicking 2nd Scan) whereby data is read into the 2nd buffer. Finally go into FSxx flip the light switch back (to its initial position) and then enter FS-Interrogate and perform the 3rd scan (by clicking the 3rd Scan button) whereby data as read into the 1st buffer. Now the FS-Interrogate will automatically find those variables that had the same value in the 1st and 3rd scan but a different value in the 2nd scan.

This method is not fault proof since variables "by coincidence" might have had the same value in the 1st/3rd scan but different value in the 2nd whereby it would qualify. However it is omitting values that have simply changed from one value into another. As seen above the 3-Scan function has located a change to a "variable" at $028C" even though this has nothing to do with the Lights. If you are "having trouble" with the same variables over and over it would be a good idea to enter these into the Exclude Areas (even though it is an "area" it can contain single variables as well "FromAddr=028C, ToAddr=028C").

The OK button serves 2 purposes. In this example; 2 variables were located (even though only one of them were useful) so clicking OK would return you to the previous window (Interrogate) but the 2 found variables would be selected, hence they would be easy to find and performing either of the Read buffer functions would only read data into these (now) selected rows. If you look at the screen-shot above you'll see that the "Field Name" column contains a small button to the right and clicking this would enter the Field Description dialog (previously described). Likewise if you simply enter or change a field name then the Field Description dialog will be launched. If you have described new fields then remember to click the OK button to make sure that the changes you have made will be transferred back to the Interrogate window (clicking the Cancel button will simply discard any changes).

Export

Export Formats
The screenshot shown below will be visible when adding new formats or editing old formats. The title-bar of the form shows the name of the exportformat. This name can't be changed (however you can always copy the format to a new name, and then remove the original format). The first input field (Default Extension) lets you enter the (3 char) extension that FS-Interrogate will suggest when using that Export format. The 2nd field lets choose the variable name case. This decide if the exported [VARNAME] shout be in "UPPER CASE", "lower case" or "As Is". Choosing "As Is" will return the variable names as they are entered. The 3 memo fields contains the text that is inserted into the file being exported to (see below for an explanation). The Header and Footer is written once in the beginning and the end of the files, whereas Body is written once per variable (the export function pays no attention to export areas, hence ALL variables are exported).

Export Variables
If you could only enter fixed text into the Header, Body and Footer the export feature wouldn't be worth anything. Therefore you can insert "variables" into the memo fields. When exporting the data these variables will be replaced by the values of these variables. The table below shows which variables can be inserted into which memo fields. The memo fields will show all variables in blue and fixed text in black. All text between '[' and ']' are considered to be a variable even if you misspell the name so its YOUR JOB to make sure that you use valid names. Right clicking the memo-fields will show a menu from where you can pick the variables. These variables that you can pick have been split into 3 categories. Standard Values has nothing to do with the FSxx variables and contains data like filename, export format used time/date of export. Variable Properties are the properties that the user has entered for each variable (e.g. Filename, variable type and so on). Derived Properties are data that can be derived from the variable properties (e.g. when the variable type has been identified you know the size in bits or bytes or a variable).

Specifying length
When using the variable names as they are shown above they will be replaced by the value of variable, hence the "resulting length" of those values will vary. However when exporting there will be cases when you want the data to appear nicely ordered in columns (e.g. when exporting to source-code). You can therefore enter a 1 or 2 digit size. If the size you enter is longer than the length the value then the value will be padded with spaces to make sure that the variable end up having the desired length. Likewise if the size you enter is smaller than the actual length of the variable then the variable is trimmed down to the desired length.

Lets imagine that the variable "[CATEGORY]" contains the value "Engines". If you simply use "[CATEGORY]" then the resulting length will be 7 since the length of "Engines" is 7 chars. If you in stead write "[CATEGORY3]" or "[CATEGORY03]" you will force the size to be 3 hence the value will be trimmed so only "Eng" is used. Likewise if you instead use "[CATEGORY10]" then the value "Engine   " (padded with 3 spaces) will be used.

Registry
From version 1.06 onwards FS-Interrogate has made use of the registry to save application data, however projects are sill contained in external FSI files (like FSUIPC.FSI). Since FS-Interrogate is meant for 3rd party programmers it shouldn't be necessary to describe how to use the windows registry, but I will offer a few pointers anyway. All values are stored in "HKEY_CURRENT_USER/Software/Liljendal/FS-Interrogate". So if you want to move all your settings to another computer you would only have to export this "branch" within RegEdit. Likewise if the settings should become FUBAR you can clear all settings by removing this "branch" from the registry.