HP-41 binary calculator with page 4 library

The binary calculator manipulates numbers that are interpreted as binary numbers, which are bit strings of certain length.

The numbers are entered and kept in the HP-41 stack as normal decimal numbers or, optionally and when the word size allows, as hexalpha numbers, i.e. hexadecimal characters as Alpha data. The word size (maximum 32 bits), active sign mode (signed or unsigned), active base mode (decimal, binary, octal or hexadecimal), output mode preference (decimal or hexalpha), and carry and overflow flags reflecting the result of the last calculation are kept in user flags 00 to 10.

The binary calculator can be used as an interactive program, which has its own keyboard, or by executing programmable XROM functions.

The binary calculator program is coded entirely in MCODE. A significant part of its implementation is in page 4 – for speed and easyness of programming. The page 4 library part khp4lib of the program can also be used by MCODE programmers as a library of useful subroutines.

The program has been developed and tested in a SY-41CL but no specific CL instructions have been used, so if you have means to store the two program images and use page 4 appropriately for the library image, you can use the program also in any model of HP-41.

Both ROM images and their source code (in KHP-41 assembly language, partially commented) are available on this page.

Copyright © 2019 Kari Pasanen

Contents

Revision history

Binary images

This 4k image must be put in page 4:

khp4lib.rom

This 4k image can be put in any page from 8 to F, like a pluggable ROM module, but you must have the page 4 library in place to use it:

khpbin.rom

This MOD file, containing both images, can be used in some MLDLs and in the V41 emulator:

khpbin.mod

Source code

KHP-41 assembly source of the page 4 library:

khp4lib.a41

KHP-41 assembly source of the application ROM:

khpbin.a41

Compiling

If you wish to compile the source code yourself, you can do it with the asm41 program.

For assembly you need this HP-41 mainframe entry points include file:

sysrom.i41

The following files, in addition to the .rom object files, are results of assembly (listing files and include file of khp4lib entry points):

khp4lib.x41 khp4lib.i41 khpbin.x41

Additional features

Page 4 was reserved by HP for the Service Module, which is a take-over ROM. There are calls in the HP-41 operating system code to the beginning of page 4. These calls have now been taken in use for benefit: The binary calculator doesn't wait key presses in an active loop but instead allows the calculator to go into light sleep. When a key is pressed, the operating system calls the Service Module entry point, which returns the control to the binary calculator.

In addition to the implementation of the power-saving trick the beginning of the page 4 library contains a code sequence which solves a problem with the Time Module Clone of Systemyde International, the first one described here, by consuming enough time in a loop executed when the calculator wakes up from light sleep. No Flash image update is needed in a SY-41CL; the added wake-up time is meaningless in other calculators where it isn't needed.

Usage

The binary calculator can be used in two ways:

Also BIN itself is a programmable function. It can be used in a program to receive a binary number as input from the user.

Interactive keyboard

Keyboard map

This keyboard map shows the assignment of HP-41 keys within the interactive binary calculator program BIN. The keys work in the following ways:

When you press a function key, the name of the function on that key is displayed until you release the key, then the function is executed. If you press the key down long enough, the function name is NULLed and no function is executed.

Modes display

When the interactive binary calculator is entered or when the base mode, sign mode or word size is set or viewed – by a specific key within the BIN program or by an XROM function, but not in a running program, – the active modes and word size are displayed in the format

BAS-X-WS=nn

where

The modes display is a message that can be cancelled by pressing the backarrow key <- to view the X register contents.

When a program executes BIN, the modes display is shown only if there wasn't a message in display. If there was another message, it is allowed to stay. This feature can be used to prompt the user about what input is expected.

Binary numbers in display

When displayed in the interactive binary calculator or viewed by the BVIEW function, numbers appear right-justified in the display and in the following forms according to the active sign and base mode:

Binary numbers in stack

The inputs for and outputs from binary calculator functions can appear in the stack in the form of decimal numbers or hexalpha numbers.

Decimal input is the standard way of input. When you work outside of the BIN program, take care of the limits implied by the active sign and base mode.

Hexalpha input is always an option. Any character has an interpretation in hexalpha input, so no errors will result from "illegal" characters. The interpretation rules for character ab (hexadecimal value) are: When a is in the set {0, 1, 2, 3, 8, 9, A, B} take b as the value of the character. Otherwise take (b + 9) mod 16 as the value. Limits should be followed also with hexalpha input.

Decimal output is the standard way of output.

Hexalpha output is activated when flag 05 is set and the word size is at most 24. Numbers output in hexalpha format don't include a visible sign. Only true hexadecimal characters are used. The number of characters used is the minimum needed to represent all numbers within the active word size.

Binary numbers in Alpha register

Binary numbers appear in Alpha register only as input for function BANUM or as output from functions BARCLX and BARCLYX.

