RespeQt Folder Images and PCLink: Sharing a PC Folder with Your Atari
Mounting ATR images is the usual way to use a PC as an Atari disk drive. But if all you want is to move a few files across, building an ATR first is a chore. RespeQt offers two shortcuts. A folder image makes a directory on your PC look like a DOS 2 disk in one of the Atari's drive slots. PCLink goes further: with SpartaDOS X and its PCLINK.SYS driver, the Atari can read and write files in that folder, subdirectories included.
What you'll learn: how folder images work and where their limits are, how to set up PCLink under SpartaDOS X, the naming rules that trip everyone up, how to reach PCLink from BASIC, and which other programs speak the same protocol.
What you need: a working SIO2PC connection with RespeQt (see SIO2PC and RespeQt: Using Your PC as an Atari Disk Drive for cables, handshake and drivers). For PCLink you also need SpartaDOS X 4.43 or later and its Toolkit disk.
1. Folder images: a PC directory as a read-only disk
Every drive slot in RespeQt can hold either a disk image or a folder. Use the slot's menu to mount a folder image and pick a directory. The Atari then sees a disk in that drive, built on the fly in the DOS 2.x format. That format is also readable by MyDOS and by SpartaDOS X's ATARIDOS.SYS.
What you get:
- Instant loading. Copy a game or utility into the folder on the PC and it appears on the Atari. From DOS 2.5 you can binary-load a file with option L. From BASIC,
LOAD "D3:PROGRAM.BAS"works. - Read-only access. The disk reports 0 free sectors and is permanently write-protected. Files flow one way only: PC to Atari.
- A DOS 2 directory limit. DOS 2 directories hold 64 entries. Put more files than that in the folder and RespeQt's log warns that it "cannot mirror" the rest because the Atari directory is full. Keep a small folder for each job.
Booting from a folder
A folder image can also be made bootable. RespeQt keeps the boot sectors and DOS files for several DOSes in folders named $bootata, $bootmyd, $bootxl, $bootspa and so on, next to the program. Choosing a DOS for a mounted folder makes it boot that DOS. These $boot folders must be present, and some early release packages left them out by mistake. On macOS, RespeQt looks for them inside the application bundle. Booting SpartaDOS from a folder is the weak spot: RespeQt's own manual listed problems with it. In practice SpartaDOS users treat folder images as a source for copying files onto a hard disk or a large ATR, and boot from something else.
2. PCLink: read/write access for SpartaDOS X
PCLink is a file-level protocol, not a disk emulation. The Atari doesn't ask for sector 361. It asks the server to "open this file", "write these bytes", "list this directory". That removes the size, directory and write limits of a fake disk. The protocol, also called DOS2DOS, was designed by Konrad Kokoszkiewicz (Drac030) of the SpartaDOS X team for his SIO2BSD server. The Atari side is the PCLINK.SYS driver, included with SpartaDOS X from version 4.43. In 2016 the developer TheMontezuma ported the server code into RespeQt for Linux and Windows. The same protocol is understood by Altirra's built-in PCLink device and by the Ultimate1MB and Incognito firmware.
Setting it up
- Get the driver.
PCLINK.SYSis on the SpartaDOS X Toolkit disk, not on the cartridge. Extract it from its archive with SDX'sARCcommand, for example intoC:\TKIT\DRV\. -
Load it. Run it once from the command line, or load it at every boot by adding a line to
CONFIG.SYS:DEVICE C:\TKIT\DRV\PCLINK.SYS
It reports something like PCLink v0.3, dev. 6, SIO id $6F. The driver talks to SIO device $6F.
3. Mount a folder in RespeQt. There is no separate PCLink window. RespeQt reuses the folder-image slots, so the folder in slot n is reachable two ways: as Dn: (the read-only DOS 2 disk from section 1) and as PCLn: (read/write through PCLink). A slot holding an ATR has no PCLink side.
A first session in the SDX command processor, with a folder mounted in slot 3:
D1:DIR PCL3:
D1:COPY D1:*.COM PCL3:
D1:X PCL3:GAME.XEX
D1:PCL3:
PCL3:DIR
PCL: on its own means PCL1:, just as D: means D1:. The last two lines make the PCLink folder the current drive (supported from SDX 4.48). Copying the other way, from a hard-disk partition to PCLn:, is how people back up a whole Atari hard disk to the PC.
Naming rules
This is where most "it doesn't work" reports come from:
- 8.3 names only. SpartaDOS X uses DOS-style 8.3 filenames. Files on the PC with longer names are simply not listed.
- One case only. By default RespeQt's PCLink shows only lower-case 8.3 names, and files the Atari writes are stored in lower case. An option added in 2016 switches it to upper case instead. Mixed-case names on the PC are ignored.
- Altirra applies similar rules. Names must fit 8.3 and use only A–Z, 0–9 and
_. Files of 16 MB or more are invisible. Names that collide with reserved Windows device names such asCOM1get a!prefix on the host.
Anything the Atari itself writes to PCLn: follows the rules automatically. The trouble comes from files you drop into the folder on the PC side. Rename them to short lower-case names (or switch the case option) and they appear.
PCLink from BASIC and other programs
Under SpartaDOS X, programs that go through CIO, such as BASIC or the Assembler Editor, can't use the kernel device name PCL3: directly. Prefix it with D, which hands the name to the SDX kernel:
10 OPEN #1,8,0,"DPCL3:SCORES.DAT"
20 PRINT #1;"HELLO FROM THE ATARI"
30 CLOSE #1
40 LOAD "DPCL3:MYPROG.BAS"
Without SpartaDOS X there is no PCL: device. Atari DOS and BASIC on their own can't see PCLink, because it needs that operating-system support. In an emulator, use Altirra's H: host device instead.
3. Other places the same tools appear
- Altirra has a PCLink server built in (System > PCLink). Set a base folder and tick Allow write access if the Atari may change files. Its SIO patch and burst options apply to PCLink too. Loading the driver with
PCLINK.SYS /Smakes it use the OS SIO routine instead of SpartaDOS X's own, which lets the SIO patch accelerate it. Altirra also has its own virtual folders: per-drive folder mounts in DOS 2 format (up to 64 files) or SpartaDOS format (no file limit), always read-only. - Ultimate1MB and Incognito firmware support PCLink too, and Jonathan Halliday's Incognito firmware adds high-speed SIO for PCLink and other serial devices.
- SIO2BSD, the original server, runs on FreeBSD, Linux and macOS (and under Cygwin on Windows), with up to 15 disk images.
- RespeQt 5.4.x adds a TNFS server. A FujiNet on the same network can browse the folders you have mounted as folder images, though not the contents of mounted ATRs. Point the FujiNet at the PC's IP address and allow ports 16384 UDP and TCP through the PC's firewall. RespeQt is a TNFS server only. It doesn't connect to other TNFS servers.
4. Under the hood
PCLink uses just three standard SIO commands on device $6F. Put ($50) sends a function code and its parameters, Read ($52) fetches the reply or file data, and Status ($53) returns error codes and buffer sizes. The functions mirror a DOS's file interface: open, read, write, seek, get position, get length, close, find first and next, change attributes, make and remove directory, change and get the current directory, and get disk information. Because the PC deals with files, not sectors, there is no disk-size limit and no directory to fill up. Because it travels over normal SIO frames, it works at whatever high speed the link supports. Users have reported PCLink transfers at high-speed index 3 and down to POKEY divisor 0.
Troubleshooting
- SDX prints "no server response" or error 138 when the driver loads: RespeQt isn't answering on $6F. Check that emulation is running, that the serial link works for normal disk images first, and that a folder, not an ATR, is mounted in the slot you're addressing.
DIR PCL:works butDIR PCL2:doesn't: make sure slot 2 holds a folder. After dragging slots around in RespeQt, restart it and cold-boot the Atari.- Files you copied in on the PC are missing: they break the 8.3 or case rule. Rename them or change the case option.
- Writes to Dn: fail: that's the read-only folder image. Use PCLn: (or
DPCLn:from BASIC). - Transfers stall at high speed: try the driver with and without
/Sand drop the RespeQt speed. One user found PCLink became reliable only after removing/SfromCONFIG.SYS. - Folder won't boot: check that the
$boot…folders sit where RespeQt expects them. To boot SpartaDOS, use a real SpartaDOS ATR in D1: and keep the folder in another slot.
Further reading
- The SpartaDOS X User Guide (4.4x), chapters on drivers and
PCLINK.SYS, and the Toolkit documentation. - Altirra's help file, PCLink support and Disk drives: Virtual folders.
- The comp.sys.atari.8bit FAQ, sections 3.4.1 (PC-based SIO servers) and 7.3.2 (SpartaDOS X).
- The AtariAge RespeQt / SIO2PC Software forum threads "PCLINK.SYS support?" and "So I want to use PClink.. how?".
- Our guides SIO2PC and RespeQt: Using Your PC as an Atari Disk Drive, SpartaDOS X: Getting Started with the Command-Line DOS and FujiNet Setup Guide.
Credits
- AtariAge — PCLINK.SYS support? (RespeQt PCLink port, usage, naming rules, DPCLn: from CIO), 2016 — AtariAge forum members, 2016
- AtariAge — So I want to use PClink.. how? — AtariAge forum members
- AtariAge — RespeQt general discussion (folder images DOS 2.x, read-only, directory full warning) — AtariAge forum members
- AtariAge — RespeQt r2 released (folder images read-only; PCLink as alternative) — AtariAge forum members
- AtariAge — Respeqt, OSX, folder boot issue ($boot folders) — AtariAge forum members
- AtariAge — RespeQt r3 released (SpartaDOS folder boot issues, speeds) — AtariAge forum members
- AtariAge — RespeQt r4 released (PCLink 'no server response') — AtariAge forum members
- AtariAge — First Release Candidate for Version 5.4 of RespeQt (TNFS server) — AtariAge forum members
- Altirra 4.40 help — PCLink support; Disk drives: Virtual folders — Avery Lee (Altirra)
- comp.sys.atari.8bit FAQ (Michael Current) — 3.4.1 (SIO2BSD, RespeQt, Incognito), 7.3.2 SpartaDOS X (PCLINK.SYS as of 4.43) — Michael Current (comp.sys.atari.8bit FAQ)
