Altirra's H: Device: A PC Folder as an Atari Drive
Altirra's H: device lets the emulated Atari open files directly in a folder on your PC, with no disk image in between. Programs written with a PC editor can be loaded and run in seconds, and anything the Atari saves appears immediately where your other tools can see it. The setup guide on this site shows how to add the device. This guide covers the options in its settings dialog, what works from BASIC and from each DOS, and how to build a quick edit-and-run loop around it.
What you'll learn: what each setting in the H: device dialog does, how H1–H4 differ from H6–H9, directory listings, subdirectories and XIO commands from BASIC, which DOSes can use H: (and what to use under SpartaDOS X instead), and a practical workflow for BASIC and assembly.
What you need: Altirra 4.x (the tests here used 4.40) and a folder for your Atari files. Setting Up Altirra covers adding the device, and A Modern Cross-Development Workflow covers the command-line switches, including /hdpath and /hdpathrw.
1. The H: device dialog
Add Host device (H:) under High-level emulation on the Devices page (System > Configure System > Devices), then open its settings. The dialog has these fields:
| Setting | Default | What it does |
|---|---|---|
| H1:/H6: … H4:/H9: path | empty | Up to four PC folders. H1: and H6: share the first folder, and so on |
| Read only | on | Blocks all writes. Opening a file for writing fails with error 135 |
| Also install as D: | off | Also registers the folder as a D: device, for software that only knows D: and runs without a DOS |
| Filename mode | 8.3, encode long names | Truncate long names, encode them, or use long file names |
| Use lowercase filenames | on | Names typed in upper case on the Atari are created in lower case on the PC |
Read only is on by default, so the first SAVE to a new H: folder usually fails with error 135 until you untick it. The /hdpath command-line switch also mounts read-only, and /hdpathrw mounts read/write. With lowercase naming on, SAVE "H:HELLO.BAS" produced a file called hello.bas on the PC.
Filename modes. In the default encode mode, host files whose names don't fit DOS 2's 8.3 rules are shown under a generated short name. For example, a file called (New disk) appears as NEWDI_5M. Wildcards match the encoded names. Files the Atari creates or renames always get the short name on the PC. Long file names mode passes names through as typed: spaces and mixed case are allowed, up to 127 characters.
No Atari memory is used. The handler isn't 6502 code in RAM. Altirra registers a vector table in a free page of the hardware address space ($D600 or $D700) and services the calls itself. MEMLO doesn't move, and H: is there even with no DOS booted, so LOAD "H:GAME.BAS" works straight from the BASIC prompt. Two consequences: if both of those pages are used by other emulated hardware, H: can't install, and software that tries to copy or patch the handler's code will fail, because the code at those entry points isn't real.
On the Acceleration page, the CIO device patches: H: setting and CIO burst transfers control how calls are intercepted. Burst transfers skip CIO's byte-by-byte loop for block reads and writes. If a program receives garbled data from GET CHARACTERS, turn burst transfers off.
2. Binary and text: H1–H4 versus H6–H9
H1:–H4: pass bytes through unchanged. Use them for anything binary: SAVE/LOAD of tokenized BASIC, XEX files, data, screen dumps. H6:–H9: reach the same folders but translate line endings: CR, LF or CR/LF become the ATASCII EOL ($9B) on reading, and EOL becomes CR/LF on writing. Use them for text: LIST "H6:GAME.LST" writes a listing a PC editor can open, and ENTER "H6:GAME.LST" reads one back. File sizes and NOTE/POINT positions are counted in the translated (ATASCII) stream, so they match what GET and PUT see.
ATASCII graphics and control characters inside strings don't survive a round trip through a PC text editor well. Keep listings that need them in tokenized .BAS form, or build such strings with CHR$().
3. Directories, XIO and locking from BASIC
H: speaks the DOS 2 dialect of CIO, plus extensions. This program lists the folder, changes into a subdirectory, lists that, changes back and creates a file. It produced the screenshot:
10 DIM A$(40):GRAPHICS 0
20 TRAP 50:OPEN #1,6,0,"H:*.*"
30 INPUT #1,A$:PRINT A$:GOTO 30
50 CLOSE #1:PRINT "END OF LISTING, STATUS ";PEEK(195)
60 TRAP 70:XIO 41,#1,0,0,"H:GAMES":PRINT "CHDIR OK"
70 TRAP 90:OPEN #1,6,0,"H:*.*"
80 INPUT #1,A$:PRINT A$:GOTO 80
90 CLOSE #1:XIO 41,#1,0,0,"H:..":TRAP 120
100 OPEN #1,8,0,"H:TEST.DAT":PRINT "WRITE OPEN OK":CLOSE #1
110 END
120 PRINT "WRITE FAILED, ERROR ";PEEK(195)
The listing comes back in DOS 2 format. A subdirectory appears with a leading colon (:GAMES 000), each file shows its size in 125-byte "sectors", and the last line is always 999 FREE SECTORS. With the folder mounted read-only, the same program ended with WRITE FAILED, ERROR 135.
Other things the device supports:
- Paths. Use
>or\as the separator, and.and..for the current and parent directory. Each of H1:–H4: has its own current directory, which H6:–H9: share. A separator right after the colon, as inH:>FOO, starts from the root. - Special commands. XIO 32 rename, 33 delete, 35 lock, 36 unlock, 37 POINT, 38 NOTE, 39 get file length (SpartaDOS X style), 41 change directory (MyDOS style), 42 make directory, 43 remove directory, 44 change directory and 48 get current directory (SpartaDOS X style).
- Locking. A DOS "locked" file is a read-only file on the PC: LOCK and UNLOCK change the host attribute. While the Atari has a file open, Altirra also holds a host file lock: shared for reading, exclusive for writing. A conflicting open, from another PC program or from the Atari itself, fails with error 176 ($B0, SpartaDOS X's "access denied").
- Reserved Windows names such as CON or LPT1 are quietly mapped to
$CON,$LPT1on the host, so an Atari file calledCONcan't open the console device.
4. Which DOS can use it
H: is a CIO device, so it works for any program or DOS that goes through CIO:
- Atari DOS 2.0S and 2.5: fully, because DUP does its file work through CIO. Under DOS 2.5, the menu's L command loaded and ran
H:MODES.XEXstraight from the PC folder, andCwithH:GAME.XEX,D:GAME.XEXcopies a file from the PC onto a disk image. - MyDOS 4.5: works, with two bugs. Wildcard copies from H: fail, because MyDOS opens the "directory" of a non-disk device in the wrong mode. Its Load Binary command uses a MyDOS-specific XIO call that H: doesn't understand. Copy single files, and load programs some other way.
- SpartaDOS 3.2: works, but
COPY H:FILE.BIN D2:fails with error 163, because COPY tries to create a file called*.*. Give the full destination name:COPY H:FILE.BIN D2:FILE.BIN. - SpartaDOS X: doesn't use CIO for its own file access, so H: isn't available at the command line. Use PCLink instead. Enable it under System > PCLink (set the base folder and, if you want, Allow write access), then load
PCLINK.SYSfrom the SDX Toolkit disk (SDX 4.43 or later), directly or withDEVICE PCLINK.SYSin CONFIG.SYS. It adds aPCL:device. Adding/Sto the driver makes it use the OS SIO routine, so Altirra's SIO patch can speed it up. PCLink works the other way round from H:: BASIC and DOS 2 can't use it, because it isn't a CIO device.
5. A fast edit-on-PC, run-on-Atari loop
For BASIC, keep the program as a .LST text file in the H: folder and edit it on the PC with line numbers. Then, in the emulator:
NEW
ENTER "H6:GAME.LST"
RUN
ENTER merges lines into whatever is in memory, so the NEW matters: without it, lines you deleted in the editor live on. After the first time, all three commands are still on the screen. Move the cursor up to each line and press RETURN instead of retyping. When you've made changes on the Atari side, LIST "H6:GAME.LST" writes them back for the PC editor. Keep a tokenized SAVE "H:GAME.BAS" copy too, which loads faster and holds strings with control characters safely.
A program can also save its own work as it runs. The first test program ended with SAVE "H:HELLO.BAS", and the file was on the PC before the READY prompt appeared.
For assembly or C, point your build's output at the H: folder. Under DOS 2.5, the menu's L command then loads H:GAME.XEX without any disk image. Combine this with the command-line launching described in A Modern Cross-Development Workflow, and use the H: folder for data files the program reads at run time, such as level maps, fonts or music. Then you can change the data without rebuilding a disk.
When BASIC crashes, the debugger's .basic_save command can still write the program in memory to a host file, using the same method as BASIC's own SAVE. You can then reload it through H:.
6. When H: gets in the way
- A few programs dislike extra devices. Astro Chase, for example, hangs in its intro if any custom CIO device, such as D: or H:, is registered. Remove the device, or use a profile without it, for such titles.
- Text written to H1: instead of H6: has bare $9B line endings, which PC editors show as one long line.
- Test on real hardware or a disk image before release. A program that works from H: may assume the drive is fast or that long names exist, and neither is true on a 1050.
Troubleshooting
- ERROR 130 on H: the device isn't added, or the $D600/$D700 hook pages are taken by other emulated hardware.
- ERROR 135 when saving: Read only is ticked, or you mounted with
/hdpathinstead of/hdpathrw. - An error opening a file you can see on the PC: its name probably doesn't fit 8.3. Rename it, or use the encoded name shown in the directory listing.
- ERROR 176: the file is open in another program on the PC, or twice on the Atari.
- Listing loads as one huge line: use H6:–H9: for text.
- Works in BASIC but not under SpartaDOS X: expected. Use PCLink.
Further reading
- Altirra Help (bundled with the emulator): the Host device and PCLink topics, and the compatibility notes for MyDOS, SpartaDOS 3.2 and SpartaDOS X.
- SpartaDOS X Reference Manual and the SDX Toolkit documentation for
PCLINK.SYS. - On this site: Setting Up Altirra, A Modern Cross-Development Workflow, The Altirra Debugger, Saving and Loading BASIC Programs and CIO and IOCBs: How Atari Input/Output Really Works.
Credits
- Picture: Altirra 4.40 running the test program: a DOS-style directory of the PC folder, a MyDOS-style change of directory with XIO 41, and a file created on the host. — Program authors; screenshot by the site
- Altirra 4.40 Help — Host device (filename encoding, burst I/O, EOL translation, locking, subdirectories, reserved names, CIO restrictions, special commands, hook page) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Altirra 4.40 Help — PCLink, compatibility notes (MyDOS, SpartaDOS 3.2, SpartaDOS X, Astro Chase), BASIC loading, .basic_save — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Altirra source (H: device setup dialog IDD_HDEVICE, ATHostDeviceEmulator option defaults and filename parsing; Acceleration page) — Screenshot from Avery Lee's Altirra page, virtualdub.org
