README.TXT      30-Oct-2026

Welcome to XPLW, the Windows version of the XPL0 programming language.

The main advantage of XPLW is that it makes native compiled programs that
run directly under Windows 7 through 11.

Microsoft's ml64 assembler is required. It's available free with the
Visual Studio C++ build tools.

Programs compiled with XPLW run substantially faster than with other
versions of XPL0. For instance, the Sieve benchmark runs about twenty
times faster than under DOSBox.

XPL files can be compiled, assembled, and linked into EXE files using the
included batch file. For example,

        xx hello

creates hello.exe, which can be run from a Command Prompt window. It can
also be run from File Explorer, although a console program's window may
close too quickly to see its output.

Built-in graphics have always been an important feature of XPL0, and
video games are a good way to demonstrate this. Poker and Mineswpr are
included to get you started. Cubic, Fountain, and Baubs provide
additional graphics demos.

Most XPL0 programs for DOS and Raspberry Pi compile and run without
changes. Some require an adjustment for the larger integer size. In
particular, programs that contain

        IntSize = 4

need this changed to 8, because XPLW integers occupy eight bytes.

XPLW defaults to terminating text strings with a zero byte. Other
versions of XPL0 default to terminating strings by setting the most
significant bit of the last character. If this difference prevents a
program from working, add

        string 1;

near the beginning of the program to restore MSB termination.

Windows 11 Defender can occasionally delete some XPLW EXE files without
warning. The 2048.exe program is particularly susceptible. If necessary,
this can be prevented by adding the XPLW folder to the Windows Defender
exclusion list.


WHAT'S NEW

The F11 key alternates graphics displays between windowed and fullscreen.

A feature recently added to all versions of XPL0 is the constant byte
array. It's similar to the traditional constant array, except its
elements are restricted to byte values in the range -128 to 255. Braces
instead of brackets indicate byte elements. For example,

        Array:= {123, $FF, -23, ^A};

Byte arrays are limited to one dimension. They are especially useful
when porting arrays among the 16-, 32-, and 64-bit versions of XPL0.

XPLW intrinsic 34, WinCall, enables programs to call many Windows API
functions. It has the form

        ReturnValue:= WinCall(LibFileName, ProcName, rcx, rdx, r8, r9);

For example,

  R:= WinCall("user32.dll", "MessageBoxA", 0, "Hello World!", "Test", 0);

displays a popup message box. R = 0 if an error is detected.

XPLW intrinsic 35, MidiMsg, provides a simple way to play MIDI notes. For
example,

        MidiMsg($90, 60, 100);

plays middle C (note 60) on channel 0 using the default Acoustic Grand
Piano, with velocity (volume) 100. A useful guide to MIDI messages is:

        https://midimusic.github.io/tech/midispec.html


NOTABLE XPLW DIFFERENCES

The required file code.xpl is simply stored in the current directory,
rather than in the former path c:\cxpl\

The MAlloc intrinsic allocates bytes, not 16-byte paragraphs. The largest
single allocation observed in testing is about 1,990,000,000 bytes.
Segment addressing is no longer needed and was dropped long ago.

Printer device 2 must be closed to flush the Windows spooler and actually
print. The faster device 5 must also be closed, but this has always been
the case. The "Generic Text Only" printer driver is strongly recommended.

Display devices 0 and 6 maintain separate text cursor positions when
operating in text (non-graphic) modes.

Attribute colors in text modes do not use the palette colors set by
SetPalette. Instead, they use the standard Windows console colors.

SetVid(1) does not produce a 40-character-wide text screen. However, text
displayed in 320x200 graphics modes still uses wide characters as before.

The Random number intrinsic (Ran) currently provides only 31-bit values.

Integer divide-by-zero aborts the program without displaying an error
message. The resulting errorlevel is $C0000094 (displayed in decimal).
Interrupt vectors cannot be hooked as they could under DOS. Windows
exception handling using .try and .except might provide an alternative.

The multitasking intrinsics available in the Raspberry Pi version, such
as process:= Fork(processes), are not implemented. The Allsorts and
Manxome programs require these intrinsics.

The following features are not implemented in XPLW, and probably never
will be:

        serial device 4
        'eproc', 'efunc'
        'segment' arrays
        'short' reals

The following DOS intrinsics were never ported to the Raspberry Pi
version, and are also not implemented in XPLW:

        ExtCal, Irq, Equip, Shrink, ExtJmp, IntRet, PIn, POut, Peek,
        Poke, Blit, GetReg, SoftInt, Read, Write


I'll be glad to help anyone trying to get any version of XPL0 working.

Happy computing!
Loren

loren.blaney@gmail.com
