Wang Disk Basic Cheat Sheet

Wang Disk BASIC is a complicated arrangement of three basic
access modes mixed in with some unusual syntax and age-appropriate limitations.
This quirkiness is part of the charm of a BASIC dialect, and Wang has plenty
if it.

If you never used Wang BASIC, or it has been a long time, it would be
way too frustrating to expect you to guess how to do some simple operations
or to figure it out by reading a large manual.

The purpose of this page is to describe a few key Wang Disk BASIC concepts
and the most important commands. If you really want to understand
Wang Disk BASIC, then you'll just have to read the manual.

Wang Disk BASIC offers three access modes to the contents of a disk.
The BASIC exposes a lot of details of the disk system, and the burden is
on the programmer/program to manage things more so than any modern OS,
and even as compared to Microsoft Disk BASIC circa 1976.

All disks, from the smallest floppy to the largest hard disk uses a
256 byte sector as the atomic unit of transfer. Disks start with sector 0
and increase up to the limit of the number of sectors on the disk. A disk
can have at most 32768 sectors (65536 in BASIC-2), or about 8 MB (16 MB).
Although programs can build whatever file access mechanisms they want via
reading and writing arbitrary sectors, all the intrinsically supported file
mechanisms assume a file is allocated in a contiguous range of sector
addresses. That is, a file begins at sector N, the next sector is at N+1,
the next at sector N+2, etc., up to N+k-1, where k is the number of sectors
in the file.

Perhaps the Wang file allocated policy should be viewed more like a
random access tape. Once a file occupies a section of the disk, it
can only be expanded by moving the file to a larger open range of sectors
on the disk, or by overwriting whatever is on the sectors immediately following
the file. The programmer must spend a lot more time managing the
details of the file policy on the disk.

DA -- data access mode. This mode is
used to read or write streams of data to contiguous sectors forming a file.
Three bytes of each sector contain file meta information, such as whether
the block marks the start of the file, is the middle of a file, or is the
end of a file. Also, the remaining 253 bytes consist of a continuous
stream of <TAG><DATA> pairs, where the TAG byte (such as "number"
or "string") specify how to interpret the following DATA bytes.

DC -- Catalog file access (DC). The focus
of this page is on the third mode, the catalog file commands. This
provide the most convenient mechanism for using disks for all but the power
user. The rest of this document discusses only DC mode. Please
read the Wang Disk BASIC reference manual to learn more about the other
modes.

DC mode reserves a fixed number of sectors at the start of the disk to
contain a catalog of files on the disk. The catalog is flat, i.e.,
there are no nested directories -- just a list of filenames and locations.

In DC mode, the first 16 bytes of the first sector of a disk contains
a small amount of data describing a few key parameters of that disk's structure
for use by the DC commands. If a disk won't be operated on by the
DC commands, then this information doesn't have to be present and all sectors
of the disk can be used by the program.

the number of sectors set aside for the file catalog

the number of sectors set aside for cataloged files

The first parameter sets aside sectors 0 through N-1 of the disk to contain
a list of the files on the disk.

The second parameter allows a programmer to tell the DC commands to
use only the first N sectors of the disk, leaving any remaining sectors
for self-managed file operation.

Wang disk controllers supported up to four disk drives, arranged as two pairs.
To keep things simple, the rest of this document assumes two disk drives
attached to a given controller.

The first of each pair was called the fixed disk, and the second was the
removable disk, referenced as F and R respectively. Although this naming was
appropriate for the first disk drives produced by Wang, it didn't have any
bearing on reality for other models of disk controllers and disk drives
(e.g., a dual floppy system). Perhaps it is best to think of disk F as
"drive 0" and disk R as "drive 1".

Typographic Conventions

In all of the syntax examples below, the following typographic conventions
have been followed to make it clear what is literal syntax and what is
a dummy field representing the type of thing that needs to be entered.

{THIS|THAT}

represents that either THIS or THAT needs to be typed, but not both.

[OPTIONAL]

represents that the parameter OPTIONAL can be there but doesn't have to be.

