pForth 2.0.1 for OpenVMS VAX 7.3  --  a Forth system (ANS-like) built with DEC C
===============================================================================

pForth is Phil Burk's portable Forth written in ANSI C (https://github.com/philburk/pforth).  This
kit is a build of the 2.0.1 release for OpenVMS VAX with four small patches (see SOURCES.TXT), the
dictionary image, pForth's own Forth library files and five example programs.

Using it
--------
  $ @SYS$COMMON:[SYSLIB.FORTH]FORTH_SETUP          (once per login)
  $ PFORTH                                         (interactive; end with BYE)
  $ PFORTH "-q" MYPROG.FTH                         (load a file quietly, then the prompt)

DCL upper-cases an unquoted argument, so a switch must be quoted: "-q" (quiet), "-i" (build a
dictionary).  With SYS$INPUT redirected (DEFINE/USER SYS$INPUT NL:) PFORTH leaves at the end of
its input; interactively use BYE.

  Forth words you can try, one per line:   1 CELLS .   -1 U.   : SQUARE DUP * ;  7 SQUARE .
  Floating point:  2E0 FSQRT F.             Files:  S" X.TMP" W/O CREATE-FILE   (VMS names work)
  Words added for VMS:
    SYSTEM      ( c-addr u -- n )   run a DCL command in a subprocess, status on the stack
                                    S" SHOW TIME" SYSTEM .
    CLOCK       ( -- ticks )        CPU time of the process in 10 ms ticks (C clock())
    CLOCKS/SEC  ( -- n )            ticks per second (100)
  In pForth an interpreted S" gives a transient buffer: use the string at once, or define a word
  (: NAME S" ..." ;) to keep it.  S\" understands \" for a double quote.

What is installed (SYS$COMMON:[SYSLIB.FORTH])
  PFORTH.EXE, PFORTH.DIC   the interpreter and its dictionary (cells are 32 bits)
  [.FTH]                   pForth's Forth library: CASE.FTH, FLOATS.FTH, LOCALS... and its tests
                           (T_*.FTH); logical PFORTH_FTH points here
  [.EXAMPLES]              five programs, expected output, RUN_EXAMPLES.COM (logical FORTH_EXAMPLES)
  [.FIG]                   VAX-11 fig-Forth 2.0 (1985), if present: command FIGFORTH, screens FORTH0:
  FORTH_SETUP.COM          per-user setup; FORTH_INSTALL.COM / FORTH_UNINSTALL.COM (manifest based)
  README.TXT, LICENSE.TXT, SOURCES.TXT

fig-Forth 2.0 (VAX-11, 1985, MACRO-32, unchanged)
-------------------------------------------------
  $ FIGFORTH                 (after FORTH_SETUP; end with BYE; there is no prompt, answers say OK)
  It is the historical fig-Forth: upper case words, no recursion by name inside a definition
  (the word is hidden until the closing semicolon), loops only inside definitions, block screens in
  FORTHn: directories ( 0 DIR selects FORTH0: = the kit's [.FIG] with its *.FIG library screens ).
  HELP word        prints the glossary entry (HELP DIR);  NEED word  loads a library screen.
  To keep your own screens: $ DEFINE FORTH1 SYS$LOGIN  then in Forth  1 DIR  (the kit's directory
  is read-only for ordinary users).  Documentation: FIGFORTH.MEM, FIGFORTH_README.TXT in [.FIG].
  Not used: the 1985 prebuilt FGFORTHV2.EXE; the kit's image was built from the MACRO source here.

Examples (as any user, after FORTH_SETUP):
  $ @FORTH_EXAMPLES:RUN_EXAMPLES                   (compares each output with its .EXP file)

Installing and removing (as SYSTEM or another account with SYSPRV; nothing outside the tree is
touched: no INSTALL, no startup file, no accounts, no system logical names)
  $ @FORTH_INSTALL [saveset] [REPLACE]
  $ @SYS$COMMON:[SYSLIB.FORTH]FORTH_UNINSTALL [CHECK]

Known limits (measured, VAX 7.3, DEC C 6.4)
  * Integers are 32 bit; double-cell words give 64 bits.  Floating point is G_float (about 1E308).
  * RESIZE-FILE cannot shrink a file (C RTL lacks freopen(NULL,...)); extending works.
  * There is no line editor or history (the portable "stdio" platform I/O is used).
  * Include files of any record format load completely (EDT/EVE/TPU files, VFC, Stream_LF).
    ONLY SAVE-INPUT / RESTORE-INPUT need Stream_LF: pForth computes file positions by byte
    arithmetic, so a program that uses them silently stops loading from a variable length record
    file.  Fix: @SYS$COMMON:[SYSLIB.FORTH]FORTH_STMLF file-spec  (CONVERT to Stream_LF).
    The kit's own .FTH files are already Stream_LF.
  * pForth's own tests on a VAX 4000/90 (T_*.FTH in [.FTH]): T_COREX 124 of 124, T_STRINGS 58 of 58,
    T_LOCALS 9 of 9, T_ALLOC 1 of 1, T_FLOATS 59 of 60 (VAX floating point has no negative zero, so
    0.0 -0.0 0.0 F~ is true, not false), T_FILE 88 of 94 (RESIZE-FILE cannot shrink a file, and
    what depends on it).

Kit by Douglas P. Fields, Jr. (symbolics@lisp.engineer), 15-OCT-2026.