Archive Magazine 1996/ARCHIVE_96.iso/discs/shareware/share_46/objectlist/Manual

Text File | 1992-06-21 | 16KB | 433 lines

ObjectLister v1.10 User Manual                            (Dated 21.06.92)

OBJECTives:

1) To provide extensions to the OS to create, sort, and process lists of
   directory and/or file 'objects'.
2) To do this in as flexible a way as possible. The command parameters
   may look a bit daunting but you probably will not need all of them at
   once - start off with simple requests and work up to complicated ones!

What use is that I hear you ask. Well there are various uses - here are
some ideas to get you thinking...

1) Track down duplicate files - relocatable modules, for example, have
   a habit of turning up all over the place if you're not careful.
2) Find out what files you worked on today, yesterday, last week,
   last month...
3) Find out the sizes of the biggest files on your system.
4) Squash all your sprite files via !Compression with a few lines of an
   obey file.
5) Prepare data for charting your disk usage.
6) Keep track of any suspicious changes to files - eg modules increasing in
   length when you know they haven't been upgraded - a sign of possible
   viral attack.
7) Back up todays work.


Important bits...

You will need to ensure that the shared C library (v3.50 or greater) has
been loaded before you attempt to load and use this module.
Put a copy of this module in the !system.modules directory.


General Stuff...

A list is composed of entries - one for each object. Each entry has seven
comma separated components (numbered 0-6).
These are:-

0) Object type 1= file, 2= RiscOS directory, 3 = PC 'Hard Disc'
1) Date part of objects datestamp, or 0 if not datestamped.
2) Time part of objects datestamp, or 0 if not datestamped.
3) Filetype of file objects; always 0 for others.
4) Size of object (in Hex).
5) Objects attributes (in Hex).
6) Object name.

Components 0-4 form a string of fixed length.

You may introduce comment lines into a list if you wish. They should
begin with the character |.

In the command descriptions below :-
[] denote optional features - even where they are enclosed in quotes.
| denotes a choice e.g  a|b  means a or b
... denotes a possible repetition

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*OLmake    -    Make an object list

Syntax:
*OLmake -Path <directory> [-Ftype "[NOT] <n>|<string>..."]
  [-Match "[NOT]<string>..."] [-After <date/time>] [-Before <date/time>]
  [-Larger <n>] [-Smaller <n>] [-Recurse <n>] [-Locked y|n] [<options>]


  -path <directory name>
Required. Describes place to start.


  -ftype "[Not] <x>|<string>..."
Optional. Select all objects that have filetype x (or not - see below).
If a string is entered it is evaluated via OS_FSControl 31.
Examples of valid strings are: Text, Drawfile, Obey, Data etc.
(see the File$Type_nnn system variables for the valid text for each
filetype number)
You may specify up to ten different filetypes by separating them with
spaces or commas and enclosing them all in quotes
e.g
-ftype "Obey &FFF Data" will select obey files, text files, and data files.

You may reverse the selection process by prefixing the list with 'NOT'.
e.g
-ftype "not obey &FFF Data" will select everything but obey files, text
files, and data files.


  -match "[Not] <string>..."
Optional. Select all objects whose name matches with any of the given
patterns (or not - see below).
The string may contain the 'wildcard' characters # and *
(in fact it will in most cases). Note this matching occurs over the entire
object name and not just the leaf.

* acts as a 'wildcard' to match zero, or more, characters
# acts as a 'wildcard' to match any single character

Note that certain wildcard combinations are condensed prior to use:-
ie ** = *
   *# = *

You may enter more that one pattern to search for - they should be
separated by spaces and enclosed in quotes in the same way as multiple
filetypes (see above). The number of patterns is restricted only by the
length of the command line.
You may reverse the selection process by prefixing the patterns with
'NOT' (this word cannot be used as a pattern).


  -after <date/time>
Optional. Filter out any objects that are not younger than the moment
specified. See below for valid formats of the date/time string.


  -before <date/time>
Optional. Filter out any objects that are not older than the moment
specified. See below for valid formats of the date/time string.


-after & -before can be used together in the same command.


  -larger <n>
Optional. Select all objects whose size > n


  -smaller <n>
Optional. Select all objects whose size < n


-larger & -smaller can be used together in the same command.


  -recurse <n>
Optional flag. If present the list will contain objects from all of the
sub-directories of the -path given down to the nth level. If you want
everything select a large enough value for n eg >128.


  -locked y|n
Optional. If specified will filter out those objects not in the required
lock state.


  -x
