ARM Club 1

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / files / k / objectlist / Manual < prev next >

Wrap

Text File | 1992-06-21 | 15.2 KB | 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.