
  Using Vintage HP21xx Compilers under HP-IPL/OS with VDOS
  ========================================================
  
The vintage.ipl package permits running the old SIO-based EXTASMB assembler
and ALGOL and FORTRAN compilers, then linking the resulting "REL" code to
a stand-alone ABS binary using the BCS linker/runtime system. This requires
a VDOS-compatible VDRIVE adapter with manual file attach and punch abilities,
the instructions assume the USB disk adapter.

The following binaries are required, presently available from:
http://oscar.taurus.com/~jeff/2100/siotapes/index.html

extasmb.abs      Extended Assembler
algol.abs        ALGOL Compiler
fortran1.abs     FORTRAN Compiler pass 1
fortran2.abs     FORTRAN Compiler pass 2
sio16k11.abs     Configured SIO system
bcsprep.abs      Prepare Control System
bcsioc.rel       Input/Output Control
bcsloadr.rel     BCS Relocating Loader
bcslib.rel       BCS Relocatable Library
bcstty.rel       BCS TTY Driver
bcsptr.rel       BCS Tape Reader Driver
bcsptp.rel       BCS Tape Punch Driver

Documentation for the assembler, FORTRAN and BCS is in the document
"5951-4423_A_Pocket_Guide_To_The_2100_Computer_Sep72.pdf" available
from "BitSavers" in the pdf/hp/21xx directory. A mirror of the
BitSavers archive is at: http://bitsavers.trailing-edge.com/

Documentation for ALGOL is in "HP_Algol_02116-9072_88pages_Jun71.pdf"
available from the HP Computer Museum at: http://www.hpmuseum.net/

Before the software can be used, the SIO system needs to be patched so that
it matches the slot assignments of the system it's being run on, and a BCS
system has to be prepared. For use with HP-IPL/OS and VDOS on a HP21MX-type
CPU (HP2109 or HP2113) with at least 64KW memory, BCS must be prepared so
that it uses 31KW memory or less (HP-IPL/OS uses the top 1KW for swapping).
It is possible to use the vintage software with other HP21xx CPU's with
at least 16KW memory using manual file attaches, but that is not covered
in this document - refer to the vintage documentation.


Preliminaries
-------------

The following assumes that a TBG board is in slot 10, a console board is
in slot 11, a 16-bit I/O card for PTR/USB is in slot 12, a 8 or 16 bit I/O
card is in slot 13, and the USB disk adapter has been configured for the
I/O boards. The VDOS161.ABS build used in the example also contains drivers
for BACI (serial) in slot 22 and HPIB in slot 17, these are optional and
not used here. If the slot configuration is different then HP-IPL/OS must
be adjusted - provided the console is in slot 11 this can be done using
the CONFIG utility built into the VDOS161.ABS build. If a TBG board is
not installed then before running from location 2, set switch register
bit 15, run from 2, enter RENAME !IRQ +IRQ and enter RENAME !100MS +100MS
to keep the TBG drivers from running. If desired enter RENAME !BACI +BACI
to disable baci driver but usually it's not an issue if not present. After
renaming the drivers enter 0 S>SR 2 RUN to restart. Once the ? prompt appears
then if the slots need changing enter CONFIG followed by 2 RUN to restart.
If PTR/USB interface is not in slot 12 then enter slot# VDOS (i.e. 10 VDOS).
Verify that VDOS can see the thumbdrive by doing VDIR - if a directory is
shown then save the configured system by entering: "HPBOOT" VSAVE
Reboot the system from scratch to ensure it comes up cleanly.

There are other and possibly better ways to configure a default HP-IPL/OS
build suitable for using the vintage compilers - for example use VDOS161S.ABS
and configure the slots by directly altering memory (see summary.txt). This
might avoid hassles with interrupts and drivers. Which build to use depends
on the system and whether or not the extra drivers and features included
with VDOS161.ABS are needed.

