ST-DOS Calc usage manual


ST-DOS Calc is a spreadsheet program that can be used to do various calculating
stuff. This document explains how to get started with ST-DOS Calc.

  Contents list:

1. System requirements
2. Starting the program
3. Navigating on the table
4. Entering a cell value
5. Saving the document
6. Searching for a string on the document
7. Jumping to a specific cell
8. Functions
9. Macros


  Document contents:

  1. System requirements

ST-DOS Calc works on all IBM PC compatible computers. The operating system must
be either POSIX or DOS compatible. For the best user experience we recommend
the ST-DOS disk operating system.

To work smoothly the program has the following requirements for your system:

- 4,77 MHz 8088 or compatible processor (recommended to have at least 16 MHz 286
  with a floating-point unit)
- 512 kB system memory
- CGA graphics adapter (MDA is not currently supported)
- 80 kB of disk space

  2. Starting the program

ST-DOS Calc can be started from a command line by the command "CALC" (without
quotes). If you want to create a new empty spreadsheet document, the command
does not need any arguments. If you want to open an already existing file, the
name of the file must be given to the command as an argument.


  3. Navigating on the table

Navigating on the table is done by the arrow keys and navigation keys [HOME],
[END], [PAGE UP] and [PAGE DOWN]. If [Scroll Lock] is enabled, navigating on the
table only scrolls the table on the screen but does not change the selected
cell. With [Scroll Lock] disabled the selected cell also changes.


  4. Entering a cell value

When the cell is selected, by pressing [ENTER] the program goes into the edit
mode. Then you can write a new value for the cell by using the letter and number
keys. [BACKSPACE] deletes the last entered character. You can exit the edit mode
by pressing [ENTER] or [ESC].


  5. Saving the document

The spreadsheet document is saved to a CSV file by pressing F2. The program asks
the user for the name of the file. You can cancel the saving by pressing [ESC]
or confirm it by pressing [ENTER]. By pressing [F6] you can save only the
results for further processing.


  6. Searching for a string on the document

a) The first occurrence of a string: Press [F4]. The program asks for a search
word. You can cancel the search by pressing [ESC] or write the search word and
confirm it by pressing [ENTER]. If the search word is found on one or more
cells, the program jumps to the cell where the first occurrence was found.

b) The next occurrence of the string: Press [F3]. The program jumps to the cell
where the next occurrence of the string is, if it exists. The search order is
from left to right and from up to down.


  7. Jumping to a specific cell

Navigating on a large spreadsheet table can be slow with only the arrow keys.
That's why ST-DOS Calc has a jump function that you can use by pressing the [F7]
key. The program asks for the name of the cell. If you enter the full name of a
cell (for example LE37), the program jumps to that cell. If you enter only the
number of a row, the program jumps into the first cell of that column. If you
enter only the name of a column, the program jumps to the uppermost row of
that column.


  8. Functions

Currently ST-DOS Calc supports the following functions:

=SUM()
=MIN()
=MAX()
=COUNT()
=IF()
=AND()
=OR()
=XOR()
=NOT()
=PRODUCT()
=QUOTIENT()
=MOD()
=IMDIV()
=POWER()
=MEDIAN()
=LOG()
=ROOT()*
=MOV()*
=FOR()*
=FORMAT()*
=NOP()*
LIST()*
SLIST()*

All above functions except ROOT(), MOV(), FOR(), FORMAT(), NOP(), LIST() and
SLIST() are standard spreadsheet functions that are not explained on this
document. To become a powerful tool for advanced needs, ST-DOS Calc has some 
special properties that make Turing-strong calculations possible.

ST-DOS Calc also supports variables. The names of the variables are one letter
long and they consist of a dollar sign ($) and one uppercase letter. The
variable name $A is reserved for the return value of the currently running FOR
loop. Other variable names can be freely used and their scope of visibility is
the whole cell. A new variable is declared by referencing to it the first time
and its initial value is zero (0).


  Using the ROOT() function

Syntax: ROOT(cell1,cell2)

Operation: The ROOT function finds a root for the first argument. The result
raised to the power of cell2 equals to the first argument.

This example finds a cube root for the value of the cell A8:

  =ROOT(A8,3)

