Ds

Keyword	Abbreviation	Token (hex)	Version(s)	Classification
DS	none	44 53	3.5+	Reserved variable

Note the 'token' is really the character codes of the keyword.

Syntax

Returns	Type	Value(s)	Note(s)
diskStatus	Signed Byte	0 to 127 or -128 to -91 (rare)	Device specific

Purpose

Get the numeric code from the current diskStatus_string.

Remarks

This reserved variable returns the numeric value corresponding to the first two characters of the current diskStatus_string (see DS$). If there is no diskStatus_string, then DS will first input a string from the error/status channel of device "DosFA" (a secret variable) into DS$.

Unfortunately BASIC provides no direct way to set "DosFA", and attempting to supply any parameter to DS (such as a device number) will generate SYNTAX ERROR. Otherwise, if a diskStatus_string already exists, then DS can not generate an error.

If a diskStatus_string does not exist, then a new diskStatus_string is read into DS$ from channel 15 of the device specified by the secret "DosFA". This might cause an I/O error, like DEVICE NOT PRESENT (for example, if the device number was changed, or the device has been powered-off or disconnected). If you have previously OPEN'ed a file with fileNumber of zero to any device (I believe only the keyboard is allowed) then you may get either FILE OPEN ERROR or in some cases (not sure of how each are triggered) the cursor will appear on screen and wait for you to enter some text (which will be stored as the diskStatus_string, and your fileNumber 0 will be CLOSE'd). See examples.

When diskStatus_string is present (either already existed or newly read), the first two characters are converted into a diskStatus number. If the first characters of the string are not ASCII digits ("0" to "9"), then an erroneous diskStatus number is returned. The way it works, only unsigned values of 0 to 165 can ever be calculated: the low 4 bits of the first character is multiplied by ten then added to the low 4 bits of the second character. However BASIC will interpret this as a signed byte; so any unsigned value of 128 or more will report as a negative diskStatus.

Assuming you don't have an OPEN file 0, DS works fine in conjunction with disk-based commands like DIRECTORY, DLOAD, and such. But because the secret "DosFA" is not updated by other commands that are often used with a disk, like CLOSE, CMD, GET#, INPUT#, LOAD, OPEN, PRINT#, SAVE, and VERIFY, using DS may report on the wrong device. This is especially true in a program that uses multiple disk devices at once. To work around this bug, you can POKE the DosFA or use the "BASIC 2 Method" of reading the diskStatus_string (that is, INPUT #15,E,M$,T,S where '15' is an already OPEN'ed file to channel 15 of the desired device and E would be the diskStatus). If that sounds a bit archaiac / difficult to understand, that's because it is! Hence the reason for including DS and DS$ in BASIC... too bad it is buggy.

Here is the location of the "DosFA" secret variable for some machines:

Machine	PEEK Address
C128	284
C16	631
C64	not applicable
CBM-II	?
PET	not applicable
Plus/4	631
VIC-20	not applicable

*Update*

I just thought (and performed some testing) of a less machine-specific way to work around the bug! Use DCLOSE with a file# not in use, and specify the desired device as a parameter. For example, to be sure the next read of DS will refer to device 9, use this just before: DCLOSE #77, U9 (where 77 is a file# that was never opened). The only "problem" is it only works with the same devices that all disk commands accept (only device 8 to 11). Using the POKE method works with any IEEE/IEC device (4 to 30).

Reading DS does not clear the value, so you may read it multiple times (if diskStatus_string did not exist, then ST will be updated when the string is fetched). The DS value will remain until you use any I/O command that references a device number between 8 and 11 (traditionally disk drives). This includes both "disk commands" from BASIC 3.5+ and generic I/O commands of v2.0; all of them clear DS$ (i.e., the diskStatus_string), and a few of the disk commands will read a new diskStatus_string. See examples.

The numeric code returned is device-specific, but generally a value from 0 to 19 is an informational message, while a value of 20 or more indicates an error related to the last command sent to the device.

Like all BASIC variables, only the first two characters of the name are significant. So you may also use DSTAT if you prefer (note the "TAT" characters are superfluous). Like most BASIC reserved variables, attempting to assign a value to it will generate SYNTAX ERROR.

Warning! On the C128, using the built-in MONITOR will destroy the descriptor for the diskStatus_string, even if you don't use any MONITOR disk-commands. Thus when you return to BASIC and try to access DS or DS$ you will get unreliable results until you use a disk command or perform CLR (directly or indirectly).

Examples (normal):

SCRATCH "JUNK FILE" : REM refers to device 8
ARE YOU SURE? Y
01, FILES SCRATCHED,01,00

READY.
PRINT DS
 1

READY.
PRINT DS
 1

READY.
PRINT DS$
01, FILES SCRATCHED,01,00

READY.
PRINT DS
 1

READY.
OPEN 1,9 : REM access device 9 -- clears DS/DS$

READY.
PRINT DS : REM this will get status of device 8!
 0

READY.
PRINT DS$
00, OK,00,00

READY.

Examples (with OPEN fileNumber of zero):

PRINT DS$ : REM assumes disk device is present
00, OK,00,00

READY.
OPEN 0,0 : OPEN 1,9: CLOSE 1 : REM open 1,9 will erase DS$ (don't care if device 9 present)

READY.
PRINT DS$ : REM also "works" with PRINT DS
L9, BAD MFT ENTRY IN NTFS,12,34   user input!
** text display is mangled **

READY.
PRINT DS
-127

READY.
PRINT DS$
L9, BAD MFT ENTRY IN NTFS,12,34

READY.

Compare With

ST, ER, TI

Contrast With

CMD, CLOSE, GET#, INPUT#, LOAD, OPEN, PRINT#, SAVE, VERIFY