                 HP 32002E MPE-V/R Operating System Software Kit
                 ===============================================
                  J. David Bryan <jdbryan@acm.org>, 26 Jun 2016


This package contains a bootable disc image of an HP 3000 MPE-V/R version
E.01.00 operating system.  The image is in SIMH format, with each 16-bit disc
word in little-endian format, i.e., lower-order byte first.  It is provided for
use with the SIMH HP 3000 Series III simulator that is available at:

  https://github.com/simh/simh

Please refer to the following documents from the above site when using this kit:

  doc/hp3000_doc.doc        -- the "HP 3000 Simulator User's Guide"
  doc/simh_doc.doc          -- the "SIMH Users' Guide, V4.0"
  hp3000/hp3000_release.txt -- the "SIMH/HP 3000 Release Notes"

This kit includes the following files:

  mpe.7920.disc       -- the bootable MPE disc image
  mpe-man.sim         -- a script to cold load the disc
  mpe-auto.sim        -- a script to cold load the disc and perform a COOLSTART
  mpe-1-reload.sim    -- a script to RELOAD the system from the FOS tape
  mpe-2-sysdump.sim   -- a script to SYSDUMP the disc to tape
  mpe-3-coldstart.sim -- a script to COLDSTART the system and expand code size
  mpe-4-restore.sim   -- a script to RESTORE compilers and examples from tape
  mpe-1-reload.log    -- the console log for the mpe-1-reload.sim script
  mpe-2-sysdump.log   -- the console log for the mpe-2-sysdump.sim script
  mpe-3-coldstart.log -- the console log for the mpe-3-coldstart.sim script
  mpe-4-restore.log   -- the console log for the mpe-4-restore.sim script
  readme.txt          -- this documentation file

PDF manuals describing MPE commands are available from Bitsavers at:

  http://www.bitsavers.org/pdfs/hp/3000/

Problems with the simulator or the software kit should be directed to the SIMH
mailing list at:

  http://mailman.trailing-edge.com/mailman/listinfo/simh

...or to the SIMH issue tracker at:

  https://github.com/simh/simh/issues



--------------------
Using the Disc Image
--------------------

After unpacking the archive into a directory, the disc image is ready to run
using the HP 3000 simulator and either the "mpe-auto.sim" or "mpe-man.sim"
simulator command file.

"mpe-auto.sim" sets up the simulation environment, attaches the "lp.txt" file to
the simulated HP 2617 line printer, attaches the disc image to the simulated HP
7920 disc drive, cold loads the system, requests a COOLSTART, and supplies the
date and time to MPE (see the usage note below).  At the conclusion of the
script, the system operator is logged on at the simulation console, and the
Asynchronous Terminal Controller (ATC) is configured to listen for Telnet
connections on local port 1054.

"mpe-man.sim" performs the same setup but stops after cold loading the system.
The user must perform the remainder of the startup interaction manually --
choosing a WARMSTART or COOLSTART, etc.

Both command files assign localhost port 1054 to the ATC.  If you use a
firewall, you may have to allow the "hp3000" executable to receive incoming
connections.  If port 1054 is in use or is otherwise unsuitable, you may edit
the command files to use any available local port.

Once the HP 3000 simulator has been compiled, running:

  hp3000 mpe-auto

...should produce this output on the simulation console:

  Press <CR> to start MPE.

  HP32002E.01.00
  WHICH OPTION <WARMSTART/COOLSTART>? COOLSTART
  ANY CHANGES? NO

  DATE (M/D/Y)?02/17/88
  TIME (H:M)?17:38
  WED, FEB 17, 1988,  5:38 PM? (Y/N)Y
  LOG FILE NUMBER 4 ON
  *WELCOME*
  :HELLO OPERATOR.SYS;HIPRI
  17:38/13/SP#6/SPOOLED OUT
  17:38/#S1/14/LOGON FOR: OPERATOR.SYS,OPERATOR ON LDEV #20
  HP3000 / MPE V  E.01.00 (BASE E.01.00).  WED, FEB 17, 1988,  5:38 PM
  :

