Running VMS/VWS Crash Course

00README

This presumes you are using the disk image from bit.ly/smalltalk-80-vax
and the 2019 version of SIMH from https://www.9track.net/simh/vax4xx .

To run simh:

    $ bin/vax42b

If you have simh's autoboot turned off, you'll need to do:

    sim> boot

At the VAXstation boot console prompt ">>>", do this:

      >>> boot dka0

When you get a blank gray screen, click the mouse to get a menu.
Choose "Create a new VWS VT200 window."

For running programs, including SMALLTALK:
	Username: smalltalk, password: smalltalk

See the file USAGENOTES for more tips.

01USAGENOTES

----------------------------------------------------------------------
Notes from hackerb9 for the complete VAX neophyte.

1. Download and compile simh. Our disk image requires the 2019 version
   from 9track.net/simh/vax4xx.

2. Download the diskimage from https://bit.ly/smalltalk-80-vax
   https://drive.google.com/file/d/1Y-pTtTul_StKfrVg4QHHFFsg1g4qbzex/

   Extract the data directory and bin/simh.ini.

3. Run it:

    $ bin/vax42b
    sim> boot

      >>> [Hit Enter for English, if it asks]
      >>> show dev
      >>> boot dka0

When you get a blank screen, click the mouse to get a menu. Create a
new VWS VT200 window.

        Username: smalltalk,
        Password: smalltalk

----

TO SHUTDOWN:

create a new VT200 window, login as system/system and type 'shutdown'.
At the sim> prompt, 'quit'

If you can't shutdown properly, you can use Ctrl/E at the sim> prompt.

----

BUG IN THIS VERSION: 

Mouse is erratic in the version of SIMH from 9track.net/simh/vax4xx.
Moving it slowly seems to help, but not much. See COMPILATION below.

Keyboard shortcuts:
    Cycle between windows       F5                       {just like a VT340!}
    Resize                      SET TERM/WIDTH=132/HEIGHT=48
    Move mouse pointer          CTRL/SHIFT/↑ ↓ ← →
    Mouse buttons               CTRL/SHIFT/E4, E5, E6

======================================================================
SUPER DUPER BASIC INTRO TO VMS

----------------------------------------------------------------------
UNIX<->VMS Rosetta stone

    echo                WRITE SYS$OUTPUT
    ls                  DIR
    less                TYPE /P
    pwd                 SHOW DEFAULT
    rm                  DELETE
    mkdir subd          CREATE/DIR [.SUBD]
    cd subd             SET DEFAULT [.SUBD]
    cd ..               SET DEFAULT [-]
    cd ~                SET DEFAULT SYS$LOGIN
    cd /tmp             SET DEFAULT SYS$SCRATCH
    alias p=echo        P :== "WRITE SYS$OUTPUT"
    esc=$'\e'           ESC[0,8] == 27
    st="$esc\\"         ST == ESC+"\"
    read x              READ SYS$INPUT X
    read -p "foo" x     INQUIRE X "foo"

----------------------------------------------------------------------
Editing a file using EDIT ("EDT")

Type: EDIT FOO.COM

At the * prompt, type 'c', then 'ENTER'. Now you can use the arrow
keys to insert text.

Press Ctrl/Z to get back to the * prompt.

Type 'EXIT' to save your changes.
If you want to quit without saving use 'QUIT'.

----------------------------------------------------------------------
VMS versioning

VMS marks versions of a file as a number after a semicolon.
E.g., FOO.COM;42   FOO.COM;37  FOO.COM;30   FOO.COM;17

* The most recent file:  omit the semicolon and number.
* The previous version: ;-1
* The oldest version: ;-0 

To delete all the old versions of all files in the directory and keep
just the latest, use the command PURGE.

----------------------------------------------------------------------

.COM files (DCL scripts) are lists of VMS commands. For example,
LOGIN.COM is run automatically when you first login. Use @ to run.

See the file BASICDCL for super quick intro. 

----------------------------------------------------------------------

Arrow keys work for command line editing, but the VMS default is to
OVERWRITE instead of INSERT letters as you type. You can hit Ctrl/A to
toggle that one time, or add this to your LOGIN.COM:

        SET TERMINAL/LINE_EDITING/INSERT

