DT2K2
Extended uuencoders, uudecoders, screenshot compressor,
media transfer and plain-text listing loader
Greg Cook, 1/Aug/2002

CONTENTS

autodsk.txt	Transfers disc files to tape
autotpe.txt	Transfers tape files to disc
dd.txt		Uuencodes disc as image in .SSD format
dt.txt		Uuencodes tape with BBC header information
dtx.txt		As DT but with better unlock code and faster CRC
dtxasm.txt	Assembles machine code image used by DTX
readme.txt	Documentation for all files in DT2K2
sloadas.txt	Assembles SLOAD screenshot decompressor
ssaveas.txt	Assembles SSAVE screenshot compressor
txtload.lst	Numbered text listing of TXTLOAD (for offline systems)
txtload.txt	Loads un-numbered text listings of BASIC programs
uudecod.txt	Simple uudecoder which restores data only
uupromp.txt	As UUDECOD but prompts remote host to send next line

SYSTEM REQUIREMENTS

All programs in DT2K2 require a BBC Micro, model B with OS 1.20 and BASIC
II, however they are readily adaptable to other specifications.  See
COMPATIBILITY and BUGS below.  Machines with a 6502 second processor fitted
should be able to run AUTODSK, DD, TXTLOAD, UUDECOD and UUPROMP as
supplied.

INSTALLATION

The programs in DT2K2 are distributed as un-numbered text listings.  If the
text files are already on a BBC diskette, the TXTLOAD utility can load them
into BASIC for use.  See TXTLOAD below.  After converting each program, it
is strongly recommended to SAVE it in tokenised format and no longer use
the text listing.

Alternatively, these files can be transferred to the BBC micro over a
serial connection.  You will need to be familiar with a terminal or
terminal emulator, and be able to receive text in both directions between
the BBC micro and the terminal.  The technique for doing this is described
elsewhere.

Before starting to transfer, save all important data to diskette then reset
the BBC micro.  When the micro and terminal have been set up, type the
following on the micro's keyboard, pressing the RETURN key after each line:

	*FX 181,0
	*FX 230,1
	*FX 3,1
	*FX 2,1

The micro will be under control of the terminal until BREAK is pressed.

To transfer UUDECOD, enter the following on the terminal:

	NEW
	AUTO

Using the terminal's commands send the contents of uudecod.txt to the
micro.

When the file is finished press ESCAPE on the terminal, then enter:

	SAVE "UUDECOD"

to save the program in the usual way.  Repeat this procedure with the other
program texts.  Save the programs under the following filenames:

autodsk.txt	AUTODSK
autotpe.txt	AUTOTPE
dd.txt		DD
dt.txt		DT
dtx.txt		DTX
dtxasm.txt	A.DTXASM
sloadas.txt	A.SLOADAS
ssaveas.txt	A.SSAVEAS
txtload.txt	TXTLOAD
uudecod.txt	UUDECOD
uupromp.txt	UUPROMP

To complete the installation, run the three assembler programs as described
below.

ASSEMBLY

Before assembly, save all important data to diskette and reset the BBC
micro.  Enter the following:

	PAGE = PAGE + 512
	CHAIN "A.DTXASM"

Follow the instructions printed by the assembler.  Then enter:

	CHAIN "A.SLOADAS"
	CHAIN "A.SSAVEAS"

Each program will generate a listing.  Installation of DT2K2 is now
complete.

AUTODSK

AUTODSK reads files on one side of an Acorn DFS disc (or one volume of a
DDOS disc, if DDOS is installed) and saves them on cassette in the order
the files are written in the catalogue.
Enter CHAIN "AUTODSK" and simply type the number of the drive to be read.
Under DDOS you will also be prompted to type a volume letter.

Files in directories other than $ are saved under their full 1.7 filename.

Files in $ are saved under their 7-character name.  The lock attribute is
not preserved.

AUTOTPE

AUTOTPE reads up to 31 files from cassette and saves them to the currently
selected drive and directory.  No user input is required, except for the
ESCAPE key to stop the program.

This program is designed to read files with DFS-compatible names.  Up to 9
characters of the cassette filename will be passed to the DFS, which will
still reject bad DFS filenames.

