home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dosfin.zip / README.NOW next >
Text File  |  1993-12-03  |  9KB  |  227 lines
  1. /****************************************************************************/
  2.  
  3.                      DosFind... Test Utility
  4.                      Version 1.0 Beta
  5.                      11/10/93
  6.                      
  7.   (C) Copyright 1993 One Up Corporation                     
  8.  
  9. /****************************************************************************/
  10.  
  11. 1. The purpose of this utility is test the return codes from DosFindFirst 
  12.    and DosFindNext in situations where a network access may appear to return
  13.    a bogus value.
  14.    
  15.    Specifically, these API calls have caused some application problems where
  16.    the target directories and files are across LAN networks with LAN Server 3.0
  17.    and other network software specifically using HPFS386 and TCP\IP.
  18.  
  19.    Finding directories and filenames consist of initially calling DosFindFirst.
  20.    You send the path of the directory to search, a file or directory mask, and
  21.    a mask for the file or directory attributes.  The only difference in obtaining
  22.    files or directories is the attributes that you use in the call.
  23.  
  24.    You will receive a return code, the first item returned and a handle to
  25.    subsequent calls to DosFindNext.
  26.    
  27.    If the return code is Ok, you can loop through calls to DosFindNext retrieving
  28.    the rest of the items in the directory.
  29.  
  30.    The following two paragraphs are from the IBM on-line help facility regarding
  31.    DosFindFirst and DosFindNext.
  32.  
  33.  
  34.           /* DosFindFirst finds the first file object
  35.           or group of file objects whose names match
  36.           the specification.  The specification can
  37.           include extended attributes associated
  38.           with a file or directory. */
  39.           
  40.           #define INCL_DOSFILEMGR
  41.           #include <os2.h>
  42.           
  43.           PSZ     pszFileName;
  44.           PHDIR   pphdirDirHandle;
  45.           ULONG   ulAttribute;
  46.           PVOID   pResultBuf;
  47.           ULONG   ulResultBufLen;
  48.           PULONG  pSearchCount;
  49.           ULONG   ulFileInfoLevel;
  50.           APIRET  rc;             /* Return code */
  51.           
  52.           rc = DosFindFirst(pszFileName,
  53.                      pphdirDirHandle, ulAttribute,
  54.                      pResultBuf, ulResultBufLen,
  55.                      pSearchCount, ulFileInfoLevel);
  56.  
  57.           /* DosFindNext finds the next set of file
  58.           objects whose names match the specification
  59.           in a previous call to DosFindFirst
  60.           or DosFindNext. */
  61.           
  62.           #define INCL_DOSFILEMGR
  63.           #include <os2.h>
  64.           
  65.           HDIR    hdirDirHandle;
  66.           PVOID   pResultBuf;
  67.           ULONG   ulResultBufLen;
  68.           PULONG  pSearchCount;
  69.           APIRET  rc;            /* Return code */
  70.           
  71.           rc = DosFindNext(hdirDirHandle,
  72.                      pResultBuf, ulResultBufLen,
  73.                      pSearchCount);
  74.           
  75. 2. Copy the executable "TESTFIND.EXE" to a directory of your choice and run the
  76.    file.
  77.    
  78. 3. Click on "Test" to popup a file find dialog panel.
  79.  
  80. 4. You can navigate your directories by double mouse clicking on the desired
  81.    directory or single clicking on the desired drive.
  82.    
  83. 5. Note that the drives are located in a drop down list from the combo
  84.    control "Drive".
  85.  
  86. 6. The "\" (backslash) in the directory listbox will take you directly
  87.    to the root of the current drive.
  88.    
  89. 7. Selecting either the "Single Step" or "Auto Step" will popup a 
  90.    Step Control dialog panel.
  91.    
  92. 8. In the "Single Step" mode you will press "Step" on the "Step Control" 
  93.    panel to step through each DosFindFirst and DosFindNext API call.  
  94.    The first step in each list box initiates the DosFindFirst call.
  95.    "Cancel" will terminate the step mode and allow the box to load 
  96.    at program speed.
  97.    
  98. 9. In the "Auto Step" mode you can set the automatic step speed in 
  99.    milliseconds with the entry box next to this radio button.
  100.    The "Cancel" button on the "Step Control" panel will terminate 
  101.    this auto stepping mode and allow the list box to load at
  102.    program speed.
  103.       
  104. 10.   "Close" on the "DosFind... Test" dialog panel
  105.       will terminate this test.  "Exit" on the main menu of this
  106.       utility will terminate the application.
  107.       
  108. 11.   Note the return codes from the API calls for loading the 
  109.       Directory and File List boxes "rtn:".
  110.       
  111.       The normal return codes are as follows:
  112.       0 - No Error
  113.       18 - No more files
  114.  
  115.       Other return codes as specified in the IBM documentation
  116.       are as follows:
  117.  
  118.     DosFindFirst returns the following 
  119.     values: 
  120.  
  121.     0         NO_ERROR 
  122.     2         ERROR_FILE_NOT_FOUND 
  123.     3         ERROR_PATH_NOT_FOUND 
  124.     6         ERROR_INVALID_HANDLE 
  125.     18        ERROR_NO_MORE_FILES 
  126.     26        ERROR_NOT_DOS_DISK 
  127.     87        ERROR_INVALID_PARAMETER 
  128.     108       ERROR_DRIVE_LOCKED 
  129.     111       ERROR_BUFFER_OVERFLOW 
  130.     113       ERROR_NO_MORE_SEARCH_HANDLES 
  131.     206       ERROR_FILENAME_EXCED_RANGE 
  132.     208       ERROR_META_EXPANSION_TOO_LONG 
  133.     254       ERROR_INVALID_EA_NAME 
  134.     255       ERROR_EA_LIST_INCONSISTENT 
  135.     275       ERROR_EAS_DIDNT_FIT 
  136.  
  137.  
  138.     DosFindNext returns the following 
  139.     values: 
  140.  
  141.     0         NO_ERROR 
  142.     6         ERROR_INVALID_HANDLE 
  143.     18        ERROR_NO_MORE_FILES 
  144.     26        ERROR_NOT_DOS_DISK 
  145.     87        ERROR_INVALID_PARAMETER 
  146.     111       ERROR_BUFFER_OVERFLOW 
  147.     275       ERROR_EAS_DIDNT_FIT 
  148.  
  149. 12. The attributes for the mask of the directory and file find are
  150.     displayed as a decimal number in the "attr:" entry windows, and can 
  151.     be changed if desired.  You can use SourceCalc (Available with 
  152.     SourceLink or free from OS2AVEN Forum on CompuServe, Library 3)
  153.     to convert hex to decimal in addition to performing boolean 
  154.     operations.
  155.  
  156.       /* known as Dos File Mode bits... */
  157.       #define FILE_NORMAL     0x0000
  158.       #define FILE_READONLY   0x0001
  159.       #define FILE_HIDDEN     0x0002
  160.       #define FILE_SYSTEM     0x0004
  161.       #define FILE_DIRECTORY  0x0010
  162.       #define FILE_ARCHIVED   0x0020
  163.  
  164.       #define MUST_HAVE_READONLY   ( (FILE_READONLY  << 8) | FILE_READONLY  )
  165.       #define MUST_HAVE_HIDDEN     ( (FILE_HIDDEN    << 8) | FILE_HIDDEN    )
  166.       #define MUST_HAVE_SYSTEM     ( (FILE_SYSTEM    << 8) | FILE_SYSTEM    )
  167.       #define MUST_HAVE_DIRECTORY  ( (FILE_DIRECTORY << 8) | FILE_DIRECTORY )
  168.       #define MUST_HAVE_ARCHIVED   ( (FILE_ARCHIVED  << 8) | FILE_ARCHIVED  )
  169.  
  170. 13.   The "cnt:" display indicates the number of items returned
  171.       by the DosFindFirst or DosFindNext call (not the count of items
  172.       in the directory). This value is invalid with a non zero
  173.       return code from the API call.
  174.       
  175. 14.   The "hnd:" field displays a hex representation of the handle
  176.       returned by the DosFindFirst call. Since the call is made with
  177.       HDIR_SYSTEM, the handle will be a system constant, unless the
  178.       return code from the call is an error.
  179.       
  180. 15.   The Checkbox labelled "Try Twice" will cause the DosFindFirst
  181.       call to be repeated in the "File" listbox if the first call
  182.       fails. (Some have said that network failure of the DosFindFirst
  183.       call is due to the first one being swallowed by the system!  Sounds
  184.       a bit strange to me, but this switch will allow you to try a 
  185.       double call if the first one fails.          
  186.  
  187. 16.   The "Product Information" panel under "Help" provides you
  188.       with the phone number for One Up Corporation.  If you
  189.       experience difficulties in accessing files across your
  190.       LAN Network we would like to hear from you.
  191.        
  192. *************************************************************************
  193.  
  194. This testing utility is provided on an "AS IS" basis.  Program bugs may
  195. appear during the operation of this program.  This program is for test
  196. purposes only.  
  197.   
  198. The program specified as "DosFind... Test Utility" is a proprietary product
  199. of One Up Corporation and is protected by copyright law.  One Up Corporation 
  200. retains title to and ownership of the program.  You are licensed to use 
  201. the executable code version of this program.
  202.  
  203. You may not sell, rent, lease, assign or otherwise commercially profit from 
  204. this program.
  205.  
  206. You may not decompile, disassemble or otherwise reverse engineer the program.  
  207. You may not modify the program in any way.
  208.  
  209. One Up Corporation makes no warranties, expressed or implied, for this
  210. program including the implied warranties of merchantability or fitness for 
  211. any purpose.
  212.  
  213. IN NO EVENT SHALL ONE UP BE LIABLE, WHETHER IN CONTRACT OR TORT,
  214. FOR LOST PROFITS, LOST SAVINGS, LOST DATA, LOST OR DAMAGED
  215. PROGRAMS, OR OTHER CONSEQUENTIAL OR INCIDENTAL DAMAGES ARISING
  216. OUT OF THE USE OF THIS PROGRAM. 
  217.  
  218.    (C) Copyright 1993 One Up Corporation.
  219.    
  220.    SourceLink is a trademark of One Up Corporation.  IBM, OS/2, and
  221.    Presentation Manager are registered trademarks of International Business
  222.    Machines Corporation.  Other trademarks and registrations are property
  223.    of their respective corporations.
  224.  
  225. *************************************************************************
  226. *************************************************************************
  227.