advanced_options.txt

Some special features & controls, and experiments.

Aside from the options displayed by the help options -h, -c, -b, & -i,
there are also some debugging and special options and some environment
variables.

Command-line stwitches override env variables,
and later switches override earlier switches.

PROFILE is processed before other variables, so that the other
variables can override individual settings within a profile.

Commandline switches:

 -^  Config dump. This just displays several config options and exits.
     If used with -vv, then it shows even more info,
     including the internal results of all environment variables.

     This is a way to verify what config options are actually in effect.

     Build a command line with both variables and switches, and put -^
     as the very last argument, and the dump will show the final result
     of all the combined settings which may override each other, etc.

Environment variables:

variable      data      equivalent  (default        description if no
name          type      cli switch   value)         equivalent in -h help

FDC_MODE      bool      true = -f   (false)
PROFILE       str       -c str      (k85)
ATTR          chr       -a chr      (F)
DME           bool      -e bool     (true for k85)
TSLOAD        bool                  (true for k85)  enable magic files
TILDES        bool      -~ bool     (true)
CLIENT_TTY    str       -d str      (/dev/ttyUSB* for linux)
BAUD          #         -s #        (19200)
RTSCTS        bool      -r bool     (false)
ROOT_LABEL    str                   ("0:    ")
PARENT_LABEL  str                   ("^     ")
DIR_LABEL     str                   ("<>")
XATTR_NAME    str                   ("pdd.attr" w/ platform-specific prefix/suffix) 

str = a string
chr = a single character
# = an integer
bool = case-insensitive on/off true/false yes/no 0/1 t/f y/n

To use these, just put them in the environment. The simplest is just type
them on the same command line before the executable name.

ROOT & PARENT are padded or truncated as needed to exactly 6 bytes,
so you can give a short value without quotes

Example:

	$ ROOT_LABEL=/ PARENT_LABEL=^ dl


ROOT_LABEL="0:"
	examples:
		'ROOT'
		'/'
		'0:'
		'-root-'
		' ROOT '
		'_ROOT_'

	The original Desk-Link, and so, most other emulators also,
	puts the string "ROOT  " in the top-right corner of the TS-DOS
	display when the user is in the top level share directory.

	This variable lets you put whatever you want there.

	The field in TS-DOS is exactly 6 characters.

	Shorter than 6 bytes will be left-justified.
	Longer than 6 bytes will be truncated.

	If you want a shorter string to be centered,
	use quotes and include the spaces.

PARENT_LABEL="^"
	examples:
		'PARENT'
		'^'
		'^:'
		'  up  '
		'__up__'
		'-back-'
		'UP:'

	Similar to ROOT_LABEL, Desk-Link used the word "PARENT" for the
	the "go back up one level" directory entry in the top-left file
	slot in the directory listing screen.
	This was Desk-Links equivalent to ".."

	This variable lets you put whatever you want there instead of
	"PARENT", with limitations. Unfortunately, since this appears
	in the file list like any other file, and TS-DOS is picky about
	what it considers a "bad" filename, and you can't put just
	anything here. Most notably, you can't use "..", because normally
	"." would be an illegal character in a Model 100 filename except
	the one in the 7th byte.

	This is a TS-DOS limitation. You CAN actually use "..", in that dl2
	will send it to TS-DOS, and TS-DOS will even display it properly in
	the file listing, but if you try to select it to move back up a
	directory, TS-DOS just beeps and says "bad filename". The error is not
	dl2 rejectimng the command, TS-DOS rejects the filename and never tries
	to send any command.

	However a lot of other things do work fine. Generally, for something
	to work, it has to be left-justified like a real filename would be.
	It takes some trial & error to figure out what works.

