home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 184_01 / yanc10.doc < prev    next >
Encoding:
Text File  |  1979-12-31  |  7.9 KB  |  183 lines
  1.     YANC Version 1.0 -- Yet Another New Catalog program
  2.  
  3.     Copyright (c) 1982 by Ken Presser
  4.         permission is hereby granted for the
  5.         free use of this program in any non-
  6.         commercial manner.  Specifically
  7.         prohibited is any resale for profit
  8.         of this program in any form.
  9.  
  10. This program is based on several programs originally written by
  11. Ward Christensen and expanded upon by Lewis Moseley, Jr.  The
  12. program has been completely rewritten in C.  It is menu driven
  13. and incorporates all of the update and reporting functions in one
  14. program.  It is compatible with the original file structure of
  15. MAST.CAT but will modify the format to incorporate the user number
  16. and the file size.  It may therefore not be downward compatible
  17. with the existing catalog system programs.
  18.  
  19. The program consists of 2 modules:
  20.     YANC10.C    - The program source file
  21.     H19.L        - A source library of routines specific
  22.               to the Heath/Zenith H19 terminal.
  23. The dialect of C used is CW/C from The Code Works.  I will cover
  24. specifics of any special features used in a later section.  It
  25. should not be any trouble to modify this program to use other
  26. dialects or other terminals.
  27.  
  28. Instructions for use:
  29.  
  30. The system will display a menu of possible choices which is fairly
  31. self-explanatory however I will briefly cover them here.
  32.  
  33. Update the master catalog with the above defaults:
  34.     This will take the volume on the Add-disk drive and
  35.     read its directory and update the file MAST.CAT on
  36.     the Master-disk drive.
  37.  
  38. List the entire master catalog:
  39.     This will list the entire file MAST.CAT to the
  40.     terminal and optionally, the printer.  It uses a
  41.     two-up format.
  42.    n:xxxxxxxx.yyy  vvvvvvv.vvv  mmmK | n:xxxxxxxx.yyy  vvvvvvv.vvv mmmK
  43.     where    n is the user number
  44.         xxxxxxxx.yyy is the file name
  45.         vvvvvvv.vvv is the volume name
  46.         mmmK is the file size
  47.  
  48. List specific files with a match key:
  49.     This will list files in the above format that match a
  50.     key which may contain wild card characters.  Valid
  51.     wild cards are * to match a whole file name or
  52.     extension and ? to match a single character.
  53.  
  54. List a volume from the master catalog:
  55.     This will list files in the above format where the
  56.     volume name matches a key.  The key may contain
  57.     wild cards as above.
  58.  
  59. List the disk directory:
  60.     This will list the directory of the disk mounted
  61.     on the Add-disk drive.  The format is three-up and
  62.     similar to the above with the volume name missing.
  63.     The file name is listed as Dn:xxxxxxxx.yyy, where
  64.     D is the drive identifier, n is the user number and
  65.     xxxxxxxx.yyy is the file name with extension.  This
  66.     function also reports the space used and available
  67.     on the disk.  The listing is in alphabetical order.
  68.  
  69. Initialize the Master Catalog:
  70.     This function will ask for verification and then
  71.     will initialize the file MAST.CAT for you.  It asks
  72.     for the Exclude-files.  Those files which you do
  73.     not want included in the master catalog such as PIP
  74.     and STAT, etc.  As in the original programs, there
  75.     must be at least one Exclude-file.  If you want
  76.     everything to be in the catalog, you must enter a
  77.     dummy Exclude-file (I use DUMMY.XZX.)  Do not use
  78.     this function if you already have a MAST.CAT set up.
  79.  
  80. Update the defaults:
  81.     When the system first comes up it has the following
  82.     defaults.  The Master-drive is 'A', the Add-drive is
  83.     'B' and the printer is 'off'.  Any of these can be
  84.     changed with this function.  The Master-drive is the
  85.     drive containing the file MAST.CAT.  The Add-drive is
  86.     the drive on which the disk to be cataloged resides.
  87.     If the printer is 'on', then all reporting functions
  88.     will direct their displays to the printer as well as
  89.     the terminal.  Note: The Master-drive may be equal
  90.     to the Add-drive for a single-drive system.
  91.  
  92. Make a directory volume label:
  93.     Every disk to be cataloged must have a directory
  94.     volume label.  This is simply a (possibly null)
  95.     directory entry where the file name starts with
  96.     a '-'.  If you forgot to create this file before
  97.     you entered this program, this function will allow
  98.     you to create a null file with the volume name on
  99.     the Add-drive.
  100.  
  101. Quit this program:
  102.     Exit the program and do CP/M warm boot.
  103.  
  104. ----------------------------------------------------------
  105.  
  106. Internals:
  107.  
  108. This program is written to make use of the H/Z19 terminal.
  109. Specifically it uses the cursor addressing feature and the reverse
  110. video to indicate the current selection.  It also uses the read-
  111. cursor location function.  It maps the up-arrow, down-arrow and the
  112. home keys to their escape code + 128.  It should not be any problem
  113. to recode the functions used in the include-file H19.L if your
  114. terminal supports these features.  If not, the use of the terminal
  115. special features is limited to the function menu().  This routine
  116. may be recoded to simply ask for a number indicating the users
  117. choice.  The function simply returns a number from 1 to 9 to indicate
  118. the choice made.
  119.  
  120. CW/C supports a facility known as source libraries.  File H19.L is an
  121. example of such a library.  Basically the compiler keeps track of the
  122. need to include specific functions based on whether or not they have
  123. been referenced.  The directive 
  124. #ifneed name
  125. is used to selectively include the code between the #ifneed and #endif.
  126. If this facility is not available in your dialect of C simply remove
  127. the #ifneed, #endif pairs.  This will cause all of the routines to be
  128. included in the resulting com file.
  129.  
  130. I tried to avoid using any CW/C specific functions.  The following is
  131. a brief description of any non-standard functions that I am aware of:
  132.  
  133. cpm(bc,de)
  134.     This function takes as arguments the bc register pair and
  135.     the de register pair and returns the value in the A register.
  136.     In one instance I had to code the assembly routine hcpm(bc,de)
  137.     which is identical but returns the value of the hl register
  138.     pair.  CW/C prefixes its function names with a Q, thus the
  139.     label QHCPM in the assembly routine.
  140. chupper(c)
  141.     This is similar to the original toupper(c) function, with the
  142.     addition that it makes a range check.  It can be coded as
  143.     if (c >= 'a' && c <= 'z') return toupper(c);
  144. free(mark)
  145.     This function releases memory from 'mark' which is a pointer
  146.     variable back to the available memory pool.
  147. malloc(size)
  148.     This function gets memory from the available memory pool.  It
  149.     returns the address of a chunk of memory of 'size' bytes.
  150. setbuf(file,buffer)
  151.     This function tells the I/O routines to use 'buffer' as the
  152.     buffer for 'file'.  See setbsize().
  153. setbsize(file,size)
  154.     This function tells the I/O routines that the user supplied
  155.     buffer is 'size' bytes long.
  156. strcat(s1,s2)
  157.     This function copies s2 onto the end of s1.
  158. strcmp(s1,s2)
  159.     This function compares strings s1 and s2 and returns 0 if
  160.     they are equal, a negative number if s1<s2 and positive if
  161.     s1>s2.
  162. strlen(s)
  163.     This function returns the length of string s.
  164. strmov(dest,src)
  165.     This function move string 'src' to 'dest'.
  166.  
  167. That about covers it.  Good luck converting and/or using this
  168. program.  One reason for writing this was to make it easier to
  169. modify by virtue of it being in a higher-level language.  Some
  170. of the custom touches that have been incorporated into it are
  171. things like the indented format for the printer listings that
  172. facilitate my 8 1/2 by 11 paper which I like to 3-hole punch and
  173. store in 3-ring binders.  Also the function to add the volume
  174. label file when I forget to put the blessed thing on the disk and
  175. attempt an update only to get an error message instead.  Feel
  176. free to add your own custom touches.  I would be interested in
  177. any bugs or conversion problems you may find.  Or if I can be of
  178. any help please contact me on the cpmig bulletin board on Compuserve
  179. Information Services.  I try to sign on at least once a week to
  180. look around.
  181.                     Ken Presser
  182. bulletin board on Compuserve
  183. Information Services.  I try to s