Using a PC, copy VDOS161.ABS (or VDOS161S.ABS) to the root of a thumbdrive.
Make a copy of it and rename it to "HPBOOT". If you already have a VDOS system
named HPBOOT that's probably fine, can use that but if there are "page errors"
then load the VDOS161[S].ABS system before making the development build.

Make a directory on the thumbdrive named "WORK" (or another name) and copy
the 12 vintage binaries to it, and also copy the fcam.ipl, vintage.ipl and
sioutil.ipl files to the WORK directory. You might also want to copy over the
sham.ipl, fed.ipl, fedutil.ipl and nolf.ipl files for optional utilities.
If using VDOS161S.ABS then also copy over hpscreen.ipl, it is needed to run
anything requiring terminal control such as the editor in fed.ipl.
VDOS161.ABS already has the screen words.

Boot the HP minicomputer - turn on the HP, turn on or reset the disk adapter,
select the S register, clear display and set bits 7 and 9 (assuming slot 12),
store, preset, IBL, preset, run - about 4 seconds later LED's 0-5 should all
light on the HP, assuming the slots are configured select the P register,
clear display, set bit 1 (for location 2), preset, run. If the slots are not
configured then see above, assuming the console is in slot 11. Many things
are configured for TTY console = 11 but if for some reason that is not
convenient then (if using VDOS161.ABS) before running, select S, clear
display, put the console slot in bits 0-5, set bit 15, store, select P,
clear display, set bits 3 4 and 5 (for location 70), preset, run then
(assuming it comes up) follow the instructions to use CONFIG to set the
slot addresses.


Making a VDOS dev build
-----------------------

This, and the instructions that follow, assume that the IPL and binary
files are in a directory named "WORK" as directed in the preliminaries.
Modify accordingly if not.

Boot or load VDOS161.ABS or VDOS161S.ABS. See preliminaries for specifics.
Enter 3 ALLOCATE to reduce block allocation, making more room for IPL's.
Enter "WORK" VCD to change to the work dir (or wherever the IPL files are).
Enter "FCAM.IPL" VLOAD to load the FCAM utility package.
Ignore the F2AM NOT FOUND message, that's because IDE/XDOS isn't present.
Enter "VINTAGE.IPL" VLOAD to load the vintage compiler package.

If extra utilities are desired... (optional)
Enter "NOLF.IPL" VLOAD to permit using a terminal set to CRLF line ends.
Enter "SHAM.IPL" VLOAD to load the Show Alt Memory utility.
If using the VDOS161S.ABS version, enter "HPSCREEN.IPL" VLOAD to load in
  the screen control words, then enter TERMINAL to change to an ANSI terminal
  (unless really using a vintage HP terminal, in which case if using the
   VDOS161.ABS version, enter TERMINAL to switch to a HP terminal).
Enter "FED.IPL" VLOAD to load the "array" editor.
Enter "FEDUTIL.IPL" VLOAD to load the editor utilities.

Once all desired options have been loaded...
Enter VERSION, press Y, enter a name for the dev build (say VDOS DEV 1.61).
Enter "VDOSDEV.ABS" VSAVE to save the build. Change the name as needed.

After booting the system you can return to this build by entering
"WORK" VCD "VDOSDEV.ABS" VLOAD (change the dir/filename if different).


Configuring the SIO driver
--------------------------

Load the VDOS dev build, make sure in the same directory as sioutil.ipl
and the sio16k11.abs binary (VDIR, "dirname" VCD as needed).
Enter "SIOUTIL.IPL" VLOAD to load the SIO patch utility.
Enter "SIO16K11.ABS" VREAD to attach the original binary for reading.
Enter "SIO.ABS" VWRITE to attach the output (confirm overwrite if exists).
Enter SIOPATCH to run the utility.
Press enter to start.
Enter the slot address for the TTY console (enter 11).
Enter the slot address for the PTR (USB) interface (enter 12).
Enter the slot address for the PTP punch interface (enter 13).
(numbers in parenthesis are for the default system, mod as needed)
The utility should print...
  Patching...
  Writing new sio binary...
  Done
