Documentation for MCAT505.MAC Harold F. Bower 27 August 1985 - DateStamper is trademarked by Plu*Perfect Systems - CP/M is trademarked by Digital Research PURPOSE: MCAT v 5. provides the capability to create a file containing an alphabeti- cally sorted list of all programs and files from one or more disks for later examination. This 'catalog' may then serve as an index into one's library, and permit better organization of information on disks. The catalog (named MAST.CAT) contains the filename and type of each directory entry on disks, and optionally; the user area in which the entry is stored, and Date information provided by Plu*Perfect Systems' DateStamper(tm) system. BACKGROUND: This program is a logical extension of Irv Hoff's MCAT version 4.5. Changes made to produce this version were significant enough to warrant upgrading the version number. Among the more important changes are: - Screen oriented operation following Plu*Perfect System's TERMCAP definition thereby permitting automatic customization to a wide variety of computer systems using SETTERM (provided with DateStamper). - Incorporation of interfaces to Plu*Perfect Systems' DateStamper(tm) system of Date and Time stamping files. This feature is NOT required for operation, and automatically disables itself if DateStamper is not installed. - Protection against inadvertant corruption of MAST.CAT by incorrect settings of DATE and USER options. - Ability to delete entries for specified disk Volume numbers. (Erase disks from library) - Automatic adjustment of the internal buffer sizes to accomodate disks with different maximum numbers of directory entries. This avoids the requirement to re-assemble MCAT to accomodate different size systems. - The ability to create a basic MAST.CAT file from within MCAT, which contains a special header entry defining optional fields in the Catalog. This entry prevents conflicts in option settings for successive passes of MCAT, and cross-reference listings with the companion XCAT program. The !!!TIME&.DAT file which is on all disks initialized for use with DateStamper is automatically included in the "ignore" file list and up to 35 additional names may be entered. - Ability to enter "wildcard" or "ambiguous" file names to the IGNORE list in the MAST.CAT. This permits exclusion of entire catagories of files from the catalog. - The ability to add and/or delete the optional USER and DATE fields from the cataloging operation from within MCAT without reassembly of the program, or having different versions to handle the four possible Master Catalog formats. - The ability to change assignment of the drive to catalog, as well as the drive and user area of the Master Catalog from within MCAT. - 'Expert' provisions to short-circuit menus for drive selection, Catalog location, and option selection when calling the program from CP/M. Passing parameters causes immediate execution of MCAT, and return to CP/M upon completion, unless errors are detected. Errors cause a transfer to the menu mode of operation. - The ability to create a disk "name" on the disk if none exists. When this situation is detected by MCAT, the user is notified and has the option of aborting the run and returning to the main menu, or entering a name. This is added to the disk to be cataloged as a null length file preceded by a dash after checking to insure that the name does not already exist on the selected MAST.CAT These features were added in a fashion which provides expanded operational capabilities while retaining compatibility with existing catalogs. A compan- ion program, XCAT has been modified to take advantage of the expanded capabil- ities provided by Version 5 of MCAT. OPERATION: The basic version of MCAT Version 5 operates in an interactive manner with the operator by providing printed status and prompt statements on the user's terminal device. It should operate satisfactorily on any computer run- ning CP/M versions 2 or 3. The optional date field, however, is only accurate under version 2.2 with Plu*Perfect's DateStamper(tm) system. Built-in Help is available for MCAT, providing abbreviated information on operation and configuration. If help is selected, the window structure is not displayed on the screen, but the information is displayed, one screenful at a time. To obtain the on-line HELP, type: MCAT ? To bring up the basic system in a "windowed" menu-driven mode, type: MCAT A series of messages will appear announcing the program, and informing you of the format which will be used in the Master Catalog (what entries will be made),what disk drive you are cataloging (drive ID defined in the header of the program), and what disk and user area is assumed to contain the MAST.CAT file. A list of available commands preceded with a carat (^) is also shown. If you have installed terminal definitions, and your terminal supports these func- tions, then the carat and first character of the command are highlighted. If you have defined both the disk to be cataloged, and the location of MAST.CAT to be the same drive, a message will be displayed stating that you will alternate- ly place the disk to be cataloged and the master catalog in the drive. The Master Catalog format assumed at startup (default) can be changed by varying the two bytes in the beginning of the program for USER and DATE (NO (00H) means do NOT include, YES (0FFH) means include). If Plu*Perfect Systems' DateStamper(tm) is not installed, the user is prompted to enter the current month and day. If this is accomplished, a default year is assumed, which is stored as one two-digit Binary Coded Decimal byte in the header portion of MCAT. It can be easily changed using DDT or other debugging tool without reassembling MCAT. The current date is then added to the pseudo file '+++nnnk.FRE' on the master catalog which shows the number of free kilobytes on the disk. By examining this entry in the Master Catalog, the date of cataloging is known (providing the DATE option is active). For those who desire to initiate MCAT with different parameters (Drive to catalog, Drive and User for the MAST.CAT file, and optional fields), Version 5 includes the ability to pass these parameters on the command line. This is accomplished by adding one to three additional entries after the "MCAT" directive, and they can appear in any order. These parameters are: "<" - This symbol indicates that the following character designates the disk drive to be cataloged. The letter can be followed by an optional colon for clarity, if desired. ">" - This symbol indicates that the following parameters designate the drive/user area where the desired MAST.CAT file is to be found. A letter indicating a drive, a number in the range of 0-31 for the desired user area, or both may follow this symbol. "$" - This symbol is used to specify the format of the MAST.CAT entries. When it is detected, both USER and DATE capabilities are turned off, and must be explicitly reset. Follow this symbol with a "D" if you want Dates to be included, and "U" if you want user areas to be included. Either one or both characters are accepted. If any of these parameters are missing from the command line, default para- meters are assumed. These defaults can be changed by either re-assembling the program or changing memory locations as described later under "Customizing with DDT". Examples of acceptable entries (with alternatives) are: MCAT B10 $U <-- Catalog the 'A' drive, Look for MAST.CAT on drive MCAT B10: 'B' in user area 10, Catalog only file names and User areas. MCAT ') is issued, and a single character is accepted with no carriage return. If a space, carriage return, or other control character is entered, no change is made to the current drive. ^L (Control-L) - Log the drive and user area which contains (or should contain) the MAST.CAT Master Catalog file. The expec- ted response is a letter followed by one or more num- bers. If only a letter is entered, the user ares is unchanged. If only a number is entered, then the currently selected drive is retained, and the user area is changed. The entry is terminated when a non-numeric character is detected. NO EDITING of the entry is supported (e.g. backspace). If the first character entered is a space or carriage return, the current selection is unchanged. ^I (Control-I) - Initialize a MAST.CAT file on the currently selected disk and user area. To avoid inadvertant erasure of an existing Master catalog, two levels of protection are provided; First, a confirmation prompt is given, and secondly, MCAT renames any existing MAST.CAT to MAST.BAK. ^F (Control-F) - Change the Format to be used for the MAST.CAT. Two Command prompts (beginning with '==>') are given which expect Yes or No (Y/N) responses. These define whether or not to include USER and DATE entries in the Master Catalog. ^R (Control-R) - Remove references to a specified disk. The user is prompted to enter a disk name. This should match the name of a disk (the leading dash is shown in the prompt) to be deleted. To insure that this is OK, a confirmation prompt is issued which expects a 'Y/N' response. All MAST.CAT entries containing this name as a disk ID will be removed from the catalog. Editing (backspace) is supported during name entry. ^Z (Control-Z) - The terminal screen is cleared and redrawn. This is to support programs that may be activated from within your system and destroy the screen. At any point in the program where Yes or No responses are expected, the following conventions apply: NO - 'N', 'n', Control-C, Control-X. YES - 'Y', 'y', Carriage Return (Control-M), Space, all other characters not covered by NO. To exit MCAT, simply respond with a NO answer to the main command prompt that asks if the disk to be cataloged is installed in the correct drive. A warm boot will then be performed back to CP/M REQUIREMENTS: MCAT Version 5 will NOT operate under CP/M Version 1.x. It fully supports cataloging of file names with and without USER areas under CP/M 2.x and 3. DATE entries are NOT possible without Plu*Perfect Systems' DateStamper(tm) system, only the date of the cataloging operation (on the +++nnnk.FRE pseudo file name) will have any meaning. Release 5.05 of MCAT contains totally re-structured internal buffer formats which should permit disk directories of up to 2048 names to be cataloged provided that the transient program area is greater than that afforded in a 53K standard CP/M system. If inadequate TPA space is available, a warning will be issued, and MCAT will abort. This may occur if relocatable modules have been added which reduce the available TPA space below the minimum required values. The only effects of operating with smaller TPA spaces will be increased disk activity due to reduced input and output buffer space. The only requirements to catalog disks (without Dates) are: 1) A special directory entry to be used as a disk name. This entry MUST begin with a leading dash (-). While additional characters can be included in the file name portion (before the period), it is recommen- ded that only the dash be entered in the name portion. The file type for this pseudo name may then be a numerical field in the range of 0 to 999 and serve as the 'index' for locating disks. Additional entries preceded with a dash followed by characters will be sorted after the basic disk 'name', and will not be cataloged in the MAST.CAT file. The lack of a disk "name" will be detected by MCAT and flagged. The user then has the option of adding a name and resuming the opera- tion, or aborting. If the "name" is added from within MCAT, the 3-character ID will be checked against those already cataloged in the logged MAST.CAT and a warning will be issued if duplicates are detected. To add this file separately under CP/M version 2.x, simply enter: SAVE 0 -.nnn where nnn is the three-digit disk number. Under CP/M version 3, special techniques must be applied. See the Documentation file for MCAT v4.5 or the Source code for details. 2) A MAST.CAT must exist in the drive and user area set in MCAT. This catalog differs slightly from previous versions of MCAT, in that a special header field must exist as the first entry in the IGNORE list. MAST.CAT files created from within MCAT using the ^I command automati- cally contain this header. To use existing catalogs, the entry must be added with your editor. The rules for making this file are: - It must begin with a left curly brace immediately after the opening parenthesis at the beginning of the Ignore list. - If user areas are included, a semicolon is added. - (For new catalogs..) If dates are to be included, a vertical bar (|) is added followed by two digits for the current default year. This entry is for future enhancements to reduce the size of MAST.CAT. - Right curly braces terminate the header and should be ended with a carriage return/line feed combination. Examples are: ({} <-- Catalog contains only names ({;} <-- Catalog contains names and user areas A typical Ignore list created from within MCAT with users and dates might appear as: ({;|85} <-- Catalog has users, dates; year is 1985. !!!TIME&.DAT <-- Ignore the DateStamper file. *.BAK <-- Ignore all .BAK files. *.00? <-- Ignore all files with type beginning as 00. DDT.COM) <-- Ignore DDT. Closing parens ends IGNORE list. To make the most utility of the Date field, the disk must have the !!!TIME&.DAT file added under the DateStamper(tm) system. A null meaning entry is added if Date fields are specified for the Master Catalog and this file is not present. CUSTOMIZING WITH DDT: MCAT contains several storage areas in the beginning of the program that can be changed to tailor the program for your particular hardware configuration. Configure MCAT V5 for your terminal by using Plu*Perfect Systems' SETTERM utility, supplied with the DateStamper(tm) system. Select the Other option and specify an address of 0100hex for the terminal definition. Or use DDT to patch in the terminal data in accordance with the locations in the source code. Default parameters can be easily changed by using Digital Research's DDT debugging tool. The procedure for making changes is: DDT MCAT.COM Next PC 3100 0100 - <=== make necessary changes using Dump and Substitute -^C SAVE 48 MCAT.COM Storage locations, other than terminal commands, are: 113H Number of lines on the display terminal. 114H Number of character positions per line on the display. 193H Current year stored as a BCD digit (85H for 1985) 194H 0FFH here means include Dates on file names, 0 means do not. 195H 0FFH here means include Users on file names, 0 means do not. 196H Stores the binary drive designator (0=A, 1=B, 2=C, etc) for the default MAST.CAT file. Enter 0FFH to default to currently logged drive. 197H Stores the binary default user area for MAST.CAT (0,1,2..etc). Enter 0FFH to default to current logged user area. 198H Stores the binary drive designator (see 196H) for the default drive TO BE CATALOGED. (0FFH = currently logged drive) 199H Stores the disk general-reset flag. Set non-zero to force resetting all disks, 0 for fast reset (0 = default). If your BIOS does not determine disk type when a new disk is selected, you may not be able to mix different types of disk in a single MCAT run unless this flag is set. ------------------------------ Technical ------------------------------------- MAST.CAT Master Catalog: To accomodate optional file dating and user areas, the format for MAST.CAT entries has been extended. If only the file name is included, individual entries take the form: FILENAM.TYP,DKNAM.001 / / \ \ File name__/ / \ \___Disk number / \ File type_____/ \___Disk name without leading dash (recommended to be null entry) Examples: DDT.COM,MASTER.215 (With disk name) ED.COM,.301 (No disk name) With only user areas selected, the format adds the user area as a single digit or alphabetic character preceded by a semi-colon. User areas range from 0 through 31. Areas 0-9 are the digits '0'-'9' with areas 10-31 using the alphabet ('A'-'V'). Typical entries might be: DDT.COM,.193;F ED.COM,.193;0 MAST.CAT,.193;6 If both USER and DATE fields are selected, six additional characters are added to comprise the date. The first two are the DAY, the next two are the MONTH, and the last two are the YEAR. The configuration is: FILENAM.TYP,DKNAM.NUM;UDDMMYY / / | | | \ \ \___Year File Name_/ / | | | \ \________Month File Type___/ | | \ \____________Day Disk Name/ | \___User Area Disk Number Examples: DDT.COM,.193;F270485 (User area 15, 27 Feb 1985) ED.COM,.340;0090184 (User area 0, 9 Jan 1984) If the DATE field is selected, but the USER is not, the semicolon is changed to a vertical bar ('|') character to provide proper distinction from the User to both human, and automated users of the Master catalog. Examples of this layout are: DDT.COM,.193|270485 ED.COM,.340|090184 -------------------------------------------------------------------------------- Additional Notes. DateStamper(tm) Interface: If DateStamper(tm) is installed, the system date is automatically read and displayed. If not, the user must supply the current month and day. In addition, when the user has installed MCAT for cursor addressing, the time is displayed at a pre-determined location on the screen, but is only updated if a real time clock is installed. The 'Relative' time at entry is displayed if a clock is not present. Screen-Oriented Operation: This is the recommended method of operating MCAT Version 5. When the proper cursor addressing and video attribute codes are added, the screen is functionally divided into a series of 'windows' which display specific information. MCAT can operate on systems displaying somewhat less than 80 characters per line, but overwrite may occur with consequent disruption of the screen if less than 72 characters are available. Six lines (rows) are required to establish the basic 'windows'. Operation on an 8-line terminal such as the small LCD displays sometimes used in portables is possible, although the instructions will quickly jump off the screen. A typical screen layout might appear as: - - - - - - - - - - - - - - - - Top of Screen - - - - - - - - - - - - - - - - MCAT Catalog Pgm v 5.01 - for - DateStamper 30 Jun 1985 ^Drive Change ^Log MAST.CAT ^Initialize ^Format (DU) ^Remove Vol. -------------------------------------------------------------------10:28------ Catalog Drive : B | Format ==> FN.FT /User -Date MAST.CAT on D/U : C16 | ------------------------------------------------------------------------------ For Help, reboot then type : MCAT ? A scratch disk must remain in Drive A: Catalog Drive B: (NO = Exit) Ready (Y/N) : _ - - - - - - - - - - - - - - - Bottom of Screen - - - - - - - - - - - - - - - - In operation, the main 'window' smoothly "paints" down the screen and wraps around to avoid problems in scrolling experienced by many types of terminals. Enjoy using Version 5 of MCAT! Any comments or suggestions on improving this program would be appreciated. If you make any improvements or enhancements to this program, please coordinate them with me before you release them to the public. In that manner some semblance of order might be maintained in the development of MCAT. Thank you. Harold F. Bower Box 946 APO NY 09128