Fresh Fish 5

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

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / util / dirking-3.00.lha / DirKING / Docs / UserManual.doc < prev next >

Wrap

Text File | 1994-02-18 | 106.6 KB | 2,369 lines

__ / //// __ /// \ \ /// < < <<< DirKING v3.00 >>> > > \ \/// \__//// USER MANUAL - Release : 16-Feb-94 Copyright ©1990-1994 Chris P. Vandierendonck, [AmiSYS]. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Copyright Notice ~~~~~~~~~~~~~~~~ DirKING is released as SHAREWARE, not excluding the copyright and all other rights which remain with the author Chris P. Vandierendonck. The program and files included with this distribution are not freely distributable. Shareware means that you must register if you use the program. Prior written permission from the author is required to distribute DirKING or to use it in commercial releases, on coverdisks or diskmagazines. When distributed, all files must be kept together, in the original unmodified form. (AmigaDOS and Workbench are trademarks of Commodore Amiga Inc.) Disclaimer ~~~~~~~~~~ DirKING is provided "AS IS", WITHOUT ANY WARRANTY to its quality, performance or fitness for a particular purpose. In no event shall the author be liable or responsible to the user or any other person, for any kind of damage caused by the use of this software. Registering for DirKING is necessary to ensure future development. More information on how to register can be found in this document or in the "Registration.doc". Registrations, suggestions, remarks and bug reports about this program can be send to the following address : Chris Vandierendonck Koning Albertstraat 188 B-8210 VELDEGEM BELGIUM Preface ~~~~~~~ DirKING is a feature packed directory list program, which overlaps the AmigaDOS commands List, Dir and Info. It has all the features of the AmigaDOS commands, but also includes many enhancements. The program supports different filters for reading a directory, allows complex sorting and gives full control on the listing format. DirKING is reentrant, so it can be made resident. System Requirements ~~~~~~~~~~~~~~~~~~~ DirKING requires AmigaDOS v1.2 or higher. DirKING fully supports all AmifaDOS v2.x and v3.x innovations. DirKING v3.0x User Manual - Page 1 Shareware Registration ~~~~~~~~~~~~~~~~~~~~~~ You can register in two ways: o Minimal registration. This includes: - the registered version of DirKING. - one free future update of DirKING. Sharewarefee : USD 12.00, GBP 6.00, DEM 15.00, BEF 300. o Full registration. This includes: - the registered version of DirKING. - one free future update of DirKING. - a laserprinted copy of the manual. - a reference card with all options and codes. Sharewarefee : USD 25.00, GBP 12.00, DEM 30.00, BEF 600. Payment ~~~~~~~ o You can transfer the money in three ways : - in cash (PAPER money ONLY) -> fast and cheap; - by EuroCheck (only in Belgian Francs [BEF] !!); - by (international) postal money order. DO NOT SEND FOREIGN BANKCHECKS, since it's too expensive to clear them. o All above mentioned amounts include P&P. So you don't have to pay extra, wherever you live. Registration form ~~~~~~~~~~~~~~~~~ o If possible, use a printout of the included 'RegForm' file to register, since it makes registering (ordering) much easier. o From the moment I receive the registration (order) form and the necessary payments, your order will be processed. Page 2 - DirKING v3.0x User Manual ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ USER MANUAL CONTENTS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ §1 Preliminary remarks. . . . . . . . . . . . . . . . . . . 4 §2 DirKING keyword and argument syntax. . . . . . . . . . . 5 §3 Directory scanning . . . . . . . . . . . . . . . . . . . 6 A. Specifying the directory path . . . . . . . . . . . . 6 A.1. Normal directory paths . . . . . . . . . . . . . 6 a. General use . . . . . . . . . . . . . . . . . 6 b. Advanced use : recursive directory paths. . . 7 A.2. Deep level pattern matching. . . . . . . . . . . 7 A.3. Multiple and late assigns. . . . . . . . . . . . 8 A.4. Linked directories . . . . . . . . . . . . . . . 8 A.5. System requesters. . . . . . . . . . . . . . . . 9 B. Filtering directory information . . . . . . . . . . . 9 B.1. Global filters . . . . . . . . . . . . . . . . . 9 B.2. Filter options . . . . . . . . . . . . . . . . . 10 B.3. File- and directoryname filtering. . . . . . . . 10 B.4. Conditional date filters . . . . . . . . . . . . 12 B.5. Comment filters. . . . . . . . . . . . . . . . . 13 B.6. Protectionflag filters . . . . . . . . . . . . . 13 B.7. Datatype type filters. . . . . . . . . . . . . . 14 C. Hunting for particular files and directories. . . . . 14 D. Tracing the scanning process. . . . . . . . . . . . . 15 §4 Directory information. . . . . . . . . . . . . . . . . . 15 A. Volume (disk) information . . . . . . . . . . . . . . 16 B. Listing header/end information. . . . . . . . . . . . 17 C. File- and directory fields. . . . . . . . . . . . . . 19 D. Additional directory information. . . . . . . . . . . 20 E. Limiting listed directory levels. . . . . . . . . . . 21 §5 Directory sorting. . . . . . . . . . . . . . . . . . . . 21 §6 Listing formatting . . . . . . . . . . . . . . . . . . . 22 A. Listing table formatting. . . . . . . . . . . . . . . 22 A.1. Setting the listing table width. . . . . . . . . 22 A.2. Setting the list order of the table fields . . . 23 A.3. Formatting the listing table . . . . . . . . . . 24 B. Predefined listing table formats. . . . . . . . . . . 26 C. Free formatting and script generation (LFORMAT) . . . 26 §7 DirKING MULTI-mode (multiple directory scanning) . . . . 28 §8 Listing styles . . . . . . . . . . . . . . . . . . . . . 29 A. Information format. . . . . . . . . . . . . . . . . . 29 B. Listing print styles. . . . . . . . . . . . . . . . . 30 §9 Listing output redirection . . . . . . . . . . . . . . . 31 §10 Listing paging . . . . . . . . . . . . . . . . . . . . . 32 §11 Disk identification coding support . . . . . . . . . . . 34 §12 Environment variables. . . . . . . . . . . . . . . . . . 34 §13 DirKING program information. . . . . . . . . . . . . . . 35 Appendix: DirKING keyword reference. . . . . . . . . . . . . 36 DirKING v3.0x User Manual - Page 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIRKING USER MANUAL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ §1 Preliminary remarks. ~~~~~~~~~~~~~~~~~~~~ o Although DirKING can be used in the same way as the AmigaDOS command List, the real power and flexibility of DirKING is found in the additional features. For the more advanced features, you'll need to experiment a bit, but you'll soon get the hang of it. o Like the AmigaDOS command List, DirKING can only be used from a Shell (CLI) or script. DirKING can also be made resident by using the AmigaDOS command 'Resident', since DirKING is reentrant. o From the DirKING usage prompt you'll notice that all option keywords are printed in upper case. This doesn't mean you have to type them as well in upper case, lower case will do since DirKING doesn't parse the arguments on a case sensitive basis. The rule is that everything may be printed in lower case, unless explicitly stated otherwise. Except for one argument, all arguments can be typed on the command line in any order you want. This means that for example you could type in the directory path at the end. DirKING will still recognize it. Some options however, consist of two separate arguments, which are a keyword argument and a data-argument. Naturally these arguments have to be typed in that order. The exception as mentioned earlier, is the LFORMAT argument. This argument has always to be typed last, since everything after the keyword is regarded as being the format string. Due to the fact that the arguments can be typed in any order, you must be careful not to override a previous typed option. For instance, if you first type 'INCL' and then 'EXCL', the latter can alter the settings of the INCL option if you don't watch it. o Some DirKING options need a data-argument in the form of a string. In case this string should contain spaces, then you've to enclose it between double quotation marks. o DirKING also supports pattern matching. Under AmigaDOS v1.x, only a limited range of pattern matching codes are supported: ? : matches just one character; # : the next character may occur zero or more times; ' : take the next character literally; * : although not supported by AmigaDOS, DirKING accepts this equivalent for '#?'. (This wildcard is also used in all examples.) | : separator for using multiple patterns. ( : may be used but is ignored. ) : may be used but is ignored. Page 4 - DirKING v3.0x User Manual Under AmigaDOS v2.0 and later the full range of AmigaDOS patterns are automatically available. Refer to your AmigaDOS manual for more information on how to use these patterns. NOTE: as of AmigaDOS v2.0 and later, the first use of DirKING makes the wildstar '*' pattern available to the system. So other commands can also benefit of this. IMPORTANT: when using multiple patterns, always place the entire pattern between parentheses, otherwise you'll get an error under AmigaDOS v2.0 and later! o Throughout this manual, you'll find numerous examples to demonstrate the use of DirKING's features. Those examples are always printed after '|'s. What has to typed on the command line, is enclosed between single quotation marks ('). I didn't use double quotation marks ("), since they may sometimes be part of a data-argument. o If you think it's a bit tedious to type 'DirKING' each time to run the program, then it's probably better that you save DirKING under a short name, such as 'DK'. o The program can always be interrupted with CTRL-C. §2 DirKING options syntax. ~~~~~~~~~~~~~~~~~~~~~~~ To get the usage prompt type 'dirking ?', something like the following will appear: Usage: [PATH] [[F|D]<path|p>] [QUICK] [ALL] [TOLEVEL <#>] [DIRS] [FILES] [HUNT [F|D]<pattern>] Filters: [READ [F|D]<pattern>] [PASS [F|D]<pattern>] [SUB [F|D]<string>] [SINCE "[F|D]<[DOSdate] [time]>"] [UPTO "[F|D]<[DOSdate] [time]>"] [FROMTO [F|D]<ch><ch>] [DATATYPE <pattern>] [FLAGS [F|D]<flags>] [COMMENT [F|D]<pattern>] Info: [INCL {nkribladtsocpfhvwygjmex}] [EXCL {nkribladtsocpfhvwygjmex}] [DIRINFO [BASE]] [DISKUSE] [LISTLEVELS <#>] [LOCVALS] [HEXVAL] [DATES] [BINFLAGS] Sorting: [FD|DF|MIX] [SORT {nkribladtcygme}] [NOSORT] [DESC] System: [NOREQ] [ASSLATE] [LINKDIRS] [DISKINFO] [FULLPATH] [MULTI] [NOENV] Listing: [HEAD {fdvpimtse}] [MAXHEAD] [BARELIST] [NOHEAD] [NOSTAT] [EOD] [NEWPAGE [[{cmhte}]<#>]] [DISKID <string>] [EXPAND] [MAXWIDTH <#>] Output: [TRACE] [PRT] [TO <file>] [PRTSTYLE {rdlbpes}] [TEXT] [SHOWLEVEL] [DIRSTYLE [r|i|b|y|f|a|e][r|i|b|y|f|a|e]] DirKING v3.0x User Manual - Page 5 Format: [LISTF <0..4>] [SFORMAT <fmt>] [LISTORD <fmt>] [DATEF <0..7>] [DFORMAT <fmt>] [TABLEFMT <fmt>] [TIMEF <0..3>] [TFORMAT <fmt>] [EXEC <file>] [LFORMAT [<fmtstr>]] §3 Directory scanning. ~~~~~~~~~~~~~~~~~~~ The following arguments direct the way the directory is read. By default DirKING will only read the files and directories of the current directory or the specified path. Thus DirKING won't descend in the sub-directories. A. Specifying the directory path. A.1. Normal directory paths. » [F|D|B]<path|pattern>] a. General use. If you don't specify a file or directory path to scan, then the current directory will be read. | current directory : 'Workbench:c' | 'DirKING' : will read the 'Workbench:c' directory If you do specify a path, then DirKING will obviously check if this path exists, and if so, list its contents. This path must be a valid AmigaDOS path, otherwise you'll cause a DOS error. | 'DirKING workbench:s' : will read 'Workbench:S' More than one path can be given to DirKING to read. | 'DirKING work:devs env: t:' It's also possible to use pattern matching. Patterns can not only be given for a given path, but also for the current directory. Normally this pattern will be effective on both files and directories, but you can alter this by using the '[F]' or the '[D]' option. To select one of these options, you have to put an 'F' or an 'D' at the beginning of the path. (See par. B.2., p.xx for more information on filter options.) IMPORTANT: this option code has always to be typed in UPPER CASE and must be the first character of the path! Otherwise DirKING will interprete it as being part of the path. The specified patterns will be effective during the whole scanning process. Thus not just for the scanned directory, but for all further read sub-directories. If you only want the pattern to be effective in one directory level, then you must use "deep level pattern matching", which is explained later. | 'DirKING workbench:*s*' : only read those files and | directories which contain an 's' in their name Page 6 - DirKING v3.0x User Manual | 'DirKING Fworkbench:(*a*|*b*)' : only read those files | which contain an 'a' or 'b' in their name. (All | directories will be accepted. b. Advanced use : recursive directory-paths. Recursive paths to a directory or a file always start from the current directory. To climb up the directory tree (recurse) you have to make use of the '/' and ':' characters. Using ':' goes back to the root of the volume on which the current directory is situated. | current directory : 'Workbench:devs/keymaps' | 'DirKING :' : DirKING use 'Workbench:' as the path. The '/' character refers to a parent directory of your current directory. The more '/'s you use, the higher you climb the directory tree. How many '/'s you may use, depends on how far you're away from the root directory. If you enter more '/'s than there are parent directories, then DirKING will fail and output an invalid path error! | current directory : 'Workbench:devs/keymaps' | 'DirKING /' : read the 'Workbench:devs' directory | 'DirKING //' : read the 'Workbench:' directory | 'DirKING ///' : error, no parent of 'Workbench:' exists » PATH The only function of PATH is to inform DirKING that the argument following is the path, and not an argument keyword. PATH is only useful in case you want to scan directory which has the same name as an argument keyword. If PATH wouldn't be used in such a situation, then DirKING would interprete your path as an argument keyword, and not as the path (the AmigaDOS commands 'List' and 'Dirs' make this mistake). A.2. Deep level pattern matching. The term 'deep level pattern matching' is the only way I can describe the following feature. As mentioned above, this kind of pattern matching is more suited when DirKING has to descend the directory tree. Since you can specify patterns for upto 32 directory levels. The patterns are typed in the place where you would normally type the name of a directory in the path. When nothing is typed in this place then this means that there's no pattern for that directory level. Note: the patterns are also effective on both files and directories, unless you make use of the 'F' or 'D' options. | 'DirKING workbench:*s*/(p*|*x*)' will be interpreted as : | path = 'workbench:', | pattern for level 0 = '*s*', for level 1 = 'p*' & '*x*' | 'DirKING workbench:s/p*' will be interpreted as : | path = 'workbench:s', pattern for level 0 = 'p*' DirKING v3.0x User Manual - Page 7 | 'DirKING work:/(p*|*x*)//(*c*|*y)' is interpreted as : | path = 'work:', | pattern for level 0 = '' (no pattern), | " for level 1 = 'p*' & '*x*', | " for level 2 = '', (no pattern) | " for level 3 = '*c*' & '*y', 'Deep level pattern matching' can also be used in conjunction with a recursive path. It then is very important to have a clear notion of what you enter, since DirKING has to use a part of your path string as the path to scan, and the rest of it as the patterns. The recursive indicators ':' and '/' should always be at the front of the path string, without any characters in between. From the moment another character is typed in, then from thereon the string will be used as a path (with or without deep level pattern matching). | 'DirKING :/*c*' means path = ':' or volume (root) | level 0 pattern = '' (no pattern), | level 1 pattern = '*c*' | current directory = 'Workbench:devs/keymaps' | 'DirKING //*s*//*y*' means path = 'Workbench:' | level 0 pattern = '*s*', | level 1 pattern = '' (no pattern), | level 2 pattern = '*y*' | current directory = 'Workbench:devs/keymaps' | 'DirKING //devs//*s*//*y*' means path = 'Workbench:devs' | level 0 pattern = '' (no pattern), | level 1 pattern = '*s*', | level 2 pattern = '' (no pattern), | level 3 pattern = '*y*' I know it gets very complicated, but the only way to fully master this feature is to experiment a bit. The best way to do this is by sending the listing of a large directory tree to the printer, and then starting to experiment on that directory with its listing in front of you. A.3. Multiple and late assigns. Under AmigaDOS v2.0 and later, DirKING will recognize if a given assignname is a multiple assign, thus an assign which points to several directories. Each directory of the multiple assign will then be read and listed. » ASSLATE If a given assignname is a late assign, thus an assign which is only incorporated in the system when first used, DirKING will output an error. If you do want to read a late assign, then use the ASSLATE option to force the reading. A.4. Linked directories. » LINKDIRS By default, if DirKING encounters a directory linked to Page 8 - DirKING v3.0x User Manual another, then it won't descend into this directory, unless you use the LINKDIRS option. Before descending down such a linked directory, DirKING will examine if it is a circular linked directory. If so, the directory will be ignored, thus avoiding infinite scanning! A.5. System Requesters. » NOREQ If you have given a path with a non-existing volume or devicename, then a system requester will prompt you to insert this disk. If you want to avoid such requesters, use the NOREQ option. DirKING will exit immediately with an error message if it can't scan your path. B. Filtering directory information. Although you can filter what has to be read by using patterns in the path, most of the time you want more than that. For this purpose DirKING supports three kinds of powerful filters, which are explained below. B.1. Global filters. As their name suggest, these filters have an overall control on the scanning process. With most you'll be familiar, since they're also present in the AmigaDOS directory list commands. » ALL By default DirKING will only read one directory level (which is the Shell's current directory or a specified path). If you use ALL then DirKING will descend into all sub-directories it finds, until no more are found. | 'DirKING work: ALL' : the whole 'work:' disk will be | scanned. » DIRS At first glance one would assume that DirKING will only read directories. In a way this is true, but it's better to interprete in the way that DirKING is allowed to include directories. (Because using 'FILES' in conjunction with 'DIRS', will also include files.) The 'DIRS' option in conjunction with 'ALL' is a good way to get a clear view of the directory tree (since no files are listed). » FILES This DirKING option acts the same as DIRS, but now for files. If this option is used, then DirKING will only read files, and ignore all directories. This means that DirKING will only read one directory level, and that the options "ALL" and "TOLEVEL" DirKING v3.0x User Manual - Page 9 won't work. Exception: the above isn't true for the LFORMAT option. Here the FILES option means that only files will be listed. If directories are encountered, then DirKING will enter them if the "ALL" or "TOLEVEL" option is used. » TOLEVEL <#> This option works in the same way as 'ALL', except that 'TOLEVEL' specifies how many directory levels may be scanned. I speak of 'may' because it doesn't matter if the TOLEVEL value is greater than the actual number of directory levels present. | Assume current directory is 'Workbench:Devs' | 'DirKING TOLEVEL 0' : will only read entries in this | directory level, without descending down the directory | tree. | 'DirKING TOLEVEL 1' : does the same, but will also read | the 'KeyMaps' and 'Printers' directories. B.2. Filter options. -> F|D|B All the following filters (including the conditional date filters) support the use of 'F', 'D' and 'B' (or '') options. First I'd like to remind you of the meaning of the three options : - '' : if you don't enter an option code, then DirKING will use the filter on both files and directories; - 'F' : the filter will only be used for files; - 'D' : the filter will only be used for directories. - 'B' : in case the filter should begin with an 'F', a 'D' or a 'B', then to make sure that the filter is used on both files and directories, one must use this 'B' option. NOTE: the option code must always be typed in UPPER CASE, and must always be the first character of the data-argument! The use of these options with filters, add another dimension to that filter, since you can use the filter upto three times on the command line, provided that each filter argument has a different option. In other words you can enter a filter for both files and directories, one for files only, and another for directories. B.3. File- and directoryname filtering. The following filters operate on the name of files and directories, thus presenting more powerful filtering than the previous filter type. » READ [F|D|B]<pattern> This argument instructs DirKING to only read (include) those directory entries (files and/or directories) which match the given pattern(s). An unlimited number of patterns can be Page 10 - DirKING v3.0x User Manual specified. The vertical bar "|" is used to separate these patterns. (If one of the patterns should contain spaces, then you must enclose the whole data-argument between quotation marks.) | 'READ *s*' : include only those directories and files if | their name includes 's'. | 'READ (*s*|*a*)' : include only those directories and | files if their name either includes 's' | or 'a'. | 'READ F*a* READ D*b* READ *c*' : | Files are only included if their name matches the '*a*' or | the '*c*' patterns. Directories are only included if their | name matches the '*b*' or the '*c*' patterns. | 'READ F(*a*|*b*|*c*)' : | Files are only included if their name matches one of the | three specifies patterns (*a*, *b*, *c*). All directories | will be included, since this argument is only effective | for files! » PASS [F|D|B]<pattern> The PASS argument works in the same way as the READ argument, except that all directory entries (files and/or directories) that match the given pattern(s) are ignored (excluded). | 'PASS (*s*|*a*)' : ignore those directories and files if | their name either includes 's' or 'a'. | 'PASS F*a* PASS D*b* PASS *c*' : | Files are ignored if their name matches the '*a*' or the | '*c*' patterns. Directories are ignored if their name | matches the '*b*' or the '*c*' patterns. » SUB [F|D|B]<string> In order to be included in the listing, the names of the files and/or directories must contain the specified string(s). | 'SUB s|a' : include only those directories and files if | their name either contains 's' or 'a'. | 'SUB Fa|d SUB Db SUB c' : | Files are only included if their name contains 'a', 'd' or | 'c'. Directories are only included if their name contains | 'b' or 'c'. » FROMTO [F|D|B]<ch><ch> The 'FROMTO' option enables filtering on the first character of the name of files and/or directories. Since AmigaDOS names aren't handled case sensitive, typing 'A' is the same as typing 'a'. The <ch>aracter is only valid if it's in the range [0..9] or [a..z]. DirKING v3.0x User Manual - Page 11 | 'FROMTO ad' : only include directories and files, if the | first character of their name is equal or greater than | 'a', but not greater than 'd'. | 'FROMTO 5a' : only include directories and files, if the | first character of their name is equal or greater than | '5', but not greater than 'a'. | 'FROMTO Fad' : only include files if the first character | of their name is equal or greater than 'a' but not greater | than 'd'. All directories will be included, since this | filter doesn't apply to them. If the second <ch>aracter is smaller than the first <ch>aracter, then this second <ch>aracter will be replaced by the last valid character in the range. | 'FROMTO sa' : will be interpreted as 'FROM s TO z'. B.4. Conditional date filters. Conditional dates provide filters for the date- and timestamp of a file or directory. The syntax of the conditional date can be one of the following : 1° DOSdate : only a datestamp is given, in the usual AmigaDOS format, which is DD-MMM-YY (e.g. 14-aug-92). If the date is within the last week of the current date, then you may use the actual dayname of that date (Sunday...Saturday); you may also use 'Today' and 'Yesterday'. The dates after the current date can be replaced by 'Tomorrow' and 'Future' (represents the day after tomorrow and later). 2° Time : only a timestamp is given, in the usual AmigaDOS format, which is HH:MM:SS (e.g. 18:15:42). (The seconds can be omitted, in which case '00' is used). 3° DOSdate & time : a date- and timestamp is given, in the above specified formats. (Note that you can also enter the date- and timestamp in reverse order.) 4° Day offset : instead of specifying a certain date, one could define a date by giving the number of days before, or after the current day. The date is then given as a negative or positive value. A simple table makes this clear: ... -3 -2 -1 0 1 2 3 ... ------|---|---|---|---|---|---|-----> date | today | yesterday tomorrow 5° Day offset & time : similar in use as the third syntax. REMARK: the date- and timestamp must be typed in the above Page 12 - DirKING v3.0x User Manual mentioned formats, otherwise DirKING won't recognize your date/timestamp! » SINCE "[F|D|B]<[DOSdate] [time]>" Using SINCE means that only those directory entries (files and/or directories) will be included if their date- and/or timestamp is equal or later than the given conditional date. | 'SINCE 14-aug-92' : include only files and directories | which were created on or after 14 August 1992. | 'SINCE 14:30:00' : include only files and directories | which were created on or after 14:30:00. | 'SINCE "14-aug-92 14:30:00"' : include only files and | directories which were created on or after 14-Aug-92, | 14:30:00. | Assume that today is 16-Aug-92 | 'SINCE yesterday' : include only files and directories | which were created on or after 15-Aug-92. | 'SINCE Ftoday' : include only files that were created | today or later. All directories found will be included, | since this filter is only effective for files. » UPTO "[F|D|B]<[DOSdate] [time]>" Everything said for SINCE applies for UPTO, with this difference that now only files/directories will be included if their date/timestamp is equal or earlier than the conditional date/timestamp. B.5. Comment filters. » COMMENT [F|D|B]<pattern> In the same way as you would filter on a file- or dirname, one can specify a filter for file- and dircomments. If no comment is present then this directory entry is ignored. | 'DirKING RAM: ALL COMMENT F*1994*' : this will only list | files which have '1994' in their comment. B.6. Protectionflag filters. » FLAGS [F|D|B]<flags> DirKING makes it also possible to filter files and directories on their attributes (protection flags). The filter works on the visual representation of the flags, not on the real settings as programmers use them! The flags filters uses negative and positive flags. The first means that these flags may not be present in the flagset, the latter signifies the opposite. DirKING v3.0x User Manual - Page 13 As a reminder, the flagnames used by AmigaDOS are: - h : hidden - r : readable - s : script - w : writable - p : pure - e : executable - a : archived - d : deletable The filterflags can be given in any order, where negative flags are preceded by a '-' sign, and positive flags by a '+' sign. | 'FLAGS +sr-e' : '-s--rw-d' will match, '-s--rwed' not! | 'FLAGS -p+rwd' : '---arwed' will match, '--parwed' not! B.7. Datatype type filters. » DATATYPE <pattern> Under AmigaDOS v3.0 and later, it's possible to specify a filter for the datatype type of a file. Since datatype are only useful with files, the filter only works on files. The pattern is a normal string pattern. | 'DATATYPE *i*' will accept only files with a datatype type | which includes a 'i'. E.g. 'IFF, 'ASCII', etc... C. Hunting for particular files and directories. » HUNT [F|D|B]<pattern> When you want to find out where certain files or directories are in a directory, then you must use the HUNT option. The output is given in a LFORMAT way. By default the following format is used: "%F%N", thus the full path and name is given. | 'DirKING RAM: HUNT *i*' : this will look for all files and | dirs in your RamDisk which have an 'i' in their name. | Example output: | | RAM:Disk.info | RAM:CLIPS | RAM:ENV/Kickstart | RAM:ENV/Sys/icontrol.prefs | RAM:ENV/Sys/input.prefs | RAM:ENV/Sys/printer.prefs | RAM:ENV/Sys/wbconfig.prefs If you want to change this output format, then also use LFORMAT when calling DirKING. Remark: the HUNT automatically uses the ALL option. Should you want to avoid that DirKING descends too deep into a directory, then define a TOLEVEL value. Note: the HUNT option also supports the F|D|B filter options! Page 14 - DirKING v3.0x User Manual D. Tracing the scanning process. » TRACE This is a rather exotic feature of DirKING. TRACE is used to monitor the scanning process. This option is extremely useful when scanning large directories, and you want to know what's going on. The information printed consists of the following : - the currently scanned path; - the number of directories included so far, and the last one found; - the number of files included so far, and the last one found; Note: this feature will slightly slow down the scanning process, but once you used it, you'll be addicted to it. §4 Directory information. ~~~~~~~~~~~~~~~~~~~~~~ By default, DirKING will print the listing in roughly the same format as the AmigaDOS 'List' command, but with more style and information. First of all DirKING will print the scanned path and the date/timestamp of the listing. Then the actual listing is printed in a table form, with a title line indicating what all the printed fields mean (the List command doesn't print such a title line!). After the listing has been printed, a statistic line will be printed, which states the number of files and directories found, the amount of bytes and blocks used by the files and the number of bytes free on the volume. This default listing format can be altered by the options as described below. But for good understanding, it's necessary to explain some terms used : » DirectoryEntry : refers to files and directories. » Field : each separate information of a directory entry (e.g. name, blocks used, datestamp,...). » Listing : what DirKING prints on the scanned directory (consists of the listing header, the actual listing and the listing end) » ListingHeader : a block of information about the scanned directory (and volume) » ActualListing : that section of the listing, only holding the directory entries, including the title line (which states the meaning of the different fields) » ListingEnd : the block of information printed at the end of the listing (thus after the actual listing). » DiskInfoBlock : a block of extensive information on the volume that was accessed to read the directory DirKING v3.0x User Manual - Page 15 A. Volume (disk) information. » DISKINFO The DISKINFO option can be compared with the AmigaDOS command 'Info', except that it gives more information than this command. The information is printed in a block consisting of three lines of information : Line_1 : - 'Volume' : volume name - 'Created' : date/time stamp of creation Line_2 : - 'DOSType' : DOS type of the disk: - OFS : OldFilingSystem - FFS : FastFilingSystem - KICK : KICKstart disk - MSDOS : MS-DOS disk - I_OFS : International OFS - I_FFS : International FFS - DC_OFS: Directory Caching OFS - DC_FFS: directory-Caching FFS - 'DiskStatus' : status of the disk (Read/Write, ReadOnly, Validating) - 'Errors' : number of soft-errors on the disk - 'RootKey' : block number of the root directory - 'DiskSize' : number of blocks on the disk - 'BlockSize' : number of bytes in a block - 'BlocksFree' : number of blocks free on the disk - 'BytesFree' : number of bytes free on the disk - 'Full' : disk full percentage Line_3 : - 'oldest datestamp' : not filled - 'latest datestamp' : not filled - 'TotalFiles' : not filled - 'TotalDirs' : not filled - 'Links' : not filled - 'BlocksUsed' : number of blocks used on the disk - 'BytesUsed' : number of bytes used on the disk Note: some fields of the 'DiskInfoBlock' aren't filled when DISKINFO is used. Only when the volume has been scanned, will the items be filled. Using 'HEAD vpi' or 'MAXHEAD' will also show this diskinfoblock. Tip: to get the same result as DISKINFO, but with all the items filled, then you must the following startup: | 'DirKING RAM: ALL HEAD vk' | Note that the RamDisk has been fully scanned, so on e.g. | 'DF0:' it would take a bit longer to see the result. IMPORTANT: when 'DISKINFO' is used, then all other DirKING options will be ignored, except for the path argument (DirKING must know from which volume you want information). Since DirKING doesn't read a directory, the volume information is given instantly. | 'DirKING DISKINFO' : gives information about the volume on | which the current directory is Page 16 - DirKING v3.0x User Manual | situated. | 'DirKING DF1: DISKINFO' : gives information on the disk | which is inserted in drive | 'DF1:'. » DISKUSE By default the 'blocksUsed' and 'bytesUsed' infofields show how many blocks and bytes are used by the files found in the scanned directory. This however isn't the exact value of used diskspace. This is where the new option DISKUSE makes an entry. When this option is used, then the 'blocksUsed' infofield will show the exact number of blocks used by the files and directories in the scanned directory. In other words, this value also includes the blocks used by DOS (header blocks) to maintain the directory tree. The 'bytesUsed' is then equal to the number of blocks used, multiplied by the blocksize. Now DirKING gives the same value as the 'List' command. NOTE: the above mentioned infofields can be found in the listing header with the DiskInfoBlock or in the listing end with the statistic line. B. Listing header/end information. By default DirKING will use a listing header stating the following information : scanned directory (using the correct upper/lower case notation) and the date/timestamp of the listing. The listing end consists of a statistic line, giving the number of files and directories found, number of links found and the number of bytes and blocks used by them. With the following options, you can alter what is printed as a listing header an as a listing end. » FULLPATH When you normally enter a path to a directory or file, you'll use lower case characters (since AmigaDOS isn't case sensitive on this subject). However, DirKING will search for the correct upper/lower case notation of that path, before printing it in the listing. By default, DirKING will only correct the path that you've specified. It won't look for the correct path from the root on. Sometimes you'll want to know the correct path starting from the volume-root. You can do this by using FULLPATH. This option instructs DirKING to construct the path from the volume-root upto the directory or file specified. | Assume we're scanning your Workbench (system) disk. | 'DirKING devs:' : DirKING will print 'DEVS:' as the | scanned path. | 'DirKING devs: FULLPATH' : 'Workbench:Devs' is printed as | the scanned path. | Assume current directory is 'Workbench:Devs'. DirKING v3.0x User Manual - Page 17 | 'DirKING' : (read current directory) '' is printed as the | scanned path. | 'DirKING FULLPATH' : 'Workbench:Devs' is printed as the | scanned path. | Assume current directory is 'Workbench:Devs' | 'DirKING keymaps' : will read the 'Workbench:Devs/Keymaps' | directory, where DirKING will print | 'Keymaps' as the scanned path. | 'DirKING keymaps FULLPATH' : reads the same directory, but | 'Workbench:Devs/Keymaps' will | be printed as the path read. | Assume your Workbench disk in drive 'DF1:'. | 'DirKING df1:' : 'DF1:' is printed as the scanned path. | 'DirKING df1: FULLPATH' : 'Workbench:' is printed as the | scanned path. » HEAD {mnbdvpktise} The default listing header and listing end have already been explained at the beginning of '§4B'. The HEAD option now allows you to specify what information you want in the listing header and the listing end. Note: although the argument keyword is called 'HEAD', it defines both the listing header and listing end! To define which listing header and listing end you want, you have to use the following codes (the codes are given in the order they'll appear in the header) : > Predefined settings - M : equals 'HEAD dvpkti' - N : equals 'HEAD di' - B : equals 'HEAD i' > Listing head codes - D : show date of scan - V : show volumename and creationdate - P : show scanned path - K : show diskinfoblock (see DISKINFO) - T : show listing item titles - I : show listing items > Listing end codes - S : show end statistics - E : show end-of-dir message at the end of the listing. » MAXHEAD This argument is equal to using 'HEAD M' or 'HEAD dvpkti'. » NOHEAD This argument is equal to using 'HEAD N' or 'HEAD di'. » BARELIST This argument is equal to using 'HEAD B' or 'HEAD i'. Page 18 - DirKING v3.0x User Manual » NOSTAT Prevents that the statistic line is printed at the end of the listing. This option will primarily be used to suppress the default listing end (which is this statistic line). » EOD Lets DirKING print the '~~~~ End of Directory ~~~~' message after the actual listing. C. File- and directory fields. The following arguments define which fields of a directory entry are printed. By default DirKING will print the following fields: NRIBLADT. Above the table, the name of the fields are given. » QUICK If 'QUICK' is used then only the file/directory name field is printed, provided this option isn't overriden by other options such as LFORMAT or TABLEFMT. » INCL {nkribladtsocpfhvwygjmex} The INCL option is used to specify which fields you want to have listed. The following field codes are supported : - X : the equivalent of 'INCL nribladt' which is the default setting - N : list file/dir-name - K : list diskkey - R : number of sub-dirs in a dir (prints '-' with files) - I : number of files in a dir (prints '-' with files) - B : blocks used by a file (prints 'Dir' with dirs) - L : bytes used by a file (prints 'Dir' with dirs) - A : list file/dir attributes (protectionflags) The first flag reflects if it's a file ('f') or a dir ('d'). The second flag reflects if it's a hardlink ('H'), a softlink ('S') or a pipe ('P'), or nothing of the above ('-'). The rest are the usual protection flags. - D : list file/dir datestamp - T : list file/dir timestamp - S : file/dir DOS datestamp (days,mins,ticks) - O : show comment, or empty string when none is present (this comment is shown in its own column in the listing table) - C : show comment if on is present (this comment is shown on a line of its own, thus not in the listing table) - P : show the file/dir path relative to the scanned path - F : show the file/dir path, including the scanned path - H : show file and directory links For now only hardlinks are supported. - V : list datatype descriptor - W : list datatype basename - Y : list datatype type - G : list datatype group ID DirKING v3.0x User Manual - Page 19 - J : list datatype ID - M : list naked file/dirname (without last extension) - E : list the last file/dirname extension | 'INCL nd' : only print the name and datestamp fields. | 'INCL n' : only print name field (equivalent of 'QUICK'). | 'INCL nribladt' : is the same as the default setting | (explained earlier). » EXCL {nkribladtsocpfhvwygjmex} The 'EXCL' option is used to specify which fields you don't want to have listed. 'EXCL' is only useful for excluding fields from the default settings or environment variable settings, because if you've used 'INCL' earlier, then you've already specified which fields you want. | 'EXCL x' : you'll get an empty listing, only the listing | header and listing end will be printed. | 'EXCL kbladt' : is the same as using the QUICK argument, | in other words, only the name of the files | and directories is printed. » Field titles The following titles are given for the fields: field title ----- ---------------------- N F i l e N a m e K Key R Dirs I Files B Blocks L Bytes A Flags D Date T Time S DateStamp O Comment P FilePath F ScanPath H FileLink V dtDescription W dtBaseName Y dtType G dtGroup J dtID M N a m e E Suffix D. Additional directory information. » DIRINFO [BASE] As you've seen from the default listing, there're two fields called "Dirs" and "Files", they state the number of sub-dirs Page 20 - DirKING v3.0x User Manual and the number of files that were found in a dir. The fields 'Blocks' and 'Bytes' only show a value for files, but when DIRINFO is used the string 'Dir' will be replaced by a value representing the number of blocks/bytes used by the files found in the dir. Note: the use of the fields 'R' and 'I' will automatically set the DIRINFO option. The information given will reflect on all scanned levels of that directory. If you only would like these values to reflect the base of the directory, thus ignoring the sub-dirs of sub- dirs..., then you must use the BASE option. Note: the BASE option can be used on its own, since it will also automatically select the DIRINFO option. | try 'DirKING RAM: ALL INCL nribl' and notice the different | result with 'DirKING RAM: ALL INCL nribl BASE'. E. Limiting listed directory levels. » LISTLEVELS <#> In some cases you'll have scanned more directory levels then you want to have listed, e.g. when you only want to know the size used by directories of the first level. For this purpose you must use LISTLEVELS, which lets you define how many levels you want to list. If a value of 0 is given, then no directory will be listed. | 'DirKING RAM: ALL MAXHEAD LISTLEVELS 0' | 'DirKING RAM: ALL MAXHEAD LISTLEVELS 1' §5 Directory sorting. ~~~~~~~~~~~~~~~~~~ By default DirKING will sort the names of files and directories in ascending alphabetical order. In the listing itself, all files will be printed first, and last the directories. » SORT {nkribladtcygme} DirKING is able to execute a complex sort on all the fields of a directory entry. On which field to sort, is specified by their appropriate code. Important however is to type these codes in the order you want DirKING to sort the fields. The following codes (and fields) are supported : - N : sort on file/dir name - K : sort on file/dir diskkey - R : sort on number of sub-dirs in a dir (only dirs) - I : sort on number of files in a dir (only dirs) - B : sort on blocks used by a file (sometimes also dirs) - L : sort on bytes used by a file (sometimes also dirs) DirKING v3.0x User Manual - Page 21 - A : sort on file/dir attributes (sorts on the binary value of these attributes) - D : sort on file/dir datestamp - T : sort on file/dir timestamp - C : sort on file/dir comment if it's present - Y : sort on a file's datatype type (only files) - M : sort on file/dir naked name - E : sort on file/dir name last extension REMARK: since AmigaDOS file/dirnames are unique in the same directory level, any sort codes after the 'N' code aren't executed (because this would be a waste of valuable processing time!). Note: specifying the fields to sort on, doesn't mean that these items will be printed in the listing. What is actually printed depends on the options explained in '§4C'. | 'SORT ds' : first sort on the date, then on the size. | 'SORT tna' : first sort on the time, then on the name. No | sort is executed on the attributes, since | filenames are unique. » NOSORT If used then the listing won't be sorted. Thus giving a slight scanning speed increase. » DESC By default the directory is sorted ascending (thus from low to high). If you want a descending sort (from high to low), you have to use DESC. » FD|DF|MIX The files and directories can be printed at three different places in the listing. You can select the appropriate format by using one of the following arguments : - 'FD' : (default) print files first, directories last. - 'DF' : print directories first, files last. - 'MIX' : print files and directories among each other. §6 Listing formatting. ~~~~~~~~~~~~~~~~~~~ The format of the actual listing can be either a table format or a script format. Most of the time, however, you'll use the table format. A. Listing table formatting. A.1. Setting the listing table width. » MAXWIDTH <#> DirKING will expand the listing table in accordance with the Page 22 - DirKING v3.0x User Manual fields to be printed, and the length of the FileName field. In most cases, you'll want to set a limit to this expanding. With 'MAXWIDTH' you can specify how many characters may be printed on one line. If the listing is too wide, then if the name field is printed, it will be cut (the name field is the only field that can be trimmed, all other fields have a fixed length). If the name of a file or directory should be too long to fit in the FileName field, then the last character will be an '$' to indicate that more characters are following in that name. Note: the MAXWIDTH option is only effective on the actual listing, not on the listing header or listing end. REMARK: the limit set with 'MAXWIDTH' won't work in all cases. This depends on the fields to be printed. The fields that have a fixed length will always be fully printed. The only variable field is the 'FileName' field, but it can't be smaller than 16 characters. DirKING will always print the fixed fields and the minimal 16 characters, even if the total width exceeds the 'MAXWIDTH' setting. | 'MAXWIDTH 70' : the actual listing width can only be 70 | characters wide. » EXPAND By default, DirKING will only print as wide as is necessary to print all the wanted fields. So the listing width will vary from directory to directory. If you want DirKING to make use of the full allowed listing width, then you must use EXPAND. When MAXWIDTH is used, then DirKING will print a listing with an actual width as specified. When you don't use MAXWIDTH, then DirKING will use the full width of your current Shell window. A.2. Setting the list order of the table fields. » LISTORD <fmt> Normally the listing is printed in the form of a table, where each column represents a field. The default field order is 'NMEKRIBLAHDTSVWYGJOPF'. To define the order of the fields, you must use the field codes as explained with the INCL option (see above). | 'LISTORD dalnktb' : defines the order : date, flags, | bytes, name, keys, time and blocks. Note: the use of LISTORD doesn't mean that these fields will actually be printed. This depends on the options as described under '§4C'. Important: When defining the fields order, you don't have to enter all codes for the fields that will be printed. When you only define the order of the first fields, DirKING will use the default order DirKING v3.0x User Manual - Page 23 for the rest of the fields. | 'LISTORD an' : only two fields are defined, the rest are | printed in the default order. The order | will then be : flags, name, keys, blocks, | bytes, date and time. Previous versions of DirKING allowed the use of print control sequences with the LISTORD argument. This has been removed in the current version because of the implementation of TABLEFMT. But I'm thinking of supportin it again in future versions. REMARK: the LISTORD option has no effect when TABLEFMT was used! A.3. Formatting the listing table. With the following options you can customize the format of the listing table, and the format of the date- and timestamp. All these format options, support the use of AmigaDOS print control sequences. To introduce such a sequence in the formatstring, you have to use a '\' character followed by one of the following codes : - e : insert an ESCape character (refer to your AmigaDOS manual for a list of the supported print control sequences) - t : insert a TAB character - n : insert a line feed - f : insert a form feed - " : print a double quotation mark (") - \ : used to print '\'. The format options also allow formatting in the same way as with the use of the RawDoFmt() routine from the Exec.library. Programmers will have the hang of this, but for novice users, here's a short explanation how RawDoFmt() formatting works. The template for an item is as follows: %[-][0][min[.max]]code Meaning: - '%' : each item must be introduced by a '%' code. - '-' : forces the item to be left aligned, instead of the default right aligning. - '0' : if the item is smaller than the given width, then the item will be expanded with blanks or zeros. - 'min' : this value defines the minimum width an item must have. - '.max': this value defines the maximum width an item can have. If it's too long, then it's cut to the right length. - 'code': this is the field code as explained earlier with the INCL option. Page 24 - DirKING v3.0x User Manual » DFORMAT <fmtstr> DirKING uses the AmigaDOS dateformat (which is DD-MMM-YY) as its default format. With 'DFORMAT' you can define your own dateformat. This formatstring can contain normal text, print control sequences and of course the date substitution operators. The substitution operators indicate which date item has to be printed. Such an operator consists of an '%' character and one of the following date item codes : - w : insert a two character dayname (e.g.Sa,Su,Mo,...) - W : insert the full dayname (e.g.Sunday,Monday,...) - d : insert the day in the month - m : insert the month number (1..12) - M : insert a three character month name (e.g.Jul,Aug,...) - O : insert the full month name (e.g. january, august,...) - y : insert the last two digits of the year (e.g.91,92,...) - Y : insert a four digit year (e.g.1991,1992,...) | 'DFORMAT %w_%d/%Y/%m' : gives a date like Su_23/1992/08. | 'DFORMAT "\e[1m%W\e[0m \e[3m%d %M %Y\e[0m"' (Notice the | quotation marks! They're used because the DFORMAT data- | argument contains spaces!) | The defined date format will result in a date looking like | this : 'Friday 11 Sep 1992' Note: The TFORMAT and SFORMAT codes are also supported with DFORMAT! Important: the item codes are used case-sensitive! » TFORMAT <fmtstr> Everything said for DFORMAT is true for TFORMAT, the only difference is the specific set of time item codes : - H : insert the hour in 24 hour mode (0..23) - h : insert the hour in 12 hour mode (0..11) - i : insert the minutes - s : insert the seconds - T : insert AM or PM according to the hour ('T' works independent from 'H' and 'h', in other words you don't have to use 12 hour mode to use AM/PM!). | 'TFORMAT %h:%m_%T' : gives time like '08:53_AM'. | 'TFORMAT \e[1m%h\e[0m:\e[3m%i\e[0m:\e[4m%s\e[0m' : gives a | time like : '14:30:18'. Note: The DFORMAT and SFORMAT codes are also supported with TFORMAT! » SFORMAT <fmtstr> Everything said for DFORMAT and TFORMAT is true for SFORMAT, the only difference is the specific set of item codes : - D : insert number of days since 1/1/1978 - U : insert number of minutes since 00:00 DirKING v3.0x User Manual - Page 25 - I : insert number of ticks since last minute | 'SFORMAT %D/%U/%I' : gives stamp like '4900/1234/1025'. Note: The DFORMAT and TFORMAT codes are also supported with SFORMAT! B. Predefined listing table formats. As a shortcut, DirKING has several predefined formats, for selecting a listing order, a date- or timeformat. These predefined formats can be accessed by their appropriate code. » LISTF <code 0..4> The following listing orders are supported : - 0 : NKBLADT (default) - 1 : NAKLBDT - 2 : NADTLBK - 3 : NDALBKT - 4 : ALBKDTN » DATEF <code 0..7> The following dateformats are supported : - 0 : '%d-%M-%y' -> DOS format dd-mmm-yy (e.g. '14-Aug-92') - 1 : '%y-%M-%d' -> INT format yy-mmm-dd (e.g. '92-Aug-14') - 2 : '%m-%d-%y' -> USA format mm-dd-yy (e.g. '08-14-92') - 3 : '%d-%m-%y' -> CDN format dd-mm-yy (e.g. '14-08-92') - 4 : '%w %d-%M-%y' -> (DOS format - e.g. 'Fr 11-Sep-92') - 5 : '%w %y-%M-%d' -> (INT format - e.g. 'Fr 92-Sep-11') - 6 : '%w %m-%d-%y' -> (USA format - e.g. 'Fr 09-11-92') - 7 : '%w %d-%m-%Y' -> (CDN format - e.g. 'Fr 11-09-92') » TIMEF <code 0..3> The following timeformats are supported : - 0 : '%H:%i:%s' (e.g. '14:30:00' ) - 1 : '%h:%i:%s-%T' (e.g. '02:30:00 PM') - 2 : '%H:%i' (e.g. '14:30') - 3 : '%h:%i-%T' (e.g. '02:30 PM') C. Free formatting and script generation. » TABLEFMT <fmtstr> With this option you can directly specify the format of the listing table. The formatstring is constructed in the same way as with LFORMAT, but now the listing table is formatted. To introduce an item, you must use the appropriate substitution operator. This is nothing more than a '%' character followed by the wanted field code. These operators can also hold information on alignment and width of the field, as we have previously seen with Exec.RawDoFmt() formatting. To get a clean formatted table it's necessary to specify the Page 26 - DirKING v3.0x User Manual width of each field, except for the name and naked name field, because for the latter DirKING will calculate the width for you. Remember to use '-' if you want to left align the field! | 'DirKING RAM: TABLEFMT "%-12N %6.6B %10A"' will give: | F i l e N a m e Blocks Flags | Disk.info 1 f-----rw-d | CLIPS D i r d-----rwed | ENV D i r d-----rwed | T D i r d-----rwed Note: if you'd like DirKING to calculate the width of the name and naked name fields, then leave out the width values and use something like "%N" or "%M". Insert a '-' to left align the name, because otherwise the field is right aligned. Remark: when TABLEFMT is used, then the LISTORD, INCL, EXCL and LISTF will have no effect! » LFORMAT <fmtstr> LFORMAT is the only way to have full control on the actual listing print format. I say 'actual listing' because when LFORMAT is used, no listing head, title or end will be printed. The main use of LFORMAT will probable be the generation of scripts, but you don't have to limit it to this. IMPORTANT : LFORMAT MUST ALWAYS BE THE LAST ARGUMENT, SINCE EVERYTHING AFTER THE LFORMAT KEYWORD IS PART OF THE FORMAT STRING!! (This means that quotation marks may only be used if they're needed in the output!) The 'LFORMAT' option works in the same way as in the AmigaDOS 'List' command, so you should have no difficulties to understand the use of it. The format string can contain three sorts of text. Firstly normal text, secondly the substitution operators (like '%S' or '%N'), and thirdly AmigaDOS print control sequences (refer to the previous explanation on the use of these in format strings). Like the AmigaDOS command 'List', DirKING uses two sorts of substitution operators : a. Usage of '%S' operators. The usage of '%S' substitution operators is limited, because you only have access to the name and path of directory entries (files/directories). To know where and what information to print, DirKING uses the followig table of '%S' occurences : Occurences 1st 2nd 3rd 4th 5th 6th... 1 name - - - - - 2 path name - - - - 3 name path name - - - 4 path name path name - - 5 name path name path name - 6 path name path name path name ... DirKING v3.0x User Manual - Page 27 | 'LFORMAT Path:[%s] Name:[%s]' : Just try this format- | string on a directory and see the magic. Note that no | quotation marks were used, since these aren't needed for | LFORMAT, unless you want them in the output! b. Usage of field specific operators. The usage of '%S' substitution operators isn't really recommended since its range is limited, and the format string can sometimes be hard to read if many operators are used. It's better to use the field specific operators, since you can exactly specify which field to print, and where to print it. DirKING supports the same field substitution operators as the AmigaDOS command 'List'. These operators consist of a '%' character followed by one of the field codes as explained earlier with the INCL option. | Assume current directory is 'Workbench:Devs' | 'DirKING keymaps LFORMAT File:[%N] Path:[%P] FullP:[%F]' | DirKING will read the 'Workbenvh:Devs/KeyMaps' directory. | The output can then be something like this : | 'File:[usa] Path:[] FullP:[KeyMaps/]' | If you also use FULLPATH in the command line then the | output will be : | 'File:[usa] Path:[] FullP:[Workbench:Devs/KeyMaps/]' | 'DirKING TO RAM:script FILES LFORMAT RENAME %N %N.iff' : | This will generate a script in the 'RAM:' disk. When | executed, the rename commands will add an 'iff' suffix to | the name of files found in the current directory. » EXEC <file> As we've just seen, LFORMAT is ideal for generating AmigaDOS scripts which can then be later executed with the EXECUTE command. But DirKING also offers the ability to directly execute such scripts from within itself. This is done with the EXEC option. As an argument, it takes the name (incl. path) of the file to be generated. When the script has been generated, DirKING will execute this script, just like EXECUTE would. Remark: users of AmigaDOS v1.x should have the EXECUTE command in their 'C:' directory for this option to work! §7 DirKING MULTI-mode (multiple directory scanning). ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ » MULTI The MULTI mode was implemented to present a more flexible way of scanning several disks in a row. If DirKING is first started with MULTI in its command line, then the directory will immediately be read. When the listing has been printed, instead of breaking off, DirKING will print a prompt giving the choice between the following operations : - RETURN : start scanning the directory. Page 28 - DirKING v3.0x User Manual If you want to read several disks, then you must use a drive name as the path (e.g. 'DF1:'). DirKING will then always scan the disk in drive 'DF1:'. (Otherwise if you type the name of a disk like 'Workbench:', then each time you press 'S' to reply the MULTI prompt, DirKING will always access that disk.) The only time MULTI mode is useful when you've specified a path other than a drive name, is for printing several copies of that directory. - ESC : quit DirKING. - DEL : enter new program settings. Let's you enter new DirKING arguments, just like you would when starting DirKING. It's important to know that you don't have to type 'DirKING' anymore, since you aren't starting the program! Only type the arguments. REMARK: entering nothing, besides the return, preserves the current settings. Note: you don't have to type MULTI anymore, since DirKING will stay in MULTI mode until an error occurs, or you want to quit the program. - HELP : shows the usage prompt, as a reminder of the options syntax. §8 Listing styles. ~~~~~~~~~~~~~~~ DirKING normally prints the files in plain characters, and the directories in italic. The directory entries are also indented to show the structure of the directory. A. Information format. » SHOWLEVEL Instead of indenting with spaces (' '), DirKING will indent with '__' for files and '_/' for directories. SHOWLEVEL is very useful to get a clear view of the directory tree structure. | 'DirKING RAM: SHOWLEVEL ALL DIRS' : you'll get a clear | view of the directory tree of your 'Ram Disk'. Note that | the use of DIRS forces DirKING only to include | directories. » BINFLAGS By default DirKING uses 'hsparwed' to represent the file- and directory attributes (protectionflags). BINFLAGS will result in a binary value representation (e.g. 00010000) of these attributes. DirKING v3.0x User Manual - Page 29 » DATES Like the AmigaDOS command 'List', DirKING will use the daynames (Sunday...Saturday) of the dates if they're within the last week of the current date. Besides these 'Yesterday','Today','Tomorrow' and 'Future' are also used. You can disable this by using 'DATES'. This forces DirKING to print all dates in the same date format (the default is DD-MMM- YY). » HEXVAL Normally all values printed in the listing are in their decimal notation. Using 'HEXVAL' instructs DirKING to use the hexadecimal notation instead. » LOCVALS Under AmigaDOS v2.1 and later, DirKING enables the user to use the 'locale' formatted values (e.g. 1,234 instead of 1234). B. Listing print styles. The following options define in which style the entire listing is printed, and also how the directory entries themselves will be printed. » TEXT The TEXT option will remove all print control sequences from the listing, thus leaving only pure text. » DIRSTYLE [r|i|b|y|f|a|e][r|i|b|y|f|a|e] The default print style for files is plain text, while directories use italics. These styles can be altered by using predifined style codes. Only the first two characters of the 'DIRSTYLE's data-argument will be used, where the first character gives the style for directories, and the second for files. (One character data-arguments are also valid, the files will then be printed in their default style, while the directories will use the specified style.) The following character style codes are supported : - R : Red - I : Italic - B : Bold - Y : Yuppy -> Red/Italic - F : Fat -> Red/Bold - A : All -> Red/Italic/Bold - E : Elite -> Italic/Bold - N : Normal (plain) Note: DIRSTYLEs determine in which style a directory entry will be printed. If you want to print a specific field in another style, then you must make use of AmigaDOS Page 30 - DirKING v3.0x User Manual print control sequences with the DFORMAT, TFORMAT, SFORMAT or TABLEFMT option. | 'DIRSTYLE ab' : print the directories in red, italic and | bold characters, and the files in bold | characters. » PRTSTYLE {rdlbpes} If the DirKING output is directed to the printer, then the printer style settings won't be changed, unless the following codes are given : - R : reset to normal characters - D : print in draft quality - L : print in near_letter_quality - B : print in subscript - P : print in superscript - E : print in elite (12 cpi) - S : print with doublestriking | 'PRTSTYLE de' : print in elite and draft quality. §9 Listing output redirection. ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The default output is to the Shell window where DirKING was started. Although you can use the AmigaDOS redirection (e.g. '>PRT:') to output somewhere else, it's sometimes not recommended. This is the case when you use TRACE for example. If you would use AmigaDOS redirection when TRACE is active, then all TRACE information would be send to this new destination, which isn't what you want. Therefore two redirection arguments were implemented in DirKING to split the output. The DirKING messages (e.g. TRACE information) are printed in the Shell window as usual, but the directory listing will be send to the selected output device. » PRT a. General use. As the argument keyword suggest, this redirects the directory listing to the printer ('PRT:'). b. Use in MULTI-mode. When DirKING has to send the directory listing, it first opens a channel to the printer (this is called 'locking'). As you know from the explanation of MULTI, DirKING doesn't break off after printing the directory, instead a prompt is printed. When you reply this prompt with 'S' then DirKING starts scanning again. DirKING will then send this listing again along the previously opened channel. It's important to note that DirKING doesn't close this output channel when in MULTI-mode, since DirKING always uses the same arguments. ONLY when new arguments are entered (the prompt was replied with 'A'), then DirKING will close this output channel DirKING v3.0x User Manual - Page 31 (and open a new channel to the new specified output device)! DirKING does this to make sure it always has direct access to the printer, so the listing can be printed without interruptions. » TO <file> a. General use. With the 'TO' argument you can send the directory listing anywhere you like, as long as it's a valid AmigaDOS path. | 'DirKING DF1: TO RAM:df1' will output the listing of | 'DF1:' to a file in RAM: called 'df1'. | 'TO PRT:' : naturally you can also use the TO argument to | send the directory listing to the printer. b. Use in MULTI-mode. As mentioned with 'PRT', DirKING only opens the output channel once. Only when new arguments are supplied is this channel closed, and another opened if needed. This way of working is extremely useful, since you can send several directory listings to one file. All listings will be placed after one another. | 'DirKING DF1: TO RAM:df1_dirs MULTI' will send all | directory listings of the disks you've inserted in 'DF1:' | to the file in RAM: called 'df1_dirs' c. Use in conjunction with PRT. If only 'TO' is used, then DirKING will save the listing with the Shell control sequences. When you also use 'PRT' then DirKING will use the printer control sequence instead. Let's take a look at the printing of bold characters, to demonstrate the difference between these control sequences : -> Shell control sequences > bold on : 'esc[1m' bold off : 'esc[0m' << -> Print control sequences > bold on : 'esc[1m' bold off : 'esc[22m' << §10 Listing paging. ~~~~~~~~~~~~~~~ » NEWPAGE [[{cmhte}]<#>] By default DirKING will print the directory listing in one go. If a long listing is send to a Shell window, then it can be annoying to see it flying by. To prevent this from happening, a paging facility was implemented in DirKING. The NEWPAGE argument can be used in three different ways. Besides this, the effect of 'NEWPAGE' isn't always the same when output is send to the Shell, to a file or to the printer. Everytime a page of the listing has been shown, a prompt will Page 32 - DirKING v3.0x User Manual appear, allowing four possible responses: - RETURN : shows the next page - SPACE : shows the next line - L : shows the rest of the listing - ESC : quits listing a. Command : 'NEWPAGE'. When only 'NEWPAGE' is used, and output is redirected by 'PRT' or 'TO <file>' then at the end a new page character will be send. When the listing is shown in the Shell window, then DirKING will use the window's length as the maximum page size. b. Command : 'NEWPAGE <#>'. NEWPAGE will mostly be used in this way. By adding a value (greater than 10) to the NEWPAGE keyword, you can specify how many lines should be printed on each page. If output is send to your Shell window, then DirKING will display the NEWPAGE-prompt. When output is redirected with 'PRT' or 'TO <file>' then instead of printing the NEWPAGE-prompt in the Shell window, a new page charachter will be inserted in the listing. This means that, each time the specified number of lines is reached, a formfeed code is send to the output channel. As with the bare 'NEWPAGE' command, a new page character will be send at the end of the listing. | 'NEWPAGE 20' : only print 20 lines on a page. REMARK: If the given value is less than 10, then the number of lines will be set to 10! c. Command : 'NEWPAGE {ht}' or 'NEWPAGE {ht}<#>'. The NEWPAGE argument also supports additional options, which are indicated by the following characters (all options can be used at once) and are used in conjunction with the commands as explained in (a.) en (b.) : - H : after the listing header is printed, a formfeed character will be send. - T : always print a listing title at the beginning of a new page/screen. - C : clear the screen/page before showing the listing. - E : eject the screen/page after showing the listing. - M : clear the screen/page after each multiple assigned directory. | 'NEWPAGE c' : clear the screen first, then show the | listing. | 'NEWPAGE ht20' : print the listing header on one page, | then use only 20 lines per page to print | the listing itself. DirKING v3.0x User Manual - Page 33 §11 Disk identification coding support. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ » DISKID <str> a. General use. If you use a catalog tool to keep track of your disk collection, then this feature of DirKING is very useful. It enables you to insert a string (this can be a disk ID used for cataloging your disks, or any other message) in the listing header. REMARK: Most times the DISKID string will contain spaces, in which case you must place the string between double quotation marks. | 'DISKID PD0/00.0000' : this disk ID will be printed in the | header. | 'DISKID "This is a test ID string!"' : prints this string | in the listing header (notice the double quotation marks). b. Use in MULTI-mode. The disk ID string that was typed in the command line (thus when starting DirKING from Shell) will only be used once! Each time you reply the MULTI prompt with 'S' (start scanning), DirKING will first ask to enter a new disk ID string (or message) before reading the directory. §12 DirKING environment variables. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of V3.00 DirKING supports four environment variables: - DK_DEFAULT : in this variable you can specify your own default settings, like what fields to show, in what order, how to sort, etc... All arguments of DirKING may be given here. This variable is always parsed first, before the arguments which were given on the command line. | 'SETENV DK_DEFAULT INCL nkbladt DATES | LOCVALS DFORMAT %Y-%m-%d' Use DirKING | without options and see the result. - DK_LISTORD : this variable holds the list order of the fields, just as you would use the LISTORD option. | 'SETENV DK_LISTORD abln' will set the | LISTORD option with the 'albn' value. - DK_TABLEFMT: this variable holds the TABLEFMT string. If this variable is present, then DirKING will Page 34 - DirKING v3.0x User Manual set the TABLEFMT option! Only create such a variable when you want to have your own default table format. | 'SETENV DK_TABLEFMT %-12N %6.6B %10A' | will set the TABLEFMT option with the | '%-12N %6.6B %10A' value. - DK_LFORMAT : this variable holds the LFORMAT string, and is only used when the LFORMAT option is specified without a formatstring. | 'SETENV DK_LFORMAT %F%N' » NOENV This option disables the use of the environment variables. §13 DirKING program information. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using '©' as an argument will print the current version and copyright of DirKING. This replaces the previous VERSION option. DirKING v3.0x User Manual - Page 35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ APPENDIX : DIRKING KEYWORD REFERENCE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DiskInfoBlock fields . . . . . . . . . . . . . . . . . . . . 16 Exec.RawDoFmt() formatting . . . . . . . . . . . . . . . . . 24 F|D|B filter options . . . . . . . . . . . . . . . . . . . . 10 Pattern matching . . . . . . . . . . . . . . . . . . . . . . 4 Special control codes. . . . . . . . . . . . . . . . . . . . 24 --------------------------------------------------------------- <path|patt>. . . [[F|D|B]<path|patt>]. . . . . . . . . . . . 6 ALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 ASSLATE. . . . . . . . . . . . . . . . . . . . . . . . . . . 8 BARELIST . . . . . . . . . . . . . . . . . . . . . . . . . . 18 BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 BINFLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . 29 COMMENT. . . . . [COMMENT [F|D|B]<pattern>]. . . . . . . . . 13 DATATYPE . . . . [DATATYPE <pattern> ] . . . . . . . . . . . 14 DATEF. . . . . . [DATEF <0..7>]. . . . . . . . . . . . . . . 26 DATES. . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 DESC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 DF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 DFORMAT. . . . . [DFORMAT <fmtstr>]. . . . . . . . . . . . . 25 DIRINFO. . . . . [DIRINFO [BASE]]. . . . . . . . . . . . . . 20 DIRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 DIRSTYLE . . . . [DIRSTYLE [r|i|b|y|f|a|e][r|i|b|y|f|a|e]] . 30 DISKID . . . . . [DISKID <str>]. . . . . . . . . . . . . . . 34 DISKINFO . . . . . . . . . . . . . . . . . . . . . . . . . . 16 DISKUSE. . . . . . . . . . . . . . . . . . . . . . . . . . . 17 EOD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 EXCL . . . . . . [EXCL {nkribladtsocpfhvwygjmex}]. . . . . . 20 EXEC . . . . . . [EXEC <file>] . . . . . . . . . . . . . . . 28 EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 FD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 FILES. . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 FLAGS. . . . . . [FLAGS [F|D|B]<flags>]. . . . . . . . . . . 13 FROMTO . . . . . [FROMTO [F|D|B]<ch><ch>]. . . . . . . . . . 11 FULLPATH . . . . . . . . . . . . . . . . . . . . . . . . . . 17 HEAD . . . . . . [HEAD {mnbdvpktise}]. . . . . . . . . . . . 18 HEXVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 HUNT . . . . . . [HUNT [F|D|B]<pattern>] . . . . . . . . . . 14 INCL . . . . . . [INCL {nkribladtsocpfhvwygjmex}]. . . . . . 19 LFORMAT. . . . . [LFORMAT <fmtstr>]. . . . . . . . . . . . . 27 LINKDIRS . . . . . . . . . . . . . . . . . . . . . . . . . . 8 LISTF. . . . . . [LISTF <0..4>]. . . . . . . . . . . . . . . 26 LISTLEVELS . . . [LISTLEVELS <#>]. . . . . . . . . . . . . . 21 LISTORD. . . . . [LISTORD <fmt>] . . . . . . . . . . . . . . 23 LOCVALS. . . . . . . . . . . . . . . . . . . . . . . . . . . 30 MAXHEAD. . . . . . . . . . . . . . . . . . . . . . . . . . . 18 MAXWIDTH . . . . [MAXWIDTH <#>]. . . . . . . . . . . . . . . 22 MIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 MULTI. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 NEWPAGE. . . . . [NEWPAGE [[{cmhte}]<#>]]. . . . . . . . . . 32 NOENV. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 NOHEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 NOREQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 NOSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NOSTAT . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 PASS . . . . . . [PASS [F|D|B]<pattern>] . . . . . . . . . . 11 PATH . . . . . . [F|D|B]<path|patt>. . . . . . . . . . . . . 7 PRT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Page 36 - DirKING v3.0x User Manual PRTSTYLE . . . . [PRTSTYLE {rdlbpes}]. . . . . . . . . . . . 31 QUICK. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 READ . . . . . . [READ [F|D|B]<pattern>] . . . . . . . . . . 10 SFORMAT. . . . . [SFORMAT <fmt>] . . . . . . . . . . . . . . 25 SHOWLEVEL. . . . . . . . . . . . . . . . . . . . . . . . . . 29 SINCE. . . . . . [SINCE "[F|D|B]<[DOSdate] [time]>"] . . . . 13 SORT . . . . . . [SORT {nkribladtcygme}] . . . . . . . . . . 21 SUB. . . . . . . [SUB [F|D|B]<string>] . . . . . . . . . . . 11 TABLEFMT . . . . [TABLEFMT <fmt>]. . . . . . . . . . . . . . 26 TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 TFORMAT. . . . . [TFORMAT <fmtstr>]. . . . . . . . . . . . . 25 TIMEF. . . . . . [TIMEF <0..3>]. . . . . . . . . . . . . . . 26 TO . . . . . . . [TO <file>] . . . . . . . . . . . . . . . . 32 TOLEVEL. . . . . [TOLEVEL <#>] . . . . . . . . . . . . . . . 10 TRACE. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 UPTO . . . . . . [UPTO "[F|D|B]<[DOSdate] [time]>"]. . . . . 13 DirKING v3.0x User Manual - Page 37