After the prompt appears enter VCLOSE to close the output file.
VDIR should show the new configured SIO.ABS file.

Since this only needs to be done once there is no need to save a build
containing the SIOPATCH word, can be reloaded if needed. If continuing
to use the build to add then save as another system, enter FORGET SIOPATCH
to remove the utility. If just using the build it doesn't matter.


Configuring a BCS system binary
-------------------------------

Load the VDOS dev build if not already running.
Enter VDIR to make sure in the same directory as the vintage binaries.

Enter the following file copies...
"BCSTTY.REL" "A" VCOPY
"BCSPTR.REL" "B" VCOPY
"BCSPTP.REL" "C" VCOPY
"BCSIOC.REL" "D" VCOPY
"BCSLOADR.REL" "E" VCOPY

These will be selected in response to each LOAD prompt.
Enter "F" VDEL to make sure the output file does not exist.
Enter VCLOSE to make sure no write files are currently open.

Enter ALTSAVE ZAM to enable the swapper and clear alt memory.
Enter "BCSPREP.ABS" VREAD ABSLOAD to load the prepare utility into alt mem.
Enter 2 124003 APUT 3 2000 APUT to patch locations 2/3 to run 2000.
Enter 11 S>SR to put 11 into the switch reg (change if TTY not in slot 11).
Enter -IRQ PTRMODE 77000 RUN to run the prepare utility. Now it gets dicy...

BCS requires CRLF line ends so if using a terminal set to the normal
CR enter, type enter control-J or control-M control-J at the end of lines.
Alternatively, the terminal can be set to send CRLF enters, however if
doing that either load the NOLF.IPL package into HP-IPL/OS (and 2 RUN to
enable), or switch back to CR enters when HP-IPL/OS is running. The
HP-IPL/OS prompt itself can tolerate line feeds, but anything that
prompts for more input will fail if CRLF enters are enabled. Also NOLF
just controls the interpretation of data, so the display will still
double-space for CRLF enters. All things considered, I simply use
control-MJ instead of enter when running BCS apps.

Type carefully, there is no usual backspace. Backspace or Del (depending
on the terminal, whichever is "rubout") followed by control-MJ can be
used to start an entry over.

At the HS INP? prompt, enter 12 (or whatever PTR is)
At the HS PUN? prompt, enter 13 (or whatever PTP is)
At the FWA MEM? prompt, enter 200
At the LWA MEM? prompt, enter 75777

When it displays * LOAD and halts (run light goes out), press the A switch
on the USB disk adapter twice so that it shows "RF:A" on the LCD. If it
overshoots just hold the switch to cycle or press the D switch and try again.
Once the "A" file is selected for read press the C switch to confirm the
selection and return to ready mode, then press the Run switch on the HP.

The console should display cryptic information then display another * LOAD
prompt and halt. Press the A switch on the adapter 3 times to select the "B"
file, press the C switch to confirm, press Run on the HP to load.

Repeat for files "C" and "D", at the end of loading file "D" it should
display * TABLE ENTRY then EQT? then halt, press Run on the HP to continue.

Enter the following for TTY, PTR, PTP, change the 11, 12, 13 if different...
11,D.00
12,D.01
13,D.02
/E

It should then display SQT? followed by prompts.
For -KYBD? enter 7
For -TTY? enter 7
For -LIB? enter 10
For -PUNCH? enter 11
For -INPUT? enter 10
For -LIST? enter 7
For DMA? enter 0

It should then display * LOAD and halt, use the adapter switches to select
read file "E", confirm, press Run on the HP to load the final module.

After more cryptic info should display INTERRUPT LINKAGE ? and halt, press run
and enter the following for TTY, PTR, PTP, adjust the 11,12,13 if different...
11,101,I.00
12,102,I.01
13,103,I.02
/E

