@database "FloppyHalt"
@wordwrap
@node main
@title "Contents of FloppyHalt"
@{b}The Contents Page@{ub}

@{"Introduction     " link Intro}
@{"Quick overview   " link Over}
@{"Quickstart       " link Quick}
@{"Installing       " link Install}
@{"Instructions     " link Instruct}
@{"Troubleshooting  " link Troubles}
@{"About the program" link ProgInfo}
@{"Distribution     " link Distribute}
@{"About the author " link AuthorInfo}
@endnode

@node Intro
@title "Introduction to FloppyHalt"
@{b}Introduction@{ub}

You are using a program which is about to write a file to a floppy disk. It opens the file and begins writing. However, after doing this for a short while you realize you have made a horrendous mistake. The file it has begun writing will be completely useless. And there is no stopping it! Plus it will take ages until it closes the file. And even longer when it comes to deleting it and starting all over again.

Your life would have been made easier if you had FloppyHalt. Well, now you do, as soon as you install it in your system. Why? What will it do? FloppyHalt would have let you stop writing to the file almost immediately and safely close it for you, all without any tedious waiting or disk corruption. FloppyHalt acts as a normal commodity waiting for it's hotkeys to be pressed. When they are it will patch into the operating system and attempt to track down what drive is being written to. If it finds a drive writing it will give you the option of ignoring any further writes to the disk, or cancelling the operation.

As you can see, this program might become quite useful, and you might need it some time or another.
@endnode

@node Over
@title "Quick overview on FloppyHalt"
@{b}Quick overview@{ub}

FloppyHalt is a commodity that will halt a file being written to floppy disk at the touch of a hotkey and let you have the option of stopping it being written further and close the file without any disk corruption.
@endnode

@node Quick
@title "Quickstart to FloppyHalt"
@{b}Quickstart@{ub}

The program runs as a normal commodity so just run it once and if no @{"errors" link Troubles} occur then its ready to use. It be will asleep in the background waiting to be activated. Now press the hotkeys. By default the hotkeys are set to @{i}Ctrl-LAmiga-H.@{ui} A requester should pop up stating that FloppyHalt is tracking down a drive being written to. You can abort this operation also if you wish. If it tracks down a drive it will give you further options of ignoring writes to the file or cancelling altogether. If no floppy drives are being written to then it will wait endlessly. You can also do this before you start writing as an experiment, such as checking the response time or to see how long it takes to open a file. For further information for which you will no doubt require please refer to the @{"instructions" link Instruct} for a full explanation.
@endnode

@node Install
@title "How to install FloppyHalt"
@{b}Installation@{ub}

By double-clicking on the Install icon will start up a script that will install it for you. Don't worry, it's not too stupid or arrogant. It won't simply copy files without asking. There are two main files to install, the program file, the guide file and their assorted icons. The installer will by default select your WBStartup directory for the program file and the logical assign HELP: for the guide file. Before it copies any files it will bring up a file requester where you can select an alternate drawer if you wish or select "Cancel" to avoid copying particular files. By selecting "Okay" you will give it the go ahead and it will start copying files across. To function the script requires the command RequestFile to be in your path.
@endnode

@node Instruct
@title "Instructions on using FloppyHalt"
@{b}Instructions@{ub}

FloppyHalt can be run from either the Workbench or a CLI window. Workbench Tool Types and CLI Arguments are explained below. If any @{"errors" link Troubles} are encountered they will be reported in a nice system requester which will also try to explain what went wrong.

FloppyHalt acts as a normal commodity so when it is running on your system it will be waiting for the hotkey combination. By default this is set to @{i}Ctrl-LAmiga-H.@{ui} It can also be activated or made inactive with the Exchange program. When woken up by the hotkey combination it will come to life and try to find a floppy drive being written to, and what to do to stop it. FloppyHalt has two stages it goes through in order to stop a file being written. The first is the tracking down stage where it attempts to find a drive where a file is being written to and the second is the intervention stage where you decide what to do with a file if it finds one being written. These two stages are split into separate windows each with a different task to perform and are explained below in the order in which you will encounter them.

@{fg highlight}Overview of the FloppyHalt windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~@{fg text}
FloppyHalt has two windows as mentioned above which form it's GUI. These are standard system requesters and are all that is needed in order to use it. The first is the Tracking window and the second is the Ignoring window.

@{b}The Tracking window@{ub}
This is opened by pressing the hotkeys. In this window you will see the message "Tracking..." and an "Abort" gadget. Once this window is open FloppyHalt is attempting to track down what floppy drive is being written to. It will wait until it finds one unless you click the "Abort" gadget in which case it will close the window, abort the whole process and stop tracking. If, however, you do not click the "Abort" gadget and FloppyHalt tracks down a drive, it will close this window and open up another window; the Ignoring window.

