 
             VD - Virtual Disk Driver and Utilities 
 
 A virtual disk is merely a file on a larger physical (or a larger virtual)
 disk. It is allocated contiguously, containing the number of blocks which
 corresponds to the size of the virtual disk desired. 
 
 A virtual disk is completely transparent to RSX-11M, that is it appears to be
 a unique and real device, separate from the disk on which the file resides.
 You must INItialize it, MOUnt the disk for use, create UFD's, and run VFY
 occasionally. Once a virtual disk is allocated, it can be used like any other
 disk on the system. 
 
 About the only operations that cannot be done on a virtual disk are SAV and
 non-system operations such as hardware bootstraps or stand-alone BAD, DSC or
 BRU. 
 
 Additional qualifiers for VD are:

   OPERATION - operational description    VDC  - Dismount and deassign VD's
   AVD       - Creating/assigning VD's    VDA  - Listing VD assignments
   DVD       - Deasigning VD's
 
2 OPERATION
 
 VDDRV Operational Description:
 
 The contents of a virtual disk are accessed via the virtual disk driver, 
 VDDRV. It looks like a disk driver to the system and its operation is simple 
 and straight forward. 

 When an I/O request is queued to VD:, and the driver de-queues that packet
 ($GTPKT), it checks that the block number is legal for the file size
 ($BLKCK), performs a read-only check if XF.RON is set, adds an offset to the
 I/O packet block number and queues the request to the driver for the device
 which contains the virtual disk file. Note that this file may reside on
 another virtual disk in which case the VD driver would get the QIO again,
 massage it as previously described and pass it on to the driver for the
 device which contains that virtual disk file. This can be handy for creating
 a virtual disk which is a collection of other virtual disks, however it will
 slow down disk accesses to some extent so it is not reccommended for disks
 which will receive a lot of accesses. 
  
 The offset added to the block number is the starting physical block number of
 the virtual disk file. This is the reason for allocating the file contiguously.
 Any access to a block within the virtual disk can be accessed through the
 driver for the device that contains the virtual disk file by adding the
 starting block number of the virtual disk file. 
2 AVD
 
 Creating and/or assigning virtual disks (AVD):
 
The AVD utility is used to create new virtual disks as well  as  assign 
existing  virtual  disks.   
 
 Usage:     Form 1:    >AVD VDn:=file[/sw] 
                               or       
            Form 2:    >AVD file[/sw]   
                         
The first form will assign a particular VD unit to the file. The second form
will assign the first available offline VD to the file. The arguments are: 
                                                         
             VDn:    Virtual disk unit to assign. 
             file    File to be used as virtual disk             
             /sw     Switches
                                                         
 Additional qualifiers for AVD:

 SWITCHES     - Valid switches         ERRORS - Error messages & Exit status
 DESCRIPTION  - Operational desc.      RETURN-CODES - Successful return codes

3 SWITCHES

 AVD switches:

 /CR:n   Create file with n blocks       /RK     Create file with 4800 blocks 
 /ID     Report AVD version number.      /RL01   Create file with 10240 blocks 
         If this switch is used,         /RL02   Create file with 20480 blocks 
         only the version will be        /RX01   Create file with 494 blocks 
         printed. No other action will   /RX02   Create file with 988 blocks 
         occur regardless of what is     /RO     Allow only read access 
         in the command line.                    (write protect)
 /PL:n   Used with any of the file       /NM     Do not print messages
         creation switches to allow 
         placement control of the file 
         to logical block n. 
 

3 DESCRIPTION

 AVD description:

        Since there is no support for AVD in VMR, virtual disks must be
        assigned after the system is booted. If permanently assigned
        virtual disks are desired then they can be assigned in the
        STARTUP.CMD file. All virtual disk units are marked "off-line"
        when the VD: driver is loaded to indicate that there are no files
        assigned to those units. When a virtual disk unit is assigned to
        a file with the AVD utility, the unit is set to "on-line" and the
        starting physical block number of the virtual disk file is stored
        in that units UCB for subsequent use by the virtual disk driver. 

