Introduction

This is an attempt at creating a coding standard for FOCAL (FOrty-one CALculator language). It’s purpose is to make HP-41 programs structured, easily managed and offer a standard user interface.

Overview

An HP-41 program contains a “header”, a “body” and a “footer”.

The header contains the program version, main global label, program initialisation (setting variables and flags, pointer to extended memory file etc.) and the main menu.

The body contains the main parts of the program organised under each local alpha label in this sequence: A,a,B,b,C,c,D,d,E,e and F,G,H,I,J if needed.

The footer contains subroutines used by several parts of the program body.

It is advisable to modularise a program so that any part that can be separated is made a module. A module does not necessarily contain a header or footer. It stands on its own but is used by the main program as a global subroutine. In this way, it can also be used by other programs. A module can be optional thus freeing program space.

If you have several modules with related functionality, group them into a library. A library has one main lable (like LIBXM for a library of extended memory functions/modules) and then one global label for each function.

Header

The header serves three purposes. First is the program version – simply entered as an alpha string without any AVIEW or PROMPT and just for reference. The second purpose is to initialise the program; Store initial values to registers, clear stack and/or registers, set or clear flags, set pointer to correct extended memory file, any useful initial functions etc. The third purpose is to show the menu for the top keys. First is the menu for the keys A-E, then the keys a-e and if needed, the menu for the keys F-J. Ideally the menus should cover the whole display, no more, no less and as evenly spread out as possible so that each menu option shows above its key.

Example header:

001 *LBL "EXAMPLE"
002  "V:0.3"    	    (program version)
003  "SAMPLE"	    (pointing the program to an XM file)
004  0
005  SEEKPTA
006  SF 27		    (activate USER mode)
007  LBL e		    (using LBL e as initiating/menus is good)
008  "+ - * / EXP"	    (A-E menu - abbreviations for mnemonics)
009  PROMPT
010  "% T% %CH"	    (example for shifted top row menu) 
011  PROMPT
012  GTO e		    (return to top of header)

Body

The program body is only the labels A-E/a-e + F-J and their local labels (those labels belonging to each local alpha-label). The number scheme for the local subroutine labels under each alpha label goes like this:

LBL A	20-24
LBL a	25-29
LBL B	30-34
LBL b	35-39
LBL C	40-44
LBL c	45-49
LBL D	50-54
LBL d	55-59
LBL E	60-65
LBL e	65-69
LBL F	70-74
LBL G	75-79
LBL H	80-84
LBL I	85-89
LBL J	90-94

This leaves label numbers 00-14 for various short jumps, label numbers 15-19 for header subroutines and 95-99 for the footer subroutines.

It is important that all routines returns to the header or a local alpha label as its last step (after it stops). In this way, the user will not end up in a wrong place if he or she presses R/S after a routine comes to a stop.

Footer

The footer contains the subroutines used by several parts of the body. It also contains any parts that does not naturally fit elsewhere. These are labels integral to the program and not really useful as separate functions/modules with their own global labels.

Other dos and don’ts

• Keep the program structured and tight. Be clever and save memory, but do not engage in spaghetti programming where you use to much branching into and out of program parts.
• Decide on who the user is. Only use functions you know the user will have use for.
• Specify the requirements for the program clearly (i.e. “needs PPC rom”).
• Make good user documentation showing clearly the key mapping (what each local alpha label does).

Short form exeption

When a program is short (less than 100 lines) it can be advisable to do away with the overhead of showing version number and returning to an initiating label.