QLWARZ - QLWA virtual hard disk ResiZe
                    ======================================

The issue of hard disks filling up and needing to be stretched keeps
cropping up in various fora. But there is no command or utility to alter the
size of a virtual hard disk directly!

The obvious work around is to create a new virtual hard disk of the desired
size and copy the contents of the old hard disk over. However, there arent
many "QL" file managers or utilities to copy bulk data from one device to
another, while maintaining the directory structure and original file dates.

This rough hack sets out to remedy that while we wait for better things.
Sorry about the length of this readme, but YOU are the other half of this
utility, so you need to be briefed!


Limitations:
------------
This is not a "real" program! It is a hack, a script, a bunch of macros.
So you are advised to keep up-to-date backups, concentrate on the process,
and not be doing other heavy lifting while running the script!

Basic error checking is performed, but should an error occur, the program
will stop with a, hopefully, enlightening error message. You are then
expected to rectify the problem (perhaps with the aid of this readme) and
try again.

This version works on QPC2 only! If you use QPC2 V4.04+, it must run under
Windows Vista or above!

It shouldnt be too hard to convert it to other platforms that also use QLWA
virtual hard disks. Alternatively, even if you use another platform, you
could just fire up QPC2 for the purpose of running this script. Ive not
tested it on QPC2 under Wine on Linux. Please let me know how it worked if
you have!


Usage:
------

Make sure your "QL" is not busy. If you run QDT, or other programs that
keep open files on the disk, you will need to close them down. If WIN_USE
is active it will be disabled right at the start of the program and must be
restored manually (or reboot QPC2). DOS device, slot 4 is also used briefly.
This is not asked about, so must be configured in the code if inconvenient.

        130 dos% = 4: dos$ = 'dos' & dos% & '_'

LOAD and RUN the program in the main interpreter (Job #0) in the classic
3-window format. Dimensions not important. Enter:

        WMON 4

first, if in doubt.

Answer the prompts:

"Which drive to stretch? <1..8>" - This query is for the drive you wish to
   stretch/shrink (or simply refresh). Press a key from 1 to 8 for win1 to
   win8. If you press <ESC> the program aborts with an Error Incomplete.

"Enter new size in Mb <1 to 2048>" - Here you can also specify a smaller
   size tha your original, provided it is large enough to fit the data from
   the old drive. If you choose a larger size, you need to consider that
   the larger the disk, the more space each file takes! This is because the
   * Allocation Unit size needs to change to accommodate the new size. The
   amount of space required cannot be calculated accurately without scanning
   the source disk to measure and count the number of files and directories
   it contains. This is an obvious improvement that could be made to the
   script, but it adds time to the process and complexity to the program,
   so I have omitted it here: If the cloning process fails due to the disk
   becoming full, re-LOAD the program and start again, choosing a larger
   size for the new disk. (You will need to go into Windows and delete the
   spoilt disks later.)

"I need a temporary win drive slot <1..8>" - This is so the files can be
   transferred to the new disk. Dont use one of your main drive slots for
   this but choose a little used, or spare, slot. Whatever was attached to
   it will be restored on a successful completion. However, the disk
   occupying the temporary slot will become detached should the copying
   process fail! You could use QWIRC (available from Dilwyn's site) to
   re-attach it, or do so manually, if you know how (or quit and restart
   the emulator, if desperate!)

   NB: The temporary slot has to be different to the source slot, or you
   wont escape from the input except by ESCaping the program. It should
   also not have open channels on it.

Only minor changes have been made until this point. Now, however, the real
business takes place: You will be asked for a two letter code to confirm
that you wish to format the hard disk. Once youve entered the correct code,
the new hard disk is created. If you enter the wrong code, or bail out at
this point, your temporary disk slot will be rubbish (see above) but no new
file will have been created (and nothing deleted or destroyed). If you
intend to try again, no need to reset the temporary slot, as the "damage"
has already been done and cant be made worse. Just re-LOAD and try again.

Now the copying takes place. If the program ignominiously falls over with a
"Disk full" error, just try again with a larger size, as described above.
If you get the odd question whether to overwrite a file, just press Yes.
If this happens repeatedly, you could try removing the REMark in the
following program line:

        1300    REMark DELETE tdv$ & nm$: rem Un-rem if required

and start again..

If all went according to plan, your new disk should be in the same slot as
your old one, with the same name, but with a new size (or just fresh and
de-fragmented!) The whole process should complete in a matter of a minute
or so, depending on the number of files to copy.

* The Allocation Unit (au) size may be calculated thus:

        au =  (Mb x 2048 DIV 2^16 + 1) x 512 b, minimum 2048 b

Each file of length b bytes then takes up

        ((b + 64) DIV au + 1) * au

However, this is not the whole story, as each file also has a directory
entry which takes up 64 b, and this must also be factored in. Since the
size increase of the directory will depend on the directory structure and
previous contents, an accurate calculation is hard to make without an
actual scan of the source disk.

So on a 2Gb disk even a 1 b file will take up 33 k of space! The optimal
hard disk size is always 1 Mb less than the transition size, ie

        optimum Mb = ((Mb  DIV 32) + 1) * 32 - 1 | for Mb >= 127

Allocation Unit sizes (sample only):
to    127 Mb:  2,048 b (127 Mb is the optimal size for numerous small files)
from  256 Mb:  4,608 b (255 Mb is optimal for this size bracket)
from  512 Mb:  8,704 b (511 Mb is optimal for this size bracket)
from 1024 Mb: 16,896 b  etc
at   2048 Mb: 33,280 b


Tidying up:
-----------
Check the information displayed on screen, and then minimize QPC2 and go
to the location of your win drive. Delete or archive your old disk, which
will now be called something like D:\QL\WIN\69599014599D.win (Hopefully
this is not something youd normally call your disks!) Your new disk will be
called whatever your old disk was called before the stretch. Rename the
funny file to something sensible if you intend to keep it, to avoid
confusion.

If you had errors and needed to run the utility more than once:
Look out for residual files of a similar name in any other win folder
that might be affected.

Re-boot (shut down and restart) QPC2 at the end of the process to put your
world to rights again.


Medium Name:
------------
If you wanted to give your hard disk another medium name than the old one,
use the utility's SetName procedure:

With QLWARZ LOADed, type (assuming you wish to name win8_ to My Disk):

        ERT SetName("win8_", "My Disk")


Troubleshooting:
----------------
Most of the problems anticipated have been covered above. But what if the
copying program fails at some point during copying, yet not because the
target disk is full? This is probably due to some corruption of your disk
or filing system. There is no simple answer to this, as there could be so
many reasons.

The first step could be to try Tony Tebby's DRVCHK and DRVLINK on the
source drive.

If this doesnt work, you could try to find where the problem occurs. The
program output should give a clue as to that. See if the cause may be
removed by deleting the offending file(s) or directory on the source disk.
You may loose some data but save most of the rest.

Re-RUN QLWARZ again and when it stops try entering CONTINUE repeatedly
until the awkwardness has been passed.

If youve had to fix your disk by one of the methods above, it may be a
good idea to use the utility to make a further copy of the copy to a fresh
disk, as the copying routine (QLone) is a good test of the filing system's
integrity.

Make sure you tidy up (see above) if this utility has failed at some point
after a successful format.


Program Status:
---------------
This is a QL Public Utility Program. A condition of its use is that you
report any problems you encounter, or errors in the program or manual, so
they may be fixed! This to avoid annoyance or misery to other users. Apart
from that, it is free to use and spread around.

Feel free to make or suggest improvements! This is optional (as is my
response to any such suggestions ;o)

pjwitte at googlemail dot c0m, January 7th 2017