.ap
.hy
.title ########Virtual Disk Users' Guide
.subtitle ########[313,45]GUIDE.DOC   JMB  2-OCT-1986 
#
.c; Virtual Disk User's Guide
.skip 1
.c; Jim Bostwick
.c;  2-OCT-1986 
.page
.hl 1 Introduction
 This document is intended to provide both a brief introduction to 
the virtual disk package, and a guide to its use.
The internal details of the package have been avoided. 
For a technical details, see Ralph Stamerjohn's
excellent article in the Fall 1981 DECUS Proceedings. 

 A virtual disk is a file which the system (RSX-11M or M+) thinks is an
actual disk. A special device driver (VDDRV) is at the heart of this deception.
Two programs (AVD and DVD) allow you to 
make and break the connection between files and virtual disk units.
Once a virtual disk has been set up, the system cannot tell it from a real
disk. With two exceptions, you can do anything with a virtual disk
that you can with a real one. 
.hl 2 Why?
So why use virtual disks? The primary reason for virtual disks'
existence is to partition a large disk into a number of smaller ones.
This allows each programmer or project to have their 'own' disk,
to assign UICs as they wish, and (not incidentally) to manage
their share of the real disk space as they see fit. 
It is also much easier to back up virtual disks (of RL0x or RK0x size)
than it is to back up a single large disk. You can also backup and 
restore a virtual disk (to gain contiguous space), without disturbing
the operating system which lives on the real disk. 

 There are numerous other uses for virtual disks, but all depend upon
the ability to give various users of a single large disk their 'own'
small disk.

.hl 2 A Quick Look

 In order to use a real disk, say an RL01, you go through several setps.
First, you obtain a pack. Next, you must gain access to the RL01 drive,
and spin up your pack on it. You then tell RSX about the 
disk by using the mount command. Usually, you
assign some pseudodevice - often SY: - to the disk. Finally, you go 
to work. When finished, you dismount the disk, and remove the pack,
freeing the drive for other uses.
 With virtual disks, you must go through a similar process. Your
'pack' is a file, which will exist on a real disk which is already
mounted. 
You 'spin up' this 'pack' by assigning it to a virtual disk unit
using AVD. Then, you can mount the disk, and go to work. When you
are finished, you deassign the disk ('remove the pack') using DVD.

.hl 1 Virtual Disk Container Files
Virtual disk files, called container files, 
are created by the system manager. You will be given the filespec
for the container file of each virtual disk to which you have access.
Once created,  the owner of the disk
is completely responsible for its contents, backup, and use. 
The container file will be created with the extension ".DSK",
for example "DR:[1,5]JIM.DSK". The file must be contiguous, and will
be given read and write access priveleges only for the system and owner.
No extend or delete priveleges will be given to anyone.
Some virtual disks will have group or world read and/or write access,
if appropriate. 
 You must never attempt to directly manipulate the container file, 
even though
it is an ordinary Files-11 file. To do so will certainly corrupt the
virtual disk, and could lead to bizarre system behavior. Virtual disks
are always manipulated by mounting the virtual disk, and using normal
DISK utilities. 
 Container files may be RENAMED, although this will not usually be done.
 Container files are excluded from the normal system backup procedures,
for a number of reasons. It is up to the owner of the virtual disk to 
decide when it should be backed up, and to do so. Backup is as simple
as assigning the virtual disk, and using BRU (or whatever) as if it
were a real disk. 
.hl 1 VD, VS, AND VM Devices
 The virtual disk package uses three types of device and pseudodevice.
Virtual disk 'drives' are named VD0: thru VDn: (n depends upon how
many 'drives' were genned into the driver), and correspond to the 
physical disk drives. Each virtual disk which you allocate is 
given a VS assignment (VS0:, VS1:, etc.), which only applies to 
your terminal. Finally, the last virtual disk you allocate is 
assigned to pseudodevice VM0: (as well as to a VS: pseudodevice). 
.hl 2 VD "DRIVES"
The driver is built with a number of units, VD0: through VDn:. 
Each unit can be associated with a single file ('pack') at a time. 
So, before you can access your virtual disk, there must be a 
unit ('drive') available. 
 The actual VDn: devices are of little interest or use to you, as
