Building a Human68k disk catalogue utility

A Sharp X68000 hard disk can contain years of scattered software: games, utilities, development tools, disk images, documentation and half-finished experiments. Once several SCSI devices, partitions or backup disks are involved, relying on memory becomes risky. A small Human68k command-line utility can create a reliable inventory of every file without requiring a modern computer or a complicated transfer process.

The useful result is more than a list of names. A well-designed catalogue records the path, size, attributes and timestamp of each entry, then writes the information in a format that can be searched on the X68000 or imported elsewhere. That makes it practical for retrocomputing preservation, hardware testing and deciding which disks still need a verified backup.

Approach	Strengths	Weaknesses	Best use
Shell commands	Already available and quick	Awkward recursion and limited output	A one-off small directory
Human68k utility	Fast, repeatable and self-contained	Requires compiling and testing	Regular disk inventories
Host-side imaging	Good for full preservation	Needs a transfer workflow and compatible hardware	Forensic or archival backup
GUI file manager	Easy visual browsing	May hide attributes and errors	Casual inspection

Define what the catalogue must record

Start with a plain specification before writing code. Each output row should contain the drive letter, complete path, filename, byte count, file attribute, date, time and an indication of whether the entry was read successfully. Directories should usually be recorded as well, even though their size is not meaningful. Empty directories are part of the disk’s structure and can matter when reconstructing software.

A practical line format is tab-separated text:

C:\TOOLS\README.TXT    1842    A    1993-07-14 21:08:00
C:\TOOLS\BUILD         <DIR>   D    1993-07-14 21:09:12

Keep the format deliberately boring. Human68k software often works best with CRLF line endings, short filenames and conservative character handling. Tabs make the file readable in a text editor while allowing a modern script to split the columns later. Avoid commas unless you are prepared to quote filenames consistently.

Decide whether hidden and system files belong in the inventory. For preservation, the answer should be yes. A catalogue that omits files because they are not normally visible can give a false impression of the disk. Also decide whether the utility follows subdirectories, how it reports an unreadable directory, and whether it can continue after a single bad entry.

Work within Human68k’s filesystem model

Human68k presents a DOS-like environment, so the utility should begin with drive and path conventions familiar to that system. A command such as CATALOG C:\ /O:C:\CATALOG.TSV is easier to use than a configuration file, particularly when booting an old machine from a floppy or a small SCSI disk. Support a current directory when possible, but make the root-directory behaviour explicit.

Most X68000 software uses short DOS-style names rather than modern long filenames. That simplifies output, yet Japanese text still needs care. A filename may contain Shift-JIS characters, and a terminal or editor configured for another encoding can display it incorrectly. The program should preserve the original bytes returned by the operating system instead of attempting an unnecessary conversion. The catalogue remains useful even when a Western PC cannot render every name.

Human68k installations vary. Some machines use a SCSI hard disk, some use an emulator or compact flash adapter, and some have several logical partitions. The program should never assume that drive C: is the only target. Accepting a drive letter or path on the command line makes the same executable useful for A:, C:, and removable media without recompilation.

Choose a directory traversal method

The simplest implementation calls the Human68k directory-search functions to obtain the first matching entry and then repeatedly requests the next one. In a C environment these may appear as library wrappers such as _dos_findfirst and _dos_findnext; in assembly they correspond to the operating system’s directory search calls. Check the documentation for the compiler and DOS version being used, because function names, structures and attribute constants can differ.

Use a wildcard search for each directory, then distinguish files from subdirectories by inspecting the returned attribute flags. A rough algorithm is:

