home *** CD-ROM | disk | FTP | other *** search
/ Hall of Fame / HallofFameCDROM.cdr / australi / joc009.lzh / JOCX.DOC < prev    next >
Text File  |  1990-12-07  |  10KB  |  218 lines
  1. JOCx.DOC   =   John Orlay's Cataloger   v.0.9-beta               DOCUMENTATION
  2. --------       ----------------------                            -------------
  3.  
  4. SYNOPSIS
  5. ~~~~~~~~
  6. JOCx.BAT  is meant to assist reasonably experienced  PC-user-programmers,  who 
  7. keep and maintain a large collection of files.
  8.  
  9. JOCx.BAT catalogs all files present in all directories of a nominated drive.
  10. It  ignores  "hidden" and/or "system" files;  to include such files  you  must 
  11. change their "attribute"-byte.
  12.  
  13. The "x" in JOCx.BAT stands for "F" (floppy) and "H" (=hard) respectively.
  14.            JOCF.BAT catalogs floppies.
  15.            JOCH.BAT catalogs hard-drives or flopppies
  16. The topic of when to use which, and why is explained under SYNTAX.
  17.  
  18. With prompted user-responses JOCx.BAT eventually creates an ascii file DC.DAT.
  19.  
  20.      The resulting DC.DAT consists of a sequence of one-line-records.
  21.      Each line of  DC.DAT has the following left adjusted fields :
  22.  
  23.           cols  1 -  8  Filename
  24.           cols  9 - 12  Extension   (.ext)
  25.           cols 13 - 19  Filesize    (number of bytes)
  26.           cols 20 - 28  CRC32 value (blank + 4 hex bytes)
  27.           cols 29 - 35  Filedate    (blank + yymmdd)
  28.           cols 36 - 47  Volumename  (blank + up to 11 chars)
  29.           cols 48 -     Path        (blank + full path)
  30.  
  31.      Thus, each one-line record in DC.DAT contains  file-specific  "what" and
  32.      "where" data, including the calculated CRC32 value.
  33.  
  34. With the above structure, I can foresee a variety of further uses for DC.DAT :
  35.  
  36. -    With  an ascii editor one could insert comments, up to 30 chars  in  any 
  37.      line.   Comment-insertion  could,  for instance, start at  col  49  thus 
  38.      pushing  the infrequently needed Path-information further to the  right.
  39.  
  40. -    One  could concatenate a sequence of DC.DAT-s (as created by JOC.BAT  or 
  41.      with inserted comments)  to build a master-catalog which can be searched 
  42.      for user specified strings.
  43.   
  44. -    DC.DAT,  even if not used for building a master-catalog, but just  as  a 
  45.      temporary file,  printed out for a loose-leaf binder,  can be useful  as 
  46.      reference, against which one can compare sets of files of similar  names 
  47.      but possibly of different vintage or source or patching.
  48.      This specific need was my original motive  for developing JOCx  so as to 
  49.      include  CRC-values with an otherwise fairly conventional set  of  file-
  50.      statistics.
  51.  
  52.  
  53.  
  54. JOCx, in this raw beta-test version is hereby placed in the public domain, in
  55. good faith   - without any warranties or obligations  -  hoping for written  
  56. comments, addressed  to  John Orlay,  C/- PC Users Group Ltd   PO BOX E162
  57.                                       St James  Sydney  NSW  2000  Australia.
  58.  
  59.  
  60. REQUIREMENTS
  61. ~~~~~~~~~~~~
  62. I developed JOCx on an XT-compatible, booted from hard-disk C: under DOS 3.21.
  63. I presume it will run on 286 or 386 machines as well under later DOS versions.
  64.  
  65. I keep the standard DOS utilities in a directory named on my PATH declaration.
  66. I keep other relevant program-files (listed in this .DOC) in a directory named 
  67. \JOC  which is NOT in the PATH, so as to avoid the risk of filename clashes.
  68.  
  69.  
  70. SYNTAX
  71. ~~~~~~
  72. Regardless  of whether you intend to run JOCF.BAT or JOCH.BAT, you must be  in 
  73. the directory e.g. C:\JOC  which contains all JOC related program files.
  74.  
  75. - When cataloging a floppy - (without using a RAMdrive for the process) :
  76.   ~~~~~~~~~~~~~~~~~~~~~~~~
  77. The command line syntax at the DOS prompt is : JOCF dr:
  78. For example the command JOCF A:   will catalog the floppy ex drive A:
  79.  
  80. - When cataloging a hard-drive or a floppy (processing on a RAMdrive) :
  81.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  82. The command line syntax at the DOS prompt is : JOCH dr:
  83. For example the command JOCH C:   will catalog files ex drive C:
  84.  
  85. JOCH.BAT carries out the cataloging process on a temporary RAMdrive. 
  86.  
  87. There are two subtle but serious reasons for this approach :
  88.  
  89. -    it  would  be  absurd  to carry out the  cataloging  process  (with  the 
  90.      creation of DC.DAT) on the very drive to be cataloged;
  91.  
  92. -    one  of  the intermediate processes in JOCx.BAT  (:TREE)  would  produce 
  93.      garbage, unless it first looked at the root-directory of the drive to be 
  94.      cataloged.
  95.  
  96. JOCH.BAT  avoids  these predicaments and speeds up the  otherwise  agonisingly 
  97. slow calculations of CRC values.
  98.  
  99. There is, however a catch.
  100.  
  101. JOCH.BAT  as coded,  assumes
  102. - that all pertinent program files are in C:\JOC
  103. - that you are in C:\JOC
  104. - that you do not already have a  RAMdrive
  105. - that the RAMdrive to be created by JOCH can have the drivename D: .
  106. If any one of these assumptions is wrong, then YOU will need to modify the
  107. coding of JOCH.BAT  and M-FLDATH.BAT .
  108.  
  109. The minimum necessary size of the RAMdrive itself is about 30k per 100 files.
  110. Thus a 360k RAMdrive  (created by the SETRAM D 360 line in JOCH)  is fine for
  111. cataloging a drive with up to 1000 files. 
  112.  
  113. Whatever you do, you must preserve about 120k free RAM for loading and running 
  114. JOCH.BAT and the related overlayed programs.
  115.  
  116. I would expect no difficulty if your system has 640k RAM and you do not  stuff 
  117. it up with memory-hungry TSR-s and shells.
  118.  
  119. PACKAGING LIST
  120. ~~~~~~~~~~~~~~
  121. JOC009.LZH (the name of the release package created Yoshii's LHARC) contains :
  122.  
  123. ANSWER   COM Defines user response as the value of env.variable %ANSWER% 
  124. ANSWER   DOC (called by JOCF.BAT and by JOCH.BAT)
  125.  
  126. CHANGE   COM Modifies specified strings in a specified file
  127. CHANGE   DOC (called by JOCF.BAT, JOCH.BAT, M-FLDAT.BAT, M-FLDATH.BAT)
  128.  
  129. CRC32    EXE Reports CRC32 values as per ANSI X3.66
  130.              (called by C.BAT, CH.BAT which are generated by M-CBAT.BAS or
  131.               M-CHBAT.BAS respectively)
  132.  
  133. DC       BAS Generates DC.DAT from FL.DAT and CRCLOG.DAT
  134.              (called by M-FLDAT.BAT, M-FLDATH.BAT)
  135.  
  136. JOCF     BAT Main program for cataloging floppies only 
  137. JOCH     BAT Main program for cataloging any drive
  138.  
  139. JOCX     DOC ===== this file, you are looking at it now =====
  140.  
  141. M-CBAT   BAS Makes C.BAT  (called by JOCF.BAT) 
  142. M-CHBAT  BAS Makes CH.BAT (called by JOCH.BAT)
  143.  
  144. M-FLDAT  BAT Makes DC.DAT (called by C.BAT)
  145. M-FLDATH BAT Makes DC.DAT (called by CH.BAT
  146.  
  147. TIDYF    BAT Performs housekeeping chores (called by M-FLDAT.BAT)
  148. TIDYH    BAT Performs housekeeping chores (called by M-FLDATH.BAT)
  149.  
  150.  
  151. Installation Notes :
  152.  
  153. 1.   All *.DOC files are plain ascii  (with form-feeds, but no left margin) .
  154.      They are meant to be printed, read, understood and then stored off-line.
  155.      To print them, set your printer to 3/4 inch margin, 12cpi, 6lpi,
  156.      then use the command  COPY filename.DOC PRN .
  157.  
  158. 2.   I  assume you have an on-path directory for general  purpose  utilities. 
  159.      Copy ANSWER.COM, CHANGE.COM, CRC32.EXE  to that directory .
  160.  
  161. 3.   All *.BAT and *.BAS files should be copied to \JOC i.e. to the directory 
  162.      from which you will start JOCx and to which the eventual DC.DAT will go.
  163.  
  164. 4.   The standard MSDOS utilities, including GWBASIC.EXE must be on-path.
  165.  
  166.  
  167. PROGRAMMING NOTES
  168. ~~~~~~~~~~~~~~~~~
  169. These notes are included : -
  170.  
  171. -    For myself, as a reminder in any further development.
  172. -    For those users who like to understand what goes on.
  173. -    For  those whose machine-configuration or boot-up configuration  clashes 
  174.      with  the assumptions, and installation requirements stated  earlier  in 
  175.      this documentation.
  176.  
  177. All  others  can skip this section.  
  178.  
  179. JOCF.BAT and JOCH.BAT and the chain of programs invoked by these should enable 
  180. you  to start and run, without bothering about the following  points  :
  181.  
  182.  
  183. 1.   The overall flow should be evident from reading a printout of the  chain 
  184.      of *.BAT and *.BAS files .  All these files contain internal comments.
  185.  
  186. 2.   I  avoided CALL commands, partly to allow the use of MSDOS 3.2  and  up, 
  187.      and partly to minimize demands on RAM capacity.  This why I chained  the 
  188.      sequence of .BAT-s, instead of using them as subroutines.
  189.  
  190. 3.   In this beta version I did not compile the .BAS files; they are  invoked 
  191.      as a parameter of GWBASIC.  There are two reasons for this.  One is that 
  192.      at  this  stage the further modifications can be more readily  made  and 
  193.      tested  in a pedesrian way.  The other reason (based on trials) is  that 
  194.      the increase in the size of the compiled .EXE files is not justified  by 
  195.      any appreciable increase in overall speed.  The slow step in the overall 
  196.      process  is  not in GWBASIC, but in the calculation of CRC  values,  for 
  197.      each and every file to be cataloged. 
  198.  
  199. 4.   You  may  find  M-CBAT.BAS  and M-CHBAT.BAS  a  little  unusual.   Their 
  200.      function  is  to make the very .BAT file which is then  executed.   This 
  201.      approach, however, is the crucial solution to the problem of how to cope 
  202.      with  the  task of specifying each and every directory  present  on  the 
  203.      drive to be cataloged, when - at the outset - one does not have any idea 
  204.      about  the specific directory-structure.  Messy as it seems, these  .BAS 
  205.      files create a sequence of commands, customized to suit whatever happens 
  206.      to be at that time on the drive to be cataloged.
  207.  
  208. 5.   The overall process (as it stands) ends with the creation of DC.DAT .
  209.      Further processing of DC.DAT, as envisaged in the previous SYNOPSIS,  is 
  210.      yet to be developed into a tail-end, menu-driven, add-on program.
  211.      In  the  mean  time, through standard DOS commands, one  can  of  course 
  212.      concatenate  DC.DAT  into a master-catalog and do  searches,  sorts,  or 
  213.      produce reports.  I will probably undertake this further development, at 
  214.      least  for  my  own use.  Whether I will then publish it  or  not  would 
  215.      greatly  depend on the public response to this beta version, and to  the 
  216.      implicit  principle that a file-catalog should in each line contain  all 
  217.      file-specific "what" and "where" clues together with a 4-byte CRC value.
  218.