3 RETURN-CODES

 AVD status returns:
 
 If the first form of the AVD command is used (IE.  AVD VDn:=file[/sw]), 
 and  the virtual disk is successfully created and/or assigned, the exit 
 status will be 1 and no messages will be printed. 
 
 If the second form of the command is used  (IE.   AVD  file[/sw]),  AVD 
 will  search  though  the VD UCB's and find a virtual disk unit that is 
 currently not in use (ie.  off-line) and attempt to assign  it  to  the 
 file.   On successful completion, the following message will be printed 
 (unless the /NM switch is used): 
  
        >AVD TEST 
        AVD -- VD4: has been assigned to file TEST.DSK;1 
 
 This is assuming that VD4:  was the first available off-line unit.  The 
 exit  status  will  be  set to the unit number selected by AVD plus 200 
 octal.  In the above example, the exit status would be: 
  
        4 + 200 = 204 
  
 Another message and group of exit  status  codes  are  possible  if  an 
 attempt  is made to assign a file to a virtual disk unit when that file 
 is already assigned to another  virtual  disk  unit.   For  example  if 
 TEST.DSK;1  is  already  assigned to VD0:  and the following command is 
 issued: 
   
        >AVD VD5:=TEST 
              or 
        >AVD TEST 
  
 will result in the following message: 
  
        AVD -- File TEST.DSK;1, already assigned to VD0: 
  
 In this case, the exit status  is  set  to  the  unit  number  that  is 
 assigned to the file plus octal 300.  In this case the exit status will 
 be: 
  
        0 + 300 = 300. 
  
3 ERRORS 
 
 AVD error messages -  
 
 AVD error messages are all numbered, starting  at  101  octal.   If  an 
 error  occurs,  then  the  appropriate  error message will be displayed 
 (unless the /NM switch is used) and the exit status will be set to  the 
 error message number. 
 
     101  No command line            112  VDn:  already assigned 
     102  Invalid command line       113  Pool allocation failed 
     103  Command syntax error       114  Error creating file 
     104  Unable to find VD:  DCB    115  Bad disk size 
     105  VDn:  not loaded           116  Bad placement value 
     106  No VD units available      117  File not found 
     107  Invalid virtual disk name  120  File access failed 
     110  Invalid input syntax       121  File not contigious 
     111  Invalid input filename 

 Additional help available by typing:  ? VD AVD ERROR error-number

 
 
4 101  

 101  No command line 
 
     An attempt was made  to  run  AVD  without  a  command  line  (ie. 
     RUN $AVD).  A command line must always be present. 
 
4 102  

 102  Invalid command line 
 
     Command line supplied to AVD not of the form "AVD parameters" 
 
4 103  

 103  Command syntax error 
 
     Command line had a syntax error (ie.  failed CSI$1) 
 
4 104  

 104  Unable to find VD:  DCB 
 
     This is an internal error that never should occur.   
 
4 105  

 105  VDn:  not loaded 
 
     Assign lun failed to virtual disk unit selected.  Either  the  VD: 
     driver is not loaded or an invalid virtual disk unit was entered. 
 
4 106  

 106  No VD units available 
 
     AVD has been requested to search for an off-line VD unit  and  was 
     unable  to find one.  (ie.  all the VD units gen'd into the system 
     are in use) 
 
4 107  

 107  Invalid virtual disk name 
 
     Something other than VDn:  was used as a virtual disk name in  the 
     AVD command line. 
 
4 110  

 110  Invalid input syntax 
 
     More than one file was entered or a wildcard was used somewhere in 
     the file specification. 
 
4 111  

 111  Invalid input filename 
 
     File specification contained an invalid device,  non-existant  UIC 
     or the device which contains the virtual disk file is not mounted. 
     (ie.  The .PARSE routine failed) 
 
4 112  

 112  VDn:  already assigned 
 
     An attempt has been made to  use  a  virtual  disk  unit  that  is 
     already  assigned to another virtual disk file.  (ie.  the unit is 
     not "off-line") 
 
4 113  

 113  Pool allocation failed 
 
     An attempt to allocate  pool  for  the  UCB  extension  block  has 
     failed.   (ie.   the  $ALOCB system routine failed) Your system is 
     very low on pool.  Eliminate the pool  problem  and  try  the  AVD 
     command again. 
 