Return value: ROOT returns the root.


  Using the FORMAT() function

Syntax: FORMAT(function, cell/range)

Operation: The FORMAT function formats a group of cells on the table so that
they can be used as a target for the MOV() function. Unformatted (blank) cells
cannot be referred by the MOV() function. The formatted cells get their value
from the first argument.

This example formats the cells B1:C10 to the value NOP():

  =FORMAT(NOP(),B1:C10)

After the cells have been formatted, they can be used, for example, for saving
the return values of the FOR() function via the LIST() structure.

Return value: FORMAT returns the function that is given to it as the first
argument.


  Using the NOP() function

Syntax: NOP()

Operation: NOP does not do anything and it does not change the result of the
cell.

Return value: NOP does not return anything.


  Using the MOV() function

Syntax: MOV(cell/variable,cell/variable/function)

Operation: The MOV function copies the value from the object that is given to it
as the second argument to the object that is given to it as the first argument.
The first argument can be a cell or a variable. The second argument can be a
cell, a variable or a function.

Return value: MOV returns the copied value.


  Using the LIST() and SLIST() structures

Syntax: [S]LIST(range)

Operation: The LIST structure can only be called from inside a FOR loop. When
the LIST structure has been called the first time, it creates a list of cells,
that exist in the coordinates given, to the spreadsheet program's memory.
The LIST structure builds the list in the order that the cells are visible on
the table, from left to right and from up to down. The SLIST call sorts the
cells into a numeral order from the smallest to the largest value. The state of
the LIST structure resets in the beginning of every FOR loop or after the last
cell in the list has been read.

This function call sorts the cells in the columns B:C to the columns D:E in the
numeral order:

  =FOR(;MOV(LIST(D:E),SLIST(B:C));)

Return value: The LIST structure returns the cells on the list one by one.


  Using the FOR function

Syntax: FOR(function1,function2,function3...;condition;function1,function2,function3...)

Operation: FOR-function creates a loop where other functions can be called from
within. Unlike other functions, where semicolon and normal comma can be used
interchangeably, in the FOR function the semicolon indicates the next phase
of the function. That's why the arguments must be separated by a comma.

Return value: The FOR function returns the value that was assigned to the
variable $A.

The FOR function has three phases:
1) Initialization phase. The argument list of the initialization phase can be
empty or it can have function calls. During the initialization phase the
function calls are executed in the order from left to right.

2) Condition phase. The argument list of the condition phase must have at least
one argument. The arguments can be cells, ranges, numeral constants, variables,
functions or logical expressions. The arguments are evaluated in the order from
left to right. If at least one of the arguments returns a non-zero value,
the function moves into the next phase when every argument has been evaluated.
In any other case the loop ends.

3) Execution phase. The arguments must be functions. The functions on the
argument list are executed in the order from left to right. Then the control
goes back to the phase 2 of the FOR function (condition phase).

  Examples for using the FOR function

This function counts from one to ten using the reserved variable name $A as the
counter:

=FOR(MOV($A,1);$A<10;MOV($A,SUM($A,1)))

This function calculates a power using the value of the cell A17 as the base
and the value of the cell B17 as the exponent:

=FOR(MOV($E,SUM(B17,-1)),MOV($A,A17);$E;MOV($A,PRODUCT($A,A17)),MOV($E,SUM($E,-1)))

The next function call goes through the cells on the column D from up to down
and returns the value of the first cell that has the value of 100 or larger:

=FOR(;MOV($A,LIST(D:D))<100;)


  9. Macros

To be as versatible and customizable as possible for every user's needs, ST-DOS
has a macro function. The macros can be found in the file MACROS.CLC. The syntax
of the macros is:

[MACRO NAME] [FUNCTIONCALL(%1,%2,%3,%%)]

The positional arguments are expressed using numbers that come after the percent
mark. If the macro has two consecutive percent marks, the remaining arguments go
there. In that way macros can have a variable count of arguments.

Macros can also be used to create aliases for already existing functions. For
example, the macro

MUL PRODUCT(%%)

creates a shorter name for the PRODUCT()-function that is easier to remember.

More examples of macros can be found in the MACROS.CLC file.

Document version 0.8