Documentation for RPNMI.EXE                        March 19, 1992


This document applies to version 3.0 of RPNMI
Copyright 1984-1992 by author Harry J Smith, Saratoga, CA

INTRODUCTION  (Note: See RPNM.DOC first for general introduction)

To use the program type the name of the EXE file at the DOS prompt
line with a return and no parameters. The program will load and
respond with:

  *** RPNMI *** Version 3.0, Mar 19, 1992
  Copyright (c) 1984-1992 by author: Harry J. Smith,
  19628 Via Monte Dr., Saratoga, CA 95070.  All rights reserved.

  Reverse Polish Notation Multiple-precision Integer calculator
  Has a stack of four 7349 decimal digit numbers

  Press ESCAPE to interrupt a long calculation or a slow display
  Base = 10 base ten,  Max digit = 9

  **** PRESS ANY KEY TO CONTINUE HELP OR PRESS ESCAPE ****

  n    Enter a number, may not have a + or - sign
  !    X factorial
  "    Start/stop comment field "CC...C"
  %    X = Y MOD X, Y = Y / X
  (N)  Don't display number of digits
  (Y)  Display number of digits
  *    Multiply
  **   X = Y ** X Power
  +    Add
  -    Subtract
  /    Divide
  ?    Display this help menu
  A    Auto display on/off
  ABS  Absolute value of X
  B    Set base to X
  BEL  Bell prompt on/off
  C    Change sign of X
  CL   Clear X
  D    Display X
  DL   Display learned line
  E    Enter X again

  **** PRESS ANY KEY TO CONTINUE HELP OR PRESS ESCAPE ****

  ECHO Echo input to output, toggle on/off
  EX   Execute learned line
  EXX  Execute X times
  I    Interchange X and Y
  L    Last X
  LRN  Learn
  N=   Don't display = sign
  OFF  Exit back to system
  ON   Reinitialize
  R    Square Root
  R1   Recall memory register 1
  R2   Recall memory register 2
  RMB  Recall Modulo base
  RN   Generate a random number < modulo base or 80 bits
  RR   Y = X ** 0.5, X = Remainder
  RRN  Recall random number or seed
  S    Square
  S1   Store X in memory register 1
  S2   Store X in memory register 2
  S<>  Stop if X <> 0
  S=   Stop if X = 0

  **** PRESS ANY KEY TO CONTINUE HELP OR PRESS ESCAPE ****

  SG   Set digits per group for output display of X
  SMB  Set Modulo base to X, X = 0 => no Modulo base
  SP   Set spacing value, -1...3
  SRN  Set seed for random number to X
  U    Rotate stack up   (X -> Y -> Z -> T -> X)
  V    Rotate stack down (X <- Y <- Z <- T <- X)
  Y=   Display = sign

  **** PRESS ANY KEY TO ENTER CALCULATOR MODE ****

  = 0

  COMMAND:

Commands may be entered one at a time followed by a return or
several on a line separated by one or more spaces. A space is not
required between commands if there is no ambiguity of meaning.

Since this is an RPN calculator, 3 * (4 + 5) is entered as:

     3 4 5 + *   or   3 4 5+*   or   4 5 + 3 *   or   4 5+3*

Be careful not to enter more than 4 items on the stack at any one
time. The items on the stack are referred to as X, Y, Z, and T. X
is the item on the bottom of the stack, Y is just above X, then Z
above Y, and finally T is on the top. Operations that take two
arguments to generate one, will pop X and Y off of the bottom of
the stack, perform the operation, and push the result back onto the
bottom of the stack. Such an operation will always result with Z
and T being equal since when X is popped, T is duplicated into Z.
The stack is always full. A push operation loses T. Operations that
take only one argument will pop X, perform the operation, and push
the result.

When the program is loaded it determines how much internal memory
is available for X, Y, X, T and the other long registers needed. It
then makes these registers as long as possible to use up all
available memory. The size of the decimal digit numbers on your
system may be more or less than the indicated in the example above.

This ends the introduction. I will now explain each command taking
them in ASCII sort order.

n    Enter a number, may not have a + or - sign:

Here n refers to keying in an integer like 0 or 123456789. The
integer is merely pushed onto the stack. The way to enter a
negative number is to enter its absolute value and then change its
sign with the C command. Commas may be inserted in the number
between any two digits to aid in reading. For example 12,345,678 is
a legal input number.

!    X factorial:

Replaces X with the factorial of X = 1 * 2 * 3 * ... * X.

"    Start/stop comment field "CC...C":

Comments can be entered at any time and are quite useful on the
learned line, see LRN. The comment is started and ended with a "
mark. All spaces between the " marks become part of the comment.
Normally all commands are converted to upper case as they are
input. The characters of a comment are not converted to upper case,
they must be typed in upper case if upper case is desired.

%    X = Y MOD X, Y = Y / X:

X and Y are popped off the stack, both the quotient and remainder
of Y divided by X is computed, the quotient is pushed onto the
stack and then the remainder is pushed.

