HP-15C: Programs

Version 4.5.00, Build 6308
© 2023 Torsten Manz
H E W L E T T · P A C K A R D 15C
A Simulator for Windows, Linux and macOS

# Programs

## PRGM mode

### Writing Programs

To write a program on the HP-15C, you must switch to PRGM mode. To enter PRGM mode, click g P/R or press F9 on the keyboard. The display format will change and the word "PRGM" appears in the lower right corner of the display:

You can now start to key in operations, as you would do in Run mode. The HP-15C will record the keys as you type them in but does not execute any function. HP-15C programs are more like macros than like `real´ programs.

All programs in this documentation use decimal comma style, i.e. the decimal separator is a comma and the thousands separator is a period.

Each program must begin with a label; valid labels are the letters "`A`" to "`E`" and the numbers "`0`" to "`9`" and "`.0`" to "`.9`". As an example, we will write a program that starts with label "`A`". Click f LBL A or key in F8 Q. This is the first program step and it is displayed like this:

Each key on the HP-15C is identified by a two-digit code that is derived from its position on the keypad. The first digit gives the row (starting at 1) and the second digit gives the column (where 0 means 10). For example, LBL is on the first key in the second row and therefore has the key code "`21`". Digit keys differ from that rule; the (single) digit itself identifies them.

The codes in a three-key sequence are separated by a digit separator. Codes in a two-key sequence are separated by blanks. There are also four-key sequences like STO + . 5, which adds the contents of the X-register to register 15. This sequence is displayed like this:

To complete the program, key in the following key sequence:

2 × 9 . 8 ÷ √x̅ g RTN

This little program computes the time it takes for an object to fall from a given height to the ground in the earth's gravity field. The gravitational acceleration is approximately `9.8 m/s2`.

In PRGM mode you can right-click the display to display the program popup menu. The full description of this popup menu can be found in the Pop-up Menu section.

To run the program you must switch back to Run mode. Click g P/R, or press F9, again.

In PRGM mode code in the Program File Format can be pasted from the system clipboard into the simulator using Ctrl–V or B3. The Mnemonic Converter also generates the correct format.

### Running a Program

To run a program you click the GSB key followed by the program label. Thus, GSB A will run the program that begins with LBL A. While a program is running, the display flashes "running":

On the Simulator, programs with an alpha label can also be run by clicking on the gold labels A through E, when Access 'f' and 'g' functions directly is activated in the preferences. Programs with numeric labels can only be run using the GSB key. In addition to that, the Simulator provides several shortcuts to run programs. See the Program (Run mode) section in the keyboard chapter for a complete list.

Any keystroke and any mouse click on a simulator key interrupts a running program. Mouse clicks outside of the keyboard area do not interrupt a program. You can for example move the simulator window on the screen while a program is running without interrupting it.

The GTO key can not be used to run a program. When the simualator is in Run mode, GTO A only positions the program pointer on the step with label "`A`", but does not run the program. To now run the program, click R/S or press F5.

◀ PRGM Mode ▲ Top

## Program Documentation

With the Simulator, you can add documentation to your programs, a feature not available on the real HP-15C. The documentation has no impact on the program itself. Documented programs are fully compatible with the real HP-15C.

### The Description Dialogue

To document a program, press F12 or select "Program description…" from the ON popup menu to open the program description dialogue box. The dialogue has the following elements:

- Program Title

  A one-line description of the purpose of the program.

- Usage

  A multi-line text field to describe the purpose of a program and how to use it.

  Preview mode
  In "Preview" mode, the description is rendered to give you an impression, how the HTML export will look like. You can not change the description while in "Preview" mode.

  When you open the documentation dialogue, the Preview mode is automatically activated when Automatic preview is activated in the preferences and the "Usage" field contains HTML tags.

  Edit mode
  The mode to add or change the program description. Standard editor shortcuts, like Ctrl–X, C, V and Z (undo) / Y (redo), are supported.

  There are different options, how to enrich the documentation with HTML tags or HP-15C specific CSS classes:

  - The toolbar below the text field
  - A popup menu accessible via right mouse button click
  - Using keyboard short-cuts (see table below)
  - and finally typing tags manually

  When the complete range of a tag is highlighted, e.g. "<bold>some text</bold>", applying the same tag again removes the tag (undo).

  When applying a list item tag, there are two options how the selected text is handled:

  - As one single list item: Button li / or the menu entry "List item"
  - Multiple list items separated by a new lines or hard breaks: Button li…li / or the menu entry "Multiple list items":

  Hard line breaks should only be used to structure the text, i.e. to insert an empty line. The layout of the final text should be checked by resizing the documentation dialogue in "Preview" mode. Empty lines at the end of the text are deleted when the documentation is saved.

  The following table lists the HTML tags and HP-15C specific classes supported in preview mode and the corresponding keyboard short-cut in edit mode. If more than one tag is listed, the keyboard short-cut will insert the first in the list.

  HTML tag | Short-cut | Description
  --- | --- | ---
  | Windows, Linux | macOS |
  <strong>, <b> | Ctrl–Shift–B | shift–command–B | Text conventionally styled in bold
  <em>, <i> | Ctrl–Shift–I | shift–command–I | Text conventionally styled in italic
  <pre> | Ctrl–Shift–P | shift–command–P | A block of preformatted text
  <sup> | Ctrl–Shift–S | shift–command–S | Superscript text
  <sub> | Ctrl–Shift–T | shift–command–T | Subscript text
  <ul> | Ctrl–Shift–U | shift–command–U | Unordered list of items
  <ol> | Ctrl–Shift–O | shift–command–O | Ordered list of items
  <li> | Ctrl–Shift–L | option–command–L | Represents a list item.
  <code> | Ctrl–Shift–C | shift–command–C | Code fragment, conventionally using a monospace font
  <h1>…<h6> | - | - | Headings 1 through 6 for the sections
  <a> | Ctrl–Shift–A | option–command–A | Represents a hyperlink. When the selected text is a valid URL, it is set as value of the "href" attribute.
  HP-15C CSS class |  |  |
  HP15CRegister | Ctrl–Shift–R | shift–command–R | Registers, e.g. X
  HP15CKey | Ctrl–Shift–K | shift–command–K | Primary HP-15C key functions,e.g. SST
  HP15CfKeyLabel | Ctrl–Shift–F | shift–command–F | Gold alternate HP-15C key functions,e.g. LBL
  HP15CgKeyLabel | Ctrl–Shift–G | shift–command–G | Blue alternate HP-15C key functions, e.g. BST
  HP15CfKey | Ctrl–Alt–F | options–command–F | Gold prefix f-key f
  HP15CgKey | Ctrl–Alt–G | options–command–G | Blue prefix g-key g

  Additional keyboard short-cuts in Edit mode:

  Short-cut | Description
  --- | ---
  Windows, Linux | macOS |
  F3 | F3 | Find next occurence of search string
  F5 | F5 | Refresh the HTML-tag highlighting
  F6 | F6 | Toggle between Preview and Edit mode
  Ctrl–F | option–F | Open the search and replace window
  Ctrl–_ | option–- | Inserts Unicode character "—" (Em Dash). Useful to type fraction lines in pre-formatted code
  Ctrl–> | n/a | Inserts Unicode character "→" (right arrow)
  Ctrl–< | n/a | Inserts Unicode character "←" (left arrow)
  Ctrl–× | command–× | Inserts Unicode character "·" (middot). Multiplication sign or dot operator

- Labels

  One field for each label in a program step starting with f LBL, GTO or GSB.

  It is possible to use a label more than once in a program, but you can have only one description for all occurrences.

  If a label description starts with a "#", it will not show up in the GSB menu. This allows it to hide subprograms that should be called from inside the program only.

- Data Storage Registers

  A one-line field for each data storage register in a program step starting with STO or RCL.

- Flags

  A one-line field for each Flag in a program step starting with SF, CF or F?.

- Reload

  When the button is pressed, the current program is analysed and the dialogue is redrawn with the current set of labels, data storage registers and flags. See the next section for more details.

- OK

  Stores the documentation in the memory of the Simulator. The documentation is NOT written to the program file at that time.

- Cancel

  The documentation in the memory of the Simulator remains unchanged.

Changes to the documentation are indicated by a * in the windo title bar.

The elements in the dialogue box, i.e. labels, data storage registers and flags, are displayed in

- 1 column, when not more than 1 element of a type is used
- 2 columns, when in total not more than 30 elements are used
- 3 columns, when in total more than 30 elements are used or more than 10 elements of one type are used or the vertical screen size is 800 pixels or less.

### Documentation Life Cycle

When you start documenting a program, the documentation is only in the simulator memory. To include it in the program, you must save the program file. This also applies to changes to the documentation: You must always save the program manually. When you open a documented program file, the documentation is copied to the simulator memory. Any existing documentation is overwritten.

If you delete a label or flag or if you no longer use a data storage register, its description is not deleted until you close the Simulator or save the program file. In these cases, the documentation is cleaned up, that is, descriptions that are no longer used are deleted and not saved.

If you reuse an element that was previously deleted before you close the Simulator or save the program, the program description dialog displays the previous description of that element.

◀ Documentation ▲ Top

## Program Files

### Saving and Opening Programs

The current program is always part of the memory file and is therefore saved automatically every time you save the memory. In addition, programs can also be saved separately: Pressing Ctrl–S opens the operating system's "Save file" dialogue box. The default file name for new programs is "`New.15c`" or, if available, the first 40 characters of the "Program title". The Simulator supports the file extensions "`.15c`" and "`.txt`"; the default is "`.15c`".

To open a program file press Ctrl–O. The operating system's "Open file" dialogue box opens. If a program is read in, all currently loaded programs are deleted. If the new program is larger than the available memory, the display shows ERROR 4 and the program is not loaded. There is no possibility to merge programs while reading in. For information on how to do this manually, see the next section on file format.

The Simulator remembers the last directory that was used for writing or reading a program file. This directory is used as the start directory the next time you open a dialogue box.

### Program File Format

Simulator program files are simple text files. The following figure shows the program file for the little program used in the previous sections:

HP-15C Simulator program
     # --------------------------------------------
     # HEWLETT·PACKARD 15C Simulator program
     # Created with version 3.0.00
     # --------------------------------------------

        000 {             }
        001 {    42 21 11 } f LBL A
        002 {           2 } 2
        003 {          20 } ×
        004 {           9 } 9
        005 {          48 } .
        006 {           8 } 8
        007 {          10 } ÷
        008 {          11 } √x̅
        009 {       43 32 } g RTN

     # --------------------------------------------

As on the real HP-15C, step "`000`" is always empty.

Each line in a program file must be of one of the following types:

- Documentation

  Documentation lines begin with "`#<type>:`" where <type> can be one of the following:

  T | Program title.
  D | Program description (the content of the "Usage" field).
  Ln | Label description. n is "-1"…"-5" for labels "A"…"E" or a number between "0" and "19" for labels "0"…".9".
  Rn | Data storage register description. n is a number between "0" and "19" for registers "0"…".9" or "`I`" for the index register.
  Fn | Flag description. n is a digit between "0" and "9" for flag "0"…"9".

  Editing the documentation manually is discouraged; use the program description dialogue box instead.

