# Utility Applications

The simulation contains a number of utility programs that can be used for various off-line tasks.

- Simple Assembler
- Telecode Tape Printer
- Telecode Tape Writer
- Tape Copier
- Tape Reverser
- Core File Formatter
- Trace File Formatter
- Binary Tape Formatter
- Telecode File Formatter
- Machine Image Formatter

To run any of these utility programs you must ensure the simulator JAR file is on the Java CLASSPATH.

## Simple Assembler

### Command

>     java elliott803.utils.Assembler inputfile outputtape

#### Parameters

> `inputfile`
>   The assembler source code file.
> `outputtape`
>   The name of the output binary tape file.

The simple assembler will create binary program tapes that can be loaded by the 803 initial instructions. It can create standard tapes or self-triggering tapes that will automatically jump to the program entry point when the tape is loaded. This is a very simple assembler intended to produce fairly basic test programs.

- The assembler source consists of a set of lines. Blank lines are ignored and any characters following a "*" are comments and are also ignored.
- A line may start with a label (an identifier followed by a ":") and this will assign the address of the next instruction to that label.
- A line may define a single instruction or a pair of instructions in the form
  `op1 addr1`
  `or op1 addr1 b op2 addr`
  where op1 and op2 are two digit octal instruction op-codes and addr1 and addr2 are either integer storage addresses or labels. b is either the character ":" or "/".
- A line may contain one or more constants which are a positive or negative integers separated by commas. Each constant is placed in subsequent words of store.
- A line may contain a string in 'single quote' characters which will be turned into a sequence of telecode characters (including any necessary shift characters) one character per subsequent words or store.
- A directive =nnnn (where nnnn is a storage address) can be used to define the load address of the program. If this is omitted the program will be loaded into the high end of store.
- A directive @addr (where addr is either a storage address or label) can be used to define an entry point. A trigger will be generated at the end of the tape to jump to the entry point.

Here is an example of the assembler source, showing most of the function. Look at the sample assembler programs for further examples:

         *
         * Simple Hello World program
         *
                  =8160                * Load program starting at address 8160
                  @entry               * Define the entry address

         begin:
         loop:   22 index / 30 hello   * Get next character
                 42 end   : 40 write   * Check for zero at end of string or write char
         write:  20 char  / 74 4096    * Write character to teletype
                 40 loop               * Loop back to next character
         end:    74 4125  : 74 4126    * Write CR and LF to finish line
         done:   72 8191               * Exit when finished

         entry:  30 m1    : 20 index   * Program entry point
                 40 begin              * Initialize 'index' and begin output

         char:   0                     * Character workspace
         index:  0                     * Index into string
         hello: 'Hello World?'         * Text - will be {LS}HELLO WORLD{FS}? in telecode
                 0                     * Zero marks end of string
         m1:    -1, 2, +4              * A few constant values (not all used!)

Note: This example uses the simulator control instruction `72 8191` to cause the simulation to stop.

## Telecode Tape Printer

### Command

>     java elliott803.utils.TapePrint [options] inputtape [outputfile]

#### Parameters

> `inputtape`
>   The telecode tape to be printed.
> `outputfile`
>   The name of an output file. Defaults to standard out.

#### Options

> `-ascii`
>   Print using only US-ASCII characters
> `-encoding encoding_name`
>   The output file encoding. Defaults to the standard platform encoding. This option is rarely needed.

This will print out the contents of an Elliott telecode encoded tape, as defined by the telecode conversion methods. If the `-ascii` is used only characters from the US-ASCII code set will be used when printing, in particular the GB-pound sign (`£`) (telecode character figure-shift 26) will be printed as the number sign (`#`).

## Telecode Tape Writer

### Command

>     java elliott803.utils.TapeWrite [options] inputfile outputtape

#### Parameters

> `inputfile`
>   The name of the input file to be encoded.
> `outputtape`
>   The name of the telecode output tape.

#### Options

> `-encoding encoding_name`
>   The input file encoding. Defaults to the standard platform encoding. This option is rarely needed.

This will take a standard system text file and write an equivalent telecode encoded tape, according to the telecode conversion methods.

## Tape Copier

### Command

>     java elliott803.utils.TapeCopy [options] inputtape1 [inputtape2 ...]

#### Parameters

> `inputtapeN`
>   One or more input tape names.

#### Options

> `-outputoutputtape`
>   The output tape name.

