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.