D 2019-08-16T00:27:47.196
L Running\sFOCAL,1969
N text/x-markdown
U tangent
W 5074
The PiDP-8/I project defaults to [U/W FOCAL][uwf], but it has [an option][opt] that lets you either add FOCAL,1969 to this or switch to it by disabling U/W FOCAL entirely:
$ ./configure --enable-os8-focal69 --disable-os8-uwfocal
Once that software is built and installed, you might then wonder, "How do I get started?" This document is our answer to that question.
# Running Programs with OS/8
OS/8 is not like Unix or DOS or any other OS that has a command `PATH`. The first word in an OS/8 command is handled by the OS/8 keyboard monitor (i.e. that which handles responses to the "`.`" prompt) so it has to be an OS/8 keyboard monitor command. In other words, OS/8's keyboard monitor does not search for `*.BN`, `*.SV` and similar files on disk and treat them as top-level command names. See page 1-35 in the [1974 edition of the OS/8 Handbook][hb].
The optional CCL feature of OS/8 extends the Keyboard Monitor with more commands, some of which add aliases for running binaries that makes it work more like Unix or DOS (e.g. "TECO"), but don't get confused about what's going on here. (See page 1-52 in the OS/8 handbook for more on CCL.)
If you want a Unix analogy, it's as if OS/8 has nothing but [shell built-in commands][sbi], no external commands. To run a binary on disk, you have to get at it through one of the shell commands — that is, Keyboard Monitor or CCL commands — or one of the commands you can get to *via* such commands.
# Starting FOCAL,1969
I've taken the time to go into all of that detail because it explains why none of the following commands start the `FOCAL.BN` binary we ship when you build the OS/8 disk packs with FOCAL,1969 enabled:
.FOCAL
.R FOCAL
.RUN FOCAL
What you actually want is to start the OS/8 absolute binary loader, which is what handles `*.BN` files such as `FOCAL.BN`:
.R ABSLDR
*FOCAL/G
The `/G` option means "go," starting the program immediately after loading it into core memory.
You'll get another "`*`" prompt after that, but it's from FOCAL, not `ABSLDR`. See page 1-108 in the OS/8 handbook linked above for more detail about `ABSLDR` commands.
# Returning to OS/8 from FOCAL,1969
Say "L" (`LOGICAL EXIT`) at the FOCAL `*` prompt to get back to OS/8. Unlike U/W FOCAL, FOCAL,1969 does not do this on Ctrl-C.
# Using FOCAL,1969
There are several freely-available PDF documents for DEC FOCAL which apply to varying degrees to what we ship. We recommend reading them in this order:
* [DEC FOCAL booklet](https://www.grc.com/pdp-8/docs/Focal_Booklet.pdf) (PDF, 255 kB) — This is an excellent introductory booklet to get you started with programing in general through the medium of DEC FOCAL.
* [Programming Languages: PDP-8 Family Computers](http://bitsavers.org/pdf/dec/pdp8/handbooks/programmingLanguages_May70.pdf) (PDF, 19.2 MB) — This is the second book of a 2-volume set, with "[Introduction to Programming]((https://www.pdp8.net/pdp8cgi/query_docs/view.pl?id=537))" being the first. The first book did originally cover FOCAL (Chapter 9), but that material was later moved to this second volume and improved considerably, so we cannot recommend learning FOCAL via "Introduction to Programming." The first volume was later re-published without detailed coverage of the various programming languages, focusing on foundational matters.
The FOCAL material in "Programming Languages" is in Chapter 11. It doesn't talk about OS/8 FOCAL,1969 specifically, but rather in a generic fashion about all DEC FOCAL variants.
* [FOCAL-8 Programming Manual](https://www.pdp8.net/pdp8cgi/query_docs/view.pl?id=144) (PDF, 2.6 MB) — We include this mainly for historical value, because it focuses on the original versions of DEC FOCAL, being the old 4k paper tape version and the version for the old Disk Monitor System. We don't know how well these versions map to the OS/8 version we ship.
# On Naming
You might be wondering about our use of the name "FOCAL,1969". That's because that's how the software identifies itself on starting up. It refers to a fairly specific version of the software, which matches what we distribute. It is sometimes also called "FOCAL 69", though that term was not favored by DEC.
Another name that *was* favored by DEC marketing is "FOCAL-8." This is a generic name not referring to any specific version of FOCAL. You can read it as "DEC FOCAL on the PDP-8."
There were many variants of FOCAL back in the day, some from DEC and some from outsiders. Because the language was never formally standardized, and there never was one dominant version, it can be useful to be specific about which variant you're talking about. Generic terms like "FOCAL", "FOCAL 69", or "FOCAL-8" should be used only when you're not trying to refer to a specific version.
[hb]: https://archive.org/details/bitsavers_decpdp8os8_39414792
[opt]: https://tangentsoft.com/pidp8i/doc/trunk/README.md#options
[sbi]: https://en.wikipedia.org/wiki/Shell_builtin
[uwf]: /doc/trunk/doc/uwfocal-manual.md
Z 7fd9de9f09bc32a06896408ec9cd6ca1