                 HP 32002E MPE-V/R Operating System Software Kit
                 ===============================================
                        J. David Bryan <jdbryan@acm.org>
                             Last update: 2020-01-10


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:

  http://simh.trailing-edge.com/hp/

This package requires Release 8 or later of the simulator.  Earlier releases,
or releases based on SCP 4.x will not work.

Please refer to the following documents from the simulator distribution archive
file when using this kit:

  Filename                  Title
  -----------------------   ------------------------------------
  doc/hp3000_guide.pdf      the "HP 3000 Simulator User's Guide"
  doc/simh_doc.pdf          the "SIMH Users' Guide"
  doc/simh_supplement.pdf   the "SIMH Users' Guide Supplement"
  doc/hp3000_release.txt    the "SIMH/HP 3000 Release Notes"

Problems with the simulator or this software kit should be reported as indicated
in the Release Notes document.

This kit includes the following files:

  Filename              Description
  -------------------   ------------------------------------------------------
  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-restore.sim     a script to RESTORE compilers and examples from tape
  mpe-3-sysdump.sim     a script to SYSDUMP the disc to tape for alteration
  mpe-4-coldstart.sim   a script to COLDSTART the system to load the changes
  mpe-1-reload.log      the console log for the mpe-1-reload.sim script
  mpe-2-restore.log     the console log for the mpe-2-restore.sim script
  mpe-3-sysdump.log     the console log for the mpe-3-sysdump.sim script
  mpe-4-coldstart.log   the console log for the mpe-4-coldstart.sim script
  readme.txt            this documentation file

PDF manuals describing MPE commands are available from Bitsavers at:

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



--------------------
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 "printer.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:

  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 5 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.

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 at
the system console:

  :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 OBTAIN THE SCP PROMPT
    AND ENTER 'SHOW CPU SPEED' TO DISPLAY THE SPEED
    IN MULTIPLES OF THE SPEED OF A REAL SERIES III

  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 obtain an SCP prompt and
enter the "show cpu speed" command:

  scp> show cpu speed
  Simulation speed = 36x

This shows that the simulator is executing machine instructions approximately 36
times faster than a real Series III.  Finally, 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:

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

  >EXIT

  END OF SUBSYSTEM
  :

Note that if you try a SHOW CPU SPEED command while MPE is idle (e.g., while
sitting at the CI prompt), you will get an unrealistic reading:

  :
  scp> show cpu speed
  Simulation speed = 210x

This is because MPE executes a PAUS instruction while idle, and PAUS is
implemented as a tight, two-word microcode loop with no memory accesses and no
instruction fetches.  Consequently, it appears to execute very rapidly to the
simulator, which results in the invalid report.  CPU speed is accurately
measured only when MPE or a user program is busy.


Two example COBOL programs are also provided in the OPERATOR.SYS account.
"COBINT" calculates interest payments, while "COBTAX" calculates a 6% sales tax
on a purchase.  They may be run as follows with the COBOL-II compiler:

  :COBOLIIGO COBINT

  PAGE 0001   HP32233A.02.05  [74] Copyright Hewlett-Packard CO. 1989

  [...]

  LINE # SEQ #   COL  ERROR  SVRTY  TEXT OF MESSAGE
  ------ -----   ---  -----  -----  ---------------
  00040  035000  80    050     W    ARITHMETIC OVERFLOW MAY OCCUR.

  0 ERROR(s), 0 QUESTIONABLE, 1 WARNING(s)

      DATA AREA IS %000370 WORDS.
      CPU TIME = 0:00:00.  WALL TIME = 0:00:00.

  END OF PROGRAM

  END OF PREPARE

  ENTER THE PRESENT VALUE (999999):
  001000

  ENTER THE NUMBER OF TERMS (999):
  036

  ENTER THE ANNUAL INTEREST RATE PERCENTAGE (99V99):
  0400

  PRESENT VALUE ... $  1000
  TERMS ...........  36
  INTEREST RATE ...   4.00%

  THE PAYMENT AMOUNT IS $    29.52

  END OF PROGRAM
  :COBOLIIGO COBTAX

  PAGE 0001   HP32233A.02.05  [74] Copyright Hewlett-Packard CO. 1989

  [...]

  0 ERROR(s), 0 QUESTIONABLE, 0 WARNING(s)

      DATA AREA IS %000245 WORDS.
      CPU TIME = 0:00:00.  WALL TIME = 0:00:00.

  END OF PROGRAM

  END OF PREPARE

  ENTER COST OF SALE (BEFORE TAX) NO DECIMAL PT
  (4 DIGITS MAX) INCLUDE LEADING ZEROS!
  1200
  TOTAL COST OF PURCHASE = $   12.72
  ARE YOU FINISHED? (Y OR N)
  Y

  END OF PROGRAM
  :

The COBOL-II firmware instruction set must be "installed" (enabled) to run
COBOL-II programs.  The supplied simulator command files "mpe-auto.sim" and
"mpe-man.sim" enable the firmware.

