@DATABASE "Upcat.guide" @NODE MAIN "Upcat documentation" Upcat - Disk catalog program Version 1.3 - 11 April 1994 Copyright © 1993-1994 Frans Zuydwijk @{" Introduction " LINK "UPCAT1"} @{" Distribution " LINK "UPCAT2"} @{" Running Upcat " LINK "UPCAT3"} @{" Main window layout " LINK "UPCAT4"} @{" Menus " LINK "UPCAT5"} @{" ARexx interface " LINK "UPCAT6"} @{" Catalog file layout " LINK "UPCAT7"} @{" Developing environment " LINK "UPCAT8"} @{" Thanks " LINK "UPCAT9"} @{" Bug reports " LINK "UPCAT10"} @{" History " LINK "UPCAT11"} @ENDNODE @NODE "UPCAT1" "Introduction" Upcat is a disk catalog program with the following features : - Read file information from disks. - Store it in a catalog in memory. - Save/load catalogs to/from disk. - Display catalog in several ways. - Select files to be displayed. - Print (selection of) catalog. - 32 user definable categories. - Add comment to records in catalog. - ARexx macro interface. - User definable macro menu. - User definable volume ID's. - Automatic scan of inserted disks. Upcat requires Release 2.04 or higher. @ENDNODE @NODE "UPCAT2" "Distribution" Upcat is NOT Public Domain, but copyrighted freeware : it may be distributed and used freely. Upcat may not be sold, but inclusion in a PD-library is permitted as long as only a SMALL fee is charged to cover the costs of copying and distribution. The Fred Fish Library is the perfect example. The files in the distribution are : Upcat Upcat.info Upcat.guide Upcat.guide.info ReadMe ReadMe.info Example.cat Example.cat.info DemoMacro.upcat SetCategory.upcat PrintLong.upcat All these files must be distributed together, and they may not be changed. @ENDNODE @NODE "UPCAT3" "Running Upcat" Upcat may be started from Shell or Workbench. If started from Shell, Upcat detaches from the Shell and runs as a background process. When started from Shell the name of a catalog may be given as argument. Starting from Workbench can be done by clicking the Upcat icon, or clicking the icon of an Upcat catalog, in which case the catalog will be loaded. If no catalogname is supplied and a default catalog is defined in the Settings menu, the default catalog will be loaded. Upcat uses a 640 x 256 (PAL) or a 640 x 200 (NTSC) non-interlaced screen. If the user specified text overscan with Prefs/Overscan, the text overscan sizes will be used. Upcat will use your default system text font, provided it is 8 pixels high and 8 pixels wide. If this font has a companion 9 pixels high and 10 pixels wide, this will be used for gadget texts etc. Default Topaz-8 and Topaz-9 will be used. Upcat is controlled by using the mouse to operate the gadgets and the menus. Some keyboard equivalents may be used, as indicated on the gadgets and in the menus. The Tab key may be used to cycle between active string gadgets, Tab will activate the next string gadget and Shift + Tab the previous one. All changes are performed in the catalog, which is currently in memory, and are lost, if you quit Upcat or load another catalog without saving the catalog first. @ENDNODE @NODE "UPCAT4" "Main window layout" The main window consists of 3 areas : @{" Main display area " LINK "UPCAT4.1"} @{" Title bar " LINK "UPCAT4.2"} @{" Scroll bar " LINK "UPCAT4.3"} @ENDNODE @NODE "UPCAT4.1" "Main window layout - Main display area" In the main display area you see the catalog records. Clicking the left mouse button on a record will select it. The record will be highlighted then. Depending on the type of the selected record (volume, directory or file), one or more menu items in the Catalog menu will be enabled. Instead of selecting Catalog menu item 'Detail Info' or keying its keyboard equivalent, a second click on the selected record is effective too. An exception to this is, when you use display type 'Volumes only' or 'Directories only'. In this case a second click will change the display type to 'Hierarchy' and the selected volume or directory will be displayed. @ENDNODE @NODE "UPCAT4.2" "Main window layout - Title bar" The title bar shows you the catalog name and the number of volumes, directories and (selected) files in the catalog. After the number of files you see either '(A)' or '(S)', this indicates whether all or a selection of the files are currently displayed. Selecting the Window Close gadget in the upper left corner is the same as selecting 'Quit Upcat' in the Project menu, but this works only when no other window or requester is active. There is a screen depth gadget next to the standard window depth gadget in the upper right corner. Selecting this will bring the screen to the back. @ENDNODE @NODE "UPCAT4.3" "Main window layout - Scroll bar" The scroll bar in the right border shows which part of the currently displayed records is visible on screen. You can move through the records by operating the arrow gadgets at the bottom of the scroll bar, by moving the knob of the scroll bar, or by clicking above (screen up) or below (screen down) the knob. Keyboard equivalents are : cursor up, cursor down, shift cursor up (screen up), shift cursor down (screen down), Alt or Ctrl cursor up (top of catalog), Alt or Ctrl cursor down (bottom of catalog). @ENDNODE @NODE "UPCAT5" "Menus" Upcat has 5 menus in the menu bar : @{" Project menu " LINK "UPCAT5.1"} @{" Settings menu " LINK "UPCAT5.2"} @{" Catalog menu " LINK "UPCAT5.3"} @{" Display menu " LINK "UPCAT5.4"} @{" User menu " LINK "UPCAT5.5"} @ENDNODE @NODE "UPCAT5.1" "Project menu" @{" New " LINK "UPCAT5.1.1"} @{" Open " LINK "UPCAT5.1.2"} @{" Save " LINK "UPCAT5.1.3"} @{" Save As " LINK "UPCAT5.1.4"} @{" Delete " LINK "UPCAT5.1.5"} @{" Print " LINK "UPCAT5.1.6"} @{" Print As " LINK "UPCAT5.1.7"} @{" Help " LINK "UPCAT5.1.8"} @{" About " LINK "UPCAT5.1.9"} @{" Quit Upcat " LINK "UPCAT5.1.10"} @ENDNODE @NODE "UPCAT5.1.1" "Project menu - New" A new, empty catalog will be created in memory. If there is currently a catalog in memory, which is changed and not saved, a requester will pop up to ask you whether the catalog may be deleted from memory or not. @ENDNODE @NODE "UPCAT5.1.2" "Project menu - Open" A catalog will be loaded from disk. By means of a file requester you can select directory and catalog. If there is currently a catalog in memory, which is changed and not saved, a requester will pop up to ask you whether the catalog may be deleted from memory or not. In case of a load error, this will reported to you, together with the offending line number. The first line number is 1. @ENDNODE @NODE "UPCAT5.1.3" "Project menu - Save" The catalog will be saved to disk. If the catalog has no name yet, you will be asked for the directory and filename by means of a file requester. @ENDNODE @NODE "UPCAT5.1.4" "Project menu - Save As" The catalog will be saved to disk in another directory and/or with another filename. You must supply this information in a file requester. @ENDNODE @NODE "UPCAT5.1.5" "Project menu - Delete" A catalog (in fact any file you want) will be deleted. You must supply the name of the file to be deleted in a file requester. Before deleting this file, Upcat asks you to confirm the deletion. If the file to be deleted has an icon, this will be deleted too. @ENDNODE @NODE "UPCAT5.1.6" "Project menu - Print" Send the currently selected or all records to the printer (PRT:). This is a rather simple print, no special print formatting is done. All records, which are currently displayed, will be sent to the printer in the current display format. By means of the ARexx interface you can make your own print formats. @ENDNODE @NODE "UPCAT5.1.7" "Project menu - Print As" Does the same as Print, but writes the records not to the printer, but to a disk file. You must supply directory and filename in a file requester. @ENDNODE @NODE "UPCAT5.1.8" "Project menu - Help" Instead of selecting this menu item, you may also press the Help key. The menu item is only accessible in the main screen, but the Help key may be pressed always. AmigaGuide will be called to show the documentation file Upcat.guide. The file Upcat.guide must reside in the same directory as the program file Upcat, or in a directory from 'Env:AmigaGuide/Path'. The library amigaguide.library must be present in the LIBS: directory. @ENDNODE @NODE "UPCAT5.1.9" "Project menu - About" Displays the About requester. @ENDNODE @NODE "UPCAT5.1.10" "Project menu - Quit Upcat" The current catalog is removed from memory and Upcat quits. If there is currently a catalog in memory, which is changed and not saved, a requester will pop up to ask you whether the catalog may be deleted from memory or not. @ENDNODE @NODE "UPCAT5.2" "Settings menu" The Settings menu has a single item, Preferences. When you select this, the Preferences window will open and you can set and save several (default) settings. These settings will be loaded at startup time. Some of them will be effective immediately too. @{" Default directory " LINK "UPCAT5.2.1"} @{" User menu items " LINK "UPCAT5.2.8"} @{" Default catalog " LINK "UPCAT5.2.2"} @{" Default input device " LINK "UPCAT5.2.3"} @{" Confirm record deletion " LINK "UPCAT5.2.9"} @{" Default display type " LINK "UPCAT5.2.4"} @{" Create catalog icons " LINK "UPCAT5.2.10"} @{" Default display items " LINK "UPCAT5.2.5"} @{" Exclude .info files " LINK "UPCAT5.2.11"} @{" Default volume display " LINK "UPCAT5.2.6"} @{" Write comment to disk " LINK "UPCAT5.2.12"} @{" Preferences directory " LINK "UPCAT5.2.7"} If you operate the Use button, the current settings of the User menu items and the 4 checkboxes will be used by the program, the other settings will be used at startup time only, if saved. If you operate the Save button, it has the same effect as the Use button, but furthermore your preferences will be saved to disk. @ENDNODE @NODE "UPCAT5.2.1" "Preferences - Default directory" Select the default directory where catalogs must be stored. You see the current default directory. If you want to change this, operate the 'C' button. A requester will show up and you may select another directory. Upcat default is no default directory. @ENDNODE @NODE "UPCAT5.2.2" "Preferences - Default catalog" Select the default catalog. This catalog will be loaded at startup time and must reside in the default directory. You see the current default catalog. If you want to change this, operate the 'C' button. A requester will show up and you may select another catalog. Upcat default is no default catalog. @ENDNODE @NODE "UPCAT5.2.3" "Preferences - Default input device" Operate the cycle gadget to select the default input device. The current input device is not changed, use the Input Device item in the Catalog menu for that. Upcat default is DF0. @ENDNODE @NODE "UPCAT5.2.4" "Preferences - Default display type" Operate the cycle gadget to select the default display type. This does not affect the current display, use the Display menu for that. Upcat default is Hierarchy. For more information, see @{" Display menu " LINK "UPCAT5.4"} @ENDNODE @NODE "UPCAT5.2.5" "Preferences - Default display items" Operate the cycle gadget to select the default display layout. This does not affect the current display, use the Display menu for that. Upcat default is Name Size Date. For more information, see @{" Display items " LINK "UPCAT5.4.9"} @ENDNODE @NODE "UPCAT5.2.6" "Preferences - Default volume display" Operate the cycle gadget to select the default volume display. This gadget does not affect the current display, use the Display menu for that. Upcat default is ' by Name'. For more information, see @{" Display volume " LINK "UPCAT5.4.10"} @ENDNODE @NODE "UPCAT5.2.7" "Preferences - Preferences directory" Operate the cycle gadget to select where the preferences file will be stored at save time. Initially you will see the directory where the current preferences file was loaded. The choices from Preferences will be saved in a file 'Upcat.prefs'. You may choose the directory where this file will be saved, either the directory where the program Upcat was loaded from, or the directories 'ENV:Upcat' and 'ENVARC:Upcat'. These latter directories contain all system preferences files too. At startup, Upcat will look in the program directory first and then in the 'ENV:Upcat' directory. If 'Upcat.prefs' is not found, the Upcat defaults will be used. @ENDNODE @NODE "UPCAT5.2.8" "Preferences - User menu items" A window appears when you operate this button. In this window you may define 0-10 menu items, which will be placed in the User menu. Each menu item consists of a text (max 20 characters), which will show up when the User menu is selected, and a ARexx command string (max 80 characters), which will be sent to ARexx when the menu item is selected. The command string may be anything acceptable for ARexx, macro names with or without arguments, or quoted short programs. The extension for Upcat macronames is '.upcat'. If Upcat finds '%SelectRec' in the command string, it will be replaced by the full name of the currently selected record. Each menu item has one of the keyboard equivalents F1-F10, as shown in the requester. Empty menu items will not appear in the User menu. Upcat default : no user defined menu items. @ENDNODE @NODE "UPCAT5.2.9" "Preferences - Confirm delete" If checkmarked, confirmation will be asked before deleting records from the catalog in memory. Upcat default is ON. @ENDNODE @NODE "UPCAT5.2.10" "Preferences - Create icons" If checkmarked, icons will be created for catalog files during save, unless they already exist. If not checkmarked, existing icons will be removed during save. Upcat default is ON. @ENDNODE @NODE "UPCAT5.2.11" "Preferences - Exclude .info files" If checkmarked, files with names ending with '.info' (icon files) will be excluded from the catalog during a 'Insert Volume' or 'Update Volume' operation. Upcat default is OFF. @ENDNODE @NODE "UPCAT5.2.12" "Preferences - Write comment to disk" If checkmarked, Upcat will write the comment to the fileheader of the file on disk, if the comment was changed in the Detail Information window. This setting concerns files only. Upcat default is OFF. @ENDNODE @NODE "UPCAT5.3" "Catalog menu" @{" Input Device " LINK "UPCAT5.3.1"} @{" Insert Volume " LINK "UPCAT5.3.2"} @{" Update Volume " LINK "UPCAT5.3.3"} @{" Auto Insert " LINK "UPCAT5.3.4"} @{" Auto Update " LINK "UPCAT5.3.5"} @{" Detail Info " LINK "UPCAT5.3.6"} @{" Show Vol/Dir " LINK "UPCAT5.3.7"} @{" Delete Record " LINK "UPCAT5.3.8"} @{" Categories " LINK "UPCAT5.3.9"} @{" Information " LINK "UPCAT5.3.10"} @ENDNODE @NODE "UPCAT5.3.1" "Catalog menu - Input Device" Select the device from which the file information must be read. In the submenu you see the available devices. @ENDNODE @NODE "UPCAT5.3.2" "Catalog menu - Insert Volume" The file information of the volume in the current Input Device will be read and inserted in the catalog. Icon (.info) files will be excluded, if this is selected in the Settings menu. If the volume is in the catalog already, you may choose between 'Update' and 'Cancel'. @ENDNODE @NODE "UPCAT5.3.3" "Catalog menu - Update Volume" Same as Insert Volume, but if the volume is already present, the information in the catalog will be updated with the new information without asking you first. Update means : - Delete records not existing in the new information. - Insert records not existing in the old information. - Replace old records by new records with the same name, but keep the categories and the comment of the old records. @ENDNODE @NODE "UPCAT5.3.4" "Catalog menu - Auto Insert" If this menu item is checkmarked, insertion of disks in the current input device will be noticed and the file information will be automatically read and inserted in the catalog. If there are no more disks to be inserted, you may select this menu item again to turn it off. Insertion of disks may be neglected, if done while Upcat is doing something else (i.e. not waiting for input). Icon (.info) files will be excluded, if this is selected in the Settings menu. If a volume is in the catalog already, you may choose between 'Update' and 'Cancel'. @ENDNODE @NODE "UPCAT5.3.5" "Catalog menu - Auto Update" Same as Auto Insert, but if a volume is already present, the information in the catalog will be updated with the new information without asking you first. Insertion of disks may be neglected, if done while Upcat is doing something else (i.e. not waiting for input). Update means : - Delete records not existing in the new information. - Insert records not existing in the old information. - Replace old records by new records with the same name, but keep the categories and the comment of the old records. @ENDNODE @NODE "UPCAT5.3.6" "Catalog menu - Detail Info" This menu item is usually disabled. It is enabled when you click on a record, which is highlighted then. Clicking a second time (except when display type is 'Volumes only' or 'Directories only') or selecting 'Detail Info' brings up the Detail Information window, which shows you all available information about the record. Gadgets, which are not appropriate for volumes or directories, will be ghosted. If this is a volume record, you may optionally edit a volume ID for this volume. This volume ID may be 30 characters long. You can use this f.i. to add your own sequence number, indicating where to find the volume. If the volumes are currently sorted in ID sequence and you add or change a volume ID, this will not change the sequence of the volumes in the display immediately. Select 'Display - Display volume' again to see any sequence changes. The comment field may be edited. For files, this originally contains the comment from the file header on disk, but you may change it. For files, the comment will be written to their fileheader on disk, if the Write Comment menu item in the Settings menu is checkmarked. You can mark categories for a file by selecting category gadgets. When a volume is updated, existing comment and category information will be transferred to the records, which were just read from disk. @ENDNODE @NODE "UPCAT5.3.7" "Catalog menu - Show Vol/Dir" This menu item is usually disabled. It is enabled when the Display type is 'Volumes only' or 'Directories only' and you click on a record. This record is highlighted then. Selecting this menu item will then change the Display type to 'Hierarchy' and will display the selected volume or directory. Clicking a second time on the record has the same effect as selecting the menu item. @ENDNODE @NODE "UPCAT5.3.8" "Catalog menu - Delete Record" This menu item is usually disabled. It is enabled when you click on a record, which is highlighted then. Selecting 'Delete Record' will bring up a requester asking you whether you want to delete the volume or directory or file record(s) or not. If Confirm Delete in the Settings menu is not checkmarked, this requester will not appear. If you delete a directory record, all file records belonging to that directory will be deleted too. If you delete a volume record, all directory and file records belonging to that volume will be deleted too. @ENDNODE @NODE "UPCAT5.3.9" "Catalog menu - Categories" There are 32 user definable categories in each catalog. These categories are saved in the catalog files. Selecting the 'Categories' menuitem in the 'Catalog' menu will bring up the Categories window, which shows you the defined categories, the number of files in each category and the number of files, which are not in any category. Select and edit the 32 string gadgets to add or change a category. Selecting a string gadget will enable the 'Delete' and 'Swap' gadgets. Swapping two categories only affects the physical place of the categories in the windows. Deleting a category will delete all references to this category in all records of the current catalog in memory. Selecting the 'Load' gadget will bring up a file requester. Choose a catalog and the categories information will be read from this catalog and overwrite the current categories information in memory. In this way you may use the same categories for more than one catalog. @ENDNODE @NODE "UPCAT5.3.10" "Catalog menu - Information" A requester will be displayed with some information about the current catalog : - Name of the catalog. - Number of volumes in the catalog. - Number of directories in the catalog. - Number of files in the catalog. - Number of categories in use. - Total free diskspace for all volumes in the catalog. - Memory used for the catalog records. - Memory free. @ENDNODE @NODE "UPCAT5.4" "Display menu" The record information can be displayed in several ways. You may set the startup defaults for display type, display items and volume display in the Preferences window. @{" File Selection " LINK "UPCAT5.4.0"} @{" Hierarchy " LINK "UPCAT5.4.1"} @{" Volumes only " LINK "UPCAT5.4.2"} @{" Directories only " LINK "UPCAT5.4.3"} @{" Files - Name sorted " LINK "UPCAT5.4.4"} @{" Files - Date sorted " LINK "UPCAT5.4.5"} @{" Files - Size sorted " LINK "UPCAT5.4.6"} @{" Paths - Vol. sorted " LINK "UPCAT5.4.7"} @{" Paths - Dir. sorted " LINK "UPCAT5.4.8"} @{" Display items » " LINK "UPCAT5.4.9"} @{" Display volume by » " LINK "UPCAT5.4.10"} @ENDNODE @NODE "UPCAT5.4.0" "Display menu - File Selection" This brings up the File Selection window. Initially all files are selected for display. You may set the following selection criteria (each criterium used will restrict the selection further) : @{" Name and Comment " LINK "UPCAT5.4.0.1"} @{" Date and Size " LINK "UPCAT5.4.0.2"} @{" Protect " LINK "UPCAT5.4.0.3"} @{" Categories " LINK "UPCAT5.4.0.4"} Clicking the 'Select all files' gadget will set all gadgets in the requester in such a way, that all files will be selected. If any files are selected, the menu item 'File Selection' will be checkmarked and the titlebar will show '(S)' instead of '(A)'. @ENDNODE @NODE "UPCAT5.4.0.1" "Display menu - File Selection - Name and Comment" - Name : substring which must occur in the file name. You may use the special character '*' as starting OR ending character of the substring. In the middle of the substring it is just an ordinary character. If the substring ends with '*', the filename must start with the substring e.g. 'Up*'. If the substring starts with '*', the filename must end with the substring e.g. '*.LZH'. If the substring is '*', all filenames will be accepted. - Comment : substring which must occur in the comment field. Use of "*' is the same as for Name. @ENDNODE @NODE "UPCAT5.4.0.2" "Display menu - File Selection - Date and Size" - MinDate : The date of the selected files must be >= MinDate. - MaxDate : The date of the selected files must be <= MaxDate. - MinSize : The size of the selected files must be >= MinSize. - MaxSize : The size of the selected files must be <= MaxSize. @ENDNODE @NODE "UPCAT5.4.0.3" "Display menu - File Selection - Protect" Select files with any combination of protect bits. The protect bits are '-sparwed' (script, pure, archive, read, write, executable, deletable). The position of these bits is fixed. Use the character to indicate that the protect bit must be set, use '- ' to indicate it must not be set, use '*' to indicate both are accepted. For instance, '*s*****-' will select all script files, which are not deletable. @ENDNODE @NODE "UPCAT5.4.0.4" "Display menu - File Selection - Categories" You may select and checkmark the individual categories used for the file selection. You may select and checkmark one of the 'Or' and 'And' gadgets. 'Or' means that a file to be selected must be in one or more of the selected categories. 'And' means that a file to be selected must be in all of the selected categories. Clicking the 'All' gadget will select all categories. Clicking the 'None' gadget will deselect all categories. Checkmarking the 'Include No Category' gadget will select all files, which are in no category. @ENDNODE @NODE "UPCAT5.4.1" "Display menu - Hierarchy" Display the records in the same hierarchical way as they were found on disk. For each level one space is indented. @ENDNODE @NODE "UPCAT5.4.2" "Display menu - Volumes only" Display only the volumes in the catalog. You can display the contents of a volume by clicking on it twice, or clicking on it once and then selecting the 'Show Vol/Dir' item in the Catalog menu. The Display type will change to 'Hierarchy' then and the selected volume will be displayed. @ENDNODE @NODE "UPCAT5.4.3" "Display menu - Directories only" Display only the volumes and the directories in the catalog. You can display the contents of a volume or directory by clicking on it twice, or clicking on it once and then selecting the 'Show Vol/Dir' item in the Catalog menu. The Display type will change to 'Hierarchy' then and the selected volume or directory will be displayed. @ENDNODE @NODE "UPCAT5.4.4" "Display menu - Files - Name sorted" Display the files only, sorted by name. If you press a character key, the display jumps to the first filename, of which the first character is equal to or higher than the selected character. @ENDNODE @NODE "UPCAT5.4.5" "Display menu - Files - Date sorted" Display the files only, sorted by descending date and time. @ENDNODE @NODE "UPCAT5.4.6" "Display menu - Files - Size sorted" Display the files only, sorted by descending size. @ENDNODE @NODE "UPCAT5.4.7" "Display menu - Paths - Vol. sorted Display the files with the complete path. The records are sorted by volume name, then directory name, then file name. Empty volumes and directories are displayed too. @ENDNODE @NODE "UPCAT5.4.8" "Display menu - Paths - Dir. sorted Display the files with the complete path. The records are sorted by directory name, then file name. This might be useful, when the catalog contains volumes with the same directory structure. Empty volumes and directories are not displayed. @ENDNODE @NODE "UPCAT5.4.9" "Display menu - Display items" Individual records can be displayed in three ways : 1. Name Size Date If you checkmark this menu item, the lines in the display will show the name, size, date, time, protect. 2. Name Categories If you checkmark this menu item, the lines in the display will show the name and a list of the categories for the record. If the line is longer than the display width, it will be chopped. So this is only useful, if there are only a few categories set for a record. 3. Name Comment If you checkmark this menu item, the lines in the display will show the name and the comment. If the line is longer than the display width, it will be chopped. The 'Display items' selection has no effect for both 'Paths' display types. @ENDNODE @NODE "UPCAT5.4.10" "Display menu - Display volume" A volume can be displayed in four ways : 1. by the volume name, which was read from disk. 2. by the volume ID, which was optionally set by the user in the Detail Information window. 3. by the volume name, followed by the volume ID. 4. by the volume ID, followed by the volume name. If a volume has no volume ID, the volume name will be used always. Depending on the selected subitem, the volumes will be sorted by name or by ID. In the catalog file on disk, the volumes are always sorted by name. @ENDNODE @NODE "UPCAT5.5" "User menu" From the User menu you can call your ARexx macros. @{" ARexx macro " LINK "UPCAT5.5.1"} @{" User definable menu items " LINK "UPCAT5.5.2"} @ENDNODE @NODE "UPCAT5.5.1" "User menu - ARexx macro" You must select a ARexx macro program via a filerequester. The selected program name will be sent to ARexx to be executed. Place your ARexx macro programs in the REXX: directory, that is the best place for them. The extension '.upcat' is used for Upcat macro names. @ENDNODE @NODE "UPCAT5.5.2" "User menu - User definable menu items" There may be 0-10 menu items in the User menu defined by the user by means of the Settings menu item 'User menu items'. Selecting one of these menu items causes the according command string to be sent to ARexx, in order to be executed. @ENDNODE @NODE "UPCAT6" "ARexx interface" @{" General information " LINK "UPCAT6.1"} @{" Upcat macro commands " LINK "UPCAT6.2"} @{" Record layout " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.1" "ARexx interface - General information" You start an ARexx macro program by selecting an item from the User menu. The command will be sent to ARexx then, in order to be executed. If ARexx detects an error during execution, it will return an errorcode, otherwise it returns 0. Your ARexx macro may return 0 or an errorcode via the Exit instruction. If a code unequal 0 is returned, Upcat will report this. The Upcat host address is 'UPCAT.x', where x is a number determined at runtime. The statement 'Host = Address()' delivers the host address. Upcat opens an 'auto' window for you on the Upcat screen. This window opens automatically when you write output (Say) or read input (Pull). @ENDNODE @NODE "UPCAT6.2" "ARexx interface - Upcat macro commands" You may send the following commands to the Upcat host address : @{" FirstCat " LINK "UPCAT6.2.1"} @{" NextCat " LINK "UPCAT6.2.1"} @{" FirstRec " LINK "UPCAT6.2.2"} @{" NextRec " LINK "UPCAT6.2.2"} @{" FirstVol " LINK "UPCAT6.2.3"} @{" NextVol " LINK "UPCAT6.2.3"} @{" FirstDir " LINK "UPCAT6.2.4"} @{" NextDir " LINK "UPCAT6.2.4"} @{" FirstFile " LINK "UPCAT6.2.5"} @{" NextFile " LINK "UPCAT6.2.5"} @{" FirstSortFile " LINK "UPCAT6.2.6"} @{" NextSortFile " LINK "UPCAT6.2.6"} @{" SelectRec " LINK "UPCAT6.2.7"} @{" FileSelect " LINK "UPCAT6.2.8"} @{" Path " LINK "UPCAT6.2.9"} @{" SetCategory " LINK "UPCAT6.2.12"} @{" CatalogName " LINK "UPCAT6.2.10"} @{" Requester " LINK "UPCAT6.2.13"} @{" ScreenName " LINK "UPCAT6.2.11"} All commands return a code in RC. Most commands return an information string in Result. An 'Options Results' statement in your ARexx program is necessary to get this string. If you send an invalid command to Upcat, RC = 20 will be returned. @ENDNODE @NODE "UPCAT6.2.1" "Upcat macro commands - FirstCat and NextCat" FirstCat returns in Result information about the first category of the catalog. NextCat does the same for the next category. Layout : CategoryName/CategoryNumber/FileCount. If a category is undefined, an empty string will be returned. The sequence of returned categories is the sequence in which they appear on screen in Upcat. The CategoryNumber identifies the category and is NOT related to this sequence. RC : 0 = OK. 5 = No (more) categories. 10 = NextCat without FirstCat. @ENDNODE @NODE "UPCAT6.2.2" "Upcat macro commands - FirstRec and NextRec" FirstRec returns in Result information about the first record of the catalog. NextRec does the same for the first record after the current record pointer. Both commands set the current record pointer at the returned record. If a FileSelect ON macro command was executed, the current file selection criteria from the File Selection window will be used for file records. RC : 0 = OK. 5 = No (more) records. 10 = No current record pointer yet (NextRec). @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.3" "Upcat macro commands - FirstVol and NextVol" FirstVol returns in Result information about the first volume of the catalog. NextVol does the same for the first volume after the current record pointer. Both commands set the current record pointer at the returned record. RC : 0 = OK. 5 = No (more) volumes. 10 = No current record pointer yet (NextVol). @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.4" "Upcat macro commands - FirstDir and NextDir" FirstDir returns in Result information about the first directory of the catalog. NextDir does the same for the first directory after the current record pointer. Both commands set the current record pointer at the returned record. RC : 0 = OK. 5 = No (more) directories. 10 = No current record pointer yet (NextDir). @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.5" "Upcat macro commands - FirstFile and NextFile" FirstFile returns in Result information about the first file of the catalog. NextFile does the same for the first file after the current record pointer. Both commands set the current record pointer at the returned record. If a FileSelect ON macro command was executed, the current file selection criteria from the File Selection window will be used. RC : 0 = OK. 5 = No (more) files. 10 = No current record pointer yet (NextFile). @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.6" "Upcat macro commands - FirstSortFile and NextSortFile" FirstSortFile returns in Result information about the first file in the catalog. NextSortFile does the same for the next file. The files are returned in sorted sequence. The sort criterium (name, date, size) depends on the current display type, as set in the Display menu. If the display is not one of the 'Files - xxxx sorted', an error is returned. If a FileSelect ON macro command was executed, the current file selection criteria from the File Selection window will be used. RC : 0 = OK. 5 = No (more) files. 10 = No FirstSortFile executed yet (NextSortFile). 11 = Display type is not 'Files - xxxx sorted'. @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.7" "Upcat macro commands - SelectRec" SelectRec returns in Result information about the currently selected (highlighted) record. The current record pointer is set at the selected record. RC : 0 = OK. 10 = No record selected. @{" Layout of record in Result " LINK "UPCAT6.3"} @ENDNODE @NODE "UPCAT6.2.8" "Upcat macro commands - FileSelect" With FileSelect you can indicate, whether you want the file selection criteria from the File Selection window to be used or not. Argument : ON Return selected files only. OFF Return all files in the catalog. When a macro starts running, FileSelect is default OFF. This file selection is used in the macro commands FirstRec, NextRec, FirstFile, NextFile, FirstSortFile and NextSortFile. RC : 0 = OK. 10 = Invalid argument. 11 = FileSelect ON, but no file selection criteria set in the File Selection window. FileSelect stays OFF. @ENDNODE @NODE "UPCAT6.2.9" "Upcat macro commands - Path" Path returns in Result the path belonging to the current record pointer. For volumes, the path will be an empty string. The returned path includes a trailing ':' or '/'. RC : 0 = OK. 10 = No current record pointer yet. @ENDNODE @NODE "UPCAT6.2.10" "Upcat macro commands - CatalogName" CatalogName returns in Result the filename of the current catalog. RC : 0 = OK. Returned always. @ENDNODE @NODE "UPCAT6.2.11" "Upcat macro commands - ScreenName" ScreenName returns in Result the name of the public Upcat screen. This name is defined at runtime and consists of the string 'Upcat' followed by a sequence number, which starts at 1. You can use this name to open your own macro window on the Upcat screen. RC : 0 = OK. Returned always. @ENDNODE @NODE "UPCAT6.2.12" "Upcat macro commands - SetCategory" SetCategory updates the categories information of the record, belonging to the current record pointer. Only file records contain categories. Argument 1 : 'ON' or 'OFF'. Argument 2 : Category number (0-31), which must be set ON or OFF. You can obtain the category numbers, together with the category names, with FirstCat/NextCat. The numbers are NOT related to the sequence in which the categories appear in requesters. RC : 0 = OK. 5 = Category is already ON or OFF for this record. 10 = No current record pointer yet. 11 = Current record is not a file record. 12 = Invalid argument. 13 = Category number not in use. @ENDNODE @NODE "UPCAT6.2.13" "Upcat macro commands - Requester" Requester displays a requester on the macro or main Upcat window and waits until a gadget in the requester is selected. You must supply two arguments : - The gadget string. This string contains the text for 1-2 gadgets, which will be in the requester. If you have 2 gadgets, you must use '|' as a separation character. The maximum length of a gadget text is 10. - The text string. This string contains the text for 1-3 text lines. You must use '|' as a separation character. The maximum length for a text line is 56. RC : 0 = The only or the left gadget was selected. 5 = The right gadget was selected. 10 = Invalid argument. @ENDNODE @NODE "UPCAT6.3" "ARexx interface - Record layout" This is the layout of the records, returned by the Firstxxx, Nextxxx and SelectRec commands : Level/Type/Name/Size/Date/Time/Protect/Categories/Comment If a volume ID was set for a volume, the layout of Name is Name:ID. Size does contain the free space in KiloBytes for a volume. Size does not contain relevant information for a directory. Protect does not contain relevant information for a volume. Categories does not contain relevant information for a volume or directory. Categories contains a string of 8 hexadecimal characters. This represents 32 bits, each bit indicating whether (1) or not (0) this file is in the corresponding category. Bit 0 (the rightmost, least significant bit) corresponds with category number 0, bit 31 (the leftmost, most significant bit) with category number 31. Category numbers and names can be found with @{" FirstCat/NextCat " LINK "UPCAT6.2.1"}. @ENDNODE @NODE "UPCAT7" "Catalog file layout" @{" General layout " LINK "UPCAT7.1"} @{" Category record layout " LINK "UPCAT7.2"} @{" File record layout " LINK "UPCAT7.3"} @ENDNODE @NODE "UPCAT7.1" "Catalog file layout - General layout" The first record is always 'Upcat Catalog'. The second record is always 'Categories'. Next there are 0-32 category records. The next record is always 'Records'. The remaining records are the file records. Records are always separated by the linefeed character (hex 0A). @ENDNODE @NODE "UPCAT7.2" "Catalog file layout - Category record layout" A category record consists of the following fields : Position number (0-31). / Category number (0-31). / Category name (max 15 characters). @ENDNODE @NODE "UPCAT7.3" "Catalog file layout - File record layout" A file record consists of the following fields : Level number (0-255). Volumes are always at level 0. / Record type ('V' = volume, 'D' = directory, 'F' = file). / Name (max 30 characters). If a volume ID is set for a volume record, Name will be followed by ':' and the volume ID (max 30 characters). / Size (0 for directories, free space in KB's for volumes). / Date and time (12 characters YYMMDDHHMMSS). Year range is 1950-2049. / Protect (max 2 hex characters). / Categories (max 8 hex characters). / Comment (max 79 characters). @ENDNODE @NODE "UPCAT8" "Developing environment" Computer : A2000, 1 MB Chip RAM, 2 MB Fast RAM. Harddisk : Supra WordSync Series II + Quantum 52 MB. OS : 2.1 Compiler : SAS/C 6.51 @ENDNODE @NODE "UPCAT9" "Thanks" I like to thank the following people for their comments, suggestions, bug reports and testing : Arne Otte, Arnout Grootveld, Bill Bennett, Frank Cizek, Fred Hamilton, Frits Blankenzee, Hans Seifert, Jorgen Grahn, Jussi Lindgren, Klaus Stengel, Marcel Offermans, Michael Vissers, Paul van der Valk, Raf Hofmans, Reinier de Ruiter, Torsten Bondieck, Werner Scholz. @ENDNODE @NODE "UPCAT10" "Bug reports" Bug reports, comments etc. can be sent to: Frans Zuydwijk Konijnenweide 84 2727GH Zoetermeer Nederland FidoNet : 2:281/614 InterNet : zuydwijk@vcgn.hacktic.nl @ENDNODE @NODE "UPCAT11" "History" @{" Version 1.0 " LINK "UPCAT11.1"} @{" Version 1.1 " LINK "UPCAT11.2"} @{" Version 1.2 " LINK "UPCAT11.3"} @{" Version 1.3 " LINK "UPCAT11.4"} @ENDNODE @NODE "UPCAT11.1" "History - Version 1.0" Date : 16 March 1993 First release. @ENDNODE @NODE "UPCAT11.2" "History - Version 1.1" Date : 9 July 1993 New : - Border of editable string gadgets changed from recessed to non-recessed. - Screen and window size adapted to text overscan size. - Delete file menu item in Project menu. - Number of files in categories displayed in Categories requester. - New display type 'Paths - Dir. sorted'. Display type 'Paths / Files' is renamed to 'Paths - Vol. sorted'. Bugfix : - Records with a date in the years 2000-2009 were saved incorrectly, causing errors when reading the catalog. - Icons were saved in the current directory instead of in the catalog directory. @ENDNODE @NODE "UPCAT11.3" "History - Version 1.2" Date : 24 September 1993 New : - Documentation is in AmigaGuide format now. - Selecting the Help item in the Project menu or pressing the Help key will call AmigaGuide to display the documentation. - Show Comment menu item in Display menu allows switching between display of comment and display of size/date/etc. - New gadget keyboard equivalents in File Selection requester. - Comments can be added for volumes and directories. - Information menu item in Catalog menu displays information about the current catalog. - ARexx interface. - User definable macro menu. - Write comment to fileheader on disk (Settings menu toggle). - Confirm Delete toggle in Settings menu. Bugfix : - During loading of a catalog, some date errors were not detected and others were reported with a wrong line number. @ENDNODE @NODE "UPCAT11.4" "History - Version 1.3" Date : 11 April 1994 New : - Static gadget data replaced by dynamic functions. - Tab key used for cycling of active string gadgets. - Screen depth gadget added to window titlebar. - Gadgets in Categories requester rearranged. - Upcat detaches from Shell and runs as a background process. - Most requesters replaced by windows. - Preferences window instead of menu items. - Menu item 'Input device' moved to Catalog menu. - Auto Insert/Update added to Catalog menu. - Display menu changed, categories and volume ID's can be displayed now. - User definable volume ID's. - When display type is 'Volumes only' or 'Directories only', clicking twice on a record will display the records of the selected volume or directory, as it was in version 1.0. Bugfix : - Enforcer hits during initialization and Print As. These hits did not influence functional behaviour. - LINK's in Upcat.guide across line boundaries. - Comments for volumes and directories were not preserved, when a volume was updated. - Display was not updated, if a file was no longer selected after a change in Detail Info. @ENDNODE