BANUM accepts always a sign, + or -, even multiple signs. An odd number of minus signs indicates a negative number. It also accepts any number of digit grouping characters ('.' when user flag 28 is clear, ',' when it is set) in any position of the number.

BARCLX outputs a sign when signed mode is active or when the input is a negative decimal number. BARCLYX outputs a sign when signed mode is active.

The first character after the optional sign string, as input for BANUM or output from BARCLX or BARCLYX, is the base indicator:

Reading of input by BANUM stops at the first character which couldn't be part of the number, as indicated by the base indicator if one is present. If BANUM finds a number in Alpha register that it can convert, it sets the numeric entry flag 22. Anything may be appended after a number representation in Alpha register, but only the number which is at the beginning is recognized as input.

BARCLX and BARCLYX append their output to the current contents of Alpha register.

BANUM and BARCLX don't take the active word size into account. They accept numbers up to 232 - 1 in absolute value.

The purpose of BARCLYX is to convert the output of function BSMUL (in signed mode) or BMUL (in unsigned mode) to readable form. It checks that both inputs, in Y and X registers, are within the range implied by the active word size. Output of BARCLYX is always in hexadecimal base [16].

Easy ways to do base conversions

Base conversion means only a change in how a number is displayed. The most obvious way to do the conversion from base 'a' to base 'b' is to use the interactive keyboard and key in the number while the active base mode is 'a' and then switch the mode to 'b'. Example:

BRESET BIN BINMODE 1101 HEXMODE <- displays HD.

You may also utilize the normal HP-41 operation mode in which binary numbers are displayed in decimal. Continuing with the previous example, exit the binary calculator by pressing ON, then you see the number 13. Continuing further:

BIN OCTMODE <- displays O15.

The example demonstrates that B1101 [base 2], O15 [base 8], HD [base 16] and 13 [base 10] all are representations of the same binary number but in different bases.

Setting user flag 05 changes the preferred output mode to hexalpha. This control by flag gives more options in doing base conversions where either the initial or target base is hexadecimal, but they work only when the word size is at most 24.

You can use the BNORM function to normalize the number in X, then you immediately see it in decimal or hexalpha according to the state of user flag 05, or the BVIEW function to normalize the number in X and to display it in the active sign and base mode, after clearing the display you see it in decimal or hexalpha. Alternatively you may just visit the BIN program and press the backarrow key <- to cancel the modes display. This does the same things as BVIEW.

The BANUM and BARCLX functions may be used to convert values between X register and Alpha register, with the benefit that Alpha register can hold longer values in binary base [2] than X register due to display limitations. BARCLX and BARCLYX accept hexalpha input. User flag 05 doesn't affect the output format of BANUM which is always decimal.

Binary calculator functions

General rules

XROM functions

The XROM module id of the khpbin ROM is 16. Nothing prevents you from changing it to whatever you choose.

All of the XROM functions are programmable.

Most of the function names begin with B, which isn't shown in the keyboard map or in the function name display. Function names that logically haven't the B prefix are STOWS, RCLWS, BINMODE, OCTMODE, DECMODE, HEXMODE.

In the function descriptions x means the contents of X register interpreted as a binary number, y means the contents of Y register interpreted as a binary number, and ws means the word size.

Interactive keyboard functions that aren't XROM functions

Technical information

Use of flags

User flags 00 to 05 are used in the following meanings:

Flags 00 to 04 have their indicators in the display.

User flags 06 to 10 code the word size. When all of them are clear, word size is 32 bits. Otherwise begin counting the word size from zero:

Sign modes

The sign mode affects basically only displaying the results, not what is allowed as input nor the results as such except that in signed mode logically negative results are, of course, output as negative numbers.

Input is generally interpreted neutrally: A positive number x and a negative number x - 2ws mean the same binary number which is simply a bit string. Negative input is allowed in unsigned mode, and positive unsigned input with the uppermost bit (the sign bit) set is allowed in signed mode. Internally in the binary calculator functions any input is first converted to a bit string; results are calculated as bit strings and then converted back to the format in which they are stored in the stack. The sign mode controls only the latter conversion.

There are specific functions where the input is always interpreted as signed and also the results should be viewed as signed numbers. To avoid confusion in interpretation of the results, signed bit shifts, multiplication and division (BSSHFR, BSSHFX, BSMUL and BSDIV) should be executed in signed mode. BARCLYX should be executed in the same sign mode as BSMUL or BMUL which gave the result to convert.

The interpretation of a hexalpha number as input for word size or bit number is independent of the active word size and thus unsigned. Hexalpha numbers can be used as input in functions expecting signed input; then the highest bit is interpreted as the sign bit.

In the interactive binary calculator you may key in negative numbers even in unsigned mode, but you should use the negative input immediately to avoid its normalization. Beware of that in unsigned mode the normalized value of a small negative number is a big positive number. Negative input values in unsigned mode are especially valid as bit numbers.