4 114  

 114  Error creating file 
 
     AVD was requested to create a new vitrual disk  file  but  failed. 
     The most common cause of this error is a lack of enough contiguous 
     space to contain the virtual disk  file.   Another  cause  can  be 
     Index-file-full. 
 
4 115  

 115  Bad disk size 
 
     The value entered with the /CR switch was not numeric 
 
4 116  

 116  Bad placement value 
 
     The value entered with the /PL switch was not numeric 
 
4 117  

 117  File not found 
 
     AVD could not find the file indicated in the file spec 
 
4 120  

 120  File access failed 
 
     AVD was not allowed write access to the virtual disk  file.   This 
     is  usually caused by the file being locked.  Previous versions of 
     AVD locked the file when it was assigned to prevent assigning that 
     file  to  another  Virtual  disk unit.  This version of AVD checks 
     saved filename blocks for all assigned VD's to  prevent  this  and 
     therefore  does  not  lock  the file.  If you encounter this error 
     then use PIP to unlock the file. 
 
4 121  

 121  File not contigious 
 
     An attempt was made to assign a non-contiguous file as  a  virtual 
     disk. 
 
2 DVD 

 De-assigning a virtual disk (DVD):
 
 The DVD utility is used to de-assign a virtual disk.  When  de-assigned 
 the  unit  is  marked  "off-line"  and  can  now be assigned to another 
 virtual disk file with the AVD utility.  
 
 Usage:     >DVD VDn:[/sw] 
 
 Where:     VDn:    is the unit you wish to de-assign. 
            /sw     is one of: 
       
                    /ID     Report DVD version number. If this switch is used,
                            only the version will be printed. No other action 
                            will occur regardless of what is in command line. 
                    /NM     Do not print messages               
                    /DMO    Spawn a dismount command of the form "DMO VDn:/DEV"
                            before deassigning the virtual disk. 
 
 Type ? VD DVD ERRORS for explanation of error messages.

3 ERRORS 

 DVD error messages:
 
 DVD error messages are all numbered, starting  at  101  octal.   If  an 
 error  occurs,  then  the  appropriate  error message will be displayed 
 (unless the /NM switch is used) and the exit status will be set to  the 
 error message number. 
 
 
    101  No command line 
    102  Command syntax error 
    103  VDn:  required 
    104  VDn:  invalid or not loaded 
    105  VDn:  mounted, not deassigned 
    106  VDn:  marked for dismount, not de-assigned 
    107  VDn:  in use, not deassigned 
    110  VDn:  not assigned 
 
 Additional help available by typing:  ? VD DVD ERRORS error-number

4 101  

 101  No command line 
 
     An attempt was made  to  run  DVD  without  a  command  line  (ie. 
     RUN $DVD).  A command line must always be present. 
 
4 102  

 102  Command syntax error 
 
     Command line had a syntax error 
 
4 103  

 103  VDn:  required 
 
     No virtual disk unit was specified to deassign 
 
4 104  

 104  VDn:  invalid or not loaded 
 
     Virtual disk unit specified was not gen'd into the system  or  the 
     VD:  driver is not loaded 
 
4 105  

 105  VDn:  mounted, not deassigned 
 
     DVD will not de-assign a virtual disk if it is mounted. 
 
4 106  

 106  VDn:  marked for dismount, not de-assigned 
 
     An attempt has been made to deassign a virtual disk with the  /DMO 
     switch but the unit is already marked for dismount. 
 
4 107  

 107  VDn:  in use, not deassigned 
 
     An attempt has been made to deassign a virtual disk with the  /DMO 
     switch but there is a file open on that disk. 
 
4 110  

 110  VDn:  not assigned 
 
     The virtual disk unit is not currently assigned to a virtual  disk 
     file.  (ie.  it is already off-line) 
 
