home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / catlog / mcat505.lbr / MCAT505.DQC / MCAT505.DOC
Text File  |  1985-12-13  |  22KB  |  447 lines
  1.  
  2.  
  3.              Documentation for MCAT505.MAC
  4.                 Harold F. Bower
  5.                 27 August 1985
  6.  
  7.     - DateStamper is trademarked by Plu*Perfect Systems
  8.     - CP/M is trademarked by Digital Research
  9.  
  10. PURPOSE:
  11.  
  12.    MCAT v 5. provides the capability to create a file containing an alphabeti-
  13. cally sorted list of all programs and files from one or more disks for later
  14. examination.  This 'catalog' may then serve as an index into one's library, and
  15. permit better organization of information on disks.  The catalog (named
  16. MAST.CAT) contains the filename and type of each directory entry on disks, and
  17. optionally; the user area in which the entry is stored, and Date information
  18. provided by Plu*Perfect Systems' DateStamper(tm) system.
  19.  
  20. BACKGROUND:
  21.  
  22.    This program is a logical extension of Irv Hoff's MCAT version 4.5.  Changes
  23. made to produce this version were significant enough to warrant upgrading the
  24. version number.  Among the more important changes are:
  25.  
  26.     - Screen oriented operation following Plu*Perfect System's TERMCAP 
  27.       definition thereby permitting automatic customization to a wide 
  28.       variety of computer systems using SETTERM (provided with 
  29.       DateStamper).
  30.  
  31.     - Incorporation of interfaces to Plu*Perfect Systems' DateStamper(tm) 
  32.       system of Date and Time stamping files.  This feature is NOT required 
  33.       for operation, and automatically disables itself if DateStamper is 
  34.       not installed.
  35.  
  36.     - Protection against inadvertant corruption of MAST.CAT by incorrect
  37.       settings of DATE and USER options.
  38.  
  39.     - Ability to delete entries for specified disk Volume numbers.  (Erase
  40.       disks from library)
  41.  
  42.     - Automatic adjustment of the internal buffer sizes to accomodate disks 
  43.       with different maximum numbers of directory entries.  This avoids the 
  44.       requirement to re-assemble MCAT to accomodate different size systems.
  45.  
  46.     - The ability to create a basic MAST.CAT file from within MCAT, which 
  47.       contains a special header entry defining optional fields in the
  48.       Catalog.  This entry prevents conflicts in option settings for 
  49.       successive passes of MCAT, and cross-reference listings with the
  50.       companion XCAT program.  The !!!TIME&.DAT file which is on all disks
  51.       initialized for use with DateStamper is automatically included in the
  52.       "ignore" file list  and up to 35 additional names may be entered.
  53.  
  54.     - Ability to enter "wildcard" or "ambiguous" file names to the IGNORE
  55.       list in the MAST.CAT.  This permits exclusion of entire catagories
  56.       of files from the catalog.
  57.  
  58.     - The ability to add and/or delete the optional USER and DATE fields 
  59.       from the cataloging operation from within MCAT without reassembly of 
  60.       the program, or having different versions to handle the four possible 
  61.       Master Catalog formats.
  62.  
  63.     - The ability to change assignment of the drive to catalog, as well as
  64.       the drive and user area of the Master Catalog from within MCAT.
  65.  
  66.     - 'Expert' provisions to short-circuit menus for drive selection,
  67.           Catalog location, and option selection when calling the program from
  68.       CP/M.  Passing parameters causes immediate execution of MCAT, and
  69.       return to CP/M upon completion, unless errors are detected.  Errors
  70.       cause a transfer to the menu mode of operation.
  71.  
  72.     - The ability to create a disk "name" on the disk if none exists.  When 
  73.       this situation is detected by MCAT, the user is notified and has the 
  74.       option of aborting the run and returning to the main menu, or 
  75.       entering a name.  This is added to the disk to be cataloged as a null 
  76.       length file preceded by a dash after checking to insure that the name
  77.       does not already exist on the selected MAST.CAT
  78.  
  79.    These features were added in a fashion which provides expanded operational
  80. capabilities while retaining compatibility with existing catalogs.  A compan-
  81. ion program, XCAT has been modified to take advantage of the expanded capabil-
  82. ities provided by Version 5 of MCAT.
  83.  
  84.  
  85. OPERATION:
  86.  
  87.    The basic version of MCAT Version 5 operates in an interactive manner
  88. with the operator by providing printed status and prompt statements on the
  89. user's terminal device.  It should operate satisfactorily on any computer run-
  90. ning CP/M versions 2 or 3.  The optional date field, however, is only accurate
  91. under version 2.2 with Plu*Perfect's DateStamper(tm) system.
  92.  
  93.    Built-in Help is available for MCAT, providing abbreviated information on 
  94. operation and configuration.  If help is selected, the window structure is not 
  95. displayed on the screen, but the information is displayed, one screenful at a 
  96. time.  To obtain the on-line HELP, type:
  97.  
  98.             MCAT ? <cr>
  99.  
  100.    To bring up the basic system in a "windowed" menu-driven mode, type:
  101.  
  102.             MCAT <cr>
  103.  
  104.    A series of messages will appear announcing the program, and informing you 
  105. of the format which will be used in the Master Catalog (what entries will be 
  106. made),what disk drive you are cataloging (drive ID defined in the header of the
  107. program), and what disk and user area is assumed to contain the MAST.CAT file.
  108. A list of available commands preceded with a carat (^) is also shown.  If you 
  109. have installed terminal definitions, and your terminal supports these func-
  110. tions, then the carat and first character of the command are highlighted.  If
  111. you have defined both the disk to be cataloged, and the location of MAST.CAT to
  112. be the same drive, a message will be displayed stating that you will alternate-
  113. ly place the disk to be cataloged and the master catalog in the drive.  The
  114. Master Catalog format assumed at startup (default) can be changed by varying
  115. the two bytes in the beginning of the program for USER and DATE (NO (00H) means
  116. do NOT include, YES (0FFH) means include).
  117.  
  118.    If Plu*Perfect Systems' DateStamper(tm) is not installed, the user is 
  119. prompted to enter the current month and day.  If this is accomplished, a 
  120. default year is assumed, which is stored as one two-digit Binary Coded Decimal 
  121. byte in the header portion of MCAT.  It can be easily changed using DDT or 
  122. other debugging tool without reassembling MCAT.  The current date is then added 
  123. to the pseudo file '+++nnnk.FRE' on the master catalog which shows the number
  124. of free kilobytes on the disk.  By examining this entry in the Master Catalog,
  125. the date of cataloging is known (providing the DATE option is active).
  126.  
  127.    For those who desire to initiate MCAT with different parameters (Drive to 
  128. catalog, Drive and User for the MAST.CAT file, and optional fields), Version 
  129. 5 includes the ability to pass these parameters on the command line.  This
  130. is accomplished by adding one to three additional entries after the "MCAT" 
  131. directive, and they can appear in any order.  These parameters are:
  132.  
  133.     "<" - This symbol indicates that the following character designates
  134.       the disk drive to be cataloged.  The letter can be followed
  135.       by an optional colon for clarity, if desired.
  136.  
  137.     ">" - This symbol indicates that the following parameters designate the
  138.       drive/user area where the desired MAST.CAT file is to be found.
  139.       A letter indicating a drive, a number in the range of 0-31 for the
  140.       desired user area, or both may follow this symbol.
  141.  
  142.     "$" - This symbol is used to specify the format of the MAST.CAT entries.
  143.       When it is detected, both USER and DATE capabilities are turned
  144.       off, and must be explicitly reset.  Follow this symbol with a "D"
  145.       if you want Dates to be included, and "U" if you want user areas to
  146.       be included.  Either one or both characters are accepted.
  147.  
  148.    If any of these parameters are missing from the command line, default para-
  149. meters are assumed.  These defaults can be changed by either re-assembling the
  150. program or changing memory locations as described later under "Customizing with
  151. DDT".  Examples of acceptable entries (with alternatives) are:
  152.  
  153.      MCAT <A >B10 $U    <-- Catalog the 'A' drive, Look for MAST.CAT on drive
  154.      MCAT <A: $U >B10:        'B' in user area 10, Catalog only file names and
  155.                 User areas.
  156.  
  157.      MCAT <C $DU    <-- Catalog the 'C' drive, look for MAST.CAT on the
  158.      MCAT <C $UD        default drive in the default area, Catalog file
  159.      MCAT $DU <C:        names with Dates and User areas
  160.  
  161.      MCAT $        <-- Catalog the default drive, Look for MAST.CAT on the 
  162.                 default drive in the default area, Catalog only 
  163.                 filenames.
  164.  
  165.    Five commands are available at any point where the program asks for confir-
  166. mation that the correct disks are installed.  These commands are:
  167.  
  168.     ^D  (Control-D)  - Define the disk drive to catalog.  A command prompt 
  169.             (beginning with '==>') is issued, and a single 
  170.             character is accepted with no carriage return.  If a
  171.             space, carriage return, or other control character is
  172.             entered, no change is made to the current drive.
  173.  
  174.     ^L  (Control-L)  - Log the drive and user area which contains (or should 
  175.             contain) the MAST.CAT Master Catalog file.  The expec-
  176.             ted response is a letter followed by one or more num-
  177.             bers.  If only a letter is entered, the user ares is
  178.             unchanged.  If only a number is entered, then the 
  179.             currently selected drive is retained, and the user area
  180.             is changed.  The entry is terminated when a non-numeric
  181.             character is detected.  NO EDITING of the entry is
  182.             supported (e.g. backspace).  If the first character
  183.             entered is a space or carriage return, the current
  184.             selection is unchanged.
  185.  
  186.     ^I  (Control-I)  - Initialize a MAST.CAT file on the currently selected 
  187.             disk and user area.  To avoid inadvertant erasure of
  188.             an existing Master catalog, two levels of protection
  189.             are provided;  First, a confirmation prompt is given,
  190.             and secondly, MCAT renames any existing MAST.CAT to
  191.             MAST.BAK.
  192.  
  193.     ^F  (Control-F)  - Change the Format to be used for the MAST.CAT.  Two
  194.             Command prompts (beginning with '==>') are given which
  195.             expect Yes or No (Y/N) responses.  These define whether
  196.             or not to include USER and DATE entries in the Master
  197.             Catalog.
  198.  
  199.     ^R  (Control-R)  - Remove references to a specified disk.  The user is 
  200.             prompted to enter a disk name.  This should match the
  201.             name of a disk (the leading dash is shown in the 
  202.             prompt) to be deleted.  To insure that this is OK, a
  203.             confirmation prompt is issued which expects a 'Y/N'
  204.             response.  All MAST.CAT entries containing this name
  205.             as a disk ID will be removed from the catalog.  Editing
  206.             (backspace) is supported during name entry.
  207.  
  208.     ^Z  (Control-Z)  - The terminal screen is cleared and redrawn.  This is to
  209.             support programs that may be activated from within 
  210.             your system and destroy the screen.
  211.  
  212.    At any point in the program where Yes or No responses are expected, the 
  213. following conventions apply:
  214.  
  215.     NO   -  'N', 'n', Control-C, Control-X.
  216.     YES  -  'Y', 'y', Carriage Return (Control-M), Space, all other
  217.         characters not covered by NO.
  218.  
  219.    To exit MCAT, simply respond with a NO answer to the main command prompt
  220. that asks if the disk to be cataloged is installed in the correct drive.
  221. A warm boot will then be performed back to CP/M
  222.  
  223.  
  224. REQUIREMENTS:
  225.  
  226.    MCAT Version 5 will NOT operate under CP/M Version 1.x.  It fully supports 
  227. cataloging of file names with and without USER areas under CP/M 2.x and 3.  
  228. DATE entries are NOT possible without Plu*Perfect Systems' DateStamper(tm) 
  229. system, only the date of the cataloging operation (on the +++nnnk.FRE pseudo 
  230. file name) will have any meaning.
  231.  
  232.    Release 5.05 of MCAT contains totally re-structured internal buffer formats 
  233. which should permit disk directories of up to 2048 names to be cataloged 
  234. provided that the transient program area is greater than that afforded in a 53K 
  235. standard CP/M system.  If inadequate TPA space is available, a warning will be 
  236. issued, and MCAT will abort.  This may occur if relocatable modules have been 
  237. added which reduce the available TPA space below the minimum required values.  
  238. The only effects of operating with smaller TPA spaces will be increased disk 
  239. activity due to reduced input and output buffer space.
  240.  
  241.    The only requirements to catalog disks (without Dates) are:
  242.      1)  A special directory entry to be used as a disk name.  This entry MUST
  243.      begin with a leading dash (-).  While additional characters can be
  244.      included in the file name portion (before the period), it is recommen-
  245.      ded that only the dash be entered in the name portion.  The file type
  246.      for this pseudo name may then be a numerical field in the range of 0
  247.      to 999 and serve as the 'index' for locating disks.  Additional 
  248.      entries preceded with a dash followed by characters will be sorted
  249.      after the basic disk 'name', and will not be cataloged in the MAST.CAT
  250.      file.  The lack of a disk "name" will be detected by MCAT and flagged.
  251.      The user then has the option of adding a name and resuming the opera-
  252.      tion, or aborting.  If the "name" is added from within MCAT, the 
  253.      3-character ID will be checked against those already cataloged in the 
  254.      logged MAST.CAT and a warning will be issued if duplicates are 
  255.      detected.  To add this file separately under CP/M version 2.x, simply
  256.      enter:
  257.  
  258.         SAVE 0 -.nnn
  259.  
  260.      where nnn is the three-digit disk number.  Under CP/M version 3,
  261.      special techniques must be applied.  See the Documentation file for
  262.      MCAT v4.5 or the Source code for details.
  263.  
  264.      2)  A MAST.CAT must exist in the drive and user area set in MCAT.  This
  265.      catalog differs slightly from previous versions of MCAT, in that a
  266.      special header field must exist as the first entry in the IGNORE list. 
  267.      MAST.CAT files created from within MCAT using the ^I command automati-
  268.      cally contain this header.  To use existing catalogs, the entry must be
  269.      added with your editor.  The rules for making this file are:
  270.        - It must begin with a left curly brace immediately after the 
  271.          opening parenthesis at the beginning of the Ignore list.
  272.        - If user areas are included, a semicolon is added.
  273.        - (For new catalogs..) If dates are to be included, a vertical bar
  274.          (|) is added followed by two digits for the current default year.
  275.          This entry is for future enhancements to reduce the size of 
  276.          MAST.CAT.
  277.        - Right curly braces terminate the header and should be ended with a
  278.          carriage return/line feed combination.
  279.      Examples are:
  280.         ({}    <-- Catalog contains only names
  281.         ({;}    <-- Catalog contains names and user areas
  282.      A typical Ignore list created from within MCAT with users and dates 
  283.      might appear as:
  284.  
  285.         ({;|85}        <-- Catalog has users, dates; year is 1985.
  286.         !!!TIME&.DAT    <-- Ignore the DateStamper file.
  287.         *.BAK        <-- Ignore all .BAK files.
  288.         *.00?        <-- Ignore all files with type beginning as 00. 
  289.         DDT.COM)    <-- Ignore DDT.  Closing parens ends IGNORE 
  290.                     list.
  291.  
  292.    To make the most utility of the Date field, the disk must have the 
  293. !!!TIME&.DAT file added under the DateStamper(tm) system.  A null meaning entry 
  294. is added if Date fields are specified for the Master Catalog and this file is
  295. not present.
  296.  
  297. CUSTOMIZING WITH DDT:
  298.  
  299.    MCAT contains several storage areas in the beginning of the program
  300. that can  be changed to tailor the program for your particular hardware
  301. configuration.  
  302.  
  303.    Configure MCAT V5 for your terminal by using Plu*Perfect Systems'
  304. SETTERM utility, supplied with the DateStamper(tm) system.  Select the
  305. Other option and specify an address of 0100hex for the terminal
  306. definition.  Or use DDT to patch in the terminal data in accordance with
  307. the locations in  the source code.
  308.  
  309.    Default parameters can be easily changed by using Digital Research's DDT 
  310. debugging tool.  The procedure for making changes is:
  311.  
  312.     DDT MCAT.COM
  313.  
  314.     Next   PC
  315.     3100  0100
  316.     -        <=== make necessary changes using Dump and Substitute
  317.     -^C
  318.     SAVE 48 MCAT.COM
  319.  
  320.    Storage locations, other than terminal commands, are:
  321.  
  322.     113H    Number of lines on the display terminal.
  323.     114H    Number of character positions per line on the display.
  324.     193H    Current year stored as a BCD digit (85H for 1985)
  325.     194H    0FFH here means include Dates on file names, 0 means do not.
  326.     195H    0FFH here means include Users on file names, 0 means do not.
  327.     196H    Stores the binary drive designator (0=A, 1=B, 2=C, etc) for the
  328.           default MAST.CAT file.  Enter 0FFH to default to currently 
  329.           logged drive.
  330.     197H    Stores the binary default user area for MAST.CAT (0,1,2..etc).
  331.           Enter 0FFH to default to current logged user area.
  332.     198H    Stores the binary drive designator (see 196H) for the default
  333.           drive TO BE CATALOGED.  (0FFH = currently logged drive)
  334.     199H    Stores the disk general-reset flag.  Set non-zero to force
  335.           resetting all disks, 0 for fast reset (0 = default).
  336.           If your BIOS does not determine disk type when a new disk
  337.           is selected, you may not be able to mix different types of
  338.           disk in a single MCAT run unless this flag is set.
  339.  
  340. ------------------------------ Technical -------------------------------------
  341. MAST.CAT Master Catalog:
  342.  
  343.    To accomodate optional file dating and user areas, the format for MAST.CAT 
  344. entries has been extended.  If only the file name is included, individual 
  345. entries take the form:
  346.  
  347.         FILENAM.TYP,DKNAM.001
  348.                     /    /    \    \
  349.     File name__/    /      \    \___Disk number
  350.                /        \
  351.     File type_____/         \___Disk name without leading dash
  352.                     (recommended to be null entry)
  353.  
  354.     Examples:    DDT.COM,MASTER.215        (With disk name)
  355.              ED.COM,.301        (No disk name)
  356.  
  357.    With only user areas selected, the format adds the user area as a single 
  358. digit or alphabetic character preceded by a semi-colon.  User areas range from 
  359. 0 through 31.  Areas 0-9 are the digits '0'-'9' with areas 10-31 using the 
  360. alphabet ('A'-'V').  Typical entries might be:
  361.  
  362.     DDT.COM,.193;F
  363.     ED.COM,.193;0
  364.     MAST.CAT,.193;6
  365.  
  366.    If both USER and DATE fields are selected, six additional characters are 
  367. added to comprise the date.  The first two are the DAY, the next two are the 
  368. MONTH, and the last two are the YEAR.  The configuration is:
  369.  
  370.         FILENAM.TYP,DKNAM.NUM;UDDMMYY
  371.            /     /    |    |  | \ \ \___Year
  372.     File Name_/     /     |    |  |  \ \________Month
  373.        File Type___/      |    |   \  \____________Day
  374.             Disk Name/     |    \___User Area
  375.                   Disk Number
  376.  
  377.     Examples:  DDT.COM,.193;F270485  (User area 15, 27 Feb 1985)
  378.            ED.COM,.340;0090184   (User area 0, 9 Jan 1984)
  379.  
  380.    If the DATE field is selected, but the USER is not, the semicolon is changed 
  381. to a vertical bar ('|') character to provide proper distinction from the User 
  382. to both human, and automated users of the Master catalog.  Examples of this 
  383. layout are:
  384.  
  385.         DDT.COM,.193|270485
  386.         ED.COM,.340|090184
  387.  
  388. --------------------------------------------------------------------------------
  389.  
  390.             Additional Notes.
  391.  
  392. DateStamper(tm) Interface:
  393.  
  394.    If DateStamper(tm) is installed, the system date is automatically
  395. read and displayed.  If not, the user must supply the current month and
  396. day.  In  addition, when the user has installed MCAT for cursor
  397. addressing, the time is  displayed at a pre-determined location on the
  398. screen, but is only updated if  a real time clock is installed.  The
  399. 'Relative' time at entry is displayed if a  clock is not present.
  400.  
  401. Screen-Oriented Operation:
  402.  
  403.    This is the recommended method of operating MCAT Version 5.  When the 
  404. proper cursor addressing and video attribute codes are added, the screen is 
  405. functionally divided into a series of 'windows' which display specific 
  406. information.  MCAT can operate on systems displaying somewhat less than 80 
  407. characters per line, but overwrite may occur with consequent disruption of the 
  408. screen if less than 72 characters are available.
  409.    Six lines (rows) are required to establish the basic 'windows'.  Operation 
  410. on an 8-line terminal such as the small LCD displays sometimes used in 
  411. portables is possible, although the instructions will quickly jump off the 
  412. screen.  A typical screen layout might appear as:
  413.  
  414.  - - - - - - - - - - - - - - - - Top of Screen - - - - - - - - - - - - - - - -
  415. MCAT Catalog Pgm v 5.01 - for - DateStamper                        30 Jun 1985
  416. ^Drive Change   ^Log MAST.CAT  ^Initialize      ^Format (DU)   ^Remove Vol.
  417. -------------------------------------------------------------------10:28------
  418. Catalog Drive   : B                   |  Format ==>  FN.FT  /User  -Date
  419. MAST.CAT on D/U : C16                 |
  420. ------------------------------------------------------------------------------
  421. For Help, reboot then type : MCAT ?
  422.  
  423. A scratch disk must remain in Drive A:
  424.  
  425. Catalog Drive B:  (NO = Exit)  Ready (Y/N) : _
  426.  
  427.  
  428.  
  429. - - - - - - - - - - - - - - - Bottom of Screen - - - - - - - - - - - - - - - -
  430.  
  431.   In operation, the main 'window' smoothly "paints" down the screen and wraps 
  432. around to avoid problems in scrolling experienced by many types of terminals.
  433.  
  434.   Enjoy using Version 5 of MCAT!  Any comments or suggestions on improving
  435. this  program would be appreciated.  If you make any improvements or
  436. enhancements to  this program, please coordinate them with me before  you
  437. release them to the public.  In that manner some semblance of order might  be
  438. maintained in the development of MCAT.  Thank you.
  439.  
  440.                     Harold F. Bower
  441.                     Box 946
  442.                     APO  NY  09128
  443.  
  444. er might  be
  445. maintained in the development of MCAT.  Thank you.
  446.  
  447.