@DATABASE "Upcat.guide"
@NODE MAIN "Upcat documentation"

                      Upcat - Disk catalog program

                     Version 1.2 - 24 September 1993

                     Copyright © 1993 Frans Zuydwijk

                        @{" Introduction           " LINK "UPCAT1"}
                        @{" Distribution           " LINK "UPCAT2"}
                        @{" Running Upcat          " LINK "UPCAT3"}
                        @{" Screen 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.

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. 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.

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" "Screen layout"

The screen consists of 3 areas :

   @{" Main display area " LINK "UPCAT4.1"}
   @{" Title bar         " LINK "UPCAT4.2"}
   @{" Scroll bar        " LINK "UPCAT4.3"}
@ENDNODE

@NODE "UPCAT4.1" "Screen 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.
@ENDNODE

@NODE "UPCAT4.2" "Screen 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 has no effect when a
requester is displayed.
@ENDNODE

@NODE "UPCAT4.3" "Screen 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"

By means of the Settings menu you can set and save several default
settings. These settings will be loaded at startup.

If you don't set a setting, an Upcat default will be used.

   @{" Input Device    " LINK "UPCAT5.2.1"}
   @{" Default Dir/Cat " LINK "UPCAT5.2.2"}
   @{" Default Display " LINK "UPCAT5.2.3"}
   @{" User menu items " LINK "UPCAT5.2.4"}
   @{" Confirm Delete  " LINK "UPCAT5.2.5"}
   @{" Create Icons    " LINK "UPCAT5.2.6"}
   @{" Exclude .info   " LINK "UPCAT5.2.7"}
   @{" Write Comment   " LINK "UPCAT5.2.8"}
   @{" Save Settings   " LINK "UPCAT5.2.9"}
@ENDNODE

@NODE "UPCAT5.2.1" "Settings menu - Input Device"

Select the device from which the file information must be read. 

In the submenu you see the available devices. 

Upcat default is 'DF0'.
@ENDNODE

@NODE "UPCAT5.2.2" "Settings menu - Default Dir/Cat"

Select the default directory where catalogs must be stored. 

If you select a default catalog too, this catalog will be loaded when
Upcat is started.

Upcat default is no default directory and catalog.
@ENDNODE

@NODE "UPCAT5.2.3" "Settings menu - Default Display"

Select the default display type and the default state of Show Comment. 

This does not affect the current display, use the Display menu for that.

Upcat defaults are Hierarchy and no Show Comment.
@ENDNODE

@NODE "UPCAT5.2.4" "Settings menu - User menu items"

A requester appears. In this requester 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.5" "Settings menu - Confirm Delete"

If checkmarked, confirmation will be asked before deleting records from
the catalog in memory.

Upcat default is ON.
@ENDNODE

@NODE "UPCAT5.2.6" "Settings menu - 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.7" "Settings menu - Exclude .info"

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.8" "Settings menu - Write Comment"

If checkmarked, Upcat will write the comment to the fileheader of the file 
on disk, if the comment was changed in the Detail Information requester.

This setting concerns files only.

Upcat default is OFF.
@ENDNODE

@NODE "UPCAT5.2.9" "Settings menu - Save Settings"

The choices from the Settings menu 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.3" "Catalog menu"

   @{" Show Vol/Dir  " LINK "UPCAT5.3.1"}
   @{" Detail Info   " LINK "UPCAT5.3.2"}
   @{" Insert Volume " LINK "UPCAT5.3.3"}
   @{" Update Volume " LINK "UPCAT5.3.4"}
   @{" Delete Record " LINK "UPCAT5.3.5"}
   @{" Categories    " LINK "UPCAT5.3.6"}
   @{" Information   " LINK "UPCAT5.3.7"}
@ENDNODE

@NODE "UPCAT5.3.1" "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.
@ENDNODE

@NODE "UPCAT5.3.2" "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 or selecting 'Detail Info' brings up the Detail
Information requester, which shows you all available information about the
record.

Gadgets, which are not appropriate for volumes or directories, will be
ghosted.

You can mark categories for a file by selecting category gadgets.

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.

In case a volume is updated, the existing comment and category information
of the files is preserved.
@ENDNODE

@NODE "UPCAT5.3.3" "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.4" "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.5" "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.6" "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 requester, 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 requesters. 

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.7" "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 default in the Settings menu, item Default
Display.

   @{" 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"}
   @{" File Selection      " LINK "UPCAT5.4.9"}
   @{" Show Comment        " LINK "UPCAT5.4.10"}
@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 once and
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
once and 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 - File Selection"

This brings up the file selection requester. 

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.9.1"}
   @{" Date and Size    " LINK "UPCAT5.4.9.2"}
   @{" Protect          " LINK "UPCAT5.4.9.3"}
   @{" Categories       " LINK "UPCAT5.4.9.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.9.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.9.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.9.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.9.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.10" "Display menu - Show Comment"

If you checkmark this menu item, the records will show the comment field
instead of the size/date/etc fields.

This option has no effect for both 'Paths' display types.
@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 requester 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 requester 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 requester 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 requester 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 requester. 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 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

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).
   /
   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.3
@ENDNODE

@NODE "UPCAT9" "Thanks"

I like to thank the following people for their comments, suggestions, bug
reports and testing : 

Arnout Grootveld, Frank Cizek, Frits Blankenzee, Hans Seifert, Klaus
Stengel, Marcel Offermans, Reinier de Ruiter, Torsten Bondieck.
@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"}
@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