This will make a copy of one or more input tapes, producing a single new output tape. If more than one input tape is specified the output tape will include a small amount of runout between each tape as it is copied.

## Tape Reverser

### Command

>     java elliott803.utils.TapeReverse inputtape outputtape

#### Parameters

> `inputtape`
>   The input tape name.
> `outputtape`
>   The output tape name.

This will make a copy the input tapes in reverse, producing a new output tape. This function is intended for use with ALGOL Owncode tapes which are produced by the compiler in reverse and were intended to be wound up backwards before being read back into the system.

## Core File Formatter

### Command

>     java elliott803.utils.PrintCore corefile [outputfile]

#### Parameters

> `corefile`
>   The name of simulator core dump file.
> `outputfile`
>   The name of an output file. Defaults to standard out.

This will format and print the output of a simulator core dump file. The core dump files usually have a name like `elliott‑yyyyMMdd‑HHmmss‑SSS.core`

The formatted core output shows the state of the machine registers and flags when the system dump was performed, followed by the full 8K words of store. To save space any consecutive words with the same value are omitted.

Each storage word will be output something like this:

     742:    00  553 : 63 6766   [0004245475156]   (+580287086)       ".BEGIN"
     743:    00    0 : 00    6   [0000000000006]   (+6)   'F ='

This shows the address of the word followed by its value as a pair of instructions, its value in octal (in square brackets) and its value in decimal (in round brackets). For values that might represent a single telecode character the character in letter-shift and figure-shift form is displayed in single quotes, for values that might represent packed text characters the possible packed text is displayed in double quotes.

Core dump files can be produced by using the special simulator control instruction, or by pressing the Dump button on the CPU view window.

## Trace File Formatter

### Command

>     java elliott803.utils.PrintTrace tracefile [outputfile]

#### Parameters

> `tracefile`
>   The name of simulator instruction trace file.
> `outputfile`
>   The name of an output file. Defaults to standard out.

This will format and print the output of a simulator instruction trace file. The instruction trace files usually have a name like `elliott‑yyyyMMdd‑HHmmss‑SSS.trace`

The output of the trace formatter will be something like this:

    8169.0:  22 8176 / 30 8177   -   0007100000000 (+956301312)
    8170.0:  46 8173 : 20 8175   O   0000000000037 (+31)
    8171.0:  00 8175 / 74 4096   -   0000000000037 (+31)

This shows the address of an instruction pair with a .0 or .1 suffix - normally this is .0 meaning execution starts with the first of the pair but it may be .1 following a jump to the second instruction. This is followed by the pair of instructions themselves.

Following the instruction is the state of the overflow flag (shown as '-' for no overflow and 'O' for overflow) and the value of the accumulator (in octal and in decimal) before execution of the instruction(s).

Trace files can be produced by using the special simulator control instructions, or by selecting the Trace action on the CPU view window.

## Binary Tape Formatter

### Command

>     java elliott803.utils.PrintT1 binarytapefile [outputfile]

#### Parameters

> `binarytapefile`
>   The name of binary program tape file.
> `outputfile`
>   The name of an output file. Defaults to standard out.

This will format and print the contents of a binary program tape. a binary program tape is a tape that can be loaded using the initial instructions.

## Telecode File Formatter

### Command

>     java elliott803.utils.PrintTelecode [options] inputfile [outputfile]

#### Parameters

> `inputfile`
>   The name of system text file
> `outputfile`
>   The name of an output file. Defaults to standard out.

#### Options

> `-ascii`
>   Print using only US-ASCII characters
> `-inputenc encoding_name`
>   The input file encoding. Defaults to the standard platform encoding. This option is rarely needed.
> `-outputenc encoding_name`
>   The output file encoding. Defaults to the standard platform encoding. This option is rarely needed.

This will print the contents of a input file converting to only use characters from the telecode character set. It can used, for example, to print an ALGOL program that has been written using the extended character mappings to the form it would have had on a real 803.

## Machine Image Formatter

### Command

>     java elliott803.utils.PrintMachine [options] machine [outputfile]

#### Parameters

> `machine`
>   The name of a saved machine image file
> `outputfile`
>   The name of an output file. Defaults to standard out.

#### Options

> `-nodump`
>   Omit the core dump from the output

This will print the contents of a previously saved machine image. It will show the saved window positions (if present) and will optionally show the saved core store.

Tim Baldwin June 2012 tjb803@tinymail.co.uk | Return to index © Tim Baldwin 2009,2012