Optional flag. If present, and the path name given is in the form of a
system variable (eg <font$path>) this will be expanded before being
output to the list. This allows you to delay expansion until you want.
This is handy if you move a group of objects to another place but keep
their relative structure - you only need to change the contents of the
variable and you can use the same list (you could use the list to move
the objects in the first place with a bit of tweeking).


  -d
Optional flag. If present directory objects will always be listed no matter
what other filters are in effect.
eg  *OLmake $ -f text -r 256 -d
will list all text files on the current filing system along with all the
directories. If -d were not present no directories would be listed since
they don't have a filetype. A list of only directories can be obtained by
selecting an impossible filetype along with this flag
eg *Olmake $ -f &FFFF -d


Useful Info for *Olmake

1) Use RISCOS file redirection to send the output to a data file.
   eg *OLmake $ { > RAM:$.list1 }
   will output details of the current root  directory to a file named list1
   in the root directory of the ram disc.

2) The date/time strings should be entered in one of the following
   formats :-

       i)  ccyy/mm/dd.hh:mm:ss
      ii)  yy/mm/dd.hh:mm:ss
     iii)  ccyy/mm/dd
      iv)  yy/mm/dd
       v)  hh:mm:ss
      vi)  "now"
     vii)  "today"
    viii)  "this morning"
      ix)  "this afternoon"
       x)  "first sec"

   You may substitute the following two letter combinations into the
   string for formats i) thru v) - these will be replaced from the current
   date/time values AT THE TIME THE COMMAND WAS ISSUED :-

       i) cc = current century
      ii) yy = Current year
     iii) mm = Current month if in date; or current minute if in time
      iv) hh = Current hour (24 hour clock)
       v) ss = Current second

   Formats vii) to ix) will substitute different values depending on the
   context in which they are being used e.g.
   -Before "this morning" will evaluate to -Before ccyy/mm/dd.00:00:00
   -After "this morning" will evaluate to -After ccyy/mm/dd.11:59:59

   Format x) will substitute the time 0000/00/00.00:00:01 and its main
   use is in distinguishing non-typed files which are given a date/time
   of zero.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*OLcompare    -    Compare two object lists and output a third

Syntax:
*OLcompare -List1 <filename> -Operation <opcode> -List2 <filename>
[<options>]


  -List1 <file name>
Required. Identity of primary file


  -List2 <file name>
Required. Identity of secondary file.


  -Action <action>
Required. Notes the comparison action to be taken. This can be one of:-
EQual   - Select entries which match in both files.
NOt     - Select entries that have no match in the other file.
MErge   - Combine the entries from both files dropping duplicates.
DAte    - Select entries from list 1 that have a different datestamp from
          their counterparts in list2.
YOunger - Select entries from list 1 that are younger than their
          counterparts in list2.
OLder   - Select entries from list 1 that are older than their counterparts            in list2.
SIze    - Select entries from list 1 that have a different size from
          their counterparts in list2.
SMaller - Select entries from list 1 that are smaller than their
          counterparts in list2.
LArger  - Select entries from list 1 that are larger than their counterparts           in list2.
NEwer   - Select entries from list 1 that have changed from their
          namesakes in list2 - no checking is done on object type,
          filetype, or size.
(the capital letters denote the minimum letters required by the command.)


  -x
Optional flag. If present, and the path name given is in the form of a
system variable (eg <font$path>) then it is expanded BEFORE
comparison of the name strings takes place. (see above description of
OLMAKE).


Useful Info for *Olcompare

1) Use RiscOS file redirection to create lists as for *Olmake above.

2) It is vital that you do not change the order of the lists in any way
   from when they were output by OLmake - you can put comment lines in
   however.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*OLprocess    -    Generate strings from object list data

Syntax:
*OLprocess -List <objectlist> -Template \"<string>\"
[-Obeyfile <filename>] [-Ftype <n>] [<options>]


  -List <objectlist name>
Required. Denotes the objectlist to use in the command.


  -Template <string>
Required. Gives the template to use when constructing strings.
It should contain at least one substitution marker to be useful.
Substitution markers are introduced into the template by the
percentage sign %.
Currently these markers can be any of :-
%o   Full object name.
         e.g. adfs::HardDisc4.$.!Impression.Docs.MyLetter

%p   Path name excluding system portion.
         e.g. $.!Impression.Docs

%l   Object 'leaf' name e.g. MyLetter

%s   System name with end colon e.g. adfs:

%m   Media name e.g. HardDisc4

