

                     The GATHER.TXT           Page 1




                     Version 3.01      March, 1995


                             _______
                        ____|__     |               (R)
                     --|       |    |-------------------
                       |   ____|__  |  Association of
                       |  |       |_|  Shareware
                       |__|   o   |    Professionals
                     -----|   |   |---------------------
                          |___|___|    Member




          Gather gathers specified files from specified directories and
          copies, archives, or moves, them to a destination directory.
          This allows one to collect copies of crucial files, such as
          the AUTOEXEC.BAT, or database files, into a central directory
          for transfer to another computer as a backup and for ongoing
          remote maintenance and diagnosis.  You can also use gather as
          a form of ongoing BACKUP, MOVE, or ERASE program by running it
          as a TSR or resident program.  When run as a TSR you can
          direct GATHER to periodically gather files as specified in a
          response file, or on the command line, to a specified
          directory and/or a diskette.  You may discover that gather
          occupies too much ram to be generally kept resident.  If so,
          consider periodically using it in a batch file instead, you
          should find that it is MUCH faster than other software that
          you use for similar purposes.  Gather is command line
          oriented, but the telemenu remote menu program provides a
          mousy menuing (SAA/CUA if you prefer) alternate interface.  If
          you use the resident or tsr option with the remote menu
          program, you can be in a very large program like dBASE IV and
          the menu program will swap dBASE out of RAM and swap itself in
          when you use its hotkey.  See the TELEMENU.TXT for information
          on the remote menu programs.

          Please also note that gather is designed so it CAN copy files
          over themselves, which effectively destroys them.  If you wish
          to avoid destroying files, do not copy them over themselves.
          Please note that you can use the Query switch to make gather
          ask before it acts.


          The Gather command line:






                     The GATHER.TXT           Page 2



            Usage  Gather  -time -show -clock -tsr @name -fname -d\A_DIR\ ...

           -ARCHIVE Archive by default, instead of copying.
           -CLOCK   to display the time.
           -DAYS10  to gather files within the given number of days.
           -D\DIR\  the destination directory (and file when archiving).
           -ERASE   Erases files.  See also Move.
           -Fname   to copy the NAMEd file.  You may use * as in *.dbf.
           -H       this help.  See also the GATHER.TXT.
           -MOVE    Move instead of copy files.
           -N       reName copied files by inserting a number.
           -PATH    to search for files along the PATH.
           -Q       Query.  Ask before acting.  -Q- avoids a query.
           -REDIR   for screen REDIRection to a file.
           -SCATTER to (re)install a list of files, used with @filelist.
           -SHOW    to show filenames during processing.
           -TIME60  the repeat time or delay in seconds between file copying.
           -TSR     to run as a TSR or resident program.
           -UNLOAD  to unload the TSR from RAM.
           [S] [R]  Send or Receive files by serial connection.
           @some_file  use a response file listing the files to copy/move...

          If there is 'extra' material left on the command line after
          the above checks, gather tries to use it as a destination
          directory.  You can use "GATHER @FILELIST C:\SOMEDIR\".  If
          you are archiving you can use "GATHER @FILELIST
          C:\SOMEDIR\BACKUP" to specify that the archive filename will
          be "BACKUP".


          Gather also accepts / as the switch character instead of -.



          These switches are explained further below:

          -ARCHIVE to force the default behaviour to archiving instead
          of copying.  This allows you to supply a response file without
          [archive] at the top of the file and have gather archive
          instead of trying to copy the files.  Gather actually also
          accepts -ARCH.

          -DAYS10 the number of days to the oldest file to gather.  If a
          file was last changed 9 days ago, and gather is run with
          -DAYS10, the file will be gathered.

          -D\dir\ the destination directory.  This tells gather to copy
          the file(s) to that directory.  Its a good idea to include the





                     The GATHER.TXT           Page 3



          drive as in -dD:\TRANSFER\.  It will yell and quit if the
          destination directory does not exist.  It will also yell if
          the destination file is write protected, hidden, or a system
          file.  Also, if there is 'extra' material left on the command
          line after checking for other switches, it will be checked for
          a destination directory (and filename when archiving).

          -Fname to copy the named file.  You may use * as in *.dbf.
          Use this to copy a specific file, such as -fADDRESS.DBF, or a
          group of files, as in -f*.DBF.  Use the @response_file method
          when you want to gather more files or be more specific.  If
          the source file does not exist, gather will silently continue
          to the next file.

          -H this help. You may also use /H -?  and ?, or even a blank
          command line.

          -N to reName copied files to minimise overwriting previous
          copies.  The renaming inserts a number into the file name,
          with consecutive files having a consecutive number inserted.
          The seed number is based on the current second at the time of
          the start of the copying.  Files ROSTER, SALARY.DBF, and
          WORKS.WKS will be renamed to ROSTER.20, SALARY21.DBF, and
          WORKS22.WKS if copying starts at 11:30:20.  If LASTNAME.DBF
          was the 180th file copied, it would become LASTN200.DBF, since
          20+180 = 200.  Numbers above 999 restart at 0.  Using this
          scheme might appear attractive but it can consume disk space
          rapidly.

          -PATH to search along the PATH for one or more files.  This
          instruction tells gather to look through every directory along
          your machine's current path for the file(s).  Some uses of
          this switch are incompatible with other switches, with the
          idea that if you use *.* or the like, then you do not really
          mean to copy every file along the path to the destination
          directory.

          -REDIR DOS screen display, to allow redirection to a file.  If
          you are also using -clock, the clock will continue to write
          using the bios, with the program dynamically changing screen
          drivers back to dos after each time update.  A side effect of
          this setting may be a change in gather colours.  The default
          is to use bios output.

          -SCATTER can be considered a form of uninstall, reinstall, or
          install.  For example, you might GATHER the AUTOEXEC.BAT,
          CONFIG.SYS, and all the various .INI files in a computer to
          one directory before installing some trial software.  The





                     The GATHER.TXT           Page 4



          trial software might alter one or more files, but -SCATTER can
          be used to replace the original files.  Gather uses a
          @response_file that indicates the file's original drive and
          directory with the SCATTER command.  Such a file is easily
          created with DIRDBF (as in DIRDBF -path -xf *.ini for .ini
          files) or with your text editor.

          -SHOW to show filenames as they are copied.  The source and
          destination directories are included.

          -TIME15 the repeat or delay time between file copying.  The
          default is 60, with an allowable range between 10 and 100000
          seconds.  This value is the 'sleep' time for gather when it is
          running as a TSR, and is the file update time when gather does
          short term file copies.  Use -time60 to force gather to copy
          files that have been updated in the past 60 seconds.  Note
          that this is the actual tsr sleep time, it only becomes active
          at the given intervals, and only for the length of time
          necessary to do the given task.  If you want a longer time,
          yell with an explanation, its easy to change.  You might also
          consider using the @response_file method.

          -TSR to run as a TSR or resident program.  Gather takes about
          100K when running as a TSR.  It is designed for speed, and
          interactive use more than as a background backup program.
          Gather is also designed to be very quickly and easily changed
          for custom purposes.

          -UNLOAD to unload the TSR from ram.  Eg:  gather -unload

          [S] [R] to Send or Receive files by serial connection.  Gather
          works with external file transfer tools.  It uses the
          [transfer] section in the TELE.INI configuration file,
          described below, to discover which tool to use and how to use
          it.  The default Teleshare tool is XM, for xmodem 1k, which is
          part of the TeleShare remote support package.  The default
          HANDS ON remote access tool is the OMNI protocol, (OMI.EXE,
          OMIPUT.EXE, and OMIGET.EXE) which is about as fast as zmodem,
          and is quite portable.  XM is used by default because it is
          very convenient, it automatically reads the TeleShare setup
          information from RAM memory.  Hydracom, PCZ, Jmodem, and so
          on, need more setup information.  To use the Hands On OMNI
          setup you have to also use the Wizard.  XM and Hydracom accept
          response files, as described immediately below.


          @some_file to use a response file, or control file, listing
          the files to copy.  You simply list the files to be copied as





                     The GATHER.TXT           Page 5



          a list in the given text file.  A sample that includes the
          autoexec.bat, config.sys and equip.log follows (equip.log is
          generally used to store information about your machine, often
          to be send to another machine).

          AUTOEXEC.BAT
          CONFIG.SYS
          EQUIP.LOG


          The following sample adds other commands [Copy Move Erase
          Archive], and comments.  They are generally used to change the
          copy command to a Move or Erase command, or to reverse the
          change.  Both Copy and Move should have a destination
          directory on the same command line.


          ; comments start with ; or optionally #.
          ; The ; follow the .INI file comment standard.
          ; The first command is to copy EQUIP.LOG to C:\BACKUP\
          [Copy C:\BACKUP\]
          EQUIP.LOG
          ; The NAMES and ADDRESS databases will be moved to
          ; D:\STORAGE\
          [MOVE D:\STORAGE\]
          NAMES.DBF
          ADDRESS.DBF
          ; next some old and backup (BAK) files will be erased
          [ERASE]
          oldfile
          letter.bak
          oldfile2
          \OTHER\*.BAK ; erase all the .BAK files in \OTHER\
          [archive]
          new_file
          newer_file
          [transfer]
          c:\send\*.lzh  ; send all the lha archive files


          Please note that most programs that use response files will
          not accept the additional features such as ";" and "[any]".
          For example hydracom expects a simple file listing like that
          produced by some filefinder tools such as dirdbf.  Our normal
          practice is to use such a simple response or control file when
          archiving.

          The DIRDBF tool can be used to create appropriate response





                     The GATHER.TXT           Page 6



          files listing the files in the current directory.  Use DIRDBF
          to create a FILELIST file.  Run "DIRDBF -h" to get an idea how
          it works.



          The TELE.INI configuration file

          The TELE.INI configuration file is designed to be used by some
          TELEshare tools.  Gather uses the [TRANSFER] section which
          will have a structure something like the following:

          [TRANSFER]
          archiver = PKZIP -u   ;  your archiver with switch(es)
          backup_directory = C:\BACKUPS ; central backup directory
          send=XM S %1  ; xm is the default, but you can change it.
                  ; %1 locates the filename(s) to be transferred.
                  ; Change it to OMI for the OMNI protocol, or hydracom
                  ; or DSZ for Omen's zmodem package.
          receive=XM R  ; use none to disallow file transfers
          feed=no       ; yes would feed response file lines one at a
                        ; time to the 'send' file transfer tool
          copy=yes      ; could be none or no
          move=yes
          erase=yes
          query=yes

          All of the commands are considered to be insensitive to case.
          You can use either capitals or lowercase, unless you change
          the file transfer tool to another tool that expects only one
          case.

          Archiver is your preferred archiver, such as PKZIP or LHA with
          the appropriate switch(es).

          Backup_directory is for a central backup directory where
          archives are created.  Its a good idea to create the archive
          files then copy them to diskettes or over the 'phone line.  It
          also creates a third backup copy of your information.

          The program after 'send=' is the file transfer tool and
          protocol for sending.

          The program after 'receive=' is the setup for receiving over
          the 'phone line.

          Feed indicates whether gather should feed the transfer
          instructions to the file transfer tool one line at a time, or





                     The GATHER.TXT           Page 7



          just give it the whole file to use, as a response or control
          file.  Both XM and hydracom can take the entire file if you do
          not mix copy, move, or erase commands into the file.
          Generally, its a good idea to set feed=no or feed=none for XM,
          because it also knows how to ignore copy/move/erase commands
          that it finds in files.  Do the same for hydracom and other
          transfer software if you know that the input file has no
          problem causing commands in it.

          Copy, move, and erase are for normal same machine file
          copying, moving, and erasing.

          Query is the file query switch.  Adding it on the command line
          will tell gather to ask you before copying/moving/erasing.  If
          you set "query=none", this will turn-off the the command line
          "-Q" command globally.  Use -Q- to deliberately turn it off.
          The January, 1994 Gather has query defaulting to on.  Earlier
          versions defaulted to off.

          These switches are global in that they 'overpower' any command
          line commands that you might use, as a form of security.  They
          allow you to setup gather to restrict file
          copying/moving/erasing/transfer both by itself and while using
          TeleShare.


          Filename macros

          Gather recognises two macros:  $(DAY) and $(HOUR) mainly for
          backup filenames.  So "BAK$(DAY)$(HOUR)" will become BAK2510
          if the filename is created on the 25th day of the month at 10
          AM.  If you are archiving it might become BAK2510.ZIP or
          whatever.


          Other checks:

          This version of gather does disk space checking, but does not
          check the destination for sufficient space to copy a file.  It
          uses a 'fast write' to the bios, instead of using DOS or
          direct screen writing.  Use -redir for DOS screen output.

          P.C Softsmith distributes an interactive TOUCH program that
          allows you to alter the time and date of any file to any other
          time and date, which can be useful when used for software
          development and for 'backups' with gather.  Ask for it.







                     The GATHER.TXT           Page 8



          SUPPORT


          For technical support, either call (604) 433-5189, or write to
          Suite 606 - 6455 Willingdon Avenue, Burnaby, British Columbia,
          Canada, V5H 4E4.  Both registered and soon to be registered
          users currently get the same support without any arbitrary
          time limit.  You may also try leaving a Compuserve message at
          75020, 2664, or better yet send email to

          INTERNET:vic_williams@mindlink.bc.ca


          P.C. Softsmith                       (604) 433-5189
          Suite 606 - 6455 Willingdon Avenue,
          Burnaby, British Columbia,
          Canada, V5H 4E4


          Please consider reporting the circumstances of ANY problems
          that you discover, preferably in written form, to technical
          support.


          Some possible problems:

          The TSR option will not run after MSWindows is running. If you
          must do this, ask for such a version, or just run it ahead of
          Windows.  It can be reset to do so, but it will then be
          unusually agressive running under DOS.

          You might possibly create a situation where gather runs out of
          internal memory.  Gather has the capability to have such
          memory usage altered at start-up, but this version does not
          include such a command line switch.  Yell if you find such a
          need.

          The -SHOW option overwrites your program's screen.  Sorry, but
          the other options would require delays so humans could see the
          message.  Try avoiding the -SHOW option in such a case.

          The clock appears in the wrong place.  Please wait for a
          version using the TELE.INI configuration file.

          It repeatedly copies the same file to the backup directory.
          Yes, if you are using the -days option, it is following your
          instructions.






                     The GATHER.TXT           Page 9



          It takes too much memory away from my usual applications.  Try
          running it in a batch file during gaps in your work.  There
          are some nifty small background TSR backup programs around.

          It does not check the available destination disk space before
          copying a file.  If you believe that this is a major problem,
          please indignantly say so, in order to encourage its addition
          to the next release.  From a software developer's viewpoint
          this is the start of adding an unlimited number of features
          with the next likely feature being to add priorities for
          copying individual files.  A complication is that such ongoing
          backups often overwrite previous copies of the same file, so a
          simple disk space check is not sufficient.


          This product is Copyright (C) 1993-4 P. C. Softsmith all
          rights reserved.  It is distributed as shareware and must be
          distributed with this documentation.  It is normally
          distributed with other P.C. Softsmith materials that further
          explain the shareware process.  If you wish to distribute it
          with your software or are unable to find the other
          documentation that should accompany this file (such as the
          SHR_WARE.TXT, FILE_ID.DIZ, and the VENDOR.TXT) please contact
          whoever gave you the software or P.C. Softsmith. If you just
          want to use this product on its own, you may license its use
          for $US 10.00.

          History: (by date & version)

          November, 1994
          3.01 fixed problem with DOS find_first/find_next functions
          August 3, 1994
          3.00 Added $(DAY) and $(HOUR) macros
          July 19, 1994
          3.00  Added archiving capability.
          July 14, 1994
          2.52  Correction/update:  The Hands On OMNI setup uses
          the Wizard but not a response file.  Minor usage changes.
          June 7, 1994
          2.51  minor changes to this manual.
          April 5, 1994
          2.51  Documentation changes for the HANDS ON remote
          access OMNI protocol.
          March 18, 1994
          2.5 version change to match Teleshare.  There is now a
          Teleshare Gather distribution specifically for remote and
          local file management.
          March, 1994





                     The GATHER.TXT           Page 10



          2.1 minor changes but Teleshare remote menu program mentioned
          in the manual.
          December, 1993
          2.1 improves file attribute checking for read only files etc.
          2.0  uses the TELE.INI file for copy, move, erase, the [R][S]
          file transfer capability, and the optional Query switch.
          November, 1993
          1.10 improved wild card (*) handling and PATH support.
          1.01 adds the -N rename switch and a larger stack.
          1.00 was released in June, 1993.

          ASP Introduction:

          Please also carefully read the accompanying SHR_WARE.TXT
          document.

          "This program is produced by a member of the Association of
          Shareware Professionals (ASP). ASP wants to make sure that the
          shareware principle works for you. If you are unable to
          resolve a shareware-related problem with an ASP member by
          contacting the member directly, ASP may be able to help. The
          ASP Ombudsman can help you resolve a dispute or problem with
          an ASP member, but does not provide technical support for
          members' products. Please write to the ASP Ombudsman at 545
          Grover Road, Muskegon, MI 49442 or send a CompuServe message
          via CompuServe Mail to ASP Ombudsman 70007,3536."


          THE DOCUMENTATION AND ASSOCIATED SOFTWARE ARE DISTRIBUTED AND
          SOLD WITH NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING
          ITS MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE.
          THE INFORMATION IN THIS DOCUMENTATION IS SUBJECT TO CHANGE
          WITHOUT NOTICE AND DOES NOT REPRESENT A COMMITTMENT ON THE
          PART OF THE VENDOR.

          OTHER PRODUCT AND BRAND NAMES MENTIONED ARE TRADEMARKS OR
          REGISTERED TRADEMARKS OF THEIR RESPECTIVE HOLDERS.
          SPECIFICALLY XBASE IS THE GENERIC DATABASE INDUSTRY
          REPLACEMENT FOR THE REGISTERED TERM 'DBASE' OWNED BY BORLAND
          INTERNATIONAL.












