home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / w / wtdisk11.zip / WAITDISK.DOC < prev    next >
Text File  |  1992-11-14  |  20KB  |  459 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                              WaitDisk User's Guide
  8.  
  9.                         Copyright (C) 1992 Larry B. Rice
  10.  
  11.  
  12.                                     License
  13.  
  14.         This program is licensed for evaluation use  only.   The program 
  15.         may be installed and used on single or multiple user systems for 
  16.         a  period of time not to exceed  two  weeks.    Only  registered 
  17.         copies  may  be  used beyond this time.
  18.  
  19.  
  20.                         Disclaimer & Limit of Liability
  21.  
  22.         WaitDisk  and the WaitDisk User's Guide are distributed 'as is'.  
  23.         The Author make no warrants,  either express or implied,  as  to 
  24.         appropriateness  or suitability for any particular  use of  this 
  25.         product,    or  to  the  accuracy  of  this  or  other   related 
  26.         documentation,  nor to the error-free operation of the software.  
  27.         Except  as  may be provided by law,  neither the Author nor  any 
  28.         duly  authorized  representatives  may be held  liable  for  any 
  29.         damages  or loss resulting from the use of,  or the inability to 
  30.         use,  this product.   Under no circumstances shall any liability 
  31.         for  the  use of the software,  or the information  contained in 
  32.         this and other  related documentation  exceed the purchase price 
  33.         of the program. 
  34.  
  35.  
  36.         WaitDisk  is NOT in the Public Domain  and may not be marked  or 
  37.         displayed as such.  
  38.         
  39.         WaitDisk   IS  distributed  as  Shareware.    For   Distribution 
  40.         information,   see  the  file  VENDOR.DOC.    For  Ordering  and 
  41.         Licensing  information,   see the file ORDER.DOC.
  42.  
  43.         If you have questions or comments, please contact the Author:
  44.  
  45.               Larry Rice   2907 St. Tropez Dr., Ontario, CA  91761
  46.  
  47.  
  48.                                     CONTENTS
  49.  
  50.                       What is WaitDisk?. . . . . . . . . 1
  51.                       Who can use it?. . . . . . . . . . 1
  52.                       Why use WaitDisk?. . . . . . . . . 2
  53.                       How is it used?. . . . . . . . . . 3
  54.                       Using WaitDisk in Batch Files. . . 5
  55.                       Using WaitDisk in Another Program. 6
  56.                       Sample WaitDisk Calls. . . . . . . 7
  57.                       Compatibility Problems . . . . . . 7
  58.  
  59.  
  60.         ----------------------------------------------------------------
  61.         WaitDisk User's Guide                                     Page 1
  62.  
  63.  
  64.  
  65.  
  66.                            **  What is WaitDisk?  **
  67.  
  68.         Users of Apple's MacIntosh or Commodore's Amiga computers may be 
  69.         familiar  with  their  ability to prompt a user for  a  specific 
  70.         floppy disk and wait for it to be placed into a specific  drive.  
  71.  
  72.         WaitDisk  brings this feature to DOS computers.   Briefly,   for 
  73.         those  who  may  not familiar with either  of  these  computers, 
  74.         WaitDisk  may  be called from a DOS Batch File or  from  another 
  75.         program  to  prompt the user to place a specified  disk  into  a 
  76.         specific  drive.    WaitDisk  will then wait until the  disk  is 
  77.         either  inserted  into the drive or until the user  cancels  the 
  78.         operation.  Waitdisk returns a code to inform DOS or the calling 
  79.         program which action has occurred.
  80.         
  81.         WaitDisk supports the use of a mouse  and  uses  a pop-up prompt 
  82.         window that  saves the underlying screen.   This allows WaitDisk 
  83.         to be used seamlessly in a variety of applications.  WaitDisk is 
  84.         compatible with Monochrome, CGA, EGA and VGA adapters,  requires 
  85.         DOS  version  3.0   or newer and works  from  either  floppy  or 
  86.         harddrives.    WaitDisk  can  read  Volume  Labels  from   disks 
  87.         formatted with DOS v2.0 and later, and Serial Numbers from disks 
  88.         formatted with DOS v4.0 and later. 
  89.  
  90.         IMPORTANT:   Some older disk drives can take a detectable amount 
  91.         of  time  to  return information or their  status  to  WaitDisk.  
  92.         Because  of this,  there may be a slight delay when  the  proper 
  93.         disk is inserted or the user cancels the request before WaitDisk 
  94.         can respond.
  95.  
  96.  
  97.                             **  Who can use it?  **
  98.  
  99.         Anyone  familiar  with DOS batch files may easily use  WaitDisk.  
  100.         In  its  simplest form,  WaitDisk may be called to wait for  ANY 
  101.         disk to be placed into a floppy drive.  For example, 
  102.  
  103.                                   waitdisk -da
  104.  
  105.         will prompt the user to place ANY disk into drive A:.   WaitDisk 
  106.         will return an ERRORLEVEL  code  of 0 to indicate  that drive A: 
  107.         contains  a disk.   An ERRORLEVEL code of 1 indicates  that  the 
  108.         user CANCELED the operation and that Drive A: does NOT contain a 
  109.         diskette. 
  110.         
  111.         Another parameter,  -v,  can be used  to  supply WaitDisk with a 
  112.         Volume name.   In this case,  WaitDisk will return an ERRORLEVEL 
  113.         code of 0 ONLY when a diskette with the specified volume name is 
  114.         placed into the specified drive. 
  115.  
  116.         WaitDisk can also be supplied with a Disk Title, that is, a name 
  117.         used on the disk's label.  This name can be up to 28  characters 
  118.         long and is prominently displayed in WaitDisk's prompt window.  
  119.  
  120.  
  121.         ----------------------------------------------------------------
  122.         WaitDisk User's Guide                                     Page 2 
  123.                  
  124.  
  125.  
  126.         For developers, script writers and DOS programmers, WaitDisk can 
  127.         also be supplied with a  Volume Serial Number,  for more precise 
  128.         disk  identification,  and row and column coordinates to  locate 
  129.         the pop-up window on the screen so  that it does not cover other 
  130.         important  information.   And,  WaitDisk can be set to  'silent' 
  131.         mode  to test the current disk to determine if the user needs to 
  132.         be prompted at all. 
  133.  
  134.         
  135.                            **  Why use WaitDisk?  **
  136.  
  137.         While  DOS  provides  a  mechanism  for  identifying  individual 
  138.         diskettes through Volume  Labels it doesn't provide a useful way 
  139.         of  using them.   WaitDisk not only provides that,  it lets  you 
  140.         avoid getting trapped by the infamous 
  141.  
  142.                               Abort, Retry, Fail?
  143.  
  144.         prompt.    This prompt appears anytime DOS attempts to access  a 
  145.         disk drive that is not ready to be accessed, either because it's 
  146.         empty,   the  drive door has not been properly closed or  you've 
  147.         accidentally placed an unformatted or improperly  formatted disk 
  148.         into the drive. 
  149.         
  150.         Computer  owners who keep a number of occasionally used programs 
  151.         and utilities on floppy diskette will find WaitDisk a convenient 
  152.         way to build batch files or menus that ask and wait for disks by 
  153.         name. 
  154.  
  155.         Developers  will  find  a  number  of uses  for  WaitDisk.    By 
  156.         specifying a Volume Label AND Volume Serial Number,  you can  be 
  157.         virtually  certain  that  a needed program or data diskette  has 
  158.         been  placed into  the  proper drive.   WaitDisk  preserves  the 
  159.         current  screen and cursor location,  and restores them even  if 
  160.         the  user cancels the operation.   This way your code can decide 
  161.         on  further  action,  not DOS.   WaitDisk reliably traps Int  24 
  162.         (Critical Error) calls and prevents the 
  163.  
  164.                               Abort, Retry, Fail?
  165.  
  166.         message from appearing over your carefully designed screens.
  167.  
  168.         Best of all,  you can license WaitDisk for royalty-free use  for 
  169.         less than it would take to develop a similar feature yourself. 
  170.  
  171.         ----------------------------------------------------------------
  172.         WaitDisk User's Guide                                     Page 3
  173.  
  174.  
  175.  
  176.                             **  How is it used?  **
  177.  
  178.         When called, WaitDisk will display a prompt window on top of the 
  179.         current application (or DOS)  showing prompting the user for the 
  180.         requested  disk.    At the same time,  WaitDisk will  check  the 
  181.         specified  drive  for  the requested disk.   If  it  is  already 
  182.         present,   WaitDisk  will  promptly  terminate and  return  a  0 
  183.         ERRORLEVEL  code.   If the disk is not present,   WaitDisk  will 
  184.         continuously  check  the  specified  drive  until  the  disk  is 
  185.         inserted or the user cancels the request.   Note that the  drive 
  186.         light will remain on during this time.  
  187.  
  188.         The  only action required by the user is to place the  requested 
  189.         disk into the specified drive.   Either the 'C'  or ESC keys may 
  190.         be  used to cancel the request.   WaitDisk automatically  checks 
  191.         for the presence of a mouse driver.  If one is loaded,  the user 
  192.         may click on the Window Close button in the upper left corner of 
  193.         the window or click on the Cancel button to cancel the request. 
  194.  
  195.         Developer's  Note:   You will probably need to reset  the  mouse 
  196.         driver   after a call to WaitDisk.   WaitDisk requests only Left 
  197.         Button down events from the driver. 
  198.  
  199.  
  200.                    WAITDISK -D [-V] [-S] [-N] [-R] [-C] [-X]
  201.  
  202.         Parameters  may  be  passed using either  upper  or  lower  case 
  203.         letters.    WaitDisk translates Drive,  Volume Label and  Serial 
  204.         Number   letters   to  upper  case  before  doing   comparisons.  
  205.         Parameters shown in brackets ([]) are optional. 
  206.  
  207.         -D  The Disk Drive where WaitDisk should look for a disk.   This 
  208.             is  the  only  required parameter.   If  the  Drive  is  not 
  209.             specified, an error message will  appear  along with general 
  210.             use instructions.  Examples:
  211.  
  212.                                -da   (Check Drive A) 
  213.                                -db   (Check Drive B)    
  214.  
  215.             Note that -Da, -dA, -dA:  are all valid Drive parameters.
  216.         
  217.  
  218.         -V  Look  for  a  specific  Volume  Label.    Volume  Label  are 
  219.             generally  assigned  during formatting but may be  added  or 
  220.             changed  later using DOS's LABEL command.   The Volume Label 
  221.             may be up to 11 characters long. 
  222.  
  223.                             waitdisk -dB: -vVolume_1
  224.  
  225.             If  WaitDisk  is not provided with a Volume Label,  it  will 
  226.             prompt the user for ANY volume in the specified drive. 
  227.             
  228.             Note that spaces MAY BE USED in Volume Labels.   "Util Disk" 
  229.             is a valid Volume Label and is passed to WaitDisk as 
  230.             
  231.                             waitdisk -dB: -v"Util Disk"
  232.  
  233.  
  234.         ----------------------------------------------------------------
  235.         WaitDisk User's Guide                                     Page 4
  236.  
  237.  
  238.  
  239.             Case is NOT significant.   WaitDisk changes the Volume Label 
  240.             to all upper case letters before  comparison with the disk's 
  241.             volume label.    vutil_1   and -vUTIL_1 are identical volume 
  242.             label parameters. 
  243.  
  244.  
  245.             Developer's  Note:    Volume  Labels are available on  disks 
  246.             formatted with DOS versions 2.0 and later.   DOS returns the 
  247.             Volume  Label  as  a filename,  using the file extension  to 
  248.             extend the name to eleven characters and padding short names 
  249.             to  eleven  characters using spaces.   However,  the  Volume 
  250.             Label should be passed to WaitDisk just as it was entered on 
  251.             formatting,   that is,  without an extension (and obviously, 
  252.             unpadded).   WaitDisk will transform the disk's volume label 
  253.             as returned by DOS into a similar string for comparison.  
  254.  
  255.             IMPORTANT:   When a Serial Number is provided (see -s)  BOTH 
  256.             the  Volume Label and Serial Number are read from the disk's 
  257.             boot sector. 
  258.  
  259.         
  260.         -S  FOR DISKS FORMATTED WITH DOS V4.0  OR LATER.   Search for  a 
  261.             specific  volume Serial Number.   Beginning with version 4.0 
  262.             of DOS,  formatted disks are automatically assigned a Serial 
  263.             Number.  Use the format xxxx-xxxx, i.e. 
  264.              
  265.                                    -s14FE-779A
  266.         
  267.             to supply the serial number.   This is the same format  used 
  268.             by  DOS to display the Serial Number after a disk  has  been 
  269.             formatted. 
  270.  
  271.             Generally Serial Numbers will provide a more reliable method 
  272.             of identifying a disk since the Serial Number is composed of 
  273.             a  date  and time stamp when the disk was formatted.    When 
  274.             used  with the  Volume  Label  (-v),   identification  of  a 
  275.             specific  disk  is  virtually  assured.   This  parameter is 
  276.             primarily intended for use by  developers but may be used by 
  277.             others as well. 
  278.  
  279.             Note  that  when  the -s parameter  is  provided,   WaitDisk 
  280.             retrieves  the Serial Number AND Volume Label from the  boot 
  281.             sector  of  the disk in the specified drive.   If a disk  is 
  282.             inserted  into the specified drive that has  been  formatted 
  283.             with an earlier version of DOS,  WaitDisk will only identify 
  284.             the Current Volume as 
  285.              
  286.                                    Pre-4.0 Format
  287.  
  288.  
  289.         ----------------------------------------------------------------
  290.         WaitDisk User's Guide                                     Page 5
  291.  
  292.  
  293.  
  294.         -N  Prompt the user for a specific Disk  Name.    Don't  confuse 
  295.             this with the Volume Label.   The -n parameter is an (up to)  
  296.             28-character  name  which  may be found on the  disk  label.  
  297.             More  than  one  word may be used by enclosing the  name  in 
  298.             quotation marks. 
  299.  
  300.                              -n"Disk 4 - Utilities"
  301.                              -n"Disk Utils #4"
  302.                              -n"Virus Checkers"
  303.  
  304.             If  WaitDisk is not provided with a disk name,  a  "No  Disk 
  305.             Name Specified" message will appear in the prompt window. 
  306.  
  307.  
  308.         -R  Specify an upper-left Row (-R) and/or Column (-C) coordinate 
  309.         -C  for the WaitDisk prompt window.   The column coordinate must 
  310.             be  in the range of 1 to 32  and  the row coordinate in  the 
  311.             range of 1 to 13.  The default values, c = 28 and r = 4, are 
  312.             used  for  any coordinate NOT passed.   If a  coordinate  is 
  313.             passed  that exceeds  the maximum range,  the maximum  value 
  314.             will be used. 
  315.  
  316.         -X   Make a Silent test of the disk in drive -D.   WaitDisk will 
  317.             test the drive against the parameters supplied.  If the disk 
  318.             is inserted, WaitDisk returns 0.  If the disk is not present 
  319.             or the drive is not ready,  WaitDisk returns 1.   The prompt 
  320.             window will  ONLY appear if there is an error in one  of the 
  321.             arguments.  
  322.  
  323.                       **  Using WaitDisk in Batch Files **
  324.  
  325.         WaitDisk  will  automatically  return an ERRORLEVEL  code  of  0 
  326.         (zero)  when the proper disk is placed into the specified drive.  
  327.         If the user cancels the operation, WaitDisk returns a 1 (one). 
  328.  
  329.         Examples:
  330.  
  331.             @ECHO OFF
  332.             REM  Wait for ANY disk in Drive A
  333.             waitdisk -da
  334.  
  335.             IF ERRORLEVEL 1 GOTO Canceled
  336.             IF ERRORLEVEL 0 GOTO Success
  337.  
  338.             :Success
  339.             ECHO There is a disk in Drive A
  340.             GOTO QUIT
  341.  
  342.             :Canceled
  343.             ECHO User Canceled Request
  344.             GOTO QUIT
  345.     
  346.             :Quit
  347.  
  348.  
  349.         ----------------------------------------------------------------
  350.         WaitDisk User's Guide                                     Page 6
  351.  
  352.  
  353.  
  354.         
  355.         Note  that  in  this  example,  if Drive A  already  contains  a 
  356.         diskette,  WaitDisk will immediately return with a Success code, 
  357.         without any action on the part of the user.  
  358.  
  359.  
  360.                     **  Using WaitDisk in Another Program **
  361.         
  362.         This  is  an  example  of using WaitDisk with  Turbo  C's  SPAWN 
  363.         function.   Other languages should have similar functions.   The 
  364.         return codes are: 
  365.  
  366.                          0 - Requested Disk is in Drive
  367.                          1 - User Canceled Request
  368.  
  369.          #include <process.h>
  370.          #include <stdio.h>
  371.  
  372.          main()
  373.          {
  374.             .
  375.             .
  376.             .
  377.  
  378.             if (!spawnlp(P_WAIT, "WAITDISK", "WAITDISK", "-DA",
  379.                                  "-V\"UTILITY 12\"", NULL))
  380.               printf("Volume UTILITY 1 in in Drive A");
  381.             else printf("User Canceled Request.");
  382.          }
  383.         
  384.  
  385.         Two things are worth noting.   First,  the second "WAITDISK"  is 
  386.         actually 'argv[0]',  which WaitDisk ignores but is normally  the 
  387.         path of the called program. 
  388.  
  389.         Second, note the use of quotation marks inside the -v parameter.  
  390.         If they aren't provided, WaitDisk will be passed the '12' of 
  391.         'Utility 12' as a separate argument (#3).  As a result, WaitDisk 
  392.         will display the error message:
  393.          
  394.                                  ERROR in #3: 12
  395.  
  396.  
  397.  
  398.         ----------------------------------------------------------------
  399.         WaitDisk User's Guide                                     Page 7
  400.  
  401.  
  402.  
  403.                           **  Sample WaitDisk Calls **
  404.  
  405.         Following  are  some other valid WaitDisk calls.   Note that the 
  406.         mixed  use  of upper and lower  case  is intended  to  show  the 
  407.         variety of ways in which parameters may be provided. 
  408.  
  409.  
  410.         waitdisk -db -v"Utility 1"
  411.  
  412.            Wait for Volume 'UTILITY 1' to be placed into Drive B.
  413.  
  414.         waitdisk -db -vmy_progs -n"Basic Utilities"
  415.  
  416.            Wait  for Volume 'MY_PROGS'  to be placed into Drive B.   The 
  417.            disk is titled "Basic Utilities". 
  418.  
  419.         waitdisk -db -sAC09-45F4
  420.  
  421.            Wait  for the disk with Serial Number AC09-45F4  to be placed 
  422.            into Drive B.   A   Volume Label and Disk Title have not been 
  423.            specified. 
  424.  
  425.         waitdisk -da -v"sp data 2" -s11fc-a0b0  -r11 -c29
  426.  
  427.            Wait for a disk in Drive A with a Volume Label of 'SP DATA 2' 
  428.            and Serial Number of 11FC-A0B0.   Display the WaitDisk prompt 
  429.            window in the lower right corner of the screen. 
  430.  
  431.  
  432.  
  433.                          **  Compatibility Problems  **
  434.  
  435.         WaitDisk uses BIOS interrupts 13H and 24H.  Some disk utilities, 
  436.         such as disk caching programs,  may use these interrupts as well 
  437.         in ways incompatible with WaitDisk.   Currently,  the only known 
  438.         problem  is  with  Hyperware's  HyperDisk  which  WaitDisk  must 
  439.         temporarily disable in order to operate properly.  (HyperDisk is 
  440.         reenabled to your configuration when WaitDisk terminates.   Note 
  441.         that  if you have configured HyperDisk for staged updates,   any 
  442.         disk  in the specified drive will automatically be updated,   if 
  443.         needed, BEFORE HyperDisk is disabled.) 
  444.  
  445.         If  you  experience problems with WaitDisk,  try  disabling  any 
  446.         devices,  drivers or other TSRs you may have installed,  one  by 
  447.         one.   If WaitDisk works  properly after one of these  has  been 
  448.         removed  then  you  are experiencing  a  compatibility  problem.  
  449.         Please  report the name of the program you have removed and  its 
  450.         version  number  to the author.   Every effort will be  made  to 
  451.         ensure compatibility with popular disk utilities. 
  452.  
  453.  
  454.                                   END OF FILE
  455.         ----------------------------------------------------------------
  456.  
  457.  
  458.  
  459.