- Comment

  Comment lines begin with a "`#`" not followed by one of the documentation letters. They are for internal use only.

- Blank line

  A blank line is a line that contains only white spaces or is of zero length. Blank lines are skipped.

- Program step

  Each line not recognised as a comment or a blank line is expected to contain a program step. The line must then have the form:

  `[line_number] "{" key_sequence "}" [mnemonic]`

  The "`key_sequence`" must be a valid HP-15C key sequence enclosed in curly braces; "`line_number`" and "`mnemonic`" are optional, and white space is ignored.

Program files are encoded in UTF-16 (LE) by default to preserve all special characters used in mnemonics. You can change the encoding to the system default encoding (see Files), but then mnemonics with special characters may not be stored correctly. Key sequences are not affected because key codes contain only digits.

When a file is read, only the key sequences are used. Line numbers and mnemonics are stored for documentation purposes only.

The Simulator uses the previously described file format when writing a program file. Since the files are simple text files, you can edit them with any text editor that supports UTF-16 (LE). When editing the files, you only need to address the key sequences.
For example, you can increase the precision of the acceleration due to gravity from `9.8 m/s2` to `9.81 m/s2` in the program example. To do this, you only need to insert a new program step with the key code for the number `1` behind the line "`006`":

HP-15C Simulator program
        ...
        003 {          20 } ×
        004 {           9 } 9
        005 {          48 } .
        006 {           8 } 8
                      { 1 }
        007 {          10 } ÷
        ...