2 VDC 
 
 DMO and DVD a virtual disk (VDC):
 
 The VDC utility is used to dismount and de-assign a virtual disk or all 
 virtual  disk  on  a  specified host disk.  It spawns VDA and DVD.  The 
 operation of VDC is as follows: 
 
 Usage:     Form 1: >VDC VDn:     ! same results as DVD VDn:/DMO/NM 
                   or 
            Form 2: >VDC /ddn[/NQ] 

 Where:     VDn:    is the unit you wish to de-assign. 
            /ddn    is the host device and unit which is to have all of its 
                    virtual disks deassigned 
            /NQ     (No Query) Used with /ddn. Normally VDA will be spawned to 
                    display a list of VD's that will be deassigned and then 
                    the user will be prompted as to whether to continue or not.
                    /NQ disables this action. 
       
                    Additional qualifiers for VDC are:

   ? VD VDC MESSAGES     - Infomational messages
   ? VD VDC ERRORS       - Error messages

3 MESSAGES

 VDC informational messages:
 
 VDC has several informational messages that can be displayed during its 
 execution.  These are: 
 
 1) The following VD's will be deassigned 
  
    This message is displayed prior  to  spawning  VDA  when  /ddn  is 
    specified unless the /NQ switch is used. 

 2) Continue with deassignment?  (Y/N) > 
  
    This message is displayed after VDA completes, unless the /NQ switch is 
    used. The user must respond with a 'Y' to continue with the deassignment(s)
  
 3) Deassign failure on VDn:, DVD error code (err) 

    This message will occur if DVD fails. (err) will be DVD's exit status. 
  
 4) VDn:  is deassigned 
  
    This message is displayed when a DVD is successful.
  
3 ERRORS 
 
 VDC error messages:
 
 VDC error messages are all numbered, starting  at  101  octal.   If  an 
 error  occurs, then the appropriate error message will be displayed and 
 the exit status will be set to the error message number. 
 
   101  No command line 
   102  Command syntax error 
   103  Conflicting parameters 
   104  VDn:  or /dev required 
   105  /dev invalid device or not loaded 
   106  GLUN$S failed 
   107  Unable to find VD:  DCB 
   110  DVD failed for 1 or more units 
   111  DVD failed 
 
 Additional help available by typing:  ? VD VDC ERROR error-number
 
4 101  

 101  No command line 
 
     An attempt was made  to  run  VDC  without  a  command  line  (ie. 
     RUN $VDC).  A command line must always be present. 
 
4 102  

 102  Command syntax error 
 
     Command line had a syntax error 
 
4 103  

 103  Conflicting parameters 
 
     VDn:  and /ddn were specified on the command line 
 
4 104  

 104  VDn:  or /dev required 
 
     No virtual disk unit to deassign or no host disk was specified 
 
4 105  

 105  /dev invalid device or not loaded 
 
     The host disk specified was not  gen'd  into  the  system  or  its 
     driver was not loaded 
 
4 106  

 106  GLUN$S failed 
 
     Internal error, should not  occur  since  a  previous  ALUN$S  had 
     succeeded. 
 
4 107  

 107  Unable to find VD:  DCB 
 
     This is an internal error that never should occur.   
 
4 110  

 110  DVD failed for 1 or more units 
 
     /ddn was specified but DVD was not able to dismount  and  deassign 
     all of the virtual disks on that device. 
 
4 111  

 111  DVD failed 
 
     VDn:  was specified but DVD was not able to dismount and  deassign 
     that virtual disk 
 
2 VDA

 Listing virtual disk assignments (VDA):
 
 This program is used to display the current virtual disk assignments on 
 a system.  It is invoked as follows: 
  
        >VDA [/sw]        ! Displays status of VD's selected by /sw
   or   >VDA VDn          ! Displays status of VD unit 'n' only 
  
 where /sw can be one of the following: 
  
       /OFL    - Display only VD's that are offline (IE.not assigned) 
       /ALL    - Display all VD's whether offline or online 
       /ONL    - Display only online VD's (default if no switch specified) 
       /HE     - Displays help text 
       /dev    - Displays VD's on device 'dev' only, where 'dev' is the device 
                 mnemonic and unit (if no unit then unit 0 is displayed) 
  
 The display will contain the VD unit, associated file name, disk size and the
 label of the disk if mounted (*none* if disk has no label, *dismounted* if
 disk is not mounted and *foreign* if the disk is mounted foreign). If the
 disk is mounted as a Files-11 volume, it will also display the number of free
 blocks on the disk, the maximum number of files allowed on the disk and the
 current transaction count for the disk. 
