VDISK.DOCVersion 1.0September 1, 1988

Copyright (c) 1988 Vladimir Lanin. All rights reserved.
For conditions, see license below.



OVERVIEW

VDISK is a collection of programs that emulate a fast disk drive in
memory. The drive's size, however, is specified at run time, not boot
time. As a result, unlike most RAMdisk programs, VDISK takes up only a
token amount of memory until you wish to use it. To begin using a new
VDISK, or to remove one currently in use, you need only run the VDISK
program, not re-boot the system. As with all RAMdisks, any data on the
VDISK drive disappears at power-down.



REQUIREMENTS

VDISK will run on any MS-DOS compatible computer running PC/MS-DOS 2.0
or higher.



INSTALLATION

To install VDISK, add a line of the form

DEVICE=VDISKDD.SYS

to the file CONFIG.SYS in the root directory of your boot disk. Then
copy the distributed file VDISKDD.SYS to the same directory. The next
time you boot up your system, the next available drive letter in your
system will be a VDISK drive, initially empty. For example, if you
have diskette drives A and B, and a hard disk on C, the VDISK will
be on D. Putting in more than one DEVICE=VDISKDD.SYS line into
CONFIG.SYS will install more than one VDISK device, using successive
drive letters. Each VDISK drive takes up only 416 bytes of memory.



OPERATION

1. The empty VDISK drive

When a VDISK device is empty, accessing it will produce a DOS error
message, something like:

Not ready error reading drive D
Abort, Retry, Ignore?

This is the same kind of message you get when trying to read a floppy
drive with no disk inside.


2. Setting up a new VDISK

To set up a new VDISK, you must run VDISK.EXE, specifying the size
and/or other parameters of the new VDISK. The format of this request
is as follows:

vdisk [] [v] [] [s] [n] [d] [z[-]] [!]

If there is insufficient memory to set up the requested VDISK, a
message to that effect will be displayed, along with the
parameter of the largest VDISK currently possible (with the other
parameters unchanged). Otherwise, if there is already a VDISK in
, any files on it will be lost.

The parameters' meaning is as follows:

The drive letter of the VDISK device. By default, VDISK
assumes the last drive in your system.

vSwitches on verbose output, which gives specifics of memory
allocation process.

The size in K of the data area of the new VDISK. In addition
to the data area, the VDISK needs another 96 bytes, plus space
for the disk header: boot sector, File Allocation Table (FAT),
and root directory. These, however, are not included in the
parameter: you just specify exactly how much space you
need for your files. To match the the data area of a 360K
floppy, specify a size of 354K.

The default VDISK size is 160K.

sThe new VDISK's sector size in bytes. Must be a power of 2,
and no less than 32. VDISK always uses 1 sector per cluster.
The default sector size is 512 bytes.

nThe number of sectors in the data area of the new VDISK. This
parameter can only be specified if isn't. For sector
sizes less than 1K, it serves to specify the size of the data
area more precisely.

dThe maximum number of entries in the root directory of the new
VDISK. Subdirectories can still be of arbitrary size. By
default, N is the number of entries that fit in two sectors.
Each entry takes up 32 bytes, so at the default sector size of
512, the default root directory takes a maximum of 32 files.

z[-]Specifies the highest address in RAM (in K) beyond which the
new VDISK will not be allocated. MS-DOS uses the area at the
very top end of the user RAM for a program loader and the
transient part of COMMAND.COM. MS-DOS allows a program (such
as VDISK.EXE) to temporarily allocate any part of this area
without error or warning. However, if the program keeps the
area beyond its termination with a Terminate and Stay Resident
call (such as done by VDISK), DOS gives a message like

Memory allocation error
Cannot load COMMAND, system halted

and then hangs, necessitating a re-boot. The z option makes
sure that this does not happen by not allowing VDISK to use
memory beyond the limit specified. If a '-' precedes , the
limit is - . Thus, in a system with 640K
RAM, z-15 specifies a limit of 625K.

The default is z-15. I do not know how much the various
versions of PC/MS-DOS use (besides PC-DOS 2.0, which uses
14K), and would appreciate hearing from someone who can
experiment and find out. If for some strange reason your
non-IBM system does not support BIOS call 12H (which returns
the memory size), you should not trust the default and specify
the z value (without the -) yourself.

