Meeting Pearls 3/Meeting_Pearls_III.iso/Pearls/comm/Fido/TrapDoor/docs/TrapScan.Man

Text File | 1994-06-23 | 14KB | 498 lines

     Page 1            TrapDoor's Directory Scanner             Page 1

















                                 TrapScan
                       TrapDoor's Directory Scanner
                                Version 1.7
                          Copyright (c) 1991-1994
                   Martin Laubach and Maximilian Hantsch
                            All rights reserved






                             TrapScan's Manual
                        Thursday 24-Feb-94 17:27:51
                          Copyright (c) 1991-1994
                   Martin Laubach and Maximilian Hantsch
                            All rights reserved








               "I stand in pause where I shall first begin"


















     Page 2            TrapDoor's Directory Scanner             Page 2



  1. Introduction

       This document is a brief description of TrapScan, the
     versatile TrapDoor utility for scanning directories.

       TrapScan skims through any directory indicated, extracting
     files matching certain conditions.



  2. Basics

       TrapScan is a CLI based application, it can't be run from
     WorkBench. It accepts a narrow range of configuration statements
     that allow an easy and accurate configuration.

       It is built to help FidoNet node operators in the maintenance
     of their system -- it allows them to automatically act on
     certain incoming files with specific attributes. In that vein,
     it looks very much like LIST or DIR -- with the exception that
     it allows for rather complex expressions to be met for listing a
     file.

       It supports the normal AmigaDOS filename pattern matching, as
     well as matching of the tag/value pairs the products of the
     TrapFamily use to store information in the file comment.

       TrapScan will return an error code of 5 when no matching file
     could be located. This can come in very handy in scripts (e.g.
     for looking for a new, legite nodediff).



  3. How To

       TrapScan is really easy to use. Just type "TrapScan", and it
     will show a summary of its parameters, along with their default
     settings.

  3.1. Parameters

       The following command-line parameters are recognized.

     AND

       Used to join two clauses using a logical and function. See
     below for more about complicated selection criteria.

     DIRECTORY <dir>

       Specifies the directory TrapScan should look for files. This
     defaults to the current directory "", but any other directory
     name will do just fine (e.g. "DIRECTORY Mail:inbound").


     How To                                         DIRECTORY <dir>


     Page 3            TrapDoor's Directory Scanner             Page 3



     FASTER

       The BLink compatibility switch. Consult BLink's documentation
     for more in-depth description of this option.

     FILE <pattern>

       Just as with the LIST or DIR command, you may use patterns to
     select certain files from the directory being scanned. For
     example, "FILE #?.PKT" will select only .PKT files for display.

       Note that because of the SAS supplied library function that
     performs the pattern matching, it may be possible that
     complicated patterns do not work as advertised. Break these up
     in smaller expressions, and join them with AND/OR/NOT.

     LFORMAT <format>

       Just as LIST, TrapScan can be used to build more complicated
     script files using the LFORMAT command. The format string you
     submit to LFORMAT is written verbatim to the output, with the
     exception of a couple of special formatting commands which are
     replaced with their respective value.

       These formatting commands all start with a percent sign (%%)
     and are followed by one of those characters below:

            %c ........ Inserts the file comment.
            %d ........ Inserts the current directory name, as given
                        by the DIRECTORY parameter.
            %f ........ Inserts the full file name, including full
                        path description.
            %l ........ Inserts the current file size (whatever this
                        may be good for).
            %n ........ Inserts the filename (without any path).
            %s ........ Inserts the current file name, including
                        relative path ie. the path specified
                        DIRECTORY).
            %p ........ Inserts the full path to the file, without
                        any filename.  This is different from the %%d
                        command in that the path is always given as
                        an absolute path from the root directory.

       So, for example,

       LFORMAT %f %l

       will produce output like this

          DF0:t/trapdoor.dok 8640
          DF0:t/post16.lzh 206848
          DF0:t/DiskCopy1.pic 9898



     How To                                        LFORMAT <format>


     Page 4            TrapDoor's Directory Scanner             Page 4


     NOT

       Logically inverts the following clause.

     OR

       Join the following clause to the current expression, using a
     logical or.

     TAG <tag> <value>

       Just like FILE, this is used to select certain files upon
     their tag/value pairs in the file comment. Wilcards are
     supported in both the tag name and the value description. For
     example, "TAG From 2:310/#?" will select only files that where
     sent to me from a system in the 2:310 net.

  3.2. Complicating things

       As you may have remarked, there are a couple of keywords that
     can be used to join several innocent looking expressions to
     quite a complicated selection criteria.

       Those keywords are AND, OR, and NOT. Just use them as you
     would in everyday language -- for example:

          TAG From 2:310/6.0 AND NOT FILE Nodelist.#?

       will select any file received from 2:310/6 that is not named
     Nodelist.#?.

       This may look strange or complicated to you now, but with a
     bit of experience, it will become very easy. Just start with
     simple expressions, then experiment what happens when you add
     some more...

  3.3. Return Values

       If everything was fine, and files matching the arguments were
     found, TrapScan returns 0. If the arguments were parsed fine,
     but no matching files were found, TrapScan returns 5. This
     allows you to write scripts such as

          TrapScan FILE Pointnet.??? AND FROM 2:310/3
          If NOT WARN
            ; process Pointnet
          Endif

       If fatal errors were encountered, TrapScan returns 20.







     How To                                           Return Values


     Page 5            TrapDoor's Directory Scanner             Page 5


               "Thus bad begins, and worse remains behind."




  4. Legalese

  4.1. Distribution

       TrapScan is to be considered as a FreeWare product. The
     authors retain the copyright and all other rights within, but at
     the same time allow distribution of the product.

       TrapScan may be redistributed with two restrictions.  First,
     the distributor may only charge a fee up to the costs of
     obtaining a public domain diskette from Fred Fish for the
     complete package.

       Second, the distributor agrees to cease distributing the
     programs and data involved if requested to do so by the author.
     The distributor may only distribute an unmodified copy of the
     original TrapScan package, with all the supplied documentation
     and copyright notices intact and without any files being added,
     changed or omitted.










  4.2. Support

       If you have any suggestions, bug reports etc., feel free to
     contact the authors of TrapScan/TrapDoor at the addresses below:

          Maximilian Hantsch       Martin Laubach
          Fido: 2:310/6            Fido: 2:310/3.14
          Uucp: [e-mail]   Uucp: [e-mail]

       Also, there is a FidoNet Echomail conference called TRAPDOOR,
     which should be available at major backbones. This conference is
     in English and intended for the users of TrapDoor and, of
     course, TrapScan as well. There, you can freely exchange your
     experience with these programs, discuss future enhancements you
     would like to see etc. Both authors will participate in the
     conference and try to assist you.






     Legalese                                              Support


     Page 6            TrapDoor's Directory Scanner             Page 6



  4.3. No Warranty

       THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED
     BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
     COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS
     IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
     RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
     YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
     ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
     FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
     BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
     PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
     PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
     OF THE POSSIBILITY OF SUCH DAMAGES.




  4.4. Disclaimer

       No warranty, either express or implied, is made with respect
     to the fitness or merchantability of TrapScan.

       Maximilian Hantsch and Martin Laubach (referred to as "the
     authors"), reserve the right to not develop any future versions
     of TrapScan.

       The authors will try to make a good faith attempt at
     correcting any problems if any are discovered, but are in no way
     required, nor bound to correct them.

       The authors neither assume or accept any responsibility for
     the use or misuse of this program. They also will not be held
     liable for damages or any compensation beyond the original
     registration fee due to loss of profit or any other damages
     arising out of the use, or inability to use this program.

       Neither Maximilian Hantsch nor Martin Laubach will be liable
     for any damage arising from the failure of this program to
     perform as described, or any destruction of other programs or
     data residing on a system attempting to run the program. While
     we know of no damaging errors, the user of this program uses it
     at his or her own risk.




     Legalese                                           Disclaimer


     Page 7            TrapDoor's Directory Scanner             Page 7



  5. Acknowledgements

       The following names are either trademarks or the efforts of
     the person and/or company listed:

          Amiga and AmigaDOS are trademarks of Commodore-Amiga, Inc.
          Fido and FidoNet are trademarks of Tom Jennings,
                         Fido Software.
          License Agreement inspired by Jack Radigan
                         and the GNU General Public License.
          Special Thanks to all our Registered TrapDoor Users.
          TrapDoor by Maximilian Hantsch and Martin Laubach.
          TrapList by Martin Laubach and Maximilian Hantsch.










































     Acknowledgements


     Page I            TrapDoor's Directory Scanner             Page I


  Road Map


        1. Introduction    .....................................    2
        2. Basics    ...........................................    2
        3. How To   ............................................    2
           3.1. Parameters    ..................................    2
           AND    ..............................................    2
           DIRECTORY <dir>   ...................................    2
           FASTER    ...........................................    3
           FILE <pattern>   ....................................    3
           LFORMAT <format>   ..................................    3
           NOT    ..............................................    3
           OR    ...............................................    4
           TAG <tag> <value>  ..................................    4
           3.2. Complicating things   ..........................    4
           3.3. Return Values   ................................    4
        4. Legalese    .........................................    5
           4.1. Distribution    ................................    5
           4.2. Support    .....................................    5
           4.3. No Warranty   ..................................    6
           4.4. Disclaimer    ..................................    6
        5. Acknowledgements    .................................    7





               "For some must watch, while some must sleep,"
                         "So runs the world away."


























     Road Map