Post by wsoft on Apr 14, 2024 13:13:32 GMT
The following is what I could scrounge from the Wayback Machine as was recorded back in 2004. The original docs from version 5.0 of WsDos, written in April of 1998. Delve deep into a world of brain farts and upgrades from back in the day. First brain fart? The date. The 16th of April was on a Thursday not a Friday. Another brain fart is where I "hoped" that using the address of E0A9 to detect the presence of a RamLink might lead to European compatibility, this being because the ROM routines were designed to be compatible with both PAL and NTSC and have nothing to do with either side of the ocean but much more to do with me being ripped off by CMD when I bought their damned Ramlink serial number 000646 in 1991, when I was still living in Mannheim Germany (yes this was still somewhat of a grudge thing back then).
What was keeping WsDos from being NTSC compatible was how it waited for a certain bit in $D011 and I actaully fixed the PAL version of the game A.C.E. using the same technique back in 1993.
There is a wealth of information for machine language programmers here.
---------------------------------
Documentation, version 5.0 of WS DOS Friday, April 16,1998
WS DOS (C)1992,93,94,95,98 WSoft FREEWARE- Copy Share Post Don't Sell
PREFACE
Well that about does it. I'm ready to release this latest version (5.0!) of
WS DOS. Not only have many new features been added, compatibility with the
RAMlink has also been greatly improved over version 4.1, which had problems
switching down to 64-mode unless the RL was swapped with another device. With
this newer version, you should be able to boot with the RAMlink in (or out of)
a swapped state. However, there are different ROM versions lurking around out
there, so I can only vouch that everything works fine with mine, and wish you
well with yours. For the benefit of those of you using this software for the
first time, WS DOS was concieved from the first moment on with the stock 128-
user in mind.
Utilizing the higher "burst-mode" speeds of the 1571 and 1581 disk drives to
boot up 64-mode software has been done many times, in many different ways. The
"64 boot disks" and other "stand alone" type programs come to mind. Yet all of
these programs shared a common disadvantage; you had to re-load the software
which performed this task each time you used it, or had to prepare a disk boot
sector, etc. WS DOS never followed that trail. Once you've booted it, it takes
residence in the bank 1, and you can put your disk away for either as long as
you have your computer on, or until it is overwritten by another 128 program
which uses high bank 1 memory itself. If you spend most of your time in 64-mode,
you'll want to try WS DOS. A bug has been fixed in regard to loading programs
from the older PET and CBM computers. If WS DOS finds a low byte of 0 in the
address mark of the file to be booted, it will assume that it is dealing with a
program from one of those older monsters and copy the file to $0800, regardless
of what is contained in the high byte (on older PETs and CBMs this is usually
4). If you've used WS DOS 4.1, you'll like 5.0 better. If you have a RAMlink,
you may already be yawning. Read on, Yawn. Sid Davis 1339 Hancock st. Modesto,
CA. 95351
------------------------------------------------------------------------------
NEW FEATURES in WS DOS
1) RAMlink Compatibility Good
To sum it up in a few words, this version of WS DOS gets along with (my)
RAMlink better than any other program I've ever seen (which does anything similar).
Booting a 64 program from 128-mode is now exactly as easy as it always was using
Jiffydos in 64-mode. I've given up trying to find any more bugs in the RAMlink fix.
The compatibility is that good. It is my hope that by using the address $e0a9 to
detect the presence of a RAMlink, that PAL RL users may also use WS DOS. At $e0a9
is a routine which switches in RL system memory, and it has been well documented
in the RAMlink operating manual.
2) Multiple Drive Support in a PC Environment
As you might have already guessed, WS DOS is no longer limited to devices 8 and 9.
Version 5.0 supports devices in the range of 8-31. The prompt is no longer numeric.
The drive designation is now handled much like CP/M or MS DOS, where "A:" is the
first floppy (device 8 on the bus) "B:" is device 9, "C:" is device 10, etc.
This would make the RAMlink device "I:", but you could always change that to a
drive "D:", and your hard drive to drive "C:", if you want the PC feel. I've set
mine up like that, and use device numbers of "A:" and "B:" for my 1571 and 81
disk drives. To log in a different drive, enter the letter designator and trail
it with a colon (":"). WS DOS will make sure that the requested device number
falls within the legal range of 8-31 (A to X), and then make sure the drive is
powered up. For example, if you entered;
A>d: (log request on device 11), or
A>D: (not case sensitive)
00, ok,00,00 (your report, provided the drive is on)
D> <--- drive D is now logged in.
3) Target Drive Selection for the Filecopy Function
If you've ever used WS DOS 4.1, you'll know that selecting the target drive was
as simple as binary 0 and 1. Since only devices 8 and 9 were supported anyway,
the only device which *could* be the target drive was always the one not logged
at the prompt (the sleeper). With the addition of multiple drive support in 5.0
however, some changes were made. First, I rid WS DOS of the #8 "toggle"
principle. Adding the multiple support rendered it pretty well obsolete. The "#"
is still used as a command, but now it's used as a "target device" selector for
the file copy command. To select a drive to copy to, check first that the drive
is on, or you'll get an error. Simply enter the command "#", followed by the
drive designator and a colon. Example; A>#e: (request on device 12 as target
drive) Target Device Set <--- your report, if everything went ok A> The source
drive remains the currently active, or "logged" disk drive. In the example above,
this would be device 8 (drive A:).
4) The Lira character: Read PETASCII text files
This one may later be improved to read ASCII files as well, but for the time
being it will do. Reads SEQ, PRG, or USR textfiles (a handy gadget). We RAMlink
users are quite spoiled by the ability to read a textfile on the fly. I've added
this new feature as one of convenience for the stock 128 users. Since WS DOS can
pop up anytime at the touch of the reset button and instantly be there, it's
handy to enter 128-mode, read the doc file of a program, and reboot your
software. No more wasting time searching for that (slow) file reader program.
More on this one later.
5) "DOS" Commands on the 128
WS DOS has been added on in such a way as to give the experienced machine
language programmers among us their own wedge into the system. If you can
program in machine code, then you may want to add some new command to the
pallette. For this reason, the "syntax" error is no more. As far as WS DOS is
concerned, anything you typed at the prompt could also be a valid command on
the disk. If the word you typed in matches a filename on disk, the file is
checked for a certian sequence of bytes. This PETASCII text -> wsdos98 <--
is used as an indentifying header. If these bytes are present, the following 2
bytes are used as an indirect pointer and WS DOS tranfers total control to your
code, which you must assemble to $3000. WS DOS will shove a return address onto
the stack before the jump occurs, so all your code must do to return to the
program is to terminate with an RTS. I have made about ten or eleven such "DOS"
commands as a result of beta-testing. Your code need not include a carriage
return after outputting to the screen, that is taken care of after you RTS back
to the program. The only thing that's important is that WS DOS can properly
identify the file, which must contain the proper header ID and the address mark
of $3000. If you've done that correctly, the jump over pointer $3007+8 will
occur. There are a few routines built in to WS DOS that you may find handy. At
$2fee there is a small jump table which provides easy access to 6 of them.
INTERFACING WITH WS DOS
$2fee jmp VALID
VALID is a routine which verifies the existance of a file, stores it's address
mark to $fb and $fc, and returns to the calling routine (provided the file
exists). Anytime WS DOS works with a file on disk, it calls this routine first to
weed out any possible "file not found" error. If the file does not exist, 2 bytes
are pulled from the stack and WS DOS resumes normal operation. Before calling
this routine, store the filename at $1602, and the file length (plus 1) at $1600.
$1601 is where the command character is stored within the input buffer, which
adds a byte to the length in $1600. So remember: The filename length (+1) in
$1600, and stash the filename at $1602. If you've set that up right, VALID will
handle the length and the location of the filename correctly. If you wish to
read the error channel after calling this routine, call the FULLERR routine at
$2c91. There is no return from FULLERR.
FULLERR will properly handle the error output after a call to VALID, without a
return to the calling routine. FULLERR is an abort routine, so that means it will
pop the stack twice and output the error. VALID will call FULLERR if it
encounters an error, and program execution will be resumed by WS DOS. Otherwise,
if everything went OK, the processor will return to your routine.
VALID filters possible disk errors by opening the file on disk, and reading the
first byte of the error channel. If this byte is anything other than $30 (first
byte of an "00, ok, 00,00" string), then FULLERR is called.
$2ff1 jmp BOOT
This routine will call VALID to confirm the existance of a file, and then
boot it into 64-mode. Set up just like you would for the VALID routine. In the
event of an error, control is again taken by WS DOS.
$2ff4 jmp LOAD
This will do the same as the BOOT routine, with one exception and one extra- It
will not start the program; it bails to direct mode after it has finished setting
up the 64. If you have the CONTRL key down during the load, the program will be
LISTed as well. Setting up is done the same way as with the VALID and BOOT
routines.
$2ff7 jmp CHKDSK
This powerful routine is the one which makes using "DOS" commands possible, and
could be used to chain DOS commands together. This could be done in this way:
DOS command "X" is called, copies itelf elsewhere in memory and resumes control
at the new memory location, leaving memory at $3000 free for more DOS commands.
DOS command "X" then sets the filename up with the ACTUAL number of characters
in DOS command "Y"s filename, and storing the filename text to $1601 (not $1602).
DOS command "X" then modifies the existing return address within the CHKDSK
routine to similate an RTS to itself, then the CHKDSK routine is called. DOS
command "Y" executes itself and ends with an RTS, which returns control to DOS
command "X" once again (which calls DOS command "Z", etc). Care should be taken
to restore the original return values into CHKDSK to insure the routine will work
correctly (if you still intend to use the DOS). This could be done on the fly by
pulling the first byte from the stack, stashing it into another register, pulling
the second one, restoring the CHKDSK routine with these values, and ending your
code with a direct JMP to $202b, where WS DOS outputs a new instance of the
prompt and waits. In fact, if you intend to do such things as chaining DOS
commands together, it might be best to pull the return address from the stack
right off the bat, before anything else is done. In this way, you need not concern
yourself with the stack requirement as much, and you can end your code with a jump
to $202b.
The locations where the low and high bytes exist within CHKDSK are $2e3e (low)
and $2e38 (high), respectively. These locations usually contain the values $2a
and $20, setting up an eventual (RTS) return to address $202b. When pushing a
return address onto the stack, insure that you first push the high, then the low
byte (-1) of the point in memory you wish the next RTS to return to. The
possibilities of this routine are enormous. I may attempt to program a multiple
file-copier using this technique (just an idea).
$2ffa jmp CHKPRS
The CHKPRS routine will tell you whether a drive is powered up. Set up by saving
the actual number stored in $ba, load the device number that you wish to test into
register A, and call this routine. If the drive is not on, the routine will return
with the negative flag set, and a branch with BMI could bend to your own error
handler. Remember to restore the old value into $ba before returning control to
WS DOS, to insure that the "logged" device will remain unchanged. If the test was
a failure, one option would be to pop the stack twice, restore $ba and jump to
the NODEV routine at $24a3, which will output the message "Device not present".
Then you are at the prompt, where the user will have a chance to correct the
problem (on/off switch) and try again.
$2ffd jmp ERROR
This routine is the one which outputs the error channel of the currently logged
disk drive. Be aware that there is no return from this routine, so your code
should pull the 2 RTS bytes from the stack before calling it. Other useful
locations aside from these and the NODEV routine are;
HEXOUT ($2aa0) Output a number in HEX format to the screen.
Store a number from 0 to 255 in the A register, and call this routine.
PEEP ($215d) Key click sound.
JSR to this routine after $FFE4 gets a key, for example. Remember to perform a
"pha" before calling it, otherwise the key value returned from $FFE4 will be lost.
ESCAPE ($2b5a) Exits WS DOS
If you want the program to end, this routine is the proper one to call. No
"are you sure" message. Sets top of memory in the bank 1 to $e800. Turns on
Jiffydos, outputs C128 startup screen, restores function key values, and all that
other cool programmer stuff.
------------------------------------------------------------------------------
OLD AND NEW WARMED OVER
You may still use all of the older commands from previous versions. Here is a list
of all of the commands, and how to use them.
1) The dollar sign "$". -Displays the Directory
This command will display the directory of the logged disk drive. Pattern
matching is fully supported.
Example;
A>$0:ws*
This would display a directory listing of all files on drive A: which begin with
"ws".
2) The slash "/". -Loads/Lists a Program
Enter this command before the filename of the 64 mode file you wish to load.
This load will not terminate by RUNning the file, but it will check to see if you
are pressing the CONTROL key. If you are, you will be shown a LISTing of the
file's contents upon completion of the load. Otherwise all you'll see is the C64
startup screen and a blinking cursor.
3) The arrow up "^". -Boots a Program
This command will load a file in 128-mode, and RUN it in 64 mode. Enter the
command, followed by the filename of the program you wish to boot. You'll note
that the startup screen in 64 mode will reflect the remaining number of bytes
free. This becomes inaccurate depending on the size of the file due to a bug
in the basic ROM overseen when the vic-20 operating system was adapted for use
with the C64.
4) The question mark "?". -Finds the Address Mark of a File
Many times one cannot be sure if that old file really will start with RUN, or in
which mode it was meant to be used. Luckily, the first 2 bytes of a file contain
the information we need. This is the "address mark" referred to in earlier
portions of this doc. If you have doubts about a program, type in a question mark
and follow it (no spaces between any WS DOS commands and the filenames)
immediately with the filename. After pressing return, you will see the decimal
and hexidecimal start address of that file.
Most 64 programs which start with RUN begin at 2049, or $0801. If this is the
case, then you'll see "Ok" appear directly to the right of the HEX number $0801
and more likely than not, that file is executable with RUN. Older PET and CBM
programs usually have 1024 ($0400) as an address mark. WS DOS can handle these
types of files now as well, that bug has been permanently squashed. My apologies
for telling you all in the 4.1 docfile that it would "probably" work. It didn't.
Hmmm (blush) but I meant well and... (mumbling)
5) The AT sign "@". -Reads Error Channel/Sends Disk Command
This command performs a dual function. When entered alone, it will read the error
channel of the logged drive. It is also used to send disk commands. If you wanted
to initialise the disk, enter:
B>@i
This would initialize the disk in drive 9.
6) The numbers sign "#". -Selects Target Drive
This command now selects the drive to be used as the recipient of a file when
using the COPY command. Enter "#B:" (or press F8) to set up the target drive as 9.
The drive must be turned on in order to successfully designate it as the target
device.
7) The percent sign "%". -Edits/Displays Autoboot Data
This command, like the error command, also performs a dual function. When entered
alone, it will display any current autoboot data to the screen. It also allows you
to edit this information. First of all, let me explain what I mean when I say
"autoboot data" for those of you have never used WS DOS before.
WS DOS has the ability to boot one of a possible ten files every time you press
the reset button. All you must do to boot a file automatically is be pressing one
of the number keys after you press the reset button. If you have edited and saved
an autoboot file to disk, then WS DOS will boot a file into 64-mode, saving you
the trouble of typing in the filename entirely.
Here's how to edit your own "autoboot" data file.
At the prompt, follow the percent sign "%" with a number ranging from 0 to 9, a
colon ":", and finish by entering the filename in question. This could look like
this:
A>%0:filename
I did'nt include a way to delete an entry. But you can get around this by having
an empty "%" file on hand somewhere. After loading an empty file, any autoboot
data is deleted. Take that, you typo.
8) The arrow left "<". -Saves Autoboot Data to Disk
This command is always entered alone. After using the "%" command to edit all of
your data, enter this command to save the autoboot file to disk.
In the directory, the file takes on a filename of "%". When you press the reset
key, WS DOS will look for this file. If it's there, it will be loaded into memory
and then the keyboard is checked. If you are pressing a number key at this time,
the filename which appears next to that number in your data file will be booted
into 64 mode automatically.
9) The exclamation mark "!". -Loads/Displays Autoboot Data
This command is always entered alone as well. If the disk you just inserted in
the logged drive contains an autoboot file, enter this command to load it into
memory and WS DOS will output its data to the screen.
10) The asterix "*". -Copys a File to the Target Device
This is the file copier. Before you can copy a file, you must first select a
drive to copy to with the "#" command (as explained earlier). Follow the command
with the filename of the file you wish to copy.
11) The Lira symbol "". -Reads Textfiles
Use this command to read PETASCII text files of types PRG, SEQ or USR. 80 column
mode is highly recommended. Again, enter the command followed by the filename of
the textfile you wish to read. Use the NO SCROLL key to stop the screen from
scrolling up. Press it again to resume. Abort with the STOP key.
12) The letter "x". -Escape WS DOS
This was included for those of us who can't find thier way out of a wet paper bag
unless they press the "x" button (like myself). It is merely another way to exit
WS DOS. I think I spent too much time in the monitor back in those days.
13) The HELP command -Displays a Help Screen
To reach this screen, you may either press the HELP key, or enter the word HELP
at the prompt. You will be presented with a one page HELP screen, where a short
list of all WS DOS commands and key definitions can be viewed for quick reference
purposes.
---------------------------------------------------------------------------------
DOS COMMANDS SUPPLIED WITH WS DOS
As I mentioned earlier on, I have made several DOS commands already.
Here is a brief description of what they do. Although I have made more than
these, I did'nt think the others were useful enough to include in the archive.
Here are 5 of them, which mostly have something to do with the VDC chip.
1) SMALL
This command will shrink the VDC display to half it's size, yet keeping a
readable 80X25 display. When SMALL executes, it copys itself into $0c00 (block
12), and sets up the RUN/STOP-RESTORE vector at $0a00+01 to point to itself.
However, if you exit WS DOS, this pointer is overwritten. It can be
reinitialized from Basic 7.0 with SYS 3072.
2) SIZE
This will toggle between 40 and 80 character modes, turning FAST mode off or on
when it's appropriate.
3) RIGHT
Entering this command will create a windowed area on the right side of the 80
column screen which is 40 columns wide (handy when copying files).
4) LEFT
This will do the opposite of the RIGHT command.
5) BIG
This restores the windowed area of the 80-column screen to it's original (WS DOS)
proportions of 80 columns and 23 lines after having used the LEFT or RIGHT
commands.
------------------------------------------------------------------------------
FILES IN THE ARCHIVE
After you dissolved this archive, you may have wondered what the file
"ws dos 5.0.rl" was for. This is a version of WS DOS 5.0 which will not install
itself into the bank 1, but instead must be loaded each time you need it. I
included this for those RAMlink users who would rather use their RL boot feature
when they power up or hit the reset button. Some stock 128 users may have the
same preference with thier boot disks. The file "ws dos 5.0" is the (traditional)
version, which will load itself into the bank 1 and boot itself to $2000 when you
reset the computer.
The End.
Enjoy the software!
Sid (WSoft aka Gerpsnot)
What was keeping WsDos from being NTSC compatible was how it waited for a certain bit in $D011 and I actaully fixed the PAL version of the game A.C.E. using the same technique back in 1993.
There is a wealth of information for machine language programmers here.
---------------------------------
Documentation, version 5.0 of WS DOS Friday, April 16,1998
WS DOS (C)1992,93,94,95,98 WSoft FREEWARE- Copy Share Post Don't Sell
PREFACE
Well that about does it. I'm ready to release this latest version (5.0!) of
WS DOS. Not only have many new features been added, compatibility with the
RAMlink has also been greatly improved over version 4.1, which had problems
switching down to 64-mode unless the RL was swapped with another device. With
this newer version, you should be able to boot with the RAMlink in (or out of)
a swapped state. However, there are different ROM versions lurking around out
there, so I can only vouch that everything works fine with mine, and wish you
well with yours. For the benefit of those of you using this software for the
first time, WS DOS was concieved from the first moment on with the stock 128-
user in mind.
Utilizing the higher "burst-mode" speeds of the 1571 and 1581 disk drives to
boot up 64-mode software has been done many times, in many different ways. The
"64 boot disks" and other "stand alone" type programs come to mind. Yet all of
these programs shared a common disadvantage; you had to re-load the software
which performed this task each time you used it, or had to prepare a disk boot
sector, etc. WS DOS never followed that trail. Once you've booted it, it takes
residence in the bank 1, and you can put your disk away for either as long as
you have your computer on, or until it is overwritten by another 128 program
which uses high bank 1 memory itself. If you spend most of your time in 64-mode,
you'll want to try WS DOS. A bug has been fixed in regard to loading programs
from the older PET and CBM computers. If WS DOS finds a low byte of 0 in the
address mark of the file to be booted, it will assume that it is dealing with a
program from one of those older monsters and copy the file to $0800, regardless
of what is contained in the high byte (on older PETs and CBMs this is usually
4). If you've used WS DOS 4.1, you'll like 5.0 better. If you have a RAMlink,
you may already be yawning. Read on, Yawn. Sid Davis 1339 Hancock st. Modesto,
CA. 95351
------------------------------------------------------------------------------
NEW FEATURES in WS DOS
1) RAMlink Compatibility Good
To sum it up in a few words, this version of WS DOS gets along with (my)
RAMlink better than any other program I've ever seen (which does anything similar).
Booting a 64 program from 128-mode is now exactly as easy as it always was using
Jiffydos in 64-mode. I've given up trying to find any more bugs in the RAMlink fix.
The compatibility is that good. It is my hope that by using the address $e0a9 to
detect the presence of a RAMlink, that PAL RL users may also use WS DOS. At $e0a9
is a routine which switches in RL system memory, and it has been well documented
in the RAMlink operating manual.
2) Multiple Drive Support in a PC Environment
As you might have already guessed, WS DOS is no longer limited to devices 8 and 9.
Version 5.0 supports devices in the range of 8-31. The prompt is no longer numeric.
The drive designation is now handled much like CP/M or MS DOS, where "A:" is the
first floppy (device 8 on the bus) "B:" is device 9, "C:" is device 10, etc.
This would make the RAMlink device "I:", but you could always change that to a
drive "D:", and your hard drive to drive "C:", if you want the PC feel. I've set
mine up like that, and use device numbers of "A:" and "B:" for my 1571 and 81
disk drives. To log in a different drive, enter the letter designator and trail
it with a colon (":"). WS DOS will make sure that the requested device number
falls within the legal range of 8-31 (A to X), and then make sure the drive is
powered up. For example, if you entered;
A>d: (log request on device 11), or
A>D: (not case sensitive)
00, ok,00,00 (your report, provided the drive is on)
D> <--- drive D is now logged in.
3) Target Drive Selection for the Filecopy Function
If you've ever used WS DOS 4.1, you'll know that selecting the target drive was
as simple as binary 0 and 1. Since only devices 8 and 9 were supported anyway,
the only device which *could* be the target drive was always the one not logged
at the prompt (the sleeper). With the addition of multiple drive support in 5.0
however, some changes were made. First, I rid WS DOS of the #8 "toggle"
principle. Adding the multiple support rendered it pretty well obsolete. The "#"
is still used as a command, but now it's used as a "target device" selector for
the file copy command. To select a drive to copy to, check first that the drive
is on, or you'll get an error. Simply enter the command "#", followed by the
drive designator and a colon. Example; A>#e: (request on device 12 as target
drive) Target Device Set <--- your report, if everything went ok A> The source
drive remains the currently active, or "logged" disk drive. In the example above,
this would be device 8 (drive A:).
4) The Lira character: Read PETASCII text files
This one may later be improved to read ASCII files as well, but for the time
being it will do. Reads SEQ, PRG, or USR textfiles (a handy gadget). We RAMlink
users are quite spoiled by the ability to read a textfile on the fly. I've added
this new feature as one of convenience for the stock 128 users. Since WS DOS can
pop up anytime at the touch of the reset button and instantly be there, it's
handy to enter 128-mode, read the doc file of a program, and reboot your
software. No more wasting time searching for that (slow) file reader program.
More on this one later.
5) "DOS" Commands on the 128
WS DOS has been added on in such a way as to give the experienced machine
language programmers among us their own wedge into the system. If you can
program in machine code, then you may want to add some new command to the
pallette. For this reason, the "syntax" error is no more. As far as WS DOS is
concerned, anything you typed at the prompt could also be a valid command on
the disk. If the word you typed in matches a filename on disk, the file is
checked for a certian sequence of bytes. This PETASCII text -> wsdos98 <--
is used as an indentifying header. If these bytes are present, the following 2
bytes are used as an indirect pointer and WS DOS tranfers total control to your
code, which you must assemble to $3000. WS DOS will shove a return address onto
the stack before the jump occurs, so all your code must do to return to the
program is to terminate with an RTS. I have made about ten or eleven such "DOS"
commands as a result of beta-testing. Your code need not include a carriage
return after outputting to the screen, that is taken care of after you RTS back
to the program. The only thing that's important is that WS DOS can properly
identify the file, which must contain the proper header ID and the address mark
of $3000. If you've done that correctly, the jump over pointer $3007+8 will
occur. There are a few routines built in to WS DOS that you may find handy. At
$2fee there is a small jump table which provides easy access to 6 of them.
INTERFACING WITH WS DOS
$2fee jmp VALID
VALID is a routine which verifies the existance of a file, stores it's address
mark to $fb and $fc, and returns to the calling routine (provided the file
exists). Anytime WS DOS works with a file on disk, it calls this routine first to
weed out any possible "file not found" error. If the file does not exist, 2 bytes
are pulled from the stack and WS DOS resumes normal operation. Before calling
this routine, store the filename at $1602, and the file length (plus 1) at $1600.
$1601 is where the command character is stored within the input buffer, which
adds a byte to the length in $1600. So remember: The filename length (+1) in
$1600, and stash the filename at $1602. If you've set that up right, VALID will
handle the length and the location of the filename correctly. If you wish to
read the error channel after calling this routine, call the FULLERR routine at
$2c91. There is no return from FULLERR.
FULLERR will properly handle the error output after a call to VALID, without a
return to the calling routine. FULLERR is an abort routine, so that means it will
pop the stack twice and output the error. VALID will call FULLERR if it
encounters an error, and program execution will be resumed by WS DOS. Otherwise,
if everything went OK, the processor will return to your routine.
VALID filters possible disk errors by opening the file on disk, and reading the
first byte of the error channel. If this byte is anything other than $30 (first
byte of an "00, ok, 00,00" string), then FULLERR is called.
$2ff1 jmp BOOT
This routine will call VALID to confirm the existance of a file, and then
boot it into 64-mode. Set up just like you would for the VALID routine. In the
event of an error, control is again taken by WS DOS.
$2ff4 jmp LOAD
This will do the same as the BOOT routine, with one exception and one extra- It
will not start the program; it bails to direct mode after it has finished setting
up the 64. If you have the CONTRL key down during the load, the program will be
LISTed as well. Setting up is done the same way as with the VALID and BOOT
routines.
$2ff7 jmp CHKDSK
This powerful routine is the one which makes using "DOS" commands possible, and
could be used to chain DOS commands together. This could be done in this way:
DOS command "X" is called, copies itelf elsewhere in memory and resumes control
at the new memory location, leaving memory at $3000 free for more DOS commands.
DOS command "X" then sets the filename up with the ACTUAL number of characters
in DOS command "Y"s filename, and storing the filename text to $1601 (not $1602).
DOS command "X" then modifies the existing return address within the CHKDSK
routine to similate an RTS to itself, then the CHKDSK routine is called. DOS
command "Y" executes itself and ends with an RTS, which returns control to DOS
command "X" once again (which calls DOS command "Z", etc). Care should be taken
to restore the original return values into CHKDSK to insure the routine will work
correctly (if you still intend to use the DOS). This could be done on the fly by
pulling the first byte from the stack, stashing it into another register, pulling
the second one, restoring the CHKDSK routine with these values, and ending your
code with a direct JMP to $202b, where WS DOS outputs a new instance of the
prompt and waits. In fact, if you intend to do such things as chaining DOS
commands together, it might be best to pull the return address from the stack
right off the bat, before anything else is done. In this way, you need not concern
yourself with the stack requirement as much, and you can end your code with a jump
to $202b.
The locations where the low and high bytes exist within CHKDSK are $2e3e (low)
and $2e38 (high), respectively. These locations usually contain the values $2a
and $20, setting up an eventual (RTS) return to address $202b. When pushing a
return address onto the stack, insure that you first push the high, then the low
byte (-1) of the point in memory you wish the next RTS to return to. The
possibilities of this routine are enormous. I may attempt to program a multiple
file-copier using this technique (just an idea).
$2ffa jmp CHKPRS
The CHKPRS routine will tell you whether a drive is powered up. Set up by saving
the actual number stored in $ba, load the device number that you wish to test into
register A, and call this routine. If the drive is not on, the routine will return
with the negative flag set, and a branch with BMI could bend to your own error
handler. Remember to restore the old value into $ba before returning control to
WS DOS, to insure that the "logged" device will remain unchanged. If the test was
a failure, one option would be to pop the stack twice, restore $ba and jump to
the NODEV routine at $24a3, which will output the message "Device not present".
Then you are at the prompt, where the user will have a chance to correct the
problem (on/off switch) and try again.
$2ffd jmp ERROR
This routine is the one which outputs the error channel of the currently logged
disk drive. Be aware that there is no return from this routine, so your code
should pull the 2 RTS bytes from the stack before calling it. Other useful
locations aside from these and the NODEV routine are;
HEXOUT ($2aa0) Output a number in HEX format to the screen.
Store a number from 0 to 255 in the A register, and call this routine.
PEEP ($215d) Key click sound.
JSR to this routine after $FFE4 gets a key, for example. Remember to perform a
"pha" before calling it, otherwise the key value returned from $FFE4 will be lost.
ESCAPE ($2b5a) Exits WS DOS
If you want the program to end, this routine is the proper one to call. No
"are you sure" message. Sets top of memory in the bank 1 to $e800. Turns on
Jiffydos, outputs C128 startup screen, restores function key values, and all that
other cool programmer stuff.
------------------------------------------------------------------------------
OLD AND NEW WARMED OVER
You may still use all of the older commands from previous versions. Here is a list
of all of the commands, and how to use them.
1) The dollar sign "$". -Displays the Directory
This command will display the directory of the logged disk drive. Pattern
matching is fully supported.
Example;
A>$0:ws*
This would display a directory listing of all files on drive A: which begin with
"ws".
2) The slash "/". -Loads/Lists a Program
Enter this command before the filename of the 64 mode file you wish to load.
This load will not terminate by RUNning the file, but it will check to see if you
are pressing the CONTROL key. If you are, you will be shown a LISTing of the
file's contents upon completion of the load. Otherwise all you'll see is the C64
startup screen and a blinking cursor.
3) The arrow up "^". -Boots a Program
This command will load a file in 128-mode, and RUN it in 64 mode. Enter the
command, followed by the filename of the program you wish to boot. You'll note
that the startup screen in 64 mode will reflect the remaining number of bytes
free. This becomes inaccurate depending on the size of the file due to a bug
in the basic ROM overseen when the vic-20 operating system was adapted for use
with the C64.
4) The question mark "?". -Finds the Address Mark of a File
Many times one cannot be sure if that old file really will start with RUN, or in
which mode it was meant to be used. Luckily, the first 2 bytes of a file contain
the information we need. This is the "address mark" referred to in earlier
portions of this doc. If you have doubts about a program, type in a question mark
and follow it (no spaces between any WS DOS commands and the filenames)
immediately with the filename. After pressing return, you will see the decimal
and hexidecimal start address of that file.
Most 64 programs which start with RUN begin at 2049, or $0801. If this is the
case, then you'll see "Ok" appear directly to the right of the HEX number $0801
and more likely than not, that file is executable with RUN. Older PET and CBM
programs usually have 1024 ($0400) as an address mark. WS DOS can handle these
types of files now as well, that bug has been permanently squashed. My apologies
for telling you all in the 4.1 docfile that it would "probably" work. It didn't.
Hmmm (blush) but I meant well and... (mumbling)
5) The AT sign "@". -Reads Error Channel/Sends Disk Command
This command performs a dual function. When entered alone, it will read the error
channel of the logged drive. It is also used to send disk commands. If you wanted
to initialise the disk, enter:
B>@i
This would initialize the disk in drive 9.
6) The numbers sign "#". -Selects Target Drive
This command now selects the drive to be used as the recipient of a file when
using the COPY command. Enter "#B:" (or press F8) to set up the target drive as 9.
The drive must be turned on in order to successfully designate it as the target
device.
7) The percent sign "%". -Edits/Displays Autoboot Data
This command, like the error command, also performs a dual function. When entered
alone, it will display any current autoboot data to the screen. It also allows you
to edit this information. First of all, let me explain what I mean when I say
"autoboot data" for those of you have never used WS DOS before.
WS DOS has the ability to boot one of a possible ten files every time you press
the reset button. All you must do to boot a file automatically is be pressing one
of the number keys after you press the reset button. If you have edited and saved
an autoboot file to disk, then WS DOS will boot a file into 64-mode, saving you
the trouble of typing in the filename entirely.
Here's how to edit your own "autoboot" data file.
At the prompt, follow the percent sign "%" with a number ranging from 0 to 9, a
colon ":", and finish by entering the filename in question. This could look like
this:
A>%0:filename
I did'nt include a way to delete an entry. But you can get around this by having
an empty "%" file on hand somewhere. After loading an empty file, any autoboot
data is deleted. Take that, you typo.
8) The arrow left "<". -Saves Autoboot Data to Disk
This command is always entered alone. After using the "%" command to edit all of
your data, enter this command to save the autoboot file to disk.
In the directory, the file takes on a filename of "%". When you press the reset
key, WS DOS will look for this file. If it's there, it will be loaded into memory
and then the keyboard is checked. If you are pressing a number key at this time,
the filename which appears next to that number in your data file will be booted
into 64 mode automatically.
9) The exclamation mark "!". -Loads/Displays Autoboot Data
This command is always entered alone as well. If the disk you just inserted in
the logged drive contains an autoboot file, enter this command to load it into
memory and WS DOS will output its data to the screen.
10) The asterix "*". -Copys a File to the Target Device
This is the file copier. Before you can copy a file, you must first select a
drive to copy to with the "#" command (as explained earlier). Follow the command
with the filename of the file you wish to copy.
11) The Lira symbol "". -Reads Textfiles
Use this command to read PETASCII text files of types PRG, SEQ or USR. 80 column
mode is highly recommended. Again, enter the command followed by the filename of
the textfile you wish to read. Use the NO SCROLL key to stop the screen from
scrolling up. Press it again to resume. Abort with the STOP key.
12) The letter "x". -Escape WS DOS
This was included for those of us who can't find thier way out of a wet paper bag
unless they press the "x" button (like myself). It is merely another way to exit
WS DOS. I think I spent too much time in the monitor back in those days.
13) The HELP command -Displays a Help Screen
To reach this screen, you may either press the HELP key, or enter the word HELP
at the prompt. You will be presented with a one page HELP screen, where a short
list of all WS DOS commands and key definitions can be viewed for quick reference
purposes.
---------------------------------------------------------------------------------
DOS COMMANDS SUPPLIED WITH WS DOS
As I mentioned earlier on, I have made several DOS commands already.
Here is a brief description of what they do. Although I have made more than
these, I did'nt think the others were useful enough to include in the archive.
Here are 5 of them, which mostly have something to do with the VDC chip.
1) SMALL
This command will shrink the VDC display to half it's size, yet keeping a
readable 80X25 display. When SMALL executes, it copys itself into $0c00 (block
12), and sets up the RUN/STOP-RESTORE vector at $0a00+01 to point to itself.
However, if you exit WS DOS, this pointer is overwritten. It can be
reinitialized from Basic 7.0 with SYS 3072.
2) SIZE
This will toggle between 40 and 80 character modes, turning FAST mode off or on
when it's appropriate.
3) RIGHT
Entering this command will create a windowed area on the right side of the 80
column screen which is 40 columns wide (handy when copying files).
4) LEFT
This will do the opposite of the RIGHT command.
5) BIG
This restores the windowed area of the 80-column screen to it's original (WS DOS)
proportions of 80 columns and 23 lines after having used the LEFT or RIGHT
commands.
------------------------------------------------------------------------------
FILES IN THE ARCHIVE
After you dissolved this archive, you may have wondered what the file
"ws dos 5.0.rl" was for. This is a version of WS DOS 5.0 which will not install
itself into the bank 1, but instead must be loaded each time you need it. I
included this for those RAMlink users who would rather use their RL boot feature
when they power up or hit the reset button. Some stock 128 users may have the
same preference with thier boot disks. The file "ws dos 5.0" is the (traditional)
version, which will load itself into the bank 1 and boot itself to $2000 when you
reset the computer.
The End.
Enjoy the software!
Sid (WSoft aka Gerpsnot)