!Suppresses warnings. Normally, when you try to set up a VDISK
while there is already one set up on that drive, VDISK gives
you a warning about memory fragmentation and asks you if you
want to procede. Also, if there are still files on the drive,
VDISK asks you if you really don't need them. Not responding
with 'y' to either of the two queries will abort the VDISK
program. Specifying ! on the command line suppresses both
warnings.


3. Removing a VDISK

To release the memory allocated to an unneeded VDISK, run VDISK.EXE
with the following command format:

vdisk [] [v] out [!]

Only the current VDISK is removed. The VDISK drive remains in place,
empty. You are free to set up a new VDISK on the drive. Any files that
may have been on the old VDISK are irretrievably lost.

The and v options were described in the previous section. The
! option suppresses the warning that is normally issued when there are
still files on the old VDISK.

Alternatively, you can run VDISKOUT.EXE, as in:

vdiskout [] [!]

This becomes useful when there is not enough free memory left to
load the regular VDISK program.


4. Checking a VDISK drive's status

Running VDISK.EXE without specifying either 'out' or a new VDISK
parameter will report the drive's status. Thus, the status command
format is:

vdisk [] [v]

For a description of the parameter, see the section on setting
up a new vdisk. The v parameter will turn on verbose output, reporting
on the VDISK's sector size, root directory length, position in memory,
etc.


5. Parameter format

Parameters to VDISK.EXE and VDISKOUT.EXE may be given in any order.

Case is insignificant.

A '-' or a '/' may precede most parameters, but need not do so.

The parameter may include the ':', but need not do so.

Those parameters that are given in K may end in a 'k', but need not
do so.

The ! parameter may be given separately, or appended to any other
parameter.


6. ERRORLEVEL settings

On termination, the VDISK program sets ERRORLEVEL to one of the
following values, which may be tested for by DOS's IF command:

0: Operation successful, specified drive was initially empty.
1: Operation successful, specified drive initially contained a VDISK.
2: Operation unsuccessful or negative response to an 'Are you sure?' prompt.
3: Error in program parameters.
4: Internal error, should never happen.


7. Memory allocation

Setting up a new VDISK requires:
a) a chunk of memory large enough for both the VDISK program (roughly
18K) and the disk header, and
b) possibly different chunk of memory large enough for the total
specified VDISK.

The new VDISK is usually put into the program block. If this is
impossible, an attempt is made to allocate a large-enough separate
block. Even in this case, however, MS-DOS keeps a small area at the
beginning of the program block for the lifetime of the VDISK.

Setting up a new VDISK without first explicitly removing the current
VDISK by a 'vdisk out' command will usually cause memory
fragmentation. This is the condition when free memory is scattered
over the address space in several chunks separated from each other by
allocated areas. As a result, a program that requires less than the
total available memory, but all in one chunk, may not be able to run.
Thus, although the condition is safe, some of your memory may in
effect becomes unusable. For this reason, it is always a good practice
to remove an old VDISK explicitly. In any case, the original
non-fragmented state may be restored simply by removing the new VDISK.



BUGS

VDISK has been extensively tested under PC-DOS 2.0. It has not been
tried under any other version of MS-DOS. Since the only non-documented
feature it uses is freeing old TSR blocks, it should run under higher
versions. In either case, I would appreciate any feedback.

VDISK currently can not use memory beyond the MS-DOS limit of 640K. If
there is sufficient interest in removing this limitation, I will
attempt to do so.


GENERAL INFORMATION

IBM is a registered trademark of the International Business Machine
Corporation.
MS-DOS is a registered trademark of Microsoft Inc.

If you have any questions or comments about VDISK send them to me at:

USENET:
!cmcl2!csd2!lanin

INTERNET:
[email protected]

U.S. Mail:
Vladimir Lanin
330 Wadsworth Ave, Apt 6F
New York N.Y. 10040



LICENSE

Copyright (c) 1988 Vladimir Lanin. All Rights Reserved.

You are free to copy and distribute VDISK for NON-COMMERCIAL use IF:

NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION,

NEITHER PROGRAM NOR DOCUMENTATION ARE MODIFIED IN ANY WAY,

THIS LICENSE AGREEMENT IS INCLUDED.

This program is provided AS IS without any warranty, expressed or
implied.

If you find VDISK useful and convenient, a contribution of $10 would
be appreciated. Send contributions to:

Vladimir Lanin
330 Wadsworth Ave, Apt 6F
New York N.Y. 10040

Commercial sponsorship would be welcome.