Utility for handing files in a memory card formatted for a +3E enhanced Spectrum. Version 0.5alpha.

(C)2009-2012 Miguel Angel Rodriguez Jodar (mcleod_ideafix). GPL Licensed. For support, please check http://www.zxprojects.com

CHANGELOG

January, 14, 2012

• Added a small utility, hdf2hdf256 to assist converting 8-bit HDF files into HDF256 format, so "3e" can handle it correctly. It's a single C file you can comple with: gcc -O hdf2hdf256 hdf2hdf256.c . Windows executable is included.

January, 8, 2012

• Fixed an inconsistency with return values for the backend mode. Now the front-end won't treat as an error if the image file is not a HDF file, but RAW.
• Changed the scheme for device file names for Windows. Instead of using the \.\letter: scheme, which is valid for memory cards with no partitions, the "scan" command now returns the device file name of the physical disk, which is \.\PhysicalDriveN with N being 0,1,2,etc.
• Initial support for shared disks (disks with a standard IBM partition table where the first one is a "unused/unkown" partition, where the PLUSIDEDOS volume resides). USE WITH CAUTION. The partition type used for detecting the presence of an IDEPLUSDOS disk inside a partition is type 0x7F, as suggested by Garry Lancaster at: http://www.worldofspectrum.org/zxplus3e/sharingdisks.html
• Initial support for halved size sector disks. It can now handle an HDF image file with halved sectors. USE WITH CAUTION

August, 2, 2009.

• Fixed an issue with get_partition_table. When the number of partitions * 64 is not a integer multiple of 512, the read fails, if issued against a physical device.

July, 30, 2009.

• Fixed an issue with full length names in get_file.
• PC filename is now always lowercase.
• NEW! Added "scan" support for Linux.

July, 27, 2009. v0.3alpha

• Fixed a subtle error when calculating file size for storing a file and displaying the directory.
• NEW! Added support for transferring DSK images to a partition. Just like it's currently being done with TAP files. See "USAGE". Standard DSK files are supported (1 side, 1024 bytes per block, 40 tracks, all the tracks the same size.)

July, 26, 2009. v0.2alpha

• Added more conditional compiling.
• Added -bare and -backend command line options to some commands so output is suitable for post-processing, through scripts or front-end applications.
• Added partition name support. Now, a file within the memory card / disk file can be refered using the notation partname:filename where partname is the name (not the number) of the partition the file resides in.
• Added the "scan" command (only Windows at the moment). Scans through all driver letters looking for disks with a PLUSIDEDOS partition table and shows the results. Useful for front-end applications and users who cannot figure which special file to work with.

July, 23, 2009.