See: HELP LINE_EDITING, for information about control keys.

======================================================================

COMPILATION OF SIMH SOURCE

As of 2024, hackerb9 suggests using the source from
https://www.9track.net/simh/vax4xx/, which is from 2019. Use `make
vax42b` to compile. It will tell you if you are missing any libraries.
Move the binary from BIN/vax42b to this directory's bin/.

Unfortunately, that source code is old and has a major bug: the mouse
doesn't work. Likely that is because this bug is unpatched:
https://github.com/simh/simh/issues/272.



----

Compiling the latest source from git, as of 2024-Apr-22, did not work
for me. What I tried:

   git clone https://github.com/simh/simh
   make vaxstation3100m38
   Then, copy BIN/vaxstation3100m38 to this bin/ directory. 

The machine seemed to work in that the KA42-B boot loader comes up and
'show dev' shows that the disk is attached, but typing 'boot dka0'
just hangs on a screen reading "-DKA0_", using 100% CPU. VMS never
started. I had to use Ctrl/E at the simh> prompt to abort the
simulation.

I tried various things, like 'load -r ka42b.bin' to use the boot
loader from the 2019 version, but nothing worked as I have no idea
what I'm doing.

02BASICDCL

Barebones intro to VMS shell scripts
======================================================================

.COM files ("DCL" scripts) are lists of VMS commands. For example,
LOGIN.COM is run automatically when you first login.

Use @ to run a COM file: @LOGIN

----------------------------------------------------------------------

$ Every line must start with a dollar sign.
(otherwise it is "data" and is not executed).

! Comments start with a bang
$! (But for some reasons dollar-bang seems to be de rigueur).

----------------------------------------------------------------------
Variable Assignments

    $ esc[0,8] == 27
    $ ST == esc+"\"
    $ p :== "write sys$output"

There all sorts of different flavors of assignments in DCS —
yes, "==" is an assignment! — you can try them all and see what works: 
=, ==, :=, :==. Or, use VMS's 'HELP' and then choose '=' and ':=' and
see the ATTRIBUTES and EXAMPLES to learn more.

----------------------------------------------------------------------
Parameters and Variable Expansion

P1, P2, ... are the command line arguments given to a .COM script.

    $ IF P1 .EQS. "" THEN P1=240

To force variables to expand when inside a string use ticks, for
example:

    $ p "P[800,''P1']"

Note that two quotes in a row inside a string evaluate to a single
quote. Add spaces if necessary:

    $ p "T' ''P1' '"

----------------------------------------------------------------------
Comparisons, similar to FORTRAN but also handles strings.

        .EQ.	Numerically equal to
        .NE.	Numerically not equal
	.GT. 	Greater than
	.LE.	Less than or equal to 
	.EQS.	Equality for Strings
	.GTS.   Greater than for strings (alphabetically later)

	.AND.	.OR.	.NOT. 	Boolean operators

    $ COUNT = 0
    $ LOOP:
    $ COUNT = COUNT + 1
    $ IF COUNT .LE. 10 THEN GOTO LOOP

    $ IF (P1 .EQS. "A") .OR. (P1 .EQS. "B") THEN GOTO 'P1'
    $   GOTO DEFAULT
    $ A:		! Process option A
      ...
    $ EXIT
    $ B:		! Process option B
      ...
    $ EXIT
    $ DEFAULT:		! Default processing 
      ...
    $ EXIT

----------------------------------------------------------------------
Label: and GOTO work the same as in C¹

    $  COUNT = 0
    $  LOOP:
    $      COUNT = COUNT + 1
    $	   IF P'COUNT' .EQS. "" THEN EXIT
    $	   APPEND/NEW &P'COUNT' SAVE.ALL
    $	   DELETE &P'COUNT';*
    $	   IF COUNT .LT. 8 THEN GOTO LOOP
    $  EXIT

The above example deletes the files given on the command line after
concatenating them into a file called "SAVE.ALL".  Essentially: 
`cat "$@" >save.all && rm "$@"`.

____
Footnote ¹ Except that, unlike C where GOTO is considered "harmful" and 
	   is deprecated, in DCL it is MANDATORY. :-)

----------------------------------------------------------------------
Reading input from the terminal

    $ INQUIRE VARIABLE- 
      "Enter command (DELETE, DIRECTORY, PRINT, PURGE, TYPE)" 

(Bonus: a minus sign at the end in DCL means "continued on next line".)

----------------------------------------------------------------------
Printing the Escape character

Example from hackerb9's LOGIN.COM:

    $ esc[0,8] == 27
    $ CSI == esc+"["
    $ ST == esc+"\"
    $ p :== "write sys$output"

That creates a command "p" that can be used to test out ReGIS and
Sixel graphics, like so:

    $ p esc,"PpW(C)C[+100]",ST

======================================================================

Further Reading:

"Chapter 15: Programming with Command Procedures" in OpenVMS User's Manual:
https://www0.mi.infn.it/~calcolo/OpenVMS/ssb71/6489/6489p026.htm#chapter_15

README.original

----------------------------------------------------------------------
Original FreeBSD post:

> On FreeBSD (tested on FreeBSD 12.1-RELEASE-p3 GENERIC  amd64):
> $ cd bin
> $ ./vaxstation3100m38 simh.ini

> With little mouse movements and waiting for the pointer to stabilize after each,the graphical desktop is workable, provided you are very patient. Matt is aware of this.

> Original post by Mark Wickens <mark@wickensonline.co.uk> announcing this distribution for Windows on his declegacy mailing list:

>> Good morning!

 

>> As discussed on the HECNET mailing list, I’ve built and packed up the DEC implementation of Smalltalk-80 as a SIMH executable image for Windows based on Matt’s excellent implementation of the VAXstation 3000 M38 with graphics (see https://www.9track.net/simh/vax4xx/ for more information)

 

>> Matt’s code is integrated into the mainstream SIMH GIT repository and can be built for linux as well.

 

>> The Smalltalk-80 VAX virtual machine zip file is here: https://1drv.ms/u/s!ApYWbrbJ9DxCga49cZ0wi0M4l2KqbQ?e=XWKv4K

>> This virtual machine is running VAX/VMS V5.5-2H4 with VWS graphics.

 

>> You can unpack this anywhere, my location is c:\vax. If your location is different please edit the line in simh.ini to reflect the new location:

 

>> ; Attach non-volatile RAM to a file

>> attach nvr c:\vax\minerv\VAXstation3100M38.nvr

 

>> The instance is configured to not start DECnet. If you are connected to HECnet starting networking will cause problems as it is configured for my area.

>> There are two accounts: SYSTEM password SYSTEM and SMALLTALK password SMALLTALK.

 

>> To run Smalltalk-80 login as SMALLTALK (left click on graphics display and select VT200 terminal) and type

 

>> $ smalltalk

 

>> You will see a new window that can be resized by clicking top-left on the window and menu option ‘change the size’.

 

>> I’d recommend reading the Smalltalk-80 PDF ‘Bits of History’ that describes this implementation of Smalltalk.

>> Also the ‘Smalltalk-80 Integrative Programming Environment’ and ‘Smalltalk-80 The Language and it’s Implementation’ books, both available online as PDFs.

 

>> The source code is written mostly in MACRO-32 with a C file to interface with the VWS graphical environment. There is a build script BUILD.COM that will build and link the executable from the source code. The C compiler is installed in the image, so it can be rebuilt.

 

>> Enjoy!

>> Mark.

 

>> M0NOM

simh.ini

; Microvax 3100 M38 SIMH boot configuration file
;
;set async

set cpu 32m

; Attach non-volatile RAM to a file
attach nvr data/VAXstation3100M38.nvr

;set vc capture
;set vc enable
; for text console only, comment cpu model
; for graphical console, set qvss/qdss capture and vaxstation/vaxstationgpx
; based on vaxstation-mouse-comparison.pdf in the doc directory.
; note the issues with mouse capture in graphics modes (DECwindows)
SET QVSS CAPTURE
SET CPU MODEL=VAXSTATION
;The following could be color, but it is buggy as of 2024
;SET QDSS CAPTURE
;SET CPU MODEL=VAXSTATIONGPX

;set lk debug
;set vs debug

attach rz0 data/minerv-dka0-system.vdisk

set cpu idle=VMS
set cpu conhalt
set console brk=10

; Now start the emulator
boot cpu
exit