...where the date and time reflect the current date and time of the host system
with a year selected from the 20th century whose days of the week and leap-year
status match those of the current year.  Connecting a terminal emulator (e.g.,
Reflection or QCTerm) via Telnet to local port 1054 will connect the session to
an ATC channel.  Pressing RETURN or ENTER will bring up the MPE colon prompt
from which, for example, the system manager may be logged on:

  <attempting connection to localhost>
  <localhost contacted>

  Connected to the HP 3000 simulator ATCD device, line 1


  :HELLO MANAGER.SYS
  HP3000 / MPE V  E.01.00 (BASE E.01.00).  WED, FEB 17, 1988,  5:46 PM
  :

Two example BASIC programs are provided in the OPERATOR.SYS account.  The "TEN"
program calculates and prints the square roots of the numbers from 1 to 10 in
both single- and double-precision.  It may be run from the BASIC interpreter:

  :BASIC

  HP32101B.00.26(4WD)  BASIC  (C)HEWLETT-PACKARD CO 1979
  >GET TEN
  >RUN
  TEN
  HELLO FROM HP 3000 BASIC!  HERE ARE SOME SQUARE ROOTS:

   1              1              1.000000000000000L+00
   2              1.41421        1.414213562373095L+00
   3              1.73205        1.732050807568877L+00
   4              2              2.000000000000000L+00
   5              2.23607        2.236067977499790L+00
   6              2.44949        2.449489742783178L+00
   7              2.64575        2.645751311064591L+00
   8              2.82843        2.828427124746190L+00
   9              3              3.000000000000000L+00
   10             3.16228        3.162277660168379L+00

  >EXIT

  END OF SUBSYSTEM
  :

The TEN program can also be compiled by the BASIC compiler and prepared to
produce an executable program that may be run directly from the command prompt:

  :BASICPREP TENCMD,TENRUN

  PAGE 0001   HP32103B.00.24(4WD)  BASICOMP  (C)HEWLETT-PACKARD CO 1979


  $CONTROL SOURCE,USLINIT,LABEL,MAP,LIST,WARN
  $COMPILE TEN
     10 LONG J
     20 PRINT "HELLO FROM HP 3000 BASIC!  HERE ARE SOME SQUARE ROOTS:"
     30 PRINT
     40 FOR I=1 TO 10
     45   J=I
     50   PRINT I,SQR(I),SQR(J)
     60 NEXT I
    110 END


      SYMBOL MAP

      TEN

   NAME    TYPE          STRUCTURE       ADDRESS

    I      REAL          SIMPLE VAR      Q+  4
    J      LONG          SIMPLE VAR      Q+  3,I


   LABEL MAP    ENTRY POINT     0   STACK     9
    LABEL  LOCATION   LABEL  LOCATION   LABEL  LOCATION   LABEL  LOCATION
     10=   20    31    20          31    30          46    40          50
     45          63    50          70    60         113   110         124
  $EXIT

  NO. ERRORS=000             NO. WARNINGS=000
  PROCESSOR TIME=0:00:00     ELAPSED TIME=0:00:00

  END OF COMPILE

  END OF PREPARE
  :RUN TENRUN

  HELLO FROM HP 3000 BASIC!  HERE ARE SOME SQUARE ROOTS:

   1              1              1.000000000000000L+00
   2              1.41421        1.414213562373095L+00
   3              1.73205        1.732050807568877L+00
   4              2              2.000000000000000L+00
   5              2.23607        2.236067977499790L+00
   6              2.44949        2.449489742783178L+00
   7              2.64575        2.645751311064591L+00
   8              2.82843        2.828427124746190L+00
   9              3              3.000000000000000L+00
   10             3.16228        3.162277660168379L+00

  END OF PROGRAM
  :