Connecting a terminal emulator (e.g., Reflection or QCTerm) via Telnet to local
port 1054 will connect the session to the next available 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
  :

Up to fifteen concurrent terminal sessions may be started independently of the
operator's session running on the system console.

Before exiting the simulator, MPE must be shut down to ensure that the in-memory
tables are written to the disc.  First log off any additional terminal emulator
sessions connected via Telnet with the "BYE" command.  Then log off the
operator's session at the system console:

  :BYE

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

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
  Log file closed

A log of the system console session has been saved in the "mpe-auto.log" file.



-------------------------
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-restore.sim,
mpe-3-sysdump.sim, and mpe-4-coldstart.sim) in order, i.e.:

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

"mpe-1-reload" performs a RELOAD from the MPE-V/R Fundamental Operating Software
(FOS) tape image to a new, blank disc image, producing the bootable image file
"mpe-reload.7920.disc".  "mpe-2-restore" performs a RESTORE to load the
compilers and example programs onto the disc.  "mpe-3-sysdump" performs a
SYSDUMP from disc to tape to change the code segment size from 8K to 16K,
increase the number of terminal buffers per port from 3 to 5, and install the
COBOL II library to the system SL.  "mpe-4-coldstart" performs a COLDSTART to
load the changed configuration and update the system.  The four console logs
provided may be examined to see how MPE was configured.

Finally, the new disc image was renamed manually 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 at:

  http://www.bitsavers.org/bits/HP/HP_3000/32002-11018_Rev-2548.zip

The other two files may be recreated from the supplied disc image as described
below.



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

The "subsys-compilers.tape" and "examples.tape" image files used by the
"mpe-2-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, press CTRL+E to obtain an SCP prompt and attach a new, blank tape
image file to the tape drive configured as unit 0:

  scp> attach -n ms0 subsys-compilers.tape
  MS: creating new file
  17:38/10/Vol (unlabelled) mounted on LDEV# 7

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.

  :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 using the same procedure as above:

  :STREAM EXAMJOB
   #J2
  :
  17:42/#J2/17/LOGON FOR: EXAMTAPE,OPERATOR.SYS,OPERATOR ON LDEV #10
  ?17:42/#J2/18/LDEV# FOR "MT" ON TAPE (NUM)?

  scp> attach -n ms0 examples.tape
  MS: creating new file
  17:42/10/Vol (unlabelled) mounted on LDEV# 7

  :REPLY 18,7
  :
  17:42/#J2/17/LOGOFF ON LDEV #10

Finally, detach the tape from the tape drive by pressing CTRL+E and entering:

  scp> detach ms0

The two tape images are now ready for use by the "mpe-2-restore" command file.



-----------
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
    command file used to cold load the system; see the "HP 3000 Simulator User's
    Guide" section describing the ATC unit options CAPSLOCK and NOCAPSLOCK 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"
    section describing the ATC unit options LOCALACK and REMOTEACK 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. The system SL is changed during the SYSDUMP/COLDSTART to replace the three
    COBLIB segments with their COBOL-II replacements from U00U232A.USL.SYS
    (COBLIB16 and COBLIB18) and a consolidated COBOL replacement from
    COB68LIB.PUB.SYS (COBLIB14).  This allows both COBOL and COBOL-II programs
    to run.

    SYSDUMP will generate two warnings when the COBLIB16 and COBLIB18 segments
    are added:

      *** WARNING ***
      ERROR #48 CODE SEGMENT MAY BE TOO LARGE

    These may be ignored, as the code segment size was also increased during the
    SYSDUMP process.

    SYSDUMP also reports:

      **WARNING** FOLLOWING SYSTEM FILES NOT DUMPED 
      HIOCTAP0.PUB.SYS
      HIOCIPR0.PUB.SYS
      IONRDR0.PUB.SYS

    This warning is expected and may be ignored.

 7. Programs generated by the COBOLII and COBOLIIX commands use the HP 32234A
    COBOL II firmware instructions (a.k.a., the "Language Extension
    Instructions").  The simulated CPU must be configured to enable these
    instructions, or COBOL II programs will abort at run time with a "PROGRAM
    ERROR #7 ILLEGAL INSTRUCTION" message.  As noted above, the supplied
    simulator command files "mpe-auto.sim" and "mpe-man.sim" enable the
    firmware.

 8. File transfers using the Reflection terminal emulator and its associated
    PCLINK2.PUB.SYS program are supported under simulation.  The simulator must
    be configured to use 8-bit transfers, remote ENQ/ACK, and no alphabetic
    upshifting on the ATC channel to be used for file transfer.  In addition,
    MPE must be configured to use 8-bit transfers for the channel, e.g., by
    specifying the TERM=12 parameter when logging on.  See the "Terminal Data
    Interface" subsection of the ATC section in the "HP 3000 Simulator User's
    Guide" for further configuration details.
