decode user guide

decode displays

decodeDoc.txt
decode129.txt




download decode.os9
download decodeSrc.os9

This document is ©2014 by Wayne Campbell.

Although I am releasing the documentation along with the decode program, I am asking that it remain unmodified from its original form. If you wish to try and help with solutions for decode's outstanding problems, or you wish to make corrections to typos or grammer, please make a copy of this document to detail your work with. Include the new document on the Source disk image (decodeSrc.os9) in the DOCS directory.

This web-version of the decode user guide may be updated at the discretion of the site owner, if said updates are not coming from me. Permission is granted to add a link to the box on the right so others can see your updated copy of this file. Also granted is permission to add a link and description in the body of this html document for the same purpose. Please insert new links and descriptions at the bottom of the page. There is no mechanism in place to allow you to edit this page in your browser. You will have to see what permissions the site owner will grant you.

Table of Contents

decode displays
detailed explanation of the displays in decode
Run decode 1st time
initial setup
Disk contents
directory and file identification
Setting options
using setOpts to set program options
Usage
command line syntax
Alerts
file error handling
Decoding the I-Code
the main screen
Programmer's Notes
information relevant to those wishing to understand decode's processes and code
1st Pass Decode
finding the variable and line number references
Reference Counts
total counts for variables, line references and literals encountered in the procedure
Line References
unsorted references, and line reference renumbering
Variable References
unsorted references, and variable identification
VDT Validation
validation of variables, parameters, fields and the called procedure list
DSAT Count and Validation
validation of string, array, and record variables, and the shape data for TYPEs

Running decode the first time

Before attempting to use decode, there are a few setup steps that need to be taken. There are two disk images for decode. You need both because the documentation is on the second disk.

Before doing anything else, look at the fileList files on both disks. These files list all of the files and directories that exist on the disk, each one unique to the disk it is on. Check this list against all of the directories and files to ensure you have a complete disk image, and repeat it for both disks.