@{b}The Ignoring window@{ub}
This will be opened if FloppyHalt tracks down a drive being written to. It will then freeze the task (which could be a drive task such as DF0) that sends the actual write commands to the disk, thus freezing the disk drive and leaving it in a kind of pause mode. The drive light should remain on, reminding you that it is still in the middle of an operation. In this window will be some text explaining what your options are, and some gadgets. The text is as follows:

Write access tracked to drive DF?.
Drive is now frozen.

Do you want to:
- Ignore all further writes to file?
- Ignore all further writes to device?
- Cancel?'


The first part will tell you what drive is being written too. In place of the question mark should be the unit number of the actual drive.

In the second part you are told what your options are in regards to what you can do with an unwanted file. Please note that this section is a little technical due to the fact that is has to be because of what you are doing to the file and disk and how it stops the file being written any further. You select what to do by clicking on one of three gadgets, labelled "Ignore file," "Ignore device" and "Cancel." The "Ignore" gadgets are the ones you will most need, and are explained in more detail below.

@{b}Ignore file@{ub}
This is by far the safest option but has the slight disadvantage that it can be unreliable in stopping a file being written in certain situations. This option will tell FloppyHalt to ignore any more writing into the @{i}file.@{ui} The program that is writing to the file can continue what it is doing, but no more data will actually be written to the disk by the filesystem because FloppyHalt will intercept the write command itself. The program may complain though, it may think there is not enough space on the disk for the file! This is a good option if the program you are using writes separate "chunks" of data to the file. It can be unreliable because FloppyHalt will only intercept further writes to the file. If your program writes everything in one chunk or write operation such as Workbench copying a file then it is most likely that the write command is already sent and being processed. FloppyHalt will be unable to stop it because only that write command is sent and no others. Thus, although FloppyHalt is programmed to ignore any further writes to the file, the file will continue to be written to disk. Please note that this situation will not occur all the time and is the best to use if you know the file can definitely be stopped. This option will stop your file on a high level.

@{b}Ignore device@{ub}
This could be regarded as the least safe option but has the advantage that you can rely totally on it in all situations to stop the file at hand. This option will tell FloppyHalt to ignore any more writing to @{i}disk.@{ui} The program that is writing to the file can continue what it is doing, as can the filesystem, but no more will actually be physically written to the disk itself, because FloppyHalt will intercept any write commands to the disk sectors. The program will think the whole file was written, and although the length will be correct when it has been closed, the file will contain something completely different! This is a good option to use if the program you are using writes just one "chunk" of data to the file. FloppyHalt will be able to prevent it being written nomatter what. The program and filesystem will continue to run normally as if nothing has happened. It is the least safe because it prevents any more sectors being written to disk, such as a data block, which could have a funny affect on the disk because all the blocks which make up the file are not stored on disk. Although the program does some basic checks on what type of block is stored, it is only reliable if the disk is using a Standard- (SFS) or Fast-File-System (FFS). If you know for sure that the program writes data in one big chunk then this is your only option once disk writing has begun to bring it to a halt. This option will stop your file on a low level.

@{b}Cancel@{ub}
This option will as suggested cancel any more operations with the disk and let the file be wrote normally without any interruptions.

These are the methods that FloppyHalt uses to stop a file being written to disk and in all testing none has lead to any disk corruption so it should be a safe and sure method of halting your floppy. FloppyHalt will allow the file to be closed properly so the disk should not become invalidated. I wouldn't recommend taking the disk out when FloppyHalt has paused the drive although it should be safe on the disk unless you want an invalidated disk and wish to reformat it but I do recommend deleting a file you have halted after it has been closed properly, especially if you used the "Ignore device" option.

@{fg highlight}Customising it to your requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~@{fg text}
FloppyHalt has a list of definable options to control the commodity. These can be set in the Tool Types of the program icon, or in the CLI which will override the Tool Types. The CLI command template is shown below, with the meaning of each argument listed after.

FloppyHalt Template:
AUTOQUIT/K,CX_PRIORITY/N/K,CX_POPKEY/K:

Argument Definitions:
@{b}AUTOQUIT@{ub}
This determines what happens when the program is run a second time. If set to YES then the program will quit and remove itself from memory. If set to NO then it will remain in memory and the only will to remove it is with the Exchange program.

@{b}CX_PRIORITY@{ub}
Sets the priority of the Commodity as described in the Workbench Manual. Usually this can be left as is but is provided if it needs to be set. By default is set to zero.

Example:
CX_PRIORITY=1

@{b}CX_POPKEY@{ub}
Sets the hot key combination that will alert FloppyHalt to begin tracking. By default this is set to Ctrl-LAmiga-H.

