
                        Free space & disc map display
                        =============================


Documentation for !FreeMap application version 3.20 07-Feb-2001,
for RISC OS 3.1 or later.

Issue: 3.20 07-Nov-2004, replaces:      3.17 21-Feb-2001
                                        3.10 06-Sep-1998
                                        1.00 13-Nov-1991
                                        1.11 25-Apr-1992
                                        1.20 25-Nov-1992
                                        1.30 02-Feb-1993
                                        2.00 09-Mar-1994
                                        2.10 09-Aug-1994
                                        3.00 15-Apr-1998
                                        3.15 18-Sep-1999
                                        3.16 05-Mar-2000             
Author: David J Ruck            

Copyright  DEEJ Technology PLC 1991-1998 



Overview
========

!FreeMap is designed to replace the standard display generated by the Free
option on menus from filer drive icons, located on the left hand side of the
iconbar.

!FreeMap is a multitasking RISC OS application providing a textual and
graphical display of the free space on the disc, and the disc map. A
facility is provided to fully compact all the free space on the disc.



Using !FreeMap
==============

Once the !FreeMap application has been seen by the RISC OS filer, selecting
Free from any drive menu will now load !FreeMap and display the its  window
instead of the textual display on RISC OS 2 or the simple free space window
under RISC OS 3.

Running !FreeMap by double clicking on the application will display
information on the current disc and filing system. Note: some filing systems
do not support !FreeMap (usually those that don't have a Free entry on their
filer menus), if the current filing system is one of these !FreeMap will the
complain with an error dialog. !FreeMap will continue to work correctly when
called from the filer menus. 

!FreeMap is only loaded when its window is displayed and does not use
application workspace at other times, it should be located on a hard disc if
possible, so disc swapping is not required to load the program when a Free
command is issued.


!FreeMap display
----------------
The !FreeMap window displays in numbers and graphically the following
information; the size of the disc, the total amounts of space used and free,
the largest block of free space, and the number of free blocks in the disc
map.

The disc map (the blocks of free space) is displayed with the size of each
block shown on a logarithmic scale bar graph. Green bars are used for the
map and largest free block display on new map discs (such as ADFS 'E'
format) as these values are not as important as on old map type discs.


Compact Free Space      Pressing the Compact Free Space button will fully
                        compact all the disc's free space, the compaction
                        will continue until the free space has ben collected
                        into the smallest possible number of blocks.

                        This operation may take some time and may be stopped
                        by pressing Escape. 

                        Compacting the free space is very useful for old map
                        type discs (L & D format) because when the disc has
                        lots of small free space blocks, the largest file
                        that can be created is limited to the size of the
                        largest free block. The free space map can become
                        full after 82 entries preventing any files from
                        being deleted.

                        On new map type discs (E & F formats), the free
                        space map is unlimited and does not restrict the
                        creation of files larger than the largest block (as
                        long is they are smaller than the total free space).
                        It can be useful to compact these discs as this can
                        speed access slightly, however it will usually not
                        be possible to reduce the number of free blocks on
                        hard discs by a significant amount.

Update Display          If the FreeMap display is left open, it will update
                        periodically when the free space on the disc
                        changes, The update display button can be used to
                        force the display to reflect the current state of
                        the disc.

                        On some filing systems the drive light may
                        illuminate occasionally as the free space is
                        checked, this will not affect the normal operation
                        of the disc and filing system.

                        With removable discs (such as floppy discs) the disc
                        can be changed while the !FreeMap display is open.
                        The update display button should be used to get
                        FreeMap to recognise the new disc.

Remove                  The remove option which can be found by bringing up
                        the menu attached to the !FreeMap window, will close
                        the window and prevent !FreeMap from intercepting
                        the normal RISC OS action.

                        The Free menu option of filer menus will then revert
                        back to the displaying the standard simple free
                        space window.

                        !FreeMap application must be run again allow it to
                        be accessed from the filer menus again. 


New Features
============
!FreeMap now supports large discs greater than 4G on filing systems that 
return the new 64bit free space calls introduced in RISC OS 3.6, see 
Technical Information below. The graphical display now accommodates the 
large maximum free space values found on bigger discs, and can also display 
more than 82 bars (up to a maximum of 328).

Dragging an image filing system partition file (such as DOSDisc file) to a 
!FreeMap window will display the free space in the image. A map display will 
not be available however.


Filing Systems
==============
!FreeMap will work with floppy and fixed (hard) ADFS discs, the RAM disc and
has been tested on some SCSI and IDE filing systems. It should work with any
filecore based filing systems support the idea of free space and disc maps, 
see the Technical Information below.

Non native ADFS compatible type discs such as DOS & Atari formats are 
supported, but as these types are not provided by filecore, the graphical
display  of disc map will not be displayed. The number of free blocks and the
largest  free bars will not be shown either, this will not usually be of
importance as  most foreign disc formats are similar to the new map ADFS
format, which can  split large files to use several small free disc areas.


Technical Information
=====================
!FreeMap works by setting a system alias for the showfree command which  is
issued by the Free option of filer menus. The showfree alias starts !FreeMap 
using a Filer_Run command.

FreeMap reads the disc size and free space using the generic FileSwitch SWI 
OS_FSControl (49) which should be supported by almost all filing systems, 
the new 64bit call (55) is used on filing systems that support large discs.
The  free space map info is found by issuing the *Map command for the
required  filing system and drive, and redirecting the output via a temporary
file. The  file used is specified in !Freemap.!Run and is defined to use the
PipeFS file  system by default (this uses the module area).

FreeMap will exit with an error if run on filing systems that do not support
the  idea of free space (e.g. a compressed filing system such as Computer
Concepts  CFS) or do not implement a *Map command. The alias will be
unaffected  allowing !FreeMap to still be used from filer menus that support
its operations.


Change Log
==========

3.00 15-Apr-1998  Support for discs over 2GB using 64bit free space calls
                  Reads free space of image fileing system dragged to window

3.10 06-Sep-1998  Support for RISC OS 3.8 big discs
                  Numeric values rounded up to nearest unit
                  Stippled colurs used when max bars displayed

3.15 18-Sep-1999  Improved numeric size display
                  Taller drive icons accomadated
                  New RISC OS 4 sprites
                  
3.16 05-Mar-2000  Incorrect Bar display for discs between 2G and 4G 

3.17 21-Feb-2001  Fixed crash cased by value routine when free space is 0

3.20 07-Nov-2004  Drive names beginning with digits not read as drive numbers


End of !FreeMap.!Help