(N)  Don't display number of digits:

Since RPNMI can display numbers with many digits it is some times
desirable to include in the display a count of the number of
digits. This option is selected by the command (Y) and deselected
by the command (N). For example 10 ! will display as:

  = 3628800 (7)

if the option is selected. If the count is less than 4 it is not
displayed. If the base is set to a base other than ten, the count
of the number of digits will still be in base ten. Thus fifteen in
base 2 will display as:

  = 1111 (4)

if the option is selected.

(Y)  Display number of digits:

Select the option to display the count of the number of digits
following the display of the value. See (N) above.

*    Multiply:

Pop X and Y, Push X times Y.

**   X = Y ** X Power:

Pop X and Y, Push Y to the power of X.

+    Add:

Pop X and Y, Push sum of X and Y.

-    Subtract:

Pop X and Y, Push Y minus X.

/    Divide:

Pop X and Y, Push Y divided by X.

?    Display this help menu:

Causes the help menu to be displayed. It is the same as the menu
displayed when you first enter the program, but the base displayed
will be the currently selected base.

A    Auto display on/off:

Normally, after each command line is executed, the contents of the
bottom of the stack, X, is converted to the selected base and
displayed. When computing with large numbers, the time spent in
this conversion can be more than the time spent in the calculation.
It is desirable then to be able to prevent this automatic display.
Each time the A command is given the selection status of this
option is reversed.

ABS  Absolute value of X:

Forces the sign of X to be plus. The magnitude of X is unchanged.

B    Set base to X:

Initially the base of both input and output display is set to ten.
It can be changed at any time to a number between 2 and 36 decimal.
If the base is ten, the command 36 B would Pop X and change the
base to 36 base 10 and display:

  Base = 36 base ten,  Max digit = Z

Just as the digit F is worth fifteen when we are in base sixteen,
the digit Z is worth thirty-five when we are in base thirty-six.
Note that the value used to describe a base radix is always given
in the normal decimal base, i.e. base ten. When in a base greater
than ten, numbers may have to be entered with a leading 0 to
prevent being mistaken for a command. When in base sixteen, a ten
must be entered as 0A instead of A or the auto display status will
be changed.

A special case is made for getting back to base ten. If the X
register is zero when the B command is given, X is popped from the
stack and the base is set to ten.

BEL  Bell prompt on/off:

This is good for timing long calculations.

C    Change sign of X:

Same as multiplying X by minus one. The only way to enter a
negative number is to enter its absolute value and then change its
sign.

CL   Clear X:

X is set to zero. Y, Z and T are not affected. CL + can be used to
perform a Pop operation.

D    Display X:

This command is useful when the auto display is turned off. Also
useful in the learned line to display intermediate results.

DL   Display learned line:

Displays the current contents of the learned line. While commands
may be given in either upper or lower case or even a mixture, the
non-comment portion of the learned line is always displayed in
upper case.

E    Enter X again:

This duplicates X and Pushes it onto the stack. E E E will fill the
stack with X.

ECHO Echo input to output, toggle on/off:

RPNMI allows for commands to be input from a disk file instead of
the operator's keyboard. Also, the output can be directed to a disk
file instead of the operator's console. This is done by entering at
the DOS command line the following:

     A>RPNMI in-file-name >out-file-name

Either or both fields may be present. When ECHO is off the input
commands are not sent to the output file. Normally ECHO should be
turned on with the first command of an input file.

EX   Execute learned line:

This will cause the learned line to be executed once if there is no
EX command in the learned line. Having LRN and/or EX in the learned
line can produce interesting results. A simple case is a normal
learned line with EX as its last command, this will cause the
learned line to be repeatedly executed until the ESCAPE key is
pressed.

EXX  Execute X times:

This will Pop X and cause the learned line to be executed X times.
X must be in the range 0 <= X <= 65535.

I    Interchange X and Y:

Pop X, Pop Y, Push X, Push Y.

L    Last X:

On all arithmetic operations (!, %, *, **, +, -, /, B, R, RR, and
S) the value of X is saved in LASTX, The L command retrieves LASTX
and Pushes it onto the stack. This is quite useful in undoing an
operation performed by mistake. It is one of the features that
makes an RPN calculator desirable.

LRN  Learn: 

This command stores all of the commands following on the same line
as this one into the learned line. Execution of the current line is
stopped. This line as well as all command lines are limited to 256
characters. Type the learned line:

     LRN (Y) N= 1 2 LRN 1 C SP D "! = " 1 SP * D L 1 + EX

and then do two separate EX commands. You might want to key in a
control-P after the second EX command just before you hit return to
turn your printer on. This will print a table of factorials from 2!
to 450! or so, if you wait long enough. Hit the ESCAPE key twice to
interrupt and abort the operation if you get tired of waiting.

N=   Don't display = sign:

Normally displayed results are preceded with an = sign. This is
handy so you can tell when a calculation is complete and the
display conversion is being done. Aborting a display conversion
with the ESCAPE key will not affect the value computed. If the =
sign is not desired, the N= command can be given.