• Added a little of conditional compiling to better support Linux. Now should compile straightforward with: gcc -o 3e 3e.c
• Compiles flawesly on Windows with MinGW32 (tested on C-Free 4) Forget about the issue with tempnam... ;)
• Fixed an issue with big partition tables that led to a GPF.
• Better HDF image file support. Now I can detect whether halved size sectors are being used or not, and calculate the correct offset to the raw data (uses to be 128, but with HDF specification 1.1 this changes. (thanks Velesoft for providing this information :)

July, 22, 2009. Version 0.1 alpha. First publicy available version. Works on Windows 7. Should work on previous versions (Vista & XP). Should also work on Linux, but not yet tested.

USAGE

Usage: 3e image_file command [args...]

image_file can be a HDF image file, a RAW image file, or a physicall device. For the later, you must known by advance the block device file for your device. (Use the scan command to find out detected block device files).

On Linux, block devices are named /dev/sda, /dev/sdb, etc. Issue a 'dmesg' command right after inserting your memory card to find out which special file the kernel assigns to your device. You must have read/write permissions on that file.

On Windows, block devices for installed drives can be accessed using this notation (*): \.\D: where D: is the drive letter Windows assigns to your card upon inserting it. Don't forget to CANCEL any attempt to format your memory card, as Windows thinks it needs formatting. Remember, DON'T format.

• Use the "scan" command to obtain the newer, recommended, device file name for accessing the memory card from Windows.

Commands: scan [-backend [-sep:N]]. Scans disks looking for PLUSIDEDOS partition tables. showptable [-backend [-sep:N | -bare]. Shows PLUSIDEDOS partition table. showpentry part [-backend]. Shows details about partition "part" (only +3DOS filesystem supported.) dir part [-backend -sep:N | -bare]. Shows directory for partition "part" (only +3DOS filesystem supported.) get part:file [dest_path] . Gets a file from a +3DOS filesystem and copies it to the current directory on your PC. dest_path is optional path for destination file. Must end with
put file part:file . Writes a file from your PC to a file in the selected partition. putbin file part:file [start] . Writes a file from your PC to a file in the selected partition, and adds a +3DOS header. puttap tapfile part . Scans a TAP file and writes all files within it to the specified partition with the correct +3DOS header for each one. Headerless blocks are named after the original file name, and adding 1,2,.. as extension. putdsk dskfile part . Read the contents of a DSK image file (standard DSK) and transfers all its files to the selected partition. del part:file . Deletes a file in the selected partition. The "part" argument may refer to a partition number (as numbered by the showptable command) or a partition name. In this last case, the name is case sensitive.

The -backend option of some commands performs formatted output suitable for reading it from a front-end application. See FRONTEND.TXT for details.

The -bare option of some commands performs formatted output suitable for processing it from a batch file or script.

Extra arguments in commands are ignored.

(C)2009 Miguel Angel Rodriguez Jodar (mcleod_ideafix) http://www.zxprojects.com GPL Licensed.

Filenames to be used within the +3DOS filesystem are somewhat "sanitized" so any extraneous character is changed to a '_'.

BUGS

The sep:N command option is not yet implemented (see FRONTEND.TXT).

Being alpha software, it's expected that a lot of bugs are floating around. At this moment, it does not do any consistency check about the filesystem, so any command that reads or writes to a corrupt filesystem is likely to fail with some random error.

Support for HDF image files is very limited. The program uses an HDF file just like a RAW image file or a physical device. It only takes into account that HDF files has a 128 byte header, which is completly ignored.

Support for physical devices is left upon the operating system. There's no special provision to assure that all disk access are made on a sector frontier, nor there's any checks to ensure all disk operations read or write whole sectors. In addition, support for these devices are limited to those that allows LBA addressing, and has a sector size of 512.

There's no support for physical devices with uses only 8 bits when should use 16 (some cheap interfaces) nor there's support for the so-called HDF256.

EXAMPLES (Windows, see examples for Linux below)

• Find out what PLUSIDEDOS drives are available on the system:

C:>3e scan Detected PLUSIDEDOS partition table on \.\M: . Size: 61 MB

• Shows the partition table on a memory card detected as drive M:

C:>3e \.\m: showptable

Disk geometry (C/H/S): 491/2/128

PARTITION TABLE

0 PLUSIDEDOS System 0/ 0 0/ 0 0 127 0 MB 1 juegos +3DOS C: 0/ 1 128/ 0 128 32895 16 MB 2 utils +3DOS D: 128/ 1 256/ 0 32896 65663 16 MB 3 swap Swap 256/ 1 272/ 0 65664 69759 2 MB 4 chica +3DOS 272/ 1 280/ 0 69760 71807 1 MB 5 ---------------- FREE 280/ 1 490/ 1 71808 125695 26 MB

2 partition entries remain unassigned.

The drive letter next to +3DOS in some partitions means that the partition is permanently mapped to that drive letter. This mapping can be controlled by the command MOVE drive_letter IN partition, and MOVE drive_letter OUT (see +3E manual).

• Shows details about partition #1 (named "juegos")

C:>3e \.\m: showpentry 1

Also this command can be issued as: C:>3e \.\m: showpentry juegos

DETAILS FOR PARTITION: juegos Type: +3DOS mapped to C: First LBA address: 128 Last LBA address: 32895 Size (MBytes): 16 MB Reserved bytes from begining of partition: 0 Block size: 8192 bytes Directory entries: 512 Offset to data area (directory size): 4000h Data size for this filesystem: 16711680 bytes.

XDBP parms: SPT : 512 BSH : 6 BLM : 63 EXM : 3 DSM : 2039 DRM : 511 AL0 : 192 AL1 : 0 CKS : 32768 OFF : 0 PSH : 2 PHM : 3 Sideness : 0 Tracks per side : 255 Sectors per track : 128 First sector # : 0 Sector size : 512 GAP length R/W : 0 GAP length fmt : 0 Multitrack : 0 Freeze flag : 0

This information is usually not necessary to the end user. It is presented for completeness and to aid debugging the program itself.

• List directory for partition "juegos" (partition #1)

C:>3e \.\m: dir 1

Also this command can be issued as: C:>3e \.\m: dir juegos

Directory for juegos

ROM . 16512 1.0 16512 Bytes 16384 0 32860 CIRCULO .SCR 7040 1.0 7040 Bytes 6912 16384 32903 CHCODE . 2560 1.0 2458 Bytes 2330 49406 32768 EDL .Z80 131200 Headerless file. CHAIN . 256 1.0 205 Program 77 1 77 CHAIN .SNA 49280 Headerless file. EDL .SCR 7040 1.0 7040 Bytes 6912 16384 32768

Roughly speaking, there are two kind of files: +3DOS compilant files, with header, and headerless files. The later ones are verbatim copies from the original file on the PC. For example, .SNA and .Z80 files for the SPECTRUM command must be naked binary files, without any header. On the other way, +3DOS files have a header, the same way tape blocks have headers: to identify the type of file, its length, start address, etc.

• Copy a file called EDL.SCR from the partition 1 of the memory card to the current working directory on the PC.

C:>3e \.\m: get 1:edl.scr

Also, this command can be issued as: C:>3e \.\m: get juegos:edl.scr

A file called "edl.scr" is created on C:\ containing both the header and data for this file. The header, if any, is copied along with the file.

• Copy a file called EDL.SCR from the partition 1 of the memory card to the parent directory related to the current working directory:

C:>3e \.\m: get 1:edl.scr ..\

Also, this command can be issued as: C:>3e \.\m: get juegos:edl.scr ..\

• Copy a file called "screen.bin" located on the root directory of the PC, which is a screen dump, to the memory card, but with an added header to make it work under +3DOS with the LOAD command. The +3DOS file name for this file will be "screen" and it will be stored in partition "utils" (#2). As it's a screen, we will provide the start address for this file to be 16384.

C:>3e \.\m: putbin screen.bin 2:screen 16384

Also, this command can be issued as: C:>3e \.\m: putbin screen.bin utils:screen 16384

This file can be loaded from +3DOS with: LOAD "d:screen" CODE (provided that partition "utils" is mapped to drive D:)

If the start address is not provided for the putbin command, it is assumed to be 0.

It's also possible to write a file to the memory card without adding a header. Use the "put" command instead of "putbin".

• Delete a file named "screen" from partition #2 C:>3e \.\m: del 2:screen

Also, this command can be issued as: C:>3e \.\m: del utils:screen

• Dump all the files on a TAP archive to the partition 4 of memory card and list the directory of that partition.

C:>3e \.\m: puttap "c:\SPECTRUM\Games\h\HORIZONT.TAP" 4

Also, this command can be issued as: C:>3e \.\m: puttap "c:\SPECTRUM\Games\h\HORIZONT.TAP" chica

(after a couple of seconds...)

C:>3e \.\m: dir chica Directory for chica

CARAA . 256 1.0 249 Program 121 10 121 ARCOIRIS. 33024 1.0 32993 Bytes 6912 16384 32865 LOGO . 33024 1.0 33007 Bytes 6912 16384 32879 HARDWARE. 4224 1.0 4188 Program 4060 9100 4060 . 33152 1.0 33095 Bytes 300 32256 32967 HWS . 33024 1.0 33000 Bytes 6912 16384 32872 LECCION1. 8064 1.0 7982 Program 7854 9100 7854 MCODE . 33024 1.0 32909 Bytes 299 32000 32781 LECCION2. 7552 1.0 7513 Program 7385 9100 7385 LECCION3. 7936 1.0 7859 Program 7731 9100 7731 LECCION4. 7808 1.0 7777 Program 7649 9100 7649 DICCIONA. 3072 1.0 2984 Program 2856 9980 2856 D . 33024 1.0 32936 Bytes 400 32256 32808 FILE . 33024 1.0 33001 Char array 5103 50690 32873 CARAB . 3072 1.0 2989 Program 2861 9100 2861 MURO . 4480 1.0 4370 Program 4317 300 4242 WALLG . 33152 1.0 33042 Bytes 168 65368 32914 C . 33152 1.0 33093 Bytes 300 32256 32965 CLASIFIC. 7680 1.0 7621 Program 7493 9050 7493 CHAR . 33024 1.0 32965 Bytes 168 65368 32837 EVOLUCIO. 6656 1.0 6541 Program 6413 9050 6413 BITS . 33024 1.0 32909 Bytes 32 65368 32781 LIFE . 4992 1.0 4914 Program 4786 9010 4786 P . 33152 1.0 33092 Bytes 300 32196 32964 DIBUJAR . 4992 1.0 4933 Program 4805 8000 4805 MONTECAR. 5504 1.0 5444 Program 5316 9110 5316 GENERADO. 5760 1.0 5703 Program 5575 9100 5575 ONDAS . 4480 1.0 4423 Program 4295 9100 4295 M . 33152 1.0 33095 Bytes 300 32256 32967

Take into account however, that the copy does not altere program contents. This is important because the usual way to load "the next block" is LOAD "" , and this will issue a "F Invalid file name" error. You will have to modify by hand each LOAD sentence to include proper name on it.

• Transfer a DSK image file to a partition named "utils"

C:>3e \.\m: putdsk c:\Spectrum\disks\g\devpac3.dsk utils

(after doing this, a directory listing can be show for the "utils" partition to reveal the new files)

C:>3e \.\m: dir utils

Directory for utils

GENP3 . 27264 1.0 10880 Bytes 10752 24700 0 GENP351 . 27776 1.0 11392 Bytes 11264 24700 0 GENS451 . 27904 1.0 11520 Bytes 11392 26000 32768 MONP3 . 25088 1.0 8704 Bytes 8576 24700 0 MONS4 . 6784 1.0 6784 Bytes 6656 40000 32984

The -bare option allows shell scripts to use '3e' in order to perform complex tasks not available as standalone commands within '3e'. Here are some examples:

• Retrieving all files from a partition, to a directory of the same name as the partition:

Usage: getdir.sh disk_file_name partition_to_retrieve Example: getdir.sh /dev/sdh utils

• Retrieving all the files from all partitions, each partition on a directory of the same name:

Usage: getall.sh disk_file_name Example: getall.sh mydisk.hdf

You can use egrep on the dir command to allow for wildcards. For example, get all .BIN files from the "games" partition on /dev/sdh to the "backup" directory on your PC:

for f in 3e /dev/sdh dir games -bare | egrep "*.BIN" do 3e /dev/sdh get games:$f backup/ done

• Write all files from a directory full of SCR files (binary files with a ZX Spectrum screen dump) to the "scr" partition on /dev/sdh, adding a header so you can use LOAD "somefile.scr" SCREEN$ from +3 BASIC to load one of them.

for f in myscreens/*.scr do 3e /dev/sdh putbin $f scr 16384 done