Neither the line number nor the mnemonic need be specified. Program steps are automatically renumbered when the file is read. When you write back the program with the Simulator, the full file format is used. Missing information, like the mnemonics, are added by the Simulator.

Omitting all optional information brings us to the simplest form of the example program file.

Simplified file format
     {42 21 11}
     {2}
     {20}
     {9}
     {48}
     {8}
     {10}
     {11}
     {43 32}

### HTML Export

The program code together with the documentation can be exported to an HTML-file. HTML exports can not be loaded back into the Simulator! They are for documentation purposes only.

To export a progam to HTML, open the "Save program…" dialogue box and choose `"HTML Files (*.htm, *.html)"` as the file type. The HTML files are UTF-8 encoded.

macOS:
Current releases of Tcl/Tk don't call the save dialogue box with the file type listbox activated. Therefore you must call the save dialogue box either by "File | Export program to HTML…" or by the short-cut ⌘–E to select `"HTML Files (*.htm, *.html)"` as the file type. You can also manually add "`.htm`" to the filename, to force the HTML export.

If one the following elements is empty, you are asked if you want to save the file anyway:

- Program
- Program Title
- Usage

The warning message can be disabled in the Preferences dialogue.

If you press Ctrl–F1 or Shift–F1 on the Simulator it searches the directory from where you loaded the program for an HTML-file with the same name as the program file and the extension "`.htm`" or "`.html`". If a program help file is found, it is opened in the help file browser.

All programs in the Program Examples package come with an HTML help file.

◀ Program Files ▲ Top

Menus ▶