OFF  Exit back to system:

The program exits back to the operating system.

ON   Reinitialize:

This totally reinitializes the program, the same as reloading from
disk. Similar to the ? command except the base is reset to ten.

R    Square Root:

X is replaced with the integer portion of the square root of X.
Since this is an integer calculator, the fractional portion of the
square root, if any, is lost. If X is a perfect square, it is
replaced with its exact square root. If X is not a perfect square,
it is replaced with the square root of largest perfect square less
than X.

R1   Recall memory register 1:

Besides the stack and last X there are two memory registers that
can hold any integer that can be generated by this program. The R1
command will push the contents of the first of these registers onto
the stack.

R2   Recall memory register 2:

The  R2 command will push the contents of the second memory
registers onto the stack.

RMB  Recall Modulo base:

This calculator can be set to perform all of its calculations in
modulo arithmetic. This is done by setting the modulo base to an
integer greater than zero (see the SMB command). The RMB command
will push the current value of the modulo base onto the stack.
Normally a number equal to the modulo base will be displayed as
zero, an exception to this is made when the RMB command is
executed.

RN   Generate a random number < modulo base or 80 bits:

If a modulo base greater than zero is set a random number between
zero and the modulo base will be generated and pushed onto the
stack. If no modulo base is set a random number between zero and 2
** 80 will be pushed onto the stack. Theoretically the random
number generator will cycle after 2 ** 80 numbers, but the earth
will not last that long.

RR   Y = X ** 0.5, X = Remainder:

Pop X, find both the square root and remainder of X, Push the root,
push the remainder. The remainder is defined in such a way that the
root squared plus the remainder is always the original number. This
can be used to test and to find perfect squares. The square root
remainder of a perfect square is zero. It is true that the
remainder will never be larger than twice the square root, and this
extreme case exists when X is one less than a perfect square.

RRN  Recall random number or seed:

As random numbers are generated an 80 bit random number is kept and
used as the basis for the next random number. The RRN command
pushes this value onto the stack. The value can be recorded at the
end of a session and reentered with the SRN command at the
beginning of a new session. This will prevent the same random
number from ever being reused. The value will be displayed with its
full value even if it is larger than or equal to the modulo base.

S    Square:

X is replaced with the square of X.

S1   Store X in memory register 1:

Besides the stack and last X there are two memory registers that
can hold any integer that can be generated by this program. The S1
command will set the contents of the first of these registers to X.
X remains unchanged.

S2   Store X in memory register 2:

The S2 command will set the contents of the second memory registers
to X. X remains unchanged.

S<>  Stop if X <> 0:

This command is useful in the middle of a learned line that is
going to be executed repeatedly. It will cause the execution to
stop if X is not zero.

S=   Stop if X = 0:

This command is useful in the middle of a learned line that is
going to be executed repeatedly. It will cause the execution to
stop if X is zero.

SG   Set digits per group for output display of X:

The SG command will set the number of digits per group to the
current value of X, and then X popped off the stack. If this is set
to 5, numbers will be displayed with a comma after every 5th digit
like 12,34567,89000. If this is set to zero, 1, or 2 no commas will
be displayed.

SMB  Set Modulo base to X, X = 0 => no Modulo base

This calculator can be set to perform all of its calculations in
modulo arithmetic. This is done by setting the modulo base to an
integer greater than zero. The SMB command will set the value of
the modulo base to the current value of X.

SP   Set spacing value, -1...3:

Pops X and uses it to set the spacing value. The spacing value is
initialized to two on start up which causes all output to be double
spaced, one will cause single spacing, 0 causes a single blank
character between outputs, and a -1 causes no space at all.

SRN  Set seed for random number to X:

The SRN command stores the absolute value of X into the seed of the
random number generator. As random numbers are generated an 80 bit
random number is kept and used as the basis for the next random
number. The value can be recorded using the RRN command at the end
of a session and reentered with the SRN command at the beginning of
a new session. This will prevent the same random number from ever
being reused. X remains unchanged.

U    Rotate stack up   (X -> Y -> Z -> T -> X):

This is the same as a Push X except that T is also placed on the
bottom of the stack and no stack items are lost.

V    Rotate stack down (X <- Y <- Z <- T <- X):

This is the same as a Pop X except that X is also placed on the top
of the stack and no stack items are lost.

Y=   Display = sign:  (Note: Y stands for Yes not Y register)

Normally displayed results are preceded with an = sign. This is
handy so you can tell when a calculation is complete and the
display conversion is being done. Aborting a display conversion
with the ESCAPE key will not affect the value computed. If the =
sign is not desired, the N= command can be given. When the = sign
is again desired the Y= command is used.


Report any errors by writing me or call me at my home voice phone
(408) 741-0406 evenings or weekends.


                                   Harry J. Smith
                                   19628 Via Monte Dr.
                                   Saratoga, CA 95070