scan(path):
    search path\*.* including hidden entries
    for every returned entry:
        write its metadata
        if it is a directory and not "." or "..":
            scan(path + "\" + name)

Do not build the next path with careless string concatenation. A root such as C:\ already ends with a separator, while C:\GAMES does not. A small path-join routine prevents doubled separators and buffer overruns. It should reject a path that cannot fit in the selected buffer rather than silently truncating it.

Recursion is clear and easy to test, but a very deep directory tree can exhaust a small stack. Human68k software normally deals with shallow trees, so recursion is reasonable for an initial version. A production utility can replace it with an explicit stack of pending directories, giving predictable memory usage and a clean error message when the stack limit is reached.

Make output useful on old and new systems

Writing directly to the output file is safer than storing the whole catalogue in memory. Open the destination before scanning, write a header containing the utility version and source path, and flush periodically. If the machine loses power, a partial catalogue is still more useful than an unwritten buffer. A status line on the console can show the number of files processed and the current path.

Use fixed-width integer types where the compiler supports them, but remember that some Human68k C toolchains are old. File sizes may be represented by 32-bit signed or unsigned values, and that is generally enough for individual files on period-correct partitions. If a library reports a larger value or an error, print a clear marker rather than allowing it to wrap into a negative number.

Dates and times deserve a simple policy. Convert the operating system’s packed date and time fields into a fixed representation such as YYYY-MM-DD HH:MM:SS, padding each component with zeroes. If a field is invalid, retain the raw hexadecimal value in a diagnostic message or use UNKNOWN. Do not invent a modern timezone: the timestamp is generally the value stored on the disk, not a guaranteed UTC record.

For a mixed Australian workflow, a tab-separated catalogue can be copied to a modern machine and opened in a spreadsheet, a shell script or a version-control repository. A collector in Melbourne can compare it with a backup held in Sydney without changing the original disk. The text file is also easier to post alongside a preservation project than a screenshot of a file manager.

Handle failures without hiding them

Old hard disks can return errors because of ageing media, marginal cables, termination problems or an unreliable power supply. A catalogue program should distinguish “no more entries” from “directory search failed”. If a directory cannot be opened, write an error row containing the path and error code, report it on the console, and continue with other branches when safe.

The output file itself can fail to open if the destination is full or write-protected. Check every write and close operation. It is usually wise to refuse an output path located inside the directory being scanned, since the catalogue would then appear as a new file during traversal. Writing to a different partition, a floppy, or a serial-transfer destination avoids that race and reduces the chance of altering the source.

Do not attempt repairs from inside a read-only inventory tool. A bad sector, suspicious timestamp or malformed directory should be reported for later investigation. If the disk contains irreplaceable material, make an image or a sector-level copy first. The catalogue describes the filesystem; it is not a substitute for preserving the data that the filesystem points to.

Power arrangements also matter for Australian owners. Japanese X68000 hardware was designed for Japan’s 100-volt supply, while Australian mains is 230–240 volts, so an appropriate step-down transformer and safe power setup are essential before a long scan. A utility that carefully records files is of little value if an incorrectly powered drive fails halfway through the job.

Test against realistic disk contents

Create a test directory containing ordinary files, zero-byte files, nested directories, hidden entries and names with Japanese characters. Include a directory whose name nearly reaches the permitted path length. Compare the utility’s output with a trusted listing, then repeat the test after copying the directory to another partition. The file count, byte totals and relative paths should agree.

Test special cases separately. Scan an empty directory, the root of a partition, a floppy disk and a disk containing multiple partitions. Try an output destination that is full, a source with a missing subdirectory, and a directory with an unreadable entry. If the compiler’s library treats *.* differently from modern Windows, verify that extensionless names are still found; old DOS search behaviour can surprise developers who test only on a PC.

Keep a small regression fixture with known results. Each time the source is rebuilt, scan the fixture and compare the catalogue byte for byte, allowing only the header timestamp to vary. This catches changes in attribute filtering, path joining and date conversion. It also makes porting between Human68k development environments less nerve-racking.

For physical control testing, the same preservation mindset applies to peripherals. Before blaming software for strange input during a long catalogue session, check the analogue controls and connections; the notes on joystick potentiometer repair describe the kind of hands-on maintenance common in X68000 projects. Stable hardware makes repeatable software testing much easier.

Add options that suit preservation work

A useful first release needs only a few switches: source path, output path, include-hidden mode, quiet mode and a summary option. A -n dry run can count entries without creating a file, while -e can request an error-only report. Avoid a large command-line interface until the basic scan is dependable; every extra option is another combination to test on a machine with limited memory.

A later version could calculate checksums, but this should be optional. Hashing every byte can greatly extend a scan on an old hard disk and may place additional stress on a failing mechanism. A sensible design offers a metadata-only pass first, followed by a separate verification command for selected files or a known preservation set.

Include a header with the utility version, scan path, date, drive identifier and any options used. When catalogues are exchanged with modern systems, a header prevents confusion between a complete scan and a partial scan. If you later change the column order or date format, increment the format version rather than making scripts guess.

For people who organise research through browser-based records, the same principle applies to modern file views: consistent columns and stable names are more valuable than visual decoration. A useful reference for thinking about filterable records is SharePoint views, although the Human68k program itself should remain a small native command-line tool rather than depend on an online service.

Preserve the catalogue with the disk

Store the catalogue beside the disk image, backup files and hardware notes, using a filename that identifies the machine and partition. For example, X68000_C_1994-06-18.TSV is easier to understand years later than LIST.TXT. Keep an untouched copy of the original output, then make converted copies for sorting or spreadsheet use.

A catalogue can reveal duplicate files, unexpected boot files and directories that were forgotten when a disk was copied. Compare two scans after maintenance and record what changed. If a file count drops, the catalogue provides a starting point for finding the missing path rather than relying on a vague recollection of what used to be present.

Australian collectors often buy or exchange equipment through eBay, Gumtree or local retrocomputing groups, and postage between Perth, Adelaide, Brisbane and the eastern capitals can take time. A compact text catalogue sent with a machine gives the next owner a practical record of its contents before transport. It also helps distinguish a disk that contains valuable software from one that is simply empty or duplicated.

Document the compiler, library version, Human68k release and target hardware alongside the executable. Community links such as the X68000 resources collected at X68K.NET links can help future maintainers locate related tools and preservation projects. A small, documented utility is far more likely to remain usable when the original developer’s setup is no longer available.

Build the first version conservatively, run it against a disposable test partition, and keep the source with the resulting executable. Once it produces trustworthy inventories, use it before every major disk repair, transfer or sale. That simple habit turns an ageing X68000 filesystem into something searchable, auditable and much easier to preserve.