================================================================= H P Programmer's Integer RPN Calculator Copyright (c) 1989-91 by Terry Hazen 21460 Bear Creek Road Los Gatos, CA 95030 Voice.......... (408) 354-7188 Zee-Machine.... (408) 245-1420 Ladera Znode... (213) 670-9465 HP14 is released for personal, non-commercial use only. Any commercial use of HP14 where the user receives revenue by duplicating or distributing HP14 by itself or in conjunction with any hardware or software product is expressly prohibited unless authorized in writing by the author. All rights reserved. Latest Revision --------------- Version 1.4 - 02/08/91 For revision history, see HP14.Z80 ================================================================= Overview -------- HP is a simple and very useful programmer's integer calculator modeled after a Hewlett-Packard calculator with RPN notation. It has been extensively upgraded from Eric Meyer's original HP10 as a ZCPR3 utility and enhanced to reduce code size, to increase the number of memory storage registers, to add stack roll and last-x functions, to improve the user interface and to improve input error trapping. HP is provided in several forms: HP.COM, HP.4OM (a type 4 utility for use under ZCPR3.4+), and HPVID.COM (a full- screen VLIB4D+ line graphics version that displays all memory and stack registers). HP is also provided as HPRSX.COM (installs an RSX version) and HPIOP.COM (installs an NZCOM IOP version). See the HP RSX/IOP section for more specific information on the RSX and IOP versions. If you are not familiar with RPN notation, you should review the file HP-RPN.WS for more information on RPN. HP-RPN.WS also has more detail on how HP uses its stack during stack and numeric operations as well as several calculation examples. 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. Installation ------------ Operation in ZCPR3.3+ environments requires no installation. When operating in ZCPR3.0 environments, install the program using your normal method. HP, HPRSX and HPIOP may be configured using ZCNFG.COM and the configuration files HP.CFG, HPRSX.CFG and HPIOP.CFG, respectively. The default CFG filenames may be changed, if desired. In HPRSX and HPIOP, the HP initiation character, ^@ (0h) in the distribution versions, may also be changed. Running HP ---------- When you invoke HP, it will display its single operating line (shown here for HP.COM) and wait for your input: A0>hp HP 1.4 (Type 3 at 100h) 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 HP is first loaded from disk. See the section on the HP RSX/IOP for information on invoking the HP RSX or IOP. Exiting HP ---------- Use control-C (^C) to exit HP. If you are using HP.COM, the type 3 version loading at 100H, you may use the ZCPR3 'GO' command after exiting HP and before any other command is executed and you will return to HP exactly where you left off. Changing 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 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 H. In hex mode, numbers display as four hex digits from 0000-FFFF. Decimal Display Mode: To select the decimal display mode, enter D. In decimal mode, numbers display as five decimal digits from 00000-65535. Binary Display Mode: To select the binary display mode, enter B. In binary mode, the least significant byte of the number displays as 8 binary digits, 00000000-11111111. Character Display Mode: To select the character display mode, enter 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, (^M), etc, can be entered as data in the character mode by prefixing them with the character. See the section on Entering Special Characters for more information. The HP 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.WS for more detail on how HP's functions affect the stack registers. Entering a Number: 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 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. Entering Numbers ---------------- Invoke HP and try entering the following sequence of keys: ^X D 1 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 or key corresponds to the HP 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 to enter the number in the displayed X register. You do not need to use 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 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 (^M). To enter the character 's', for example, enter 's' instead of 's', since entering 's' initiates a store to a memory register. Numeric 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. 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. HP RSX ------ The utility HPRSX loads a CP/M 2.2 resident system extension (RSX) version of HP that allows the calculator to remain installed in memory and always available for use, even within another program. HPRSX will run on any ZCPR3 system using a Z80- equivalent processor. The HP RSX is based on the Plu*Perfect CP/M 2.2 RSX standard developed by Bridger Mitchell and described in his column in The Computer Journal issue #34, p30. It will interface correctly with RSX's that have been designed to the same standards, such as DateStamper and the ZSDOS LDTIM RSX. If you are using HPRSX with other RSX's, you must determine for yourself whether they are compatible with HPRSX. When installed, the HP RSX occupies less than 1400 bytes of RAM just under the CCP or the last installed RSX, and is protected from being overwritten by transient programs. If you attempt to install it more than once, an error message containing the current HP RSX load address will be displayed. The HP RSX can be invoked for use at any time, even from within another program, by entering a user-selected 'intercept' character. The distribution default is ^@ (00h). The HP RSX has 'continuous memory'. It is initialized when first loaded to memory. Each time you later return to the HP RSX, the stack and memories will remain exactly as you last left them. If you no longer need the HP RSX and wish to recover the memory it occupies, you can use HPRSX to remove it from memory, provided that it is currently the bottom RSX. It can also be removed with a cold boot (reset). If you try to remove the HP RSX when another RSX is installed below it, an error message will be displayed. HP IOP ------ The utility HPIOP loads an IOP version of HP that, like the RSX version, allows the calculator to remain installed in memory and always available for use. The HP IOP operates in the same manner as the RSX version except that it resides in the NZCOM NZIOP buffer. The HP IOP uses only the memory allocated to the NZIOP buffer, usually 12 records (600H), while the HP RSX also protects the CCP and reduces the TPA by the RSX size plus the CCP size. If you no longer want the HP IOP active, you can use HPIOP [/]R to deselect (remove) it. It can also be removed by a cold boot (reset) or by loading any other IOP. RSX/IOP Syntax -------------- HPRSX and HPIOP syntax are the same. The example is for HPRSX: A0>HPRSX - Install the HP RSX module A0>HPRSX [/]R - Remove the installed HP RSX module A0>HPRSX // - Display HPRSX HELP screen When the HP calculator RSX module is installed: ^@ - To invoke the calculator ^C - To exit the calculator RSX/IOP Operation ----------------- Except for the additional WRITE function decribed below, the HP RSX or IOP calculator is used just like HP.COM. It works by watching the BIOS CONIN calls for character input from the keyboard. If it sees the intercept character, it invokes the HP RSX calculator, which starts its display at the beginning of the current cursor line. You may patch HPRSX and HPIOP to change the intercept character as described in the section on RSX/IOP Modifications. Unless the WRITE function is invoked, the HP RSX/IOP display is only overlaid on the screen and does not become part of the program from which it was called. When you exit the calculator, the HP RSX/IOP display, which consists of the first part of the current cursor line, is cleared, leaving the cursor at the beginning of the cleared HP RSX/IOP display. You are returned to EXACTLY where you were in the program you were running, which doesn't know that it has been interrupted and is still expecting input from you. After you exit the calculator, you may need to refresh the screen to recover the correct text display in the cursor line. If the cursor is located on a blank line when you invoke the HP RSX/IOP, as is the case with ZPATCH, no screen refresh will be needed when you exit. In any case, however, normal activity in the program you are running should soon refresh the line partially cleared by the HP RSX/IOP display. In a text editor, for example, the partially cleared HP RSX/IOP display line will be replaced by the text that's really there when you shift the screen display up or down, to move the partially cleared line off the screen, or when you move text around, covering the partially cleared line. The HP RSX/IOP may produce unexpected effects in programs that use memory-mapped video. However, these cosmetic differences shouldn't interfere with use of the calculator, or with normal editing. When you exit the HP RSX/IOP after invoking it from the command line, the cursor will be left in place at the beginning of the cleared HP RSX display and the CCP will still be expecting you to enter your desired command line just as it was when you invoked the HP RSX. Entering a will move the cursor to the next line complete with a new command prompt, but this isn't really necessary. RSX/IOP WRITE Function ---------------------- To allow you to copy the results of a calculation into another file, the HP RSX/IOP calculator has an additional WRITE function not found in HP.COM. When you invoke the HP RSX/IOP calculator from within a program such as WordStar and select the WRITE function by pressing the 'W' (or 'w') key, the current numerical calculator display, including any leading zeros but not the mode letter, will be copied into the host program STARTING AT THE POSITION OF THE CURSOR IN WHEN HPC WAS INVOKED. When you invoke the HP RSX/IOP from the command line and use the WRITE function, the numerical calculator display will be copied to the command line. Your host program will treat the characters in the HP RSX/IOP display just as if they had been entered via the keyboard at the current cursor position. Normally, the copied HP RSX/IOP display will overwrite any existing characters. If your host program is in an 'Insert' mode, the HP RSX/IOP display will be inserted into the existing text at the current cursor position. For best results, position your host program cursor and set the proper host text entry mode before you enter the HP RSX/IOP calculator to use the WRITE function. RSX/IOP Applications -------------------- When you are examining a file using DDT, ZPATCH, or other debugger, the HP RSX/IOP is very handy for calculating offsets, addresses, etc. For example, when at the DDT command prompt, you can enter the DDT 'd' command, invoke the HP RSX/IOP to calculate the starting address for the next display, use the HP 'w' command to write the address to the DDT command line, use the HP ^C command to exit HP and then enter a to end the DDT command. DDT will then start it's next display with the address you specified. While HP.COM can be run from ZPATCH using the 'Z' command, the RSX/IOP versions are much faster, since it doesn't require loading or reloading ZPATCH and the file being examined. It also maintains the register contents for later use. Note that the HP RSX/IOP aren't needed when running ZP, as ZP already contains the HP calculator. The HP RSX/IOP is also very useful when you are using WordStar, ZDE or another text editor to write programs or documentation. You can use it for doing calculations and also for converting numbers to different bases. If you wish, you can use the WRITE function to bring the results of your calculations right into your text. Since the HP RSX/IOP is only initialized when it is first loaded and subsequently retains all data between the times it is accessed, it can also be used as a note pad to store data that you want available later, perhaps from within a different program. For example, while you are viewing a LST or PRN file, you can store label addresses to be used later when you are writing documentation. You can copy the contents of any of the registers into your host program by moving them to the displayed X register using the RECALL or STACK ROLL functions. You can then use the WRITE function to copy the HP display to your host program. If you aren't going to use the WRITE function, remember to try to invoke the HP RSX/IOP with the cursor on a blank line, if possible, to eliminate the need for screen refresh when you exit HP. If you are planning on using the WRITE function, position the host program cursor where you want the display to appear before you invoke the HP RSX/IOP. Acknowledgements ---------------- HP is based on HP10, copyright (c) 1984 by Eric Meyers, and was upgraded with his kind permission. Eric's many contributions to CP/M include the famous Video Display Editor (VDE), recently upgraded to the amazing ZDE by Carson Wilson. Inspiration for the upgrades was provided by articles in The Computer Journal by Hal Bower and Cameron Cotrill on ZSDOS and Lee Hart on Programming for Performance as well as Bridger Mitchell's columns on Advanced CP/M (including his columns on relocation and CP/M 2.2 RSX's) and Jay Sage's ZCPR3 Corner columns on the Z-System (including his column on PRL files). The later availability of Al Hawley's great ZML linker allowed HP 1.4 to be upgraded to a ZCPR3 utility that can be configured at assembly time to produce type 3 or 4 REL files that can be linked to make type 3 or 4 utilities, and RSX and IOP PRL files that can be used to make RSX and IOP versions of HP using a new RSXLDR loader module. Bridger Mitchell's standard CP/M 2.2 RSX header and Joe Wright's standard IOP package structure provided the basis for the RSX and IOP versions of HP. =================================================================