%d   Provides an account of the current subdirectory depth.

%c   A general purpose incremental line counter. Set to zero at start.

%,n^ Entry component n.

%.n^ The nth directory back up from the leaf. Stops at $.
          e.g. In the example above %.1^ = Docs

%+   A means to add the percentage sign into the string.
NOTE: %p, %s, %m, %d or %.n^ will force the -x flag on.


  -Obeyfile <file name>
Optional. The generated strings will be output to an obey file using
the name given.


  -Ftype <x> | <string>
Optional. Selection behaviour is identical to the corresponding parameter in *Olmake (see above).


  -d
Optional. Always include directory objects (overrides any other settings
which might act to filter out directory names eg -Filetype).


  -x
Optional flag. If present, and the path name in the list data is given in
the form of a system variable (eg <font$path>) then it is expanded
BEFORE being output into the string. (see above description of
OLMAKE).


Useful Info for *Olprocess

1) This command carries a health warning! Be careful when using it
   with destructive commands like *Delete, *Remove etc. that you
   have made the right selection.
2) As well as creating * command strings this command can be used
   to reformat an object list, or to extract data from it, eg object size.
   Thus this provides a way of preparing system info to input into
   databases/spreadsheets and mucked about with to your hearts desire !
   (assuming you can't import the lists 'as is')


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Notes on v1.01:

1) PC emulator users who have set up PC 'Discs' will find that,
   sadly, these just show up as directories - no pc files will be listed.
   Sorry ! - but the module makes use of SWI OS_GBPB 11 which doesn't
   seem to work with PC directories. There must be a way since RiscOS 3
   gives the info on PC files just like any other - if anyone can tell me
   how it's done I would be very happy to add this.

2) In order to conserve module memory allocation when recursing down
   many directory levels a shrinking workspace strategy is employed.
   If the directory level exceeds 9 the amount of workspace obtained to
   store the directory object details is successively reduced at each level
   until a minimum value is reached. Hence, if you have a very deep
   directory structure, and the directories at the lowest levels are quite
   full, creating a list of the root directory onwards will take longer than
   a listing of the same number of objects from a more shallow structure.

   Workspace allocation details:
    Normal level allocation is 1500 bytes
    levels beyond level 9 are reduced by 40 bytes per level
    until level allocation reaches 200 bytes.
   Each object record can take up 40 bytes max so 37.5 object records
   can be stored in 1500 bytes. 37.5 is not far off half of 77 which is the
   maximum number of objects you can have in a RiscOS directory - I
   thought this middle-of-the-road figure was a good one to aim for.

3) All the commands will update a system variable with a count of
   the number of lines output. The variable is called ObjList$Val.
   This can be used as a quick check in Olmake/Olcompare to see
   if any objects conformed to the request.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
General Notes + License Agreement on Object Lister:

1) This software is supplied 'As is' - it carries no warranty, either
   expressed or implied.
   It is not guaranteed to be free of bugs - no warranty is given about
   its' suitability for use.

2) This software is public domain. It may be distributed freely
   provided it is copied whole - by this I mean :-
     This manual file.
     The Objectlister Relocatable Module.
     The entire contents of the examples directory.
     The change log file.

3) User modified versions of the items mentioned in (2) must not be
   distributed under the same name - I don't mind taking the blame for
   my own mistakes but I will not be a scapegoat for the mess of others !

4) Feel free to write your own PD applications that use it.

5) It may not be sold by itself for commercial gain of any nature. It may
   be incorporated into commercial applications provided :-

     a) You ask my permission first.
     b) The authorship is acknowledged.
     c) You copy ALL of the software (see 2 above).
     d) It is not copy protected in any way.
     e) It is excluded from any end user license agreements applying to
        your application(s).
     f) Some money is paid to a registered charity for each copy.

6) In the pipeline...
   I hope to write a desktop front end application for this module.
   I may write a Backup application also - but don't hold your breath !
   - perhaps someone else might like to try this ?

7) Constructive criticisms/suggestions, bug reports, discs for latest
   versions, praise, or money should be sent to the following address
   (preferably with S.A.E if reply required):-

   91, Little Bushey Lane,
   Bushey
   WATFORD
   Herts.
   WD2 3SD

   No phone/house calls please !

   Sorry, snail mail only - I haven't go the hang of these comms
   contraptions yet (but i'm working on it)...

   Yours,

   Tony Fewell.


P.S

I can supply this manual as an Impression document for those who want
it - just send a blank disc in a S.A.E to the above address.