After more cryptic info it should display *BCS ABSOLUTE OUTPUT then halt.
Press the B switch on the adapter 7 times so that the LCD reads "WF:F",
press the C switch to confirm the write file "F" selection.

Press the run switch and wait for the "F" file to be written.
When the machine halts, select the P register, clear display,
set bits 9 through 14 (address 77000) and press the run switch.
HP-IPL/OS should restart.

Enter VCLOSE to close the output file.
Enter "F" "BCS.ABS" VCOPY to copy the punched output to the correct filename.
Enter "BCS.ABS" VREAD ABSLOAD to verify the binary has no errors.
If CHECKSUM ERROR is displayed or it hangs then something went wrong.
Enter the following to delete the temporary files...
"A" VDEL "B" VDEL "C" VDEL "D" VDEL "E" VDEL "F" VDEL

The configured SIO.ABS and BCS.ABS files can now be used to compile and
link BCS programs, the SIO and BCS configuration procedures only need to be
repeated if the slot configuration changes or there is a need to target a
machine with less memory.


Using the vintage compiler words
--------------------------------

A BCS application is composed of one or more "REL" modules, each written
in assembler, ALGOL or FORTRAN, then linked together with a library to
produce a stand-alone ABS-format binary. The core operations are...

"source.asm" "program.rel" ASMB - assemble a module
"source.alg" "program.rel" ALGOL - compile a module written in ALGOL
"source.ftn" "program.rel" FORTRAN - compile a module written in FORTRAN
"program.rel" "program.abs" LINK - link the module(s) into an ABS binary

ASMB can also assemble directly to ABS if specified on the control line.

ASMB, ALGOL and FORTRAN prompt to overwrite the output file if it exists,
if overwrite is not confirmed then the intermediate code is appended to the
existing file, permitting all of the modules required for an application to
reside in a single file. When LINK is run it creates a temporary file
containing the combined modules file and the BCS library file. ASMB creates
a temporary file containing two copies of the assembler source, since the
assembler requires two passes. The FORTRAN compiler requires two passes
but using two programs, pass 1 writes a temporary file which pass 2 reads
and then outputs the relocatable code for the module. Each of the commands
prints operation instructions before running the vintage tool.

For a simple demo, here is a "hello world" program written in FORTRAN...

----- begin HELLO.FTN -------------------------------------
FTN,B,L,A
C FORTRAN TEST PROGRAM
      PROGRAM HELLO
      WRITE(6,101)
  101 FORMAT("HELLO WORLD")
      END
      END$
----- end HELLO.FTN ---------------------------------------

Copy between the lines into a file named "HELLO.FTN" in the "WORK" directory
of the thumbdrive (or wherever the vintage binaries and the configured SIO.ABS
and BCS.ABS binaries are located). Make sure the FTN file has CRLF line ends.
The ,A on the FTN line selects assembly listing, the ,L option selects source
listing. For long programs omit ,A since it slows down pass 2 considerably.

To compile the program, enter "HELLO.FTN" "HELLO.REL" FORTRAN and follow
the instructions printed to the console precisely. Two passes are required,
after each pass select the P register, clear display, set bits 9-14 (77000)
and press run to continue. The run should look something like...

? "HELLO.FTN" "HELLO.REL" FORTRAN
LOADING FORTRAN PASS 1 AND OPENING FILES
LOADING..LOADING.....................
RUNNING FORTRAN PASS 1...
AT HALT, SELECT P, SET TO 77000, STORE, RUN
PRESS ANY KEY TO START...
[source code listed if selected]
[halts, select P, clear, set to 77000, run]
FINISHING PASS 1... DONE
LOADING PASS 2... LOADING......
RUNNING FORTRAN PASS 2...
AT HALT, SELECT P, SET TO 77000, STORE, RUN
PRESS ANY KEY TO START...
[assembly code listed if selected]
?
[halts, select P, clear, set to 77000, run]
CLOSING FILES... DONE
REMOVING TEMP FILE... DONE
VDOS DEV 1.61
?