Example:
CX_POPKEY=Shift F6
@endnode

@node Troubles
@title "Trouble-shooting guide for FloppyHalt"
@{b}Troubleshooting@{ub}

Should you encounter any trouble or errors when using FloppyHalt this section will hopefully help you pinpoint a problem and how to resolve it.

Error: @{i}Program loads okay but does not respond to hotkeys.@{ui}
If the program has loaded okay and is on the Exchange list, yet does not respond to hotkey presses then another commodity probably has the same hotkeys as FloppyHalt. Check and see if any commodities you have running use the same hotkey as FloppyHalt. If they do you will have to change the CX_POPKEY argument in either FloppyHalt or the offending commodity. A most annoying error and hard to track down if you don't know what's going on.

Error: @{i}Program fails to load because it complained about creating a hotkey.@{ui}
This is most likely to occur on a Workbench 2.x system as it has happened before on one. I'm not completely sure why this happens, except the earlier OS has some problems with certain key combinations. Workbench 3.x as this program was written on has no problems, and that shouldn't be a problem since FloppyHalt only requires and opens OS 2.x libraries. One possible solution to this is to change the hotkey combination to something else other than what it is set at (default or other) and try again. Another annoying error especially if it seems to do it for no particular reason, as it seems to when its happened to me.

Error: @{i}Program fails to load because it complained about a ToolType.@{ui}
This would usually happen if you entered incorrect data in the icon ToolTypes or if ran from the CLI some bad arguments. FloppyHalt tries to be helpful when you have stuffed up a ToolType by telling you what you have put and what your options are. The best advice here would be to take note of what the program tells you and correct it. It should be fairly self-explanatory if you encounter such an error.       

Error: @{i}Program fails to load because it could not open required library.@{ui}
Check you have the required libraries in your LIBS: assign. These are version 37 of commodities.library, asl.library, intuition.library and the gadtools.library. And version 36 of the icon.library. FloppyHalt also opens version 37 of the dos.library and graphics.library, but that shouldn't cause a problem.

Error: @{i}Everytime the tracking window opens up my virus checker complains.@{ui}
This will happen if you have Virus Checker or something similar running in the background. To work FloppyHalt needs to temporarily patch into certain operating system vectors that are also prone to viruses. A virus checker will detect this, especially if no drive is found before it unpatches itself. It is a perfectly normal and annoying occurrence! I was going to add an option to freeze any virus checking programs FloppyHalt could find while it tracks, but this would make the program more cumbersome, slower and could give some virii the chance to invade the system. If it gets annoying you could turn off the Exec DoIO() check in your virus checker if possible, but at your risk. Unless in the future there is a way my program can tell a virus checker not to worry about this or if I find a different way of tracking a disk this is unlikely to change for a while.
@endnode

@node Distribute
@next ProgInfo
@title "Rules for distribution"
@{b}Distribution@{ub}

This program is what I consider to be @{i}EveryWare.@{ui} Since I offer it free I give you the duty of distributing it everywhere. Which you may or may not do, it's your choice. Give it to your friends. Distribute it on the net. Just make sure all the files are together and intact.
@endnode

@node ProgInfo
@last Distribute
@title "About the program"
FloppyHalt was written using Amiga E. This is the first version of the program released to the public and installed on my harddrive as well.

It was inspired by a moment at my user-group when a rather lengthy LHA file was being written accidentally to disk by DOpus. There was no way to stop it and we had only to wait for to finish before starting over again. In the time between I suggested what a good idea it would be if there was a program to stop it without corrupting the disk. And so I knew what the next program I would be writing would be. And what a pain is it when you need to do a bit of research and development...

@{b}Technical information@{ub}
FloppyHalt works by first patching into the Exec DoIO() and SendIO() vectors to find a task that is sending a device write command to the trackdisk device. If it finds one it will freeze the task, and in turn freeze any more progress on the file. Choosing "Ignore file" will patch PutMsg() to look for any DOS packets sent to the task's message port. A write message will be made nil, thus disabling it and an end message signals FloppyHalt that the file is finished and closing. Choosing "Ignore device" will patch as above and also DoIO() and SendIO() for any write commands sent from the task in which case they will flushed out. The task is then reactivated so it continues on with it's work, except no more will be written to disk. When the file is closed FloppyHalt unpatches itself from the operating system and leaves it as before, as if nothing had happened.
@endnode

@node AuthorInfo
@title "About the author"
I been programming for about five years and this program is one of my first steps into a high-level language. Future programs of mine will probably sport GUI interfaces. Something I've not gone far with by using assembler. Any way, you can contact me at this email address:

damo_rules@yahoo.com
@endnode