italics

represents something that should be replaced with a number or string.

Most commands allow an optional controller I/O address to be specified,
in hex. This parameter is shown as "[/dev]" below. If the address
isn't specified, it was whatever the most recent "SELECT DISK" command
specified. If that command hasn't been performed, then it defaults
to /310.

After a new disk has been created or reformatted, all the sectors will
be set to 00 bytes. This command initializes sector zero of the disk
with a small record of how the disk is structured for use by the DC (catalog)
commands. If a disk will not be operated upon by a DC command, then
the SCRATCH DISK command doesn't need to be performed on a disk.

Either the fixed (F) or removable (R) disk drive connected to the controller
must be specified.

Optionally, a disk controller address can be specified, in hex.

Optionally, the LS parameter specifies how many sectors should be set
aside to hold the catalog of filenames. Each sector set aside contains
the name and parameters for 16 files. However, the first sector contains
room for only 15 names since the first slot is reserved to hold the disk
structure bytes.

Examples:

SCRATCH DISK F END=300

Initialize the disk in the first drive, using the first 300 sectors to hold
the file catalog and all the cataloged files. The default number (24) of
sectors are set aside for holding the file catalog, and the rest, 300-24,
are for holding files.

SCRATCH DISK F LS=4, END=300

Initialize the disk in the first drive, using the first 300 sectors to hold
the file catalog and all the cataloged files. Four 4 sectors are set aside
for holding the file catalog, and the rest, 300-4, are for holding files.
These four catalog sectors can hold up to 16*4-1, or 63, files. In practice,
it is like that fewer files can be held, as there is a hash that maps which
sector a given filename will be stored.

SCRATCH DISK F/320 LS=4, END=300

This is like the last one, except it is the first drive of the disk controller
at address /320.

SCRATCH DISK R LS=64, END=15000

This initializes the second drive of the pair of the controller at the
default address (/310 by default, unless the SELECT DISK command has
changed it). 64 sectors are set aside for the catalog, and 15000 sectors
total are assigned for the catalog plus the files themselves.

In this example, there are four programs. The first part of the output
lists the information established by the SCRATCH DISK command, namely that
the first four sectors have been reserved for holding the disk catalog,
and that anything after sector 300 is reserved for use by the programs.
The first three entries have type "P" meaning they are executable programs,
and the fourth entry, MSTRMIND, has type "SP" indicating that the program
has been SCRATCH'd (erased), and thus can't be executed. Although
this disk doesn't have any data files, they are indicated with a "D" in
the TYPE column.

The START column indicates which sector the file begins on; END indicates
which sector is the last of the file, and USED is how many of the sectors
are in use by that file. It is possible to preallocate space for
a file on the disk and not use all of it, in which case USED is less than
(END-START+1).

Examples:

LIST DC F

List the files in the first drive of the controller at the default disk
address (/310 normally).

LIST DC R

List the files in the second drive of the controller at the default disk
address (/310 normally).

Examples:

This command actually doesn't erase the program or release the area for
further use. Instead, it simply marks the file for later removal.
In the meantime, the program can't be loaded. When a "LIST DC" command
is performed, scratched files show up with an "S" as part of the TYPE field.

Examples:

In both of these commands, the drive letter is the source drive
and the second letter is the destination drive.

MOVE operates on cataloged disks and copies all non-scratched programs
from one drive to the other drive,
skipping any that are marked as being SCRATCH'd. A common operation
is to MOVE from the F drive to a scratch disk in the R drive, and then
to immediately MOVE or COPY it back to the F drive.

COPY just does a blind sector by sector cloning from one drive to the
other drive. As such, it works for both cataloged and non-cataloged disks.
The command requires specifying the range of sectors to copy.
For the common case of cloning a disk, first sector will invariably be 0.
The second sector is determined by the size of the disk. Use the disk
inspector to find how many sectors the disk has, then use one less for the
second sector.

For instance to clone an 8" disk (which has 1024 sectors) in the first drive
to another disk in the second drive, issue the command