Now the program has to be linked to make an ABS file...

? "HELLO.REL" "HELLO.ABS" LINK
PREPARING REL FILE WITH LIBRARY
Writing USB file --TEMP--.REL
 WAIT...
Closing output buffer
LOADING BCS LINKER AND ATTACHING FILES
LOADING...........RUNNING BCS LINKER...
AT HALT, PRESS RUN AGAIN TO LOAD MORE MODULES
(I.E. IF REL HAS 6 MODULES PRESS RUN 5 TIMES)
AFTER ALL LOADED, SELECT S, SET BIT 2, STORE, RUN
AT NEXT HALT, RUN AGAIN TO OUTPUT ABS
WHEN *END DISPLAYED HALT, SELECT P, SET TO 77000, STORE, RUN
(IF SR BIT 15 WAS SET TO SUPPRESS, CLEAR FIRST)
PRESS ANY KEY TO START...

Press a key to run the BCS linker and load the first module.
There is only one module, so at the first halt, select the S register,
set bit 2 taking care not to disturb bit 14 which is already set,
press store then press run. At the next halt press run again.
It should display *END but may or may not halt depending on some
factor I haven't figured out yet (under simulation a halt instruction
can be put in location 2 to make it halt every time, but already poking
location 2 with the BCS start address so that's not convenient.. bug?)
If the run light does not go out after displaying *END, press halt.

To test the program enter: "HELLO.ABS" VLOAD
The program should display its message then halt, select P,
clear and set to 77000, run to return to HP-IPL/OS.

A more complex example is the vintage chess game from:
http://newton.freehostia.com/net/oldcomp/hpgames/chessbcs.zip
This program consists of a main module written in ALGOL with five modules
written in assembly. These are edited excerpts from the session log...

? "VINTAGE" VCD "VDOSDEV.ABS" VLOAD
LOADING..............................................................................................
Run from 77000 to return

VDOS DEV 1.61
...
? "CHESS.ALG" "CHESS.REL" ALGOL
LOADING ALGOL AND OPENING FILES
LOADING..LOADING..............RUNNING ALGOL...
AT HALT, SELECT P, SET TO 77000, STORE, RUN
PRESS ANY KEY TO START...
PAGE  001


001 02000 HPAL,L,B,"CHESS"
002 02000 BEGIN
003 02003 COMMENT MINI-TECH - WRITTEN BY JIM GILLOGLY, JUNE 1971,
004 02003 MODIFIED, ANNOTATED AND ADAPTED FOR CLASS USE BY RON OHLANDER,
005 02003 OCT 1971.  MODIFIED AND REANNOTATED BY JIM GILLOGLY, FEB L972.
006 02003 TRANSLATED TO SAIL BY PAUL DANTZIG, MAY 1973.
007 02003 CHESS POSITIONAL ANALYSIS ADDED BY KEN POCEK, JUNE 1973.
008 02003 ADAPTED TO HP ALGOL BY ED DOUST AND KEN POCEK, SEPT, 1973
.... rest of the listing
820 17051 DONE: END OF CHESS$

PROGRAM= 015052 BASE PAGE= 000464  ERRORS=000

When the machine halted, I selected the P register, cleared display,
set bits 9-4, pressed store then run.

CLOSING FILES...DONE
VDOS DEV 1.61
? "CHESS1.ASM" "CHESS.REL" ASMB
File exists. Overwrite? N WILL APPEND
PREPARING DOUBLED SOURCE FILE
Writing USB file --TEMP--.ASM
 WAIT...
Closing output buffer
LOADING EXTASMB AND OPENING FILES
LOADING..LOADING.........RUNNING EXTASMB...
AT HALT PRESS THE RUN SWITCH
AT NEXT HALT, SELECT P, SET TO 77000, STORE, RUN
PRESS ANY KEY TO START...
 PAGE 0001


0001                ASMB,R,L,B
**  NO ERRORS*

At this point the machine halted, I pressed the run switch to run pass 2.

 PAGE 0002 #01


0001                ASMB,R,L,B
0002  00000               NAM ECUTE,7
0003                      ENT ECUTE
... rest of the listing
      00364 000142
      00365 000020
0281                      END
**  NO ERRORS*

Set P to 77000, store, run.

CLOSING FILES... DONE
REMOVING TEMP FILE... DONE
VDOS DEV 1.61
? "CHESS2.ASM" "CHESS.REL" ASMB
File exists. Overwrite? N WILL APPEND
... same deal
? "CHESS3.ASM" "CHESS.REL" ASMB
File exists. Overwrite? N WILL APPEND
...
? "CHESS4.ASM" "CHESS.REL" ASMB
File exists. Overwrite? N WILL APPEND
...
? "CHESS5.ASM" "CHESS.REL" ASMB
File exists. Overwrite? N WILL APPEND
...
? "CHESS.REL" "CHESS.ABS" LINK
PREPARING REL FILE WITH LIBRARY
Writing USB file --TEMP--.REL
 WAIT...
Closing output buffer
LOADING BCS LINKER AND ATTACHING FILES
LOADING...........RUNNING BCS LINKER...
AT HALT, PRESS RUN AGAIN TO LOAD MORE MODULES
(I.E. IF REL HAS 6 MODULES PRESS RUN 5 TIMES)
AFTER ALL LOADED, SELECT S, SET BIT 2, STORE, RUN
AT NEXT HALT, RUN AGAIN TO OUTPUT ABS
WHEN *END DISPLAYED HALT, SELECT P, SET TO 77000, STORE, RUN
(IF SR BIT 15 WAS SET TO SUPPRESS, CLEAR FIRST)
PRESS ANY KEY TO START...

Ok, has 6 modules, so press run 5 times in response to each *LOAD prompt
and halt (would be cool if it actually counted the modules but it is just
fixed text). At the next *LOAD halt it's at the library, so selected the S
register, set bit 2 (without disturbing bit 14 which is also set), pressed
run, then at the next halt pressed run again. When *END is displayed the
process is done, if it doesn't halt press the halt button.
Put 77000 in P, press run...

CLOSING FILES... DONE
REMOVING TEMP FILE... DONE
VDOS DEV 1.61
? "CHESS.ABS" VLOAD
LOADING..................................................................................................................................
Run from 77000 to return

HP CHESS VERSION A  10/26/73

DUMPS AVAILABLE:
     SW0 - MOVE LIST
     SW1 - BOTTOM NODE DUMP
     SW2 - FULL DUMP



TYPE 1 FOR A NEW GAME, 0 FOR OLD 1
CHOICE: (B=1, W=-1) -1
1

 MOVE=  1

      ---------------------------------
  90  !*R !*N !*B !*Q !*K !*B !*N !*R !
      ---------------------------------
  80  !*P !*P !*P !*P !*P !*P !*P !*P !
      ---------------------------------
  70  !   !   !   !   !   !   !   !   !
      ---------------------------------
  60  !   !   !   !   !   !   !   !   !
      ---------------------------------
  50  !   !   !   !   !   !   !   !   !
      ---------------------------------
  40  !   !   !   !   !   !   !   !   !
      ---------------------------------
  30  ! P ! P ! P ! P ! P ! P ! P ! P !
      ---------------------------------
  20  ! R ! N ! B ! Q ! K ! B ! N ! R !
      ---------------------------------
0       1   2   3   4   5   6   7   8


YOUR TURN: FROM SQUARE? 
--------------------------------------------------------------------------
Last mod 11/25/10