NB: Do not use AUTOTPE to transfer files larger than 23.25 KB (&5D00.)

DD

To use DD, enter LOAD "DD" then insert the disc to be sent.  Enter RUN and
you will be prompted for an image name and drive number.  For example:

	Image name:games_0.ssd
	Drive:0

DD prints to standard output (the OSWRCH output stream) a uuencoded image
of the Acorn DFS single-density disc in the specified drive.  The program
skips the blank portion of the disc, and tests for *COMPACT-ness while
finding the last used sector.  To force the whole disc to be sent, replace
the fifth line with a statement such as H%=800 (80 track disc) or H%=400
(40 track disc.)

To simplify the code (greatly), DD writes 45 columns instead of the usual
61, so lines begin @ instead of M.  The output contains standard BBC
linefeeds; if these are converted to DOS or Unix format it will be readable
with WinZip (if saved as filename.uu) or with /bin/uudecode on Unix
systems.

DT

To use DT, enter CHAIN "DT" and when the program is loaded, play the tape
to be sent.  Watch the BBC's screen for cassette messages to rewind the
tape.  After the last file has been loaded, wait until 'Searching' is
displayed, then press the BBC's ESCAPE key.  (The one on the terminal will
be ignored while the tape interface is busy.)  Pressing ESCAPE is important
in order to save the header information of the last file.

DT prints to standard output (the OSWRCH output stream) a Unix shell
archive containing uuencoded files from a BBC cassette.  Each cassette file
is accompanied by a .inf file listing its attributes (load address,
execution address, locked/unlocked status and CRC code, plus the name of
the next file on the tape.)  The .inf file is in Wouter Schoulten's archive
format, version 0.83.  Unfortunately the format doesn't include a universal
quoting or escape schema.

The filenames in the .inf files are the cassette filenames with spaces
transformed to underscores; in the uucode headers they are also converted
to lowercase.  There is currently NO facility to resolve duplicate
filenames on the tape, or filename collisions resulting from the
transformations.  The uucode, and then the individual .inf files will need
to be edited by hand for this purpose.

To capture the NEXT parameter, the first .inf file is printed after the
second data file is loaded, the second after the third and so on.  At the
end of the tape the BBC's Escape key should be pressed, and the final .inf
file will be written.

The output contains standard BBC linefeeds; if these are converted to DOS
or Unix format it will be readable with WinZip (if saved as filename.uu) or
with /bin/sh on Unix systems.

DT as supplied will only run on tape-based systems (i.e. where PAGE =
&E00.) To use DT on disc-based systems when DTX is unsuitable, modify the
file buffer allocation code from DIMG%&63FF,... to DIMG%&58FF,...

NB: Do not use DT to transfer files larger than 25 KB (&6400.)  This figure
drops to 22.25 KB (&5900) when the Disc Filing System is active.

DTX

Operation is identical to DT, see above.  DTX has improved tape-unlocking
code which is less prone to errors, and the CRC algorithm is an order of
magnitude faster.  However, the program takes up more memory and is less
convenient to handle.  DTX cannot be used in tape mode.

NB: Do not use DTX to transfer files larger than 22 KB (&5800.)

SLOAD

NAME
	SLOAD - screen load

SYNOPSIS
	*SLOAD filename

DESCRIPTION
	A program to decompress snapshot files generated by SSAVE and write
	them to screen memory.

ARGUMENT
	filename
	The name of the snapshot file to read.

OPERATION
	The argument string is passed directly to OSFIND as the filename.
	The decompressed bytes are written to local memory starting at the
	address given by OSWORD &84.  If there are too many bytes for the
	screen then SLOAD will quit silently when the end of RAM is
	reached.
	The input file is interpreted as a series of blocks, each block
	including a two-byte header and one or more trailer bytes.  The top
	bit of the second byte indicates the type of the block; the rest is
	taken as an integer 'l', low byte first.  The range of 'l' is
	1..32768, the highest value being represented as all zeroes.  If
	the type bit is set, then the single trailer byte is to be repeated
	'l' times.  Otherwise there are 'l' trailer bytes to be copied to
	the screen in the order given.