The other example program is "SQR", which calculates the square root and sine of
the numbers from 1 to 10 and 0.1 to 1.0, respectively, in an infinite loop.  It
can be used to show the speed of the simulator in multiples of a real HP 3000
Series III machine, as follows:

  :BASIC

  HP32101B.00.26(4WD)  BASIC  (C)HEWLETT-PACKARD CO 1979
  >GET SQR
  >RUN
  SQR

  A COMPUTE-BOUND PROGRAM TO DEMONSTRATE
    THE SIMULATOR'S 'SHOW CPU SPEED' COMMAND

  LET IT RUN FOR SEVERAL SECONDS TO MEASURE THE SPEED
    AND THEN PRESS CTRL+E TO STOP THE SIMULATION
    AND ENTER 'SHOW CPU SPEED' TO DISPLAY THE SPEED
    IN MULTIPLES OF THE SPEED OF A REAL SERIES III

  THEN ENTER 'GO' TO RESUME THE SIMULATION
    THEN INTERRUPT BASIC BY PRESSING CTRL+Y
    AND ENTER 'ABORT' TO STOP THE PROGRAM
    AND RETURN TO THE BASIC COMMAND PROMPT

Once the program is started, let it run about ten seconds on an otherwise
quiescent host system to allow the speed to be calculated.  Then press CTRL+E
(i.e., control-E, ^E) on the simulation console to suspend simulation and enter
the "show cpu speed" command:

  Simulation stopped, P: 164276 (SUBI 24)
  sim> show cpu speed
  Simulation speed = 36x
  sim>

This shows that the simulator is executing machine instructions approximately 36
times faster than a real Series III.  Finally, resume the simulation, press
CTRL+Y to interrupt the program, enter ABORT to abort program execution and
return to the BASIC interpreter, and then enter EXIT to return to the command
prompt:

  sim> go

  *CONTROL-Y BREAK IN LINE 140 IN SQR
  >ABORT

  >EXIT

  END OF SUBSYSTEM
  :

Before exiting the simulator, MPE must be shut down to ensure that the in-memory
tables are written to the disc.  First log off the system operator's session:

  :BYE

  CPU=15. CONNECT=25. WED, FEB 17, 1988,  6:11 PM
  18:11/#S1/14/LOGOFF ON LDEV #20

Then press CTRL+A to get the system console prompt ("="), enter the SHUTDOWN
command, and then exit the simulator after the CPU halts:

  =SHUTDOWN
  18:11/1/ALL JOBS LOGGED OFF
  SHUT

  Programmed halt, CIR: 030377 (HALT 17), P: 161440 (BR P-1)
  sim> exit
  Goodbye



-------------------------
Creating a New Disc Image
-------------------------

The supplied disc image was created by running the simulator with each of the
four numbered simulator command files (mpe-1-reload.sim, mpe-2-sysdump.sim,
mpe-3-coldstart.sim, and mpe-4-restore.sim) in order, i.e.:

  hp3000 mpe-1-reload
  hp3000 mpe-2-sysdump
  hp3000 mpe-3-coldstart
  hp3000 mpe-4-restore

"mpe-1-reload" performs a RELOAD from the 32002-11018_Rev-2548 Fundamental
Operating Software (FOS) tape image to a new, blank disc image, producing the
bootable image file "mpe-reload.7920.disc".  "mpe-2-sysdump" performs a SYSDUMP
from disc to tape and changes the code segment size from 8K to 16K.
"mpe-3-coldstart" performs a COLDSTART to load the changed configuration to the
disc image.  Finally, "mpe-4-restore" performs a RESTORE to load the compilers
and example programs onto the disc.  The four console logs provided may be
examined to see how MPE was configured.

Finally, the new disc image was renamed from "mpe-reload.7920.disc" to
"mpe.7920.disc", which is the name used by the "mpe-auto" and "mpe-man" command
files to boot MPE.  This allows a new system to be generated without disturbing
the existing system.

The four command files expect these tape images to be present in the same
directory:

  32002-11018_Rev-2548.tape
  subsys-compilers.tape
  examples.tape

The FOS tape image is available from Bitsavers in the same directory that
contains this software kit.  The other two files may be recreated from the disc
image.



--------------------------
Recreating the Tape Images
--------------------------

The "subsys-compilers.tape" and "examples.tape" image files used by the
"mpe-4-restore" simulator command file are not supplied with the kit.  They may
be recreated by submitting the COMPJOB and EXAMJOB jobs to MPE.