ATTR="F"
	examples: 'F', ' ', any single byte

	A real TPDD drive has a one-byte field along with every filename.

	It's just a text field that the drive can use to return a group of
	matching files all together before the rest during file listings.
	It's not really used by any software I know of, but the field is
	there, and when a client gives a dirent() command, it must include
	the field with some value in it, and if trying to access an existing
	file on disk, the value must match the value on disk.

	Floppy and TS-DOS and all other KC-85 platform tpdd client software
	always writes an 'F' there, hard-coded for every file, reading or writing,
	and does not display the field to the user or give any way to change it.
	This essentially no-ops the field.

	When an emulator is serving files, usually there is no actual attribute
	byte stored with the file, so all emulators just fabricate an F there for
	every file when they give filenames to clients.

	But a real drive lets you put anything you want in that field, and actually
	matches the value in a dirent() request from a client against the values
	in the directory entries on the disk.

	All this setting does is, when the client requests a file or directory
	listing, and we're sending a filename and filesize to the client, it uses
	the specified value instead of the built-in default 'F' for the attribute byte.

	Who/what ever cares? Who knows. It's possible the Cambridge Z88 doesn't
	write 'F' in the attr field the way Floppy does, and so for those machines
	maybe you may need to specify ' ' or something else.
	Possibly also the Brother knitting machines used the field for actual file
	classification/grouping and wrote various values there.

	pdd.sh exposes the field and let's you see it and write whatever
	you want in it and search whatever you want in it.

 PROFILE=k85
 PROFILE=8.3
 PROFILE=8.2p
	Same as command line switch "-c"

	PROFILE=name
	-c name    use profile <name> - (default: "k85")

	PROFILE=#.#
	-c #.#     "raw", truncated but not padded to #.#, attr=F

	profile=#.#p
	-c #.#p    "raw", truncated and padded to #.#, attr=F

	Profiles taylor the translation between local filenames and TPDD filenames.

	A real TPDD doesn't care what's in the filename, and emulating a TPDD
	doesn't require any translation other than truncating to 24 bytes.

	But most TPDD clients write filenames to TPDD drives in specific formats,
	and we need to translate filenames between the local and client formats.

	Strictly speaking, "raw" always works for any and all clients,
	from the clients point of view. It still emulates a real drive exactly.

	The only reason for any compatibility profile is for more convenient
	local filenames. When TS-DOS saves a file like "A.BA", it actually
	writes "A     .BA" to a real drive. In "raw" mode this would create a
	local file named verbatim: "A     .BA", which is legal but inconvenient.
	And TS-DOS does not recognize any disk files that don't conform
	to the "k85" profile below. (fixed-length, space-padded, 6.2)

	"raw" still "works" because TS-DOS can both create any files it
	wants, and access any files it created, identical to a real drive.

	Profiles just make it so that a local file named "my_long_file_name.text"
	appears to TS-DOS as "my_lo~.t~", which may be ugly but TS-DOS can use it.
	And when TS-DOS tries to read or write a file named "FOO   .CO",
	we use "FOO.CO" for the local filename.

	Most of the parameters in a profile also have individual commandline flags.
	Example: "-c k85" is short for "-c 6.2p -a F -e on"
	(except k85 is the default so you don't need to use any of those)

	The #.# syntax is a way to specify any other filename pattern you might need
	that isn't covered by one of the built-in profiles below.

	If the number after the dot is >0 then the translated filename will have only
	one dot. The last dot in the original name will be taken as "the" dot.
	Everything before the last dot will be truncated down to the basename length,
	and any dots substituted with "_". Everything after the last dot will be
	truncated down to the ext length.

	To specify a simple max length without limiting or modifying dots, use #.0

	Examples:
	-c cpm      "abc.txt" -> "abc.txt"
	-c 8.3      "my.long.file.name.shtml" -> "my_long~.sh~"
	-c 8.2p     "abc.txt" -> "abc     .t~"
	-c 14.0     "my.long.file.name.shtml" -> "my.long.file.~"
	-c 6.2p -u  "abc.co" -> "ABC   .CO"

    or equivalent:
	PROFILE=cpm    "abc.txt" -> "abc.txt"
	PROFILE=8.3    "my.long.file.name.shtml" -> "my_long~.sh~"
	PROFILE=8.2p   "abc.txt" -> "abc     .t~"
	PROFILE=14.0   "my.long.file.name.shtml" -> "my.long.file.~"
	PROFILE=6.2p UPCASE=on  "abc.co" -> "ABC   .CO"
	PROFILE=k85    "abc.co" -> "ABC   .CO"

	The default is the same as: PROFILE=k85
	which is also the same as: PROFILE=6.2p UPCASE=on ATTR=F DME=on TSLOAD=on TILDES=on

	The default "k85" matches all KC-85-clone platform clients. Examples:
	Floppy, TS-DOS, DSKMGR, TEENY, etc, on TRS-80 Model 100, NEC PC-8201a, etc.

	NAME    profile name
	BASE    basename length
	EXT     extension length
	PAD     fixed-length space-padded
	ATTR    default attribute byte if no xattr
	DME     enable TS-DOS directory mode extension
	TSLOAD  enable "magic files" (ex: DOS100.CO) for TSLOAD / Ultimate ROM II
	UPCASE  translate filenames to all uppercase

	Available profiles:

	NAME  BASE EXT  PAD	 ATTR  DME  TSLOAD  UPCASE
	-------------------------------------------------------------
	raw     0   0   off  ' '   off    off   off
	k85     6   2   on   'F'   on     on    on
	wp2     8   2   on   'F'   off    off   off
	cpm     8   3   off  'F'   off    off   off
	rexcpm  6   2   on   'F'   off    off   on
	z88     12  3   off  'F'   off    off   off
	st      6   2   on   'F'   off    off   off

FDC_MODE=false
	default false
	commandline switch -f (takes no argument) is the same as FDC_MODE=true

	A TPDD1 / FB-100 drive has two main modes of operation called
	Operation-mode and FDC-mode.

	These are basically two entire different sets of commands to
	use the drive.

	A real drive has dip switches that let you set either mode to be the
	default mode at power-on.

	This setting lets you emulate the dip switch settings for starting up
	in FDC-mode instead of Operation-mode.

	Default is FDC_MODE=false, meaning dl2 starts up in Operation-mode.
	This matches the TPDD1 default dip switch settings, and the hard-wired
	solder-blob settings on Brother FB-100, KnitKing FDD19, Purple Computing D103, 
	and matches the TPDD2's only mode (tpdd2 has no FDC mode).

	Regardless which mode is the default at start-up, the drive (and dl2) still
	responds to the commands to switch between modes, and at least some clients
	like TS-DOS always send a little set/reset sequence to ensure the drive gets put
	into Operation-mode before it tries to use any other Operation-mode commands.

BAUD=19200
	valid values:
		75       model-t supports, drive does not
		110      model-t supports, drive does not
		150      drive supports, model-t does not
		300
		600
		1200
		2400
		4800
		9600     default Brother FB-100, KnitKing FDD19, Purple Computing D103
		19200    default TANDY 26-3808, TANDY 26-3814
		38400
		76800    drive supports, host platform usually does not

	Set the baud rate. Same as the "-s" commandline flag.
	Default is 19200.

	The TPDD1 has dip switches to support several different baud rates from
	75 to 76800. The default setting from the factory and in the user manual
	is 19200.

	The Brother FB-100 and re-badges like Purple Computing D103 have a set of
	solder-jumper pads instead of dip switches. They support all the same baud
	rates as TPDD1 but require soldering the jumper pads or installing a dip
	switch to change the baud rate. From the factory they are all hard-wired
	to run at 9600 baud with a solder blob on one of the dip switch positions.

	The TPDD2 has no dip switches or other means to set a different baud rate,
	and only runs at 19200 baud.

	Most tpdd client software just tries to run at 19200.

	Although the drive has a dip switch setting for 76800 baud, that is a weird
	rate that a typical linux/bsd machine today does not natively support.
	But some platforms like linux on Sparc do (apparently) support this baud
	rate. So the option is there in dl2 but isn't available unless you compiled
	on a system that supports it.

CLIENT_TTY=ttyUSB0
	examples: ttyUSB0, ttyS2, cu.usbserial-AL03RAXP

	The device name of the tty that the client is connected to,
	with or without the leading "/dev/".
	Same as the "-d" commandline flag.

	For osx/macos always use the "/dev/cu.*" interface and not the
	"/dev/tty.*" interface to the same device. The cu.* interface
	provides exclusive access to the port and avoids data corruption.

DME=true
	Enable/Disable TS-DOS directory support.
	Default depends on the PROFILE.
	Default profile is k85 which has DME enabled.
	Use this to override whatever the profile has set.

	TS-DOS/Desk-Link directory mode extensions technically violate the tpdd spec,
	which could theoretically break some legitimate tpdd client software that
	is playing by the rules, and just happens to do the same thing as what TS-DOS
	does for a "DME request".

	The only things likely to break would be things that switch between
	Operation-mode and FDC-mode on TPDD1, and the only things found so far that
	use FDC-mode at all are Sardine and the installer for Disk-Power, and both
	of those are working on dl2 without needing this option.

TSLOAD=true
	Enable/Disable the "magic files" feature.
	Default depends on PROFILE
	Default profile is k85, which has TSLOAD enabled
	Use this to override whatever the profile has set.

	In case you specifically do not want the special filenames like "DOS100.CO"
	to be recognized and work by magic even if there is no file by that name.

TILDES=true
	Enable/Disable indicating truncated filenames with a trailing "~"
	Default is true

XATTR_NAME=pdd.attr

	If compiled with -DUSE_XATTR, then this environment variable can be used
	to specify a different xattr name than the default "pdd.attr" for
	storing and retrieving the ATTR byte for each file.

	Default depends on the platform.
	Default is "pdd.attr", with platform-specific prefixes or suffixes added.
	linux:   "user.pdd.attr"
	mac:     "pdd.attr#S"
	freebsd: "pdd.attr" in EXTATTR_NAMESPACE_USER