EXIT STATUS
	RTS
	The operation completed successfully.

	BRK
	An error occurred.  The operating system is responsible for all
	exits by BRK from SLOAD.

NOTES
	Omitting the filename argument may cause SLOAD to read its own
	binary as the data file.  The user is responsible for setting the
	correct graphics MODE prior to loading the screen.  SLOAD is not
	compatible with a second processor.

SSAVE

NAME
	SSAVE - screen save

SYNOPSIS
	*SSAVE bias-character filename

DESCRIPTION
	A program to create snapshot files of the current screen display,
	compressed using modified run-length encoding.

ARGUMENTS
	bias-character
	If this argument is either of the characters R or r, then the
	output file will contain as many repeat blocks as possible;
	otherwise repeat blocks will only appear when they positively
	shorten the file.  This argument does not affect the output file's
	length, which will always be the minimum length permitted by the
	file format.

	filename
	The name of the screenshot file to create; if it exists it is
	overwritten.

OPERATION
	SSAVE encodes local memory from the display address given by OSBYTE
	&84 until the end of RAM at &7FFF.  The decision algorithm has
	constant private memory usage and linear time complexity -
	execution time is proportional to screen memory size.  The first
	character of the argument string is tested to choose the bias.  The
	third and subsequent characters are passed to OSFIND as the
	filename.

EXIT STATUS
	RTS
	The operation completed successfully.

	BRK
	An error occurred.  The operating system is responsible for all
	exits by BRK from SSAVE.

NOTES
	The program looks for the arguments at specific character positions
	relative to the end of the command name.  Omitting the filename
	argument may cause the operating system to overwrite the SSAVE
	binary.  Be sure to lock the SSAVE machine-code file.  SSAVE is not
	compatible with a second processor.

TXTLOAD

TXTLOAD programs the f0 key with a macro to load an un-numbered text listing
into the BASIC program memory.  If you have a serial link, transfer this
program as described in INSTALLATION above.  Otherwise copy the txtload.lst
file onto a BBC disc as L.TXTLOAD and then type:

	*EXEC L.TXTLOAD
	RUN

Before using the macro, save all important data to diskette.  Press f0 and
you will be prompted for the filename containing the text listing.  Enter
it and TXTLOAD will build a temporary file, then execute it.

Note that the disc will need to be write-enabled, with enough space to hold
the temporary file (about the same size as the text listing.)  TXTLOAD
cannot delete the temporary file (named Z) after using it.

UUDECOD

UUDECOD accepts a stream of ASCII characters and saves the binary file or
files it represents.  Unlike other versions of uudecode, the second and
subsequent files in the stream will also be decoded.  The format of the
ASCII stream is described elsewhere.  Note that this version does not
restore BBC header information such as the load and execution addresses.

UUPROMP

This is a modification of UUDECODE to work around any potential buffer
overflow problems.  After sending a line of text, some terminal emulators
can be programmed to wait until the BBC micro sends a CR character back,
indicating that the buffer is free to accept another line.  UUPROMP will if
necessary repeat the CR character until the next line arrives.

COMPATIBILITY and BUGS

The following are either some known compatibility issues with BBC Micros
not matching the System Requirements, or just plain bugs:
AUTOTPE, DT, DTX
	Tube,OS	- Peeking for load and execution addresses
		  in OS-specific places (works around CFS bug)
	Model	- File buffer length is hard coded for 32K machines
	Bug	- Does not abort if file is too big; uses fixed buffer

DTX
	Tube	- Machine code needs to be distributed

SSLOAD, SSAVE
	Tube	- Directly read and write to screen
		  (OSRDSC and OSWRSC are not provided in OS1.20)
	Bug	- Should use GSINIT, GSREAD to get filenames
	Bug	- Does not change to right MODE or store it in file
	Bug	- Poor compression performance

UUDECOD, UUPROMP
	Bug	- Does not save load and execution addresses with file

All assemblers
	Bug	- Should build based on current PAGE setting.

All programs
	BASIC	- All programs assume BASIC II (but might work in BASIC)

AUTHOR

Greg Cook, bbqd.org

-END-