Now that you are sure you have the correct disks (if you don't, go to the decode user guide and download a good set), you will want to copy all of the files in the CMDS and DATA directories to your default device (/DD) CMDS and (if you have one) DATA directories. If you do not have a DATA directory, you must create one before you copy the files in that directory. If you wish, you can run createDB. That procedure creates the DATA directory, if it doesn't exist, and creates all of the data files used by decode.

NOTE: createDB creates all of the files with their default values. This includes the user options. Once you modify your user settings and save them, you will lose them if you run createDB again. A future version will allow preservation of your user settings.


Disk contents

Disk 1: decode.os9

CMDS

The CMDS directory contains the following files:

createDB
creates:
  • DATA directory in root
  • initDB
  • linDefs
  • varDefs
  • procData
setOpts
sets user options
decode
main program, first module
defVars
main program, second module
buildSrc
main program, third module
instruction
main program, fourth module
readVars
displays the variable records one at a time, with formatting
readLins
simple line reference listing, same output as the <module>Lines.txt file

DATA

The DATA directory contains the following files:

initDB
initialization data
varDefs
variable reference file
linDefs
line reference file
procData
data unique to the procedure being decoded

ROOT

The ROOT directory contains the following files:

CMDS
commands directory
DATA
decode's data files
fileList
list of files and directories on this disk
ErrorCodes.lzh
archive file containing ErrorCodes, it's data file that goes in the DEFS directory, and its source files

Disk 2: decodeSrc.os9

SOURCE

The SOURCE directory contains the following files:

createDB.B09
Be extremely careful editing this file. If you do not match changes here within decode, defVars, buildSrc and instruction, you will break decode.
setOpts.B09
This file should only need to be edited if you are adding new options. Make sure you account for all changes to the initDB file in all decode modules.
decode.B09
main program, first module
defVars.B09
main program, second module
buildSrc.B09
main program, third module
instruction.B09
main program, fourth module
readVars.B09
displays the variable records one at a time, with formatting
readLins.B09
simple line reference listing, same output as the <module>Lines.txt file

DOCS

The DOCS directory contains the following files:

decode.doc
previous changes file - legacy
decode 1.2.9
version history
decode_displays
explanations of the various displays in decode
decode_user_guide
text version of the decode user guide

ROOT

The ROOT directory contains the following files:

SOURCE
source code files directory
DOCS
decode's documentation files
fileList
list of files and directories on this disk

Here is the Basic09 workspace information for all of the modules included in decode 1.2.9:


Setting options

The setOpts procedure is designed to allow you to decide what decode displays, what colors the overlay windows are, and what files (other than the source code output file) are generated.

setOpts can be run from the command line. There are no parameters. By default, decode runs setOpts when it first launches. You can change this setting to prevent setOpts from being run at startup.

There are three tabs in the setOpts dialog window. The default tab is Views. From this tab you can turn on or off each display window, the output window for displaying the source, and the setting for running setOpts at startup. If you turn off Processes, all of the window settings after it (not including the source output window) will be ignored and none of those windows will be displayed regardless of their settings here.

The Files tab allows you to select which output files (not including the source output file) will be generated. By default they are all ON, and they all will be generated. This is because decode still has issues that prevent it from producing 100% complete code (the TYPE, DIM and PARAM statements have issues, and there are still a few outstanding parsing errors in the instruction statements).

The Colors tab allows you to select the foreground and background colors you want to use for the overlay windows. I tried to select colors that would satisfy most users, but each of us has our preferences, so the option is there. Note that the HW text screen will not allow the use of more than eight colors without issues, so you only have the basic eight colors to choose from. The color settings do not apply to the Alert dialog or to the setOpts dialog (except for the foreground overlay colors in the setOpts window).

Use the up and down arrow keys to select options to change. In the Views and Files tabs, left and right arrows act as toggles. Either one will turn ON an option that is OFF, or turn OFF an option that is ON. In the Colors tab, left arrow opens the "foreground color" picker, and right arrow opens the "background color" picker. Once a picker is open, use up and down to select between colors and press [ENTER] to select that color. This closes the picker and returns you to the Colors tab, with the option selected having its color updated. While a picker is open, left and right arrows do nothing.

To select between tabs, press [V], [F] or [C]. To reset all options to their defaults, press [D]. To save changes end exit setOpts, press [S]. To exit without saving changes, press [E].


Usage

decode takes one parameter from the command line. The syntax is:

decode -? (or -h or -H): displays the built-in help.
decode <fileSpec>: launches decode and processes the file specified by <fileSpec>. <fileSpec> may be a path including filename.
decode -o (or -O),<fileSpec>: forces setOpts to open at startup, and upon exit from setOpts processes the file specified by <fileSpec>.

Note the comma in the -o version. That position in the string can be any displayable character you can type with the keyboard. I use the comma because it is the easiest to remember. decode ignores this character, but does account for its position, so don't make the mistake of typing -o<fileSpec>. This may cause undefined responses from decode.


Alerts

If you run decode without a parameter, or you use the -o option without specifying a fileSpec, decode will display an Alert dialog. From there you can enter a valid filename or press [ENTER] to exit decode. This alert is also dislayed if you specify a non-executable file, or the file is not an I-Code module.


Decoding the I-Code

The Main Screen

If you choose to turn Processes OFF, this screen is what you will see for the duration of the decode. decode will only process one module per file per run. The main screen is detailed in decode displays. Refer to that description for what follows.

The fileSpec parameter is parsed first. If the string begins with -?, -h or -H the rest of the string is ignored and the built-in help is displayed. If the string begins with -o or -O (not 0 ZERO), everything after the third character of the string becomes the fileSpec. If you leave out the fileSpec, you will be prompted with an Alert asking you to provide a fileSpec or press [ENTER] to exit decode. If you choose to exit decode, setOpts will be launched and decode will exit.

The third character of the -o/O version must not be a space. The space character is reserved by the shell as a parameter separator. Any displayable character you can type with your keyboard will do. I use comma (,) as being easiest to remember. decode ignores the character, but pays attention to the position. If you type -ofileSpec you will get undefined results.

Launching decode with no fileSpec results in the same Alert described above. If you choose to exit decode, the main screen will not be displayed, and the system cursor will return on the next line following your carraige return.

decode displays the fileSpec on the Project: line. This is to differentiate between the fileSpec and the name of the module that will be displayed below. Next decode opens the file and gets the first integer. If this integer does not contain the value $87CD, decode asserts that the file is not executable, and the Alert previously described is displayed. If you choose to exit decode, the system cursor will return at the bottom of the screen. decode closes the file before displaying the Alert.

If the file passes the executable module test, the second test is for I-Code. If the Type/Language byte is not $22, then the module is not I-Code. decode cannot process any other type of code but Basic09 I-Code. Since decode does not at present handle merged-module files, this requires the afore-mentioned Alert to be displayed. If you choose to exit decode, the system cursor will return at the bottom of the screen.

Once the I-Code test is passed, decode begins the process of decoding the module. The first thing it does is display the start time of the decode, and the module name followed by the contents of the module header for that module. The Proc Size, Data Size, Name Length and Total Program Variables fields are represented in decimal values and are right-justified on the screen. The others are all in hex format and are left-justified on the screen. The module CRC is included for completeness.

The Total Program Variables is a bit of a mosnomer. I named it that back when I began work on DCom. It seemed, at that time, to represent the total number of variables defined in the procedure, but only through a wierd series of additions and subtractions. It never was correct in all cases. Work with decode has helped me learn to understand that I was adding variables that should not have been added. Variables defined by use (no DIM or PARAM statement) of type REAL are not included in this count. I am not yet certain about type STRING, as all STRING variables require a DSAT entry, even when defined by use. I am in the process of determining what role these STRINGs play in the TPV count.

The lower part of the screen is where the action takes place. As decode goes through its processes, it will be displaying information here to allow you to see what it has found, and approximately where in the overall process decode is. The first two rows are a series of field headers. These field headers point to where you can expect to see the counts on each succeeding line, and what those counts represent. See decode displays for in-depth descriptions of the fields and their meanings.


Programmer's Notes

What follows are descriptions of the windows decode will display if Processes is turned ON, and the option for that window is turned ON. For anyone seeking to understand how decode works, and what its outputs are if the files options are turned ON. Each window represents a portion of the process, and allows you to peer into what decode is doing. I wrote it this way as the means of learning to understand where my code was going awry. It has also served as a way to give some kind of sense to an observer of what I-Code really looks like.

I am seeking to improve on this as I continue with development of decode. For anyone who wishes to collaborate or help with coding issues, I will be including my version of an API for decode. It should answer your questions about what code is doing what so you can find your way around the files decode uses, as well as understanding how it is using the VDT and DSAT to unravel the program variables.


First Pass Instruction Decode

This window is described in detail in decode displays. Refer to that description for what follows.

What you are seeing in this window is the I-Code version of the instructions that make up this module. It begins at the execution (I-Code area) offset address and continues to the DSAT (Definition Area) offset address. The first data to be displayed is the current offset of the module, and the relative offset in the I-Code area.

example:0021 0000|

The vertical bar is to separate the offset addresses from the I-Code instruction. As it makes its way through the I-Code, it identifies each token and displays the hex value of the token and the keyword or operator that the token represents, separated by a space, in < > brackets.

example: <10 IF>

Each potential variable reference is identified by a variable token. The valid token references in the I-Code area are (token values in hex):

80/F2
BYTE
81/F2
INTEGER
82/F2
REAL
83/F2
BOOLEAN
84/F2
STRING
85/F2
record, array, all parameters
86/F3
vector array, parameter
87/F4
table array, parameter
88/F5
matrix array, parameter
F6/89
all non-array fields
F7/8A
field vector array
F8/8B
field table array
F9/8C
field matrix array

Immediately following this token is an integer value that is an offset address. The definition of this address depends on the token. For all atomic variables (BYTE, INTEGER, REAL and BOOLEAN) with the 80-83 tokens, this is a pointer to the data memory address for that variable. For STRING variables with the token 84, it is a pointer to the DSAT. For all tokens F2-F9 and all tokens 85-8C, the address is a pointer to the VDT. decode wraps the token and the integer (both in hex format) within { } braces for easier identification. See The Structure of I-Code for more information on the makeup of I-Code.

When decode encounters a line reference token, $20 for GOTO, $22 for GOSUB, and $3B for bound line references occuring with IF-THEN <lref> and RESTORE <lref> statements, and ON expression GOTO/GOSUB statements, these tokens are followed by an integer value that is an offset address relative to the start of the I-Code area. decode wraps these tokens in ( ) for easier identification. Note that at this point in the process, decode has no way of naming variables or numbering line references.

Each variable or line reference is counted on the main screen as being Unique (variable, first count), or Valid (line number, first count, user-ref only), or Total (which includes all duplicate variable references, or all internal branch references as well as all valid line number references, including duplicates).

When decode encounters a $8D, $8E, $8F, $90 or $91, it understands that a literal (constant) value is next. decode wraps constants in [ ] brackets for easier identification.

8D
BYTE followed by a single byte value, range: 0-255, -128 - 127, $00-$FF
8E
INTEGER followed by a single integer (two bytes) value, range: -32768 - 32767
8F
REAL followed by a single float (five bytes) value, range: see the Basic09 reference
90
STRING followed by a series of ASCII characters, terminated with the STRING terminator: $FF
91
HEX INTEGER followed by a single integer (two bytes) value, range: $0000-$FFFF

decode also identifies other internal tokens, and places the token and its mnemonic in < > brackets.

example: <55 ivgt>

As decode progresses through the instructions, it is also counting what it finds. When it reaches a \ stacked instruction terminator, it assumes end-of-instruction and inserts a carraige-return after the \. The reason is that, in most cases, what followed was a comment, not another instruction. I myself use stacked instructions to stack short assignment statements used in initialization, three to five per line. Any code packed that way will be treated as separate instructions on separate lines. As each \ is encountered, the Total and \ fields on the Instructions line of the screen will be incremented. The same is true of the eol token. decode assumes end-of-instruction and end-of-line, inserting a carriage-return after the eol, and incrementing the Total and eol fields of the Instructions line on the screen.

The Action field of the Instructions line will notify you that decode is still decoding ("decoding"), or that the decode is finished ("decoded"). When the process finishes, the elapsed time will be displayed in the time field, and if the window is open, press [ENTER] to close it. The output of this window is written to the <moduleName>Raw.txt file.


Total Reference Counts

The Total Variable Reference Counts and Total Line and Literal Refeference Counts windows are described in detail in decode displays. Refer to those descriptions for what follows.

Immediately following the first pass, if the option for these windows is set ON, the total counts for all variable, line number and literal constant references encountered in the instructions is displayed. The first display is the Total Variable Reference Counts, and the second is the Total Line and Literal reference Counts. Press [ENTER] to close each window when you have finished viewing them.


Line References

The Unsorted Line References and Line Renumber windows are described in detail in decode displays. Refer to those descriptions for what follows.

The next step in the process of recovering your source is to identify each valid reference and determine how many potential line numbers there are. If you have the options set for ths window, the Unsorted Line References window will display all of the raw line references. You will notice that sometimes there are $20 and $3B entries with the same offset address. This is normal, as a GOTO ($20) reference can be repeated in a IF-THEN ($3B) reference, as well as in a ON expr GOTO ($20 and $3B) reference. In a special case with ON expr GOSUB, you may also see times when there are $22 and $3B entries with the same address. Any references with the same address are identified as being the same line number reference.

Press [ENTER] to close the window, and after sorting the entries, the Line Renumber window will open, if you have the option set for it to display. The display contains one entry per line, and includes the token, offset and line number assigned to this reference. This is the same data being written to the <module>Lines.txt file. Press [ENTER] when done viewing, and the window will close.

The readLins procedure (source listing on decodeSrc.os9) provides the same output, but reads the linDefs file directly. Run readLins before decoding a different module or you won't see the correct line references for the module you just decoded. I added the code to write the file inside decode to simplify and automate the file generation process. readLins is included in source form as legacy code.


Variable References

The Unsorted Variable References and Variable Identification windows are described in detail in decode displays. Refer to those descriptions for what follows.


VDT Validation

The VDT Validation window is described in decode displays. Refer to that description for what follows.


DSAT Count and Validation

The DSAT Count and DSAT Validation windows are described in decode displays. Refer to those descriptions for what follows.