After starting MPE, the system operator must first enable job streaming by
entering the "STREAMS 10" command.  Then the "STREAM COMPJOB" command may be
submitted to recreate the "subsys-compilers.tape" image:

  17:37/#S1/14/LOGON FOR: OPERATOR.SYS,OPERATOR ON LDEV #20
  HP3000 / MPE V  E.01.00 (BASE E.01.00).  WED, FEB 24, 1988,  5:37 PM
  :STREAMS 10
  :STREAM COMPJOB
   #J1
  :
  17:38/#J1/15/LOGON FOR: COMPTAPE,MANAGER.SYS,PUB ON LDEV #10
  ?17:38/#J1/16/LDEV# FOR "MT" ON TAPE (NUM)?

At this point, stop the simulator with CTRL+E, attach a new, blank tape image
file to the tape drive, and resume simulation.

  Simulation stopped, P: 071144 (PAUS 0)
  sim> attach -n ms0 subsys-compilers.tape
  MS: creating new file
  sim> go

MPE detects the tape load and reports it to the operator.  Pressing RETURN or
ENTER will bring up the MPE colon prompt.  Enter a REPLY command to inform
process ID number 16 (determined from the console query above) that the tape was
just mounted on LDEV 7.

  17:38/10/Vol (unlabelled) mounted on LDEV# 7
  :REPLY 16,7
  :
  17:38/#J1/15/LOGOFF ON LDEV #10

The job then stores the files to the tape image and completes.

In a similar manner, the "STREAM EXAMJOB" command may be used to recreate the
"examples.tape" image.



-----------
Usage Notes
-----------

 1. MPE-V/R is not year-2000 compliant.  As such, only dates from 1999 and
    earlier are accepted.  The boot scripts select a year whose days of the week
    and leap-year status are identical to the current year.  For example,
    February 29, 2016 is a Monday, as is February 29, 1988.

 2. ATC channel 0 is the system console.  It has its internal CAPS LOCK key down
    by default to accommodate stand-alone diagnostics that require input in
    upper case.  The other channels have CAPS LOCK up by default.  These
    defaults may be changed by placing the appropriate SET ATCDn commands in the
    cold load simulator command file; see the "HP 3000 Simulator User's Guide"
    for details.

 3. ATC channels 1-15 are configured as HP terminals.  As such, they require the
    use of ENQ/ACK protocol.  By default, the ATC simulator is configured to
    handle ENQ/ACK locally, i.e., the ENQ is discarded, and the ACK is supplied
    to MPE by the simulator.  This allows the use of non-HP terminal emulator
    clients.  If you use an HP terminal emulator, you may disable the local
    ENQ/ACK handling and allow the emulator to perform the handshaking, although
    typically this slows down output to the terminal and is not necessary.  If
    you use a real HP terminal, e.g., an HP 2645A, connected to a serial line,
    remote ENQ/ACK handling is required; the ATC will overrun the terminal if
    local handling is configured.  See the "HP 3000 Simulator User's Guide" for
    details.

 4. ATC channel 2 (LDEV 22) is configured as a full-duplex modem connection,
    rather than the hardwired connections used by the other ATC channels.  MPE
    will use the Data Terminal Ready (DTR) signal to drop the connection when
    the user logs out or is forcibly logged out by the system operator.  This
    demonstrates the Terminal Control Interface (TCI) capability.

 5. The languages preinstalled on the disc image are:

      - BASIC (interpreter and compiler)
      - COBOL 68
      - COBOL 74/85
      - FORTRAN 66
      - Pascal
      - RPG
      - SPL

    User-Defined Commands (UDCs) are preinstalled to provide access to the COBOL
    74 compiler with the MPE-V/E COBOLII, COBOLIIPREP, and COBOLIIGO commands,
    and to the COBOL 85 compiler with COBOLIIX, COBOLIIXPREP, and COBOLIIXGO.

 6. Programs generated by the COBOLII and COBOLIIX commands use the HP 32234A
    COBOL II firmware instructions (a.k.a., the "Language Extension
    Instructions").  The simulator must support these instructions, and the CPU
    must be configured to enable them, or COBOL II programs will abort at run
    time with a "PROGRAM ERROR #7 ILLEGAL INSTRUCTION" message.  See the
    simulator release notes ("hp3000_release.txt") for specific firmware support
    information.
