PROMAL for the Commodore 64 (last updated 2019-08-22)

PROMAL (PROgrammer's Micro Application Language) is an unusual and obscure language by Systems Management Associates, also released for the 8-bit Apple machines and the early PC. Its features include mandatory indentation (like Python), pointer arithmetic (like C), and recursion, and it has a good assembly language interface. There is also a shell with support for command recall and scripting. For some time, I had the demo version of the compiler here, which is limited to programs of a few hundred lines. But in December 2013, Jeff over at Vintage Volts sent me a complete copy, with the documentation. Many thanks to Jeff, as I had been looking for this for years! Shortly after that, I found an even more complete set (including newsletters, advertisements, and public domain disks) on eBay. The disk images and PDF files you see below are the best of the collection, and I've also included the files I originally downloaded from Q-Link back in the day, which contain additional software for PROMAL. Only one thing remains... who's got a copy of the source code for PROMAL 2.1 that Systems Management Associates used to sell?

Jeff from Vintage Volts sent me this PROMAL ad (from the September 1985 issue of BYTE magazine), which I hadn't seen before (click to enlarge).

Here are the slides and a D64 image of the demo disk from my PROMAL talk at ECCC 2014 (there's also a video of it). The disk contains the Flyer weather app I demoed at the show (as well as a modified version of jbevren's DIR program). NOTE: some time ago, I set up lyonlabs.org to be HTTPS only, and of course this breaks the weather program (which uses HTTP). But if you'd like to see the server source, I've made it available in my GitLab repository.

Here are PDFs of the listings for the weather program:

• weather.s (the stub loader)
• flyer.s (the Flyer module, reusable by other programs)
• weather_main.s (the main module)

I gave a "PROMAL Revisited" talk at VCFMW 2016. The source code for the programs I demoed is available for your browsing pleasure; there's also a D64 image of the source and executables, and a PDF of the slides from the talk. The video has been posted as well.

• getcmddate.c sets PROMAL's date from a CMD hard drive, and can be run at boot time from bootscript.j (the autoexec batch file).
• diskutils.c (library module) contains APIs for getting the next available logical file number, drive-type detection, reading a disk sector or directory header, determining partition type on CMD or sd2iec/uIEC drives, and sending disk commands and reading the command channel.
• drives.c (calls drives_main.c) lists the attached drives on a Commodore 64 system.
• pwd.c (calls pwd_main.c) prints the working directory of a CMD or sd2iec/uIEC native partition.
• ls.c (calls ls_main.c) can list a directory (long-form with time for CMD) and sort it by name or timestamp with proper wildcards (like *.s). It also accepts partition and directory arguments in CMD format.
• cp.c (calls cp_main.c) copies files across drives or partitions (CMD syntax with wildcards, as above), also allows "." as destination (meaning current partition and directory on the target drive).
• cmd.c (calls cmd_main.c) allows the sending of a DOS command to any disk device on the system.
• hexdump.s (source include file) will print core dumps.
• c64.s is an include file for the C64 kernal routines and a few other things.

David "jbevren" Wood has prepared a commented disassembly of the PROMAL runtime; he has also blogged about his research. You can find more here.

Christian Lott told me about this review of PROMAL in an Apple II magazine.

---

Disk Images

Notes (caveat utilitor!):

• PROMAL includes a built-in disk speeder called "DYNODISK"; it's fairly likely that the system disk below won't even start on your machine because of it, so you'll probably want to disable it permanently. To do that, issue the following commands:

    LOAD"PROMAL",8
    POKE 3554,128
    SAVE"@0:PROMAL",8
  

  See the notes for the DYNO command in the user's guide (page 2-22) and the memory map in Appendix G (page G-6) for more information.

• PROMAL supports two drives (devices 8 and 9), but issues "I0" commands to both 8 and 9 on startup. So if there's no disk in drive 9, this will bang the drive head. I suggest the following to disable it:

    LOAD"PROMAL",8
    POKE 2596,0
    SAVE"@0:PROMAL",8
  

  This changes the code at $0a23-$0a43 to load the accumulator with a file length of zero when calling SETNAM to open the command channels (which are kept open as long as PROMAL is running).

PROMAL 2.1 System Disk  Boot from this disk to start the PROMAL environment and enter the Executive (shell).

PROMAL 2.1 Developer's Disk  This disk contains the tools to create standalone versions of your PROMAL programs that don't need to be started from the shell.

PROMAL Graphics Toolbox 1.0  This a very extensive graphics library for PROMAL. You can find the manual below.

PROMAL public domain library disk #1 This disk includes a macro assembler written in PROMAL and the DISKFIX program.

PROMAL public domain library disk #2 The contents of this disk are listed in its manual (below). It includes the document formatter DOCFOR used for some of the PROMAL documentation.

Demo Disk  This is the PROMAL demo disk; it includes the BILLIARDS and INFILTRATOR programs.

PROMAL memory map (from Appendix G)

Manuals (PDF)

Table of Contents/Index: It looks like none of the PDFs below contain the table of contents, so I extracted it from my old version of the full PDF. This file also contains the index (which you can find in "Appendix H-Q and INDEX" below as well).

The Meet PROMAL manual tells you how to get your PROMAL system up and running.

The PROMAL 2.1 User's Guide explains how to use the Executive (shell), editor, and compiler.

The Appendix A-G and Appendix H-Q and INDEX documents are the appendices to the user's manual and cover things like sending files between two computers, detailed memory maps, machine language support, and relative file support.

The PROMAL 2.1 Language Manual is a reference to the PROMAL programming language itself.

The PROMAL 2.1 Library Manual documents the PROMAL standard library routines.

The PROMAL 2.1 Developer's Guide is a guide to creating standalone programs that do not need to be loaded from the shell.

The PROMAL Graphics Toolbox 1.0 manual describes a very extensive graphics library for PROMAL (disk above).

The PROMAL Public Domain Library manual details some public domain programs written in PROMAL (images above).

Newsletters &c.

Volume 1, No. 1

Volume 1, No. 2 (missing pages 4 and 5)

Volume 2, No. 1

Bug Report Form/Warranty Card

"Questions and Answers" Brochure

---

The Q-Link Collection: this collection was downloaded from Q-Link many years ago. There is some excellent software here, but the most interesting thing might be a version of PROMAL labeled version 2.1E, with documentation. There are some interesting differences in this version, including an alternate version of the EXECUTIVE with additional commands, additional library routines, and support for Commodore RAMDOS. Its provenance is unknown, although judging from comments in many of the files, it looks like much of this may be the work of Craig McDowell.

promal-2.1e.d64, the 2.1E version of PROMAL

promal-2.1e-docs.d64, the docs for PROMAL 2.1E

promal-docfor.d64, a document formatter (by David Long, edited by Craig McDowell)

promal-xref.d64, a cross-reference utility

promal-syslib.d64, some additional libraries (Craig McDowell's Q-Link handle is listed in SYSLIB1_DOC.T).

promal-graphics.d64, a graphics library (not the same one as above: "Written by R. D. Norrod. Modified by C. A. McDowell 11/06/86")

promal-diskfix.d64*, a "disk doctor" utility (by A. Ryan, revised by Craig McDowell)

promal-relinter.d64, relative file support (this one also contains Craig's contact info)

promal-fullscrn.d64, a screen I/O library (by Craig McDowell)

LIMPRO is an implementation of LISP in PROMAL and machine language (there's also a standalone version, which contains the infamous TED editor, written "in the TECO/SPEED tradition"). One of the documentation files (PST.T) is marked "(c)1987 by M. J. Mardesich".

* This one comes from five different ARC files, with many duplicated files between them. I don't know if that's so it could be compiled in pieces, or...? I have the ARC files for this collection as they were originally downloaded from Q-Link; I can put them up here if anyone's interested. Drop me a line (cenbe at protonmail dot com).

PROMAL Tips 'n' Tricks

Here is a list of tips 'n' tricks for PROMAL programming:

• I've put together a PROMAL cheatsheet covering common editor keystrokes, shell commands, and language features.

• PROMAL supports two disk drives, 0: and 1:, although this refers to the device number (by default 8 and 9), not the "unit number" (unless you are using an MSD or other drive with two mechanisms). This can be overriden by changing addresses $0DE0 and $0DE1 (C64DDV0, C64DDV1 in PROSYS.S). See Appendix N of the user's manual for more information. To set drive 1: as device 12 from the command line, you would type:

    set de1 c
  

• PROMAL allows a hyphen in filenames, but not in a source include file! In other words, if FILE-ONE.S contains the line INCLUDE FILE-TWO.S, you'll be able to compile FILE-TWO.S, but will get an error on the include line in FILE-ONE.S. The solution is to use an underscore instead; in Commodore 64 PROMAL, this is the back-arrow character  (←).

• By default, the FILES command only shows executables (.C). To make it list all files, precede it with this command:

    set cf2 80
  

  This can be found in PROSYS.S:

    EXT BYTE NOFNCHK AT $CF2 ; Bit 7=1=no default extension
  

  Note, however, that until you use the FILES command for the first time, all attempts to run a program will result in PROGRAM OR OVERLAY NOT FOUND.

• PROMAL works just fine with a SuperCPU, although the cursor blinks very rapidly. From jbevren comes the advice that you can get it to blink at a more reasonable rate by entering this at the shell prompt (or putting it in your startup script, bootscript.j):

    set cff 40
  

• There's an undocumented EXECUTIVE command: WHORU (it shows the PROMAL version).

• Finding the address of a variable in memory: I'll show the example from my ECCC 2014 presentation (PDFs and video at top of page), where the variable is an array of bytes.

  1. In the program weather_main, find the offset of the variable in the compiler listing (compile with the L switch). In the screenshot below, we can see that the offset of the raw[8192] variable on line 246 is at offset $C2.
     
  2. At the end of the listing, we see that scalar variables take $0A bytes of storage; since arrays are stored directly after scalars in memory, we add this to the offset.
     
     You can also find this value from the size command, where the third number ($0A) is the size of the scalar section:
     
  3. Now, with the program loaded in memory, look at the output of the map command, which tells where programs and variables are located:
     
     We can see that weather_main has code starting at $5400 and variables starting at $7a00. So the offset of the raw[] array is:

      $7a00 (start of variables)
     +  $c2 (offset of raw[] variable)
     +  $0a (length of scalar section)
     ------
      $7acc

     For a scalar variable, just don't add the length of the scalar section.

     Now you can use the PROMAL dump command (or a hardware monitor like Super Snapshot or Action Replay) to find the value of the variable.

  4. Getting a listing for a large program: the User's Guide (p. 2-58) mentions that "you should never attempt to use the L option to produce a listing file on disk at the same time as using the B option" (write object code to disk instead of memory for large programs). The solution is to compile a second time, directing the compiler not to write the object file:

     COMPILE FILENAME B
     COMPILE FILENAME O=N B L

back to main Commodore page