Desklink/TS-DOS Directory Access
TS-DOS Directory Management Extensions Programmer's Guide
By Kenneth D. Pettit
Overview
TS-DOS was developed as an alternative for accessing the TPDD and TPDD-2 drives from the Tandy and NEC line of laptops (Model 100, 102, 200 and PC-8201a). As part of the design, when used with the companion "DeskLink" PC program, TS-DOS adds the ability to create and manage a directory structure on the target media. This same directory access extension is also built into the NADSBox SD card reader and allows navigation and access of the FAT directory structure on the media card. The extensions were discovered by reverse engineering the communication between a Model 102 and Desklink (running on an HP 200LX) and between TS-DOS and a TPDD-1 using an HP 4951B serial protocol analyzer. This document describes the TS-DOS directory management extensions (DME) and is, to my knowledge, a complete description of the protocol.
Protocol Structure
History
The TPDD-1 supported two modes of operation for accessing data on the floppy disc - an "Operational" mode and an "FDC Emulation" mode. Each of these modes have a very different command structure and are well documented in the TPDD-1 reference manual. The FDC Emulation mode was used for direct sector access of the data stored on the disc. Neither the TPDD-2 nor Desklink support the FDC Emulation mode and instead add sector access commands in Operational mode to provide the same functionality.
Basic premise for extension addition
The directory management extensions in TS-DOS are implemented partially using commands to support the FDC Emulation mode, and partially using a targeted file extension ("<>") in operational mode commands to denote references to a directory or subdirectory on the media. The FDC Emulation mode commands are used to identify if the client supports DME and the "<>" extension is used to specify target directories for creation, deletion or navigation.
Request Format
Both FDC Emulation requests and Operational mode requests are issued by TS-DOS, although only a single FDC Emulation mode request is used. FDC Emulation requests consist of a single ASCII character with one or more ASCII arguments followed by a carriage return (0Dh). Operational mode requests consist of a Preamble of ZZ (5Ah 5Ah), followed by a Request ID byte, a Payload Length byte, 0 or more payload bytes, terminated by a checksum.
Note: All values are shown as hexadecimal. ASCII character strings are enclosed with quotation marks. The quotation marks are not part of the command or response.
Response Format
In operational mode, the reponse format is identical to the request format, except that no preamble is sent. In FDC Emulation mode, the reponse format varies depending on the command and the TPDD service. Specific details regarding FDC Emulation mode responses will be described as needed.
TPDD Service discovery
Since TS-DOS must operate with with various TPDD servers, and since not all servers follow the same protocol, it must determine if the server is capable of supporting DME. This is done by sending an FDC Emulation mode command to go into operational mode ("M1"), followed by an operational mode command to go into FDC Emulation mode. For this operational mode sequence, TS-DOS actually terminates the command with a carriage return (0Dh) which isn't part of the standard operational mode protocol. The following two commands are sent:
Directory Management Extensions Request (DMEReq)
| "M1" | 0D |
|
0D |
For a TPDD service that supports FDC Emulation mode, the standard response for both commands is no response. If the server does not respond to either command, or responds with an error message, then TS-DOS knows the server does not support DME.
If the server does support DME, then after the final carriage return (0Dh), it shall reply with a standard operational mode response. The response ID must be 12h and the payload field must be 11 bytes long and contain the name of the current directory, or at least the lowest level name in the tree, as shown below. The name should be 6 characters long and should be terminated with ".<>",20h. Names shorter than 6 characters should be padded with spaces before the ".<>",20h extension.
TS-DOS will display the directory name reported in the DMEResp payload in the upper right corner of the display in reverse video characters. If the current directory is the root "/" directory, then the server should return "ROOT .<> " in the payload field as a standard, although any name could be provided. TS-DOS will send the DMEReq sequence multiple times including when it has requested a directory change operation. This provides a way of reporting the new subdirectory name for display in the TS-DOS title bar.
If you are writing a TPDD service, and you wish to implement DME but not FDC mode, you can simply ignore the FDC mode change command and newline. Instead, just respond to the ZZ$08 file-access style command as described in DMEResp.
Directory Management Extensions Response (DMEResp)
| Response ID | Payload Length | Payload | Checksum | ||||||
| 12 | 0B |
|
Checksum |
Directory reporting from Server
Directory Reference Requests (Request ID $00) are part of the standard TPDD-1 and TPDD-2 protocol. They are used for enumerating directory contents. During enumeration, the client can request "pick," "get-first," "get-next," and "get-previous" search forms to reference, initialize, move forward and backward (respectively) through the current directory.
The TPDD server implementing DME (DeskLink, NADSBox, etc.) infers client support for DME by receipt of DMEReq. Directory and subdirectory names are then provided during enumeration along with filenames for the remainder of the session. If the DMEReq sequence is not received, then the server is communicating with a DOS that does not support DME (TEENY, FLOPPY, POWR-DOS, WP-2, etc.).
Once enabled, directory names are reported using the same protocol as files using the Directory Reference Request except that the extension is reported as "<>".
Directory Reference Request (DRReq)
| Preamble | Request ID | Payload Length | Payload | Checksum | ||||||
| 5A 5A | 00 | 1A |
|
Checksum |
When DME support has been established, the server reports directory information by responding to the DRReq sequence with a Directory Reference Response (DRResp) packet with the filename field containing the directory name in 6.2 filename format. The directory name should be 6 characters or less with space padding and the 2 character extension must be set to "<>". TS-DOS uses the "<>" extension to identify the entry as a directory. When the server is reporting file and directory entries for a directory other than the root, it should provide a mechanism for navigating to the parent directory. While DeskLink only provides navigation to the "ROOT.<>" directory, NADSBox, for example, allows navigation to the parent by reporting the first entry of a subdirectory as "PARENT.<>". The number of Free Sectors on the media should be a single byte with the value 80H or less. Sectors in the TPDD protocol are 1280 bytes in length.
Directory Reference Response (DRResp)
| Response ID | Payload Length | Payload | Checksum | ||||||||||||
| 11 | 1C |
|
Checksum |
Change Directory requests from TS-DOS
When the user navigates the cursor to a directory entry that has the "<>" extension and pressed Enter, TS-DOS will perform a Directory Change operation to naviagte to that directory. This is accomplished by sending a Change Directory Reference Request (CDRReq) followed by a standard Open File Request and then a Close File Request. The CDRReq packet is the same as a standard DRReq packet except the filename extension is set to "<>".
Change Directory Reference Request (CDRReq)
| Preamble | Request ID | Payload Length | Payload | Checksum | ||||||||||
| 5A 5A | 00 | 1A |
|
Checksum |
The server should respond to the CDRReq packet with a DRResp response packet containing the same directory name that was passed in the CDRReq. The server should save the directory name and expect to receive a subsequent Open File For Reading Request. When the Open File Request is received, the server should process it as a Change Directory operation to the directory specified in the CDRReq packet and return a standard Normal Response Packet (Id = 12H) with the appropriate error code. If the directory name matches the special name given for the parent directory ("PARENT.<>"), then the server should change to the parent of the current directory. The the server should then expect a Close File Request and respond as usual.
Make Directory
The "Make Directory" request is similar to CDRReq. However, instead of opening the directory "file" for reading, the client will create a new file in Write mode.
Kill Directory
TS-DOS Kill directory appears to the server as a Delete request for the picked directory "file." It is up to implementers to decide whether to permit deletion of non-empty directories.
Rename Directory
TS-DOS "Name" (rename/move) request appears to the server as a Rename request for the picked directory "file."
Checksum Algorithm
Total = Sum of all bytes from TypeID..Last byte of Payload
Checksum = (Total & FFh) XOR FFh