Number normalization

Before use in a function a function argument in stack is first made an integer discarding its fractional part. The absolute integer value is checked to fit in the active word size and converted to a bit string. Then, if the argument has negative sign, that bit string is negated. If the input is Alpha data, the conversion to a bit string is straightforward following the interpretation rules.

Functions that take a bit number argument behave differently in the input conversion as they preserve logically the original sign of the bit number even in unsigned mode.

The results are calculated as bit strings, masked to the word size, and finally put in the stack registers in the format controlled by the sign mode (user flag 04) and output mode preference (user flag 05).

Because only the original contents of X register is saved in LASTX register, the user cannot always know what the binary calculator thinks the given input means. If you want to check the interpretation of your input, you should normalize it before use in a function. This means doing the input conversion and the output conversion successively. To do it, call the BNORM or BVIEW function, or visit BIN and press either the backarrow key <- or the digit entry termination key . before exit.

In the interactive binary calculator you can use the digit entry termination key . to normalize the number that you have just keyed in. This may change its sign if you have entered a negative number while the active sign mode is unsigned.

Rules for carry and overflow

Carry flag is set in a function if the logically correct result of the calculation with unsigned values doesn't fit in the active word size.

Overflow flag is set in a function if the result of the calculation with signed values has the wrong sign. For example, when you add two positive numbers you would expect to get a positive number as the result. However, if you get a negative number, that means an overflow.

Functions that follow the basic rules:

Functions that generally clear carry and overflow flags but in special cases set one or both of them:

Functions that always clear carry and overflow flags:

Functions that don't change carry and overflow flags:

Functions on the interactive binary calculator keyboard that always clear carry and overflow flags:

Limits and errors

Rationale

Word size is limited to 32 by the HP-41 register size (56 bits) and the format of decimal numbers, as the stack is intended to be used for storage. Alpha data in stack allows only six hexadecimal characters, which means a word size of 24 bits. Also the display imposes limits for usable word sizes.

In order that the interactive binary calculator can be used with the least possible interruptions, setting of sign and base modes and word size is controlled and the results of functions are restricted to the proper range within the active word size. Thus a result, when it is displayed immediately after execution of a function, is never out-of-range.

However, when modes or word size have been changed after the number is produced, or when a number which isn't an output of a binary calculator function is tried to be displayed or used in a function, being out-of-range is possible for an input. This can happen even in the beginning of BIN program after clearing the modes display.

Action in error case

If an error occurs, the interactive binary calculator exits, or a running program stops except when the error ignore flag 25 was set – then only that flag is cleared. Setting flag 25 before execution of BIN isn't useful, because then at error the binary calculator program exits without a message.

Word size cutting

When the base mode, sign mode or word size is set or when the settings are recalled, the word size is checked against the active modes and, when necessary, cut to the maximum value that can be supported. The modes display indicates then what has really been set.

The maximum supported word size in different modes is as follows:

In the interactive binary calculator, keying in a negative number when unsigned mode is active changes the effective limit of number length to that of signed mode. During digit entry, when underscore ('_') is the rightmost character in display, still at least one more digit can be appended to the number, but no more when the underscore disappears.

Word size in Alpha register

As input in Alpha register for BANUM 32 bits are allowed because such values can be represented as decimal numbers.

The word size limit of BANUM and BARCLX imposed by the capacity of Alpha register is as follows:

The result of BARCLYX is always in hexadecimal base [16] and thus it fits in Alpha register.

Error messages

NO KHP4LIB
(All functions)
khp4lib image wasn't found in page 4.
DATA ERROR
(BSDIV, BDIV)
Attempted division by zero.
DATA ERROR
(STOWS)
Attempted to store zero word size.
TOO BIG NUM
(STOWS)
Attempted to store a word size greater than 32.
TOO BIG NUM
(BBIT, BSSHFX, BSHFX, BROTX)
A bit number greater than ws - 1 or smaller than -ws was tried to be used (ws is the active word size).
TOO BIG NUM
(Interactive binary calculator, All functions)
An out-of-range value was tried to be displayed or used in a function.

Bugs?

At the time of publication no bugs are known in the program. If you find some, please report them to the author who will make his best to republish a debugged program revision or add an explanation of a surprising phenomenon in this document.

License

This program is free software: you can redistribute it or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The full GNU General Public Licence text is available at http://www.gnu.org/licenses/gpl.html.

The attribution of this program to its original author must be preserved in any direct copy or modified version of this program. This is a supplement to the terms of the GNU General Public Licence version 3 allowed by them in section 7. Additional Terms, point b).

Author

The original author of this program is
Kari Pasanen, Jyväskylä, Finland,
Kari Pasanen <kari.pasanen@iki.fi>.

Feel free to propose additions of features to the binary calculator or routines to the page 4 library.