;
                                               
                               ---  H P  ---          
                                               
                                Version 1.4

                Programmer's Integer RPN Calculator for ZP


                         O -->  Overview           
                         H -->  Invoking HP        
                         D -->  Display Modes      
                         S -->  Stack              
                         E -->  Entering Numbers   
                         F -->  Math Functions     
                         M -->  Memory Registers   
                         N -->  RPN Notation     
                         Z -->  ZP               
:O                       
 Overview 

HP is a simple and very useful programmer's integer calculator modeled 
after a Hewlett-Packard calculator with RPN notation.  

HP can operate in any of four display modes:  hexadecimal, decimal, binary, 
and character, making it very useful for quickly converting integer numbers 
from one base to another.  It can do integer addition, subtraction, 
multiplication, division, exponentiation and bitwise logical AND and OR 
operations.  It has a 4 level stack and 6 memory storage registers.

All HP internal storage and arithmetic is unsigned 16 bit.  Thus 65537 
becomes 00001, -1 becomes 65535, and so on.  Multiplication and 
exponentiation overflow and division by 0 will generate errors.  In binary 
and character modes, the display shows only the lowest 8 bits of 16, so 8-
bit overflow does not usually cause an error.

If you are not familiar with RPN notation, see the section on RPN notation,
which also has more detail on how HP uses its stack during stack and 
numeric operations.
:H
 Invoking HP 

Use ^C to invoke HP.  It will display its single operating line and wait 
for your input:

               H>     0000

The 'H>' indicates hexadecimal display mode (the default display mode), and 
'0000' is the four digit hex calculator display of register X, which is the 
register always displayed.  The HP stack and memory are initialized to zero 
when ZP is first loaded into memory.

 Exiting HP 

Use ^C to exit HP and return to ZP.  When you use ^C to rerun HP, you will 
return to it just where you left off. 
:D
 Display Modes 

HP can operate in any of four display modes:  hexadecimal, decimal, binary, 
and character, making it very useful for quickly converting integer numbers 
from one base to another.  To change display modes, enter the escape <ESC> 
key followed by the first letter of the desired mode.  Either upper or 
lower case letters may be used to select the mode.  The display indicates 
the current mode, and the number in the X register will be displayed in the 
current mode.  You may translate numbers from one base to another by simply 
changing display modes.
 Hex Display Mode 

To select the hex display mode, enter <ESC>H.  In hex mode, numbers display 
as four hex digits from 0000-FFFF.

 Decimal Display Mode 

To select the decimal display mode, enter <ESC>D.  In decimal mode, numbers 
display as five decimal digits from 00000-65535.

 Binary Display Mode 

To select the binary display mode, enter <ESC>B.  In binary mode, the least 
significant byte of the number displays as 8 binary digits from 
00000000-11111111.
 Character Display Mode 

To select the character display mode, enter <ESC>C.  In character mode, the 
least significant 7 bits of the number display as an ASCII character.  
Control characters are indicated by a '^' prefix.  For example, 03H will 
display as '^C' and DEL (7FH), will display as '^?'.

All non-command characters can be directly entered as data in the character 
display mode.  Characters that have command functions such as 'L', '/', 
'=', ^C, <RET> (^M), etc, can be entered as data in the character mode by 
prefixing them with the <ESC> character.  See the section on Entering 
Special Characters for more information.
:S
 Stack 

The structure of HP's 4 level stack is shown below:

               T -> 0000      Stack register 4
               Z -> 0000      Stack register 3
               Y -> 0000      Stack register 2
               --------------------------------------------
               X -> 0000      Stack register 1 <- Displayed

HP always displays the contents of the X register and all values entered 
are entered into the X register.  When a number is entered into the X 
register, the previous contents of the X register are automatically moved 
up to the Y register, the previous contents of the Y register are moved up 
to the Z register, etc.  

See the file HP-RPN.HLP for more detail on how HP's functions affect the 
stack registers.
 Entering a Number 

<RET> lifts the stack, pushing the number in register X into register Y.  
The number being entered is then placed in register X.  Stack lift is 
disabled.

 Clearing the Stack 

You can clear the entire stack with Control-X (^X) at any time.  Memory and 
Last-X registers are not affected.

 Exchanging X and Y 

You can exchange the contents of the two lowest stack registers X and Y 
with the '=' function (X<>Y).  No other registers are affected.  This 
function is useful when you need to reverse the order of operands before 
performing a function sensitive to operand order such as subtraction, 
divison or exponentiation.
 Last-X 

When a numeric function is executed, a copy of the last value in the X 
register before the function is executed is saved in the Last-X register.  
That value can be restored to  the X register using the 'L' (or 'l') key.  
The stack is lifted, pushing the current contents of the X register to the 
Y register, etc, unless stack lift has been disabled by the <RET> or 
backspace key.  The value in the Last-X register is not affected.  The 
Last-X function saves you from having to reenter numbers you wish to use 
again and can assist you in error recovery.

 Stack Roll 

You can roll the stack by using '>' (or the unshifted equivalent '.') to 
roll it up one level and '<' (or ',') to roll it down one level.  When the 
stack is rolled up, the contents of all stack registers are moved up one 
level and the value in the top stack register is moved down to the X 
register.  When the stack is rolled down, the contents of all stack 
registers are moved down one level and the value in the X register is moved 
up to the top stack register.  No stack values are lost as a result of 
stack roll operations.
:E
 Entering Numbers 

Invoke HP and try entering the following sequence of keys:

               ^X  <ESC>D  1 <RET>  2  +  4  *

You have cleared the stack, selected the decimal mode, entered the decimal 
numbers '1' and '2', added them, entered '4' and multiplied 4 times the 
previous result.  The display should show '00012', which is (1+2)*4.

Your <ENTER> or <RET> key corresponds to the HP <ENTER> key.  It is used to 
separate two numbers as they are being entered one after the other or to 
copy the number in the displayed X register into the Y register.  You 
normally key in a string of digits, then press <RET> to enter the number in 
the displayed X register.  You do not need to use <RET> after every number 
entry, however, as the use of the function keys also automatically 
terminates digit entry.

Depending on the current display mode, a maximum number of digits can be 
entered into the display, after which the leading digits will begin to be 
discarded.  HP accepts a maximum of four digits in the hex display mode, 
five digits in the decimal display mode, eight digits in the binary display 
mode and one digit in the character display mode.  The console bell will 
ring if you enter a character that is not acceptable in the current display 
mode.

 Correcting Entries 

The backspace key (^H) works like the left arrow '<--' key on an HP 
calculator.  It has two functions.  During digit entry, it will delete the 
last digit typed.  Otherwise it will clear the X register and leave the 
stack lift disabled.
 Entering Special Characters 

The <ESC> key may be used as a prefix in the character display mode to 
allow you to enter as a digit those characters that would otherwise be 
interpreted by HP as calculator functions:

                       +-*^/&|~=lLsSrR<>.,

as well as the control characters ^X, ^C and <RET> (^M).

To enter the character 's', for example, enter '<ESC>s' instead of 's', 
since entering 's' initiates a store to a memory register.
:F
 Math Functions 

HP's integer numeric functions and the keys to invoke them are:

     +    Addition, X=Y+X 
     -    Subtraction, X=Y-X 
     *    Multiplication, X=Y*X 
     ^    Exponentiation, X=Y^X  (Y to the Xth power) 
     /    Integer quotient, X=INT(Y/X)  
               - Remainder Register R=X*(Y/X-INT(Y/X)) 
     &    Bitwise AND, X=Y&X 
     |    Bitwise OR, X=Y|X 
     ~    Negation [2's complement], X=~X

Negation affects only the X register.  The other operations use the numbers 
in the first two registers X and Y as operands, and display the result in 
the X register, dropping the stack.

When an integer division is performed, you are often interested in both the 
quotient and the remainder.  The remainder is saved in the special reserved 
memory register R during the division operation.  Memory register R may be 
accessed just like any of the regular memory registers 0-5.  It may also be 
used to store numbers like any other register, but any contents will be 
overwritten by the remainder during integer division operations.

The console bell will ring if an undefined key is pressed as an operator.  
It will also ring and the current multiplication (*), division (/) or 
exponentiation (^) function will not operate if 16-bit overflow occurs or 
if division by 0 is attempted.  The stack is left unchanged.  Use the 
backspace key to delete the offending operand if you wish to try again.
:M
 Memory Storage Registers 

There are 6 memory storage registers numbered 0-5 that may be used to store 
constants or intermediate values during calculations, for recalled as 
needed later.  The contents of memory registers are not affected by the 
clear stack (^X) operation.  Either upper or lower case letters may be used 
to specify memory register Store or Recall functions.

 Storing a Number 

The number in the X register may be stored in any of the memory registers 
using the command 'S' followed by the number of the desired memory 
register.  The previous contents of the memory register will be 
overwritten, but the number in the X register will not be affected.  For 
example, to store the number in register X in memory register 2, enter 
'S2'.  
 Recalling a Number 

Numbers may be recalled from a memory register to register X using the 'R' 
command followed by the number of the memory register.  The stack will be 
lifted, pushing the previous contents of register X into register Y, but 
the number in the memory register will not be affected.  For example, to 
recall memory register 0 to register X, enter 'R0'.

 Remainder Register  

An additional special memory register R is used by the division operation 
to store the remainder.  It may also be used to store and recall numbers, 
but any contents will be overwritten during a division operation.  The 
command 'RR' (Recall Remainder) after a division operation will store a 
copy of the remainder in register X and push the quotient to register Y.  
An exchange (=) operation will swap them if desired.  
:N:ZP-RPN.HLP
:Z:ZP.HLP
