DT+ Extended uuencoders, uudecoders, screenshot compressor, media transfer and plain-text listing loader Version 3.14 Greg Cook, 16 June 2021 CONTENTS adrfix.txt Edits addresses of files and erases slack autodsk.txt Transfers disc files to tape autotpe.txt Transfers tape files to disc dd.txt Uuencodes disc as image in .SSD format drain.txt Fills disc with file of &E5 bytes 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 DT+ sloadas.txt Assembles SLOAD screenshot decompressor ssaveas.txt Assembles SSAVE screenshot compressor stamp.txt CRC-check and apply BBC headers to files on disc txtload.txt Loads un-numbered text listings of BASIC programs udd.txt Uudecodes .SSD and .DSD images directly to disc uudecod.txt Simple uudecoder which restores data only SYSTEM REQUIREMENTS All programs in DT+ have been tested on a BBC Micro, model B with OS 1.20 and BASIC or BASIC II, however they are readily adaptable to other specifications. See COMPATIBILITY and BUGS below. Machines with a 6502 or ARM second processor fitted should be able to run ADRFIX, AUTODSK, DD, STAMP, TXTLOAD, UDD and UUDECOD as supplied. INSTALLATION DT+ can be installed over an ASCII serial link. 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 Then send the contents of dtplus.txt to the computer. The micro will be under control of the terminal until BREAK is pressed. ASSEMBLY If the three machine code files need to be regenerated, 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 DT+ is now complete. UNIX LINEFEEDS To send Unix linefeeds directly from the BBC Micro (so that later conversion is not necessary) enter the following commands: *FX 5,2 *FX 6,13 *FX 3,8 ADRFIX ADRFIX edits the load and execution addresses of a file on disc. On filing systems that support file truncation, it also erases data beyond end-of-file in the file's last sector, to improve compressibility of the disc image. The program will prompt for the name of the file. The file must exist and be read-write accessible. Filename:X.HELLOW ADRFIX then confirms the load and execution addresses attached to the file. These may have been lost during transfer and set to default values. If they are incorrect, press N and you will be prompted for new addresses. To keep the displayed value press RETURN, otherwise enter a hexadecimal address. ADRFIX then reprints the addresses and asks if they are correct; if they are, press Y. Load address = &FFFFFFFF Exec address = &FFFFFFFF Are these correct? (Y/N):no Load address = &8000 Exec address = &8000 Load address = &8000 Exec address = &8000 Are these correct? (Y/N):yes ADRFIX then updates the catalogue, attempts to extend the file, rewrites its last sector if successful, then restores the file's original length. By design, some filing systems do not store every 32-bit address faithfully, only catering for the most commonly used address ranges. In the event that an address read back from the catalogue is different from the one submitted, ADRFIX warns the user with the message "Warning: address accuracy lost". 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 type the number of the drive to be read. Then press the RETURN key for DFS, or a volume letter for DDOS. Files in directory $ are saved under their 7-character name. Other files are saved under their full 1.7 filename. 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. NB: Do not use AUTOTPE to transfer files larger than 23.25 KB (&5D00 bytes.) 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: Acorn DFS? yes (press Y) Image name:disc0.ssd Drive:0 Overwrite size field? no (press N) DD prints to standard output (the OSWRCH output stream) a uuencoded image of the disc in the specified drive, skipping the blank portion of an Acorn DFS disc. To include the blank portion, see DD ADVANCED OPTIONS below. Uucode should be generated with Unix linefeeds (see above.) It can be decoded with WinZip or with /bin/uudecode on Unix systems. DD ACORN DFS OPTIONS If you type Y at the "Acorn DFS?" prompt, then DD will write the shortest image that contains all the files. If there are gaps between the files then DD will warn of the redundant data that will be included in the image. To move the files down and eliminate these gaps, use the BBC's *COMPACT command. Shortened images can be restored to a standard size using bbcim v0.103 (not supplied.) The "Overwrite size field?" option, if answered with Y, will set the sector count in the catalogue to match the size of the disc image. The original disc is not changed. This prevents some emulators crashing when SAVEing to a shortened image, but when archiving discs it is not recommended. DD ADVANCED USAGE If you type N at the "Acorn DFS?" prompt, you will be asked to specify the parameters (geometry) of the disc you wish to read. DD will then transfer the entire surface, regardless of catalogue format. Watford DFS discs must be uploaded in this way, whether or not a Watford DFS ROM is fitted. As a bonus, owners of double density DFSs should be able to read other computers' discs. Many systems will transparently handle the double density formats through standard single density commands as issued by DD. The following contemporary formats have been successfully read: Format: Watford, Acorn OPUS DDOS PC-XT 360K DEC RX50K Acorn DFS? no no no no Tracks: 40 or 80 40 or 80 40 80 Sec/track: 10 18 9 10 Sector size: 256 256 512 512 Start sector: 0 0 1 1 Drive speed is 300 rpm in all cases As always, owners of 80 track disc drives should use their existing techniques to accommodate 40 track discs (such as throwing a switch on the disc drive or its housing for this purpose.) If you have DDOS but no track switching hardware, then the commands *4080 AUTO or *OPT 8,255 will allow DDOS to auto-detect the track stepping. If DD fails with "Disc error &18" (meaning sector not found) enter *CAT 0 followed by *CAT 2, or *CAT 1 followed by *CAT 3. This causes DDOS to toggle the density flags on the specified drives, when no DFS or DDOS catalogue is found. DD produces single sided disc images. As PC discs are double sided the images corresponding to the two sides will need to be merged (interleaved) into a double sided disc image before use. DRAIN DRAIN creates a file named _ on the current drive, and fills it with &E5 bytes until there is no more room for the file. Any previous file named _ is erased. This improves compressibility of the disc image. For best results delete unwanted files, then *COMPACT the drive before use. DRAIN uses screen memory for temporary storage, and is not compatible with a second processor. 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 Scholten's archive format, version 0.83. 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. 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 is reduced 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. NB: Do not use DTX to transfer files larger than 22 KB (&5800.) SLOAD SLOAD decompresses screenshots created by SSAVE, writing them to screen memory. It should be called with: *SLOAD filename where filename is replaced with the name of the screenshot file to read. The user must set the same screen MODE in which the picture was saved before calling SLOAD. The picture is always restored to the start of screen memory, as returned by OSBYTE &84. If the saved picture is too large for the screen then the remainder is silently discarded. SLOAD does not receive a filename from the command line when run from tape; however once loaded it accepts the address of a filename in XY at &190D, or an opened file handle (which it closes) in A at &1912. SLOAD is not compatible with a second processor. SSAVE SSAVE takes a screenshot of the current display and saves it in a compressed file. It should be called with: *SSAVE X filename where X is replaced by the bias character, one of C,c,R,r, and filename is replaced by the name of the screenshot file to save. If the bias character is R or r, SSAVE will prefer to write Repeat blocks for obfuscation; otherwise it will prefer Copy blocks for efficiency. In either case the screenshot file will have the minimum possible size. SSAVE will always save the whole screen, from the start of screen memory as returned by OSBYTE &84 to the end of RAM. The compressed screenshot format uses a modified form of run-length encoding; it works best on pictures with large areas of flat colour. The compressed file size will never be more than two bytes larger than a raw screen dump. SSAVE is not compatible with a second processor. STAMP STAMP will verify a set of files against Cyclic Redundancy Check values embedded in the program and apply BBC header information to those that pass. Files on cassette will be verified only. The CRC algorithm is as used in the Cassette Filing System. By default, STAMP will verify the files in DT+, but it can serve as a template to verify any other package. TXTLOAD TXTLOAD programs the f0 key with a macro to load an un-numbered text listing into the BASIC program memory. 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 _) after using it. THE UUDECODERS Both UDD and UUDECOD accept uucode - an older standard in the Unix community for transferring binary data over 7-bit communication links. The following apply to both programs: Unlike some versions of uudecode, the second and subsequent files in the stream will be decoded - which may prove convenient when the BBC micro is remote. Sending the line: exit 0 to either UDD or UUDECOD will cause it to exit. The line: exit 0; # *FX 2,0 sent to the program will cause it to re-select its local keyboard, then exit. When the BBC Micro is remote, just use "exit 0". Some terminal emulators can be programmed to wait after each line until the remote host echoes the CR character, implementing a lightweight flow control system. To turn off the CR characters, edit either program and replace F%=0 with F%=1. Please note the distinction between UDD and UUDECOD. These both accept the same style of ASCII stream; whereas UUDECOD will turn it into a file on an existing disc, UDD will rewrite the entire disc, catalogue and all. UDD UDD accepts a stream of ASCII characters and restores the disc image or images it represents. The format of the stream is described elsewhere. WARNING - UDD will delete ALL the old contents of any of the attached disc drives. Please ensure that any valuable data in these drives is safely backed-up elsewhere before using the program. WARNING - Do not try to write an 80 track image to a 40 track drive. The filename in the "begin" line must have the following format: disc0.ssd where disc = Name, any length, currently discarded 0 = Drive number, 1 digit, 0 to 3, default 0 . = Extension separator, 1 full stop ssd = Extension, 3 characters, selects type UDD currently accepts the following types of image: .ssd Single sided, single density .dsd Double sided, single density, tracks interleaved UDD USAGE Typically the ASCII stream will come from the serial port. Enter: LOAD "UDD" then give control to the remote terminal (see INSTALLATION above.) If that is a PC running Linux, enter the following: echo RUN >/dev/ttyS0 uuencode disc0.dsd disc0.dsd >/dev/ttyS0 echo "exit 0" >/dev/ttyS0 Equally, two BBC Micros can be connected together to copy physical discs. It is easiest to conduct the transfer from the sending computer, so that data flows in one direction. If the sending computer is unattended the receiver can build a *EXEC file at the sending end and make OSBYTE calls at the receiving end to prevent an echo loop. UUDECOD UUDECOD accepts a stream of ASCII characters and saves the binary file or files it represents. To restore BBC attributes, please see ADRFIX above. For usage guidelines please see UDD USAGE above; the filename in each "begin" line can have any format subject to the rules of the Disc Filing System in use. 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 AUTODSK, DD, UDD GoMMC - Does not tolerate Read ID or Seek command. SLOAD, SSAVE Tube - Directly read and write to screen (OSWRSC is not provided in OS 1.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 Bug - Does not save load and execution addresses with file HISTORY v3.14 2021-06-16 * AUTODSK handles large volumes under EDOSPAT 4.82 and up. v3.13 2020-07-25 * AUTODSK is compatible with Acorn DFS and Opus DDOS v3.12 2020-05-04 * DRAIN uses OSWORD &71 to read the free space on the volume v3.11 2019-09-19 * Added DRAIN v3.10 2019-08-23 Named DT+ * Added ADRFIX * Rewrote SLOAD * All programs are compatible with BASIC I/II and OS 1.20 v3.01 2006-07-26 * Fixes to README and STAMP v3.00 2006-07-23 Named DT2K6 * Added STAMP, UDD * Removed old UUDECOD, renamed UUPROMP to UUDECOD * Revised DIM memory allocations to be Tube compatible * UUDECOD: Made flow control optional v2.30 2004-12-02 * Compatibility with BASIC 1 * DD: floppy disc commands retried on error * DTX: Will not load machine code image twice * DT, DTX: output more closely resembles real shell archives; many space savings v2.25 2004-6-17 * DD: deleted incorrect fixing of SEL 0, SEL 1 bits of 8271 command - these are for drive, not side selection, and DFSs overwrite them anyway * README: simplified procedure for reading double density discs - formatted BBC media unnecessary v2.24 2004-5-25 * DTX: will not install OSWRCH handler twice * DTX: OSWRCH handler correctly handles newlines * DTX: condensed code clearing Locked bit errors * README: deleted reference to double sided RX50K discs v2.23 2004-5-15 Named DT2K4 * DTX: further condensed CRC code * README: expanded DDOS priming procedure v2.22 2003-4-5 * DD: improved 8271 init based on datasheet and public domain driver included in FDC.COM * Listings: made *EXEC-able using AUTO * README: Found some RX50 discs and added parameters v2.21 2003-3-28 * README: minor update v2.20 2003-3-26 Named DT2K3 * DD: generalised to all formats, made overwriting size field optional v2.10 2002-8-1 Named DT2K2B * AUTOTPE, DT: removed redundant peek of cassette file's length * DT: preserves P register during event handler, removed game-specific crack * DTX: improved logic for rejecting errors in 'locked' bit * DT, DTX: changed end comment to be more acceptable to shells * UUDECOD, UUPROMP: reformat text file to width of a uuencoded stream v2.00 2002-1-31 Named DT2K2 * Added DTX, SLOAD, SSAVE, TXTLOAD, UUDECOD, UUPROMP * DTL1 renamed DT, old DT and DTL removed * Corrected all DIM memory allocation sizes * Uses BBC standard linefeeds, improves appearance on terminal * DD: shortened instruction messages * DD: accepts non-*COMPACTed discs, warns and continues * DD: overwrites size field with no. of used sectors * DD: zeroes last byte of track buffer, same disc = same uucode * DT: simplified uuencoder, program size reduction v1.00 2000-8-16 Named TDTD * AUTODSK, AUTOTPE, DT, DTL, DTL1 added * DD: changed uuencoded mode (400) to put out read-only image v0.10 1999-5-31 Named DumpDisc (DD9) * First public release of DD ACKNOWLEDGEMENTS Sincere thanks go to Robert Schmidt, Dave Moore, Chris Richardson and others who have set up online archives for Acorn software. DT+ was intended to help make contributions to these archives when it would otherwise be impossible. Geoff Cox's series on the BBC B's operating system, including a complete annotated disassembly, has been indispensable for understanding the filing system's state during loading operations. My sincere gratitude also to the anonymous Micronet user who preserved the articles. W.H.Scholten and John Wilson's FDC.COM program provided hints for the floppy disc commands in DD. REFERENCES Geoff Cox's annotated disassembly of the OS 1.20 ROM http://www.nvg.org/bbc/doc/OS-1.2-AnnotatedDisassembly.zip W.H.Scholten's FDC.COM, based on John Wilson's FDCDEMO http://www.nvg.org/bbc/util/fdc.zip DISCLAIMER The software and documentation included in DT+ is supplied without warranty, not even the implied warranties of merchantability or fitness for a particular purpose. In no event shall the author or his suppliers be liable for any loss, damage, injury or death, of any nature and howsoever caused, arising from the use of, or failure, inability or unwillingness to use, this software or documentation. AUTHOR Greg Cook debounce@yahoo.co.uk http://regregex.bbcmicro.net/ -END-