the virtual disk package picks the VD unit to be used.
A container file may be assigned to any VD unit, and need not
be assigned to the same unit each time. The size of a virtual 
disk is entirely determined by the container file, not the VD unit
used. 
.hl 2 VS Pseudodevices
When you assign a container file to a virtual drive, the AVD utility
picks the next available VD: unit. It then associates your container
file with this unit, and also assigns the unit to pseudodevice VSn:.
The first virtual disk you assign becomes VS0:, the second VS1: and
so on. You can see these assignments with the ASN command, if you
are interested. 
.hl 2 VM Pseutodevice 
AVD also assigns pseudodevice VM0: to each virtual disk. Unlike
the VS assignments, only VM0: is used. Each time you allocate
a virtual disk VM0: points to the new disk. This is very useful
for indirect command files (which would otherwise have difficulty
determining which VD or VS unit was being dealt with). You can 
also use it to advantage in other ways. 
.hl 1 AVD
 AVD (Assign Virtual Disk) is the utility which you use to assign your
container file to a virtual drive.  For example:
.nf
#AVD DR:[1,5]JIM
.f
You must of course have at least read access to JIM.DSK.
AVD also assigns your next available VS: to the drive. 
When the assignment is completed, AVD reports:
.nf
#AVD -- Login assignment of VS0: to VD3:
#AVD -- Login assignment of VM: to VD3:
.f 
 AVD performs the equivalent function to spinning up a disk pack
on a real drive. When AVD completes it's work, you must still
MOUnt the drive before you can use it. 
 AVD knows what virtual disks are in use. If you specify a 
container file which is already assigned to some VD unit, 
AVD will simply point you at that unit (using the VS and VM
assignments). This allows multiple users to share a single
virtual disk just as they can a real one. If you ALLOCATE
a virtual disk, AVD will still make the assignment for another
user, but noone else will be able to mount the disk.
 The /RO switch in the AVD command line will assign the disk with
read only access - the virtual disk equivalent of a write-protect
switch. You can also MOUnt the disk READONLY. Or do both, if
you are paranoid. 
.hl 2 AVD Listing Options
 AVD can also list all virtual disk units and assignments. 
Full and brief listings are available. For
mounted virtual disks, the listing also gives the free/total
blocks and the io count. Note that for disks mounted /foreign,
the free/total numbers are meaningless (and usually very large).
.hl 2 HELP
 AVD contains a brief built-in help screen. AVD /HELP will show
this. 
.hl 1 DVD
 DVD (Deassign Virtual Disk)
breaks the connection between a virtual device and a file.
The syntax is:
.nf
#DVD ddnn:
.f
You must dismount the virtual disk before issuing the DVD command. 
DVD will refuse to deassign any mounted disk. DVD also deassigns
the VS unit for you. 
.hl 2 DVD ALL
The command DVD /ALL will deassign the virtual disks associated
with all VSn: units for your terminal. This is very useful at
logout time, or when switching projects, etc. For example
.nf

DMO /USER
DVD /ALL

.f
Will dismount and deallocate all disks currently in use by your
terminal. 
 DVD is smart enough to know when several people are using a virtual
disk, and won't deallocate any disk which is mounted by anyone else.
.hl 1 Usage notes.
 In general, you use virtual disks in the same way as regular ones. 
In particular, a newly created virtual disk must be BAD-ed and 
INItitlized, just like any new pack. The virtual disk may be of any
size (above a minimum of about 100. blocks). INI will make assumptions
of the initial and maximum file limits based on the disk's size, although
you are free to set your own specifications. If the virtual disk is sized
to match a real disk (such as an RL01), INI will set it up to match. 
This is handy, since you can then use real and virtual RL01's interchangeably.
 The two things you cannot do with a virtual disk are 1)boot it, and 2)
SAVe a system on it. Also, if you BRU a bootable disk to a virtual one, the
boot block will be destroyed. Later, when you BRU back to a real disk, you
must soft boot and save the system to make the disk hardware bootable once
again. 
 BRU will happily copy real to virtual or virtual to virtual disks, compressing
in the process. Of course, you could also copy the container file (JIM.DSK), 
but this is not usually a good idea. For one thing, you get no compression
(it's just a file). For another, if you BRU the container file to a real
disk, you will get an output disk with a single file on it - probably not
what you intended. BRU is happy to work with mounted or unmounted virtual
disks. Unmounted disks must of course be allocated, and mounted /foreign
for M+.
.hl 1 VD Command File
 Because handling virtual disks is a bit more confusing than using
real ones, we have created a command file to do most of the work
for you. It is VD.CMD. VD.CMD known about a number of virtual disks,
each with a unique pseudodevice. For example, my private disk is known
as "JB:". Once a virtual disk is known to the command file, you may
allocate and mount it with a single command. For example:
.sk .nf
@VD JB
.f
will allocate, mount, and assign pseudodevice JB: to my virtual disk.
For a list of known virtual disks, use 
.sk
.nf
@VD /li
.f .sk


