Shareware Supreme Volume 6 #1

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

/ Shareware Supreme Volume 6 #1 / swsii.zip / swsii / 124 / ATBAT101.ZIP / ATBAT.DOC next >

Wrap

Text File | 1993-04-04 | 59.0 KB | 1,585 lines

ATBAT (tm) Ver. 1.01 Copyright (C) 1993 SOFTWEST All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER 5120 Campbell Ave. Suite 216 San Jose, CA 95130 (408) 370-7095 (408) 370-7096 (FAX) CIS: 70205,533 (Tom Crosley) ATBAT is a utility for AuTomatically creating and executing BATch files which consist of a list of files, each associated with the same DOS command or other text. The files may be optionally selected via some criteria such as size, age, attributes, or contents. ATBAT can also be used for many other purposes, such as automatically creating "make" files used by programmers, and to generate custom directory listings. Packing List ------------ The complete ATBAT 1.0 evaluation package (typically compressed into a .ZIP or self-extracting .EXE file) should contain the following files. Please be sure that each file is present. If any of these files are missing then the package is not complete and is not suitable for distribution to others. File Name: Purpose of File: ------------ ----------------------------------------- ATBAT.DOC This text file. User manual, warranty disclaimer, plus information on registering your copy of ATBAT. ATBAT.EXE The executable program for IBM PC/XT/AT/PS2 and 100% compatible computers running MS-DOS/PC-DOS 2.10 or later with a minimum of 256K RAM (and any compatible display). FILE_ID.DIZ Standard file description ("Description In Zip"), for Bulletin Board Systems (BBS) and disk vendors. -1- ORDER.DOC Self-contained order form/mailer SYSOP.DOC Information for BBS distribution. VENDOR.DOC Information and restrictions for disk vendors, distributors, user groups, and more. Disclaimer of Warranty ---------------------- Users of ATBAT must accept this disclaimer of warranty: "ATBAT 1.0 is supplied as is. SOFTWEST disclaims all warranties, expressed or implied, including, without limitation, any warranties of merchantability or fitness for any purpose. SOFTWEST does not assume any liability for the use of this software beyond the original purchase price of this software. Improper use of this software can be hazardous, since it is possible to create a batch file which will delete or modify a large number of files at once, up to and including all the files on your computer. In no event will SOFTWEST be liable to you for any additional damages, including any lost profits, lost savings or other incidental or consequential damages arising from the use of, or inability to use, this software, even if SOFTWEST has been advised of the possibility of such damages." 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. -2- Overview ======== For a summary of program usage and options, simply run ATBAT with nothing else typed after the command. ATBAT's primary purpose is to create and execute batch files (files ending in a .BAT extension) which consist of the same command operating over and over on a list of files. If you are unfamiliar with batch files, they are described in your DOS manual and in most books that discuss using DOS on IBM-compatible PC's. ATBAT has been primarily tested under MS-DOS 5.0 and 3.3 (both with and without NDOS, a command line interpreter replacement from Norton Utilities based on the shareware product 4DOS). ATBAT should work with any version of DOS 2.1 or later, including MS-DOS, PC-DOS, and DR-DOS. There is no installation per se; just copy ATBAT.EXE to a subdirectory such as \BIN or \UTIL which is included in the PATH statement of your AUTOEXEC.BAT FILE. As an example of when to use ATBAT, let's say you're running low on free space on your hard disk, and decide you want to clear out all your ".BAK" files. If you have a large hard disk with many subdirectories, this is not an easy task to accomplish using just ordinary DOS commands since the MS-DOS DEL command cannot traverse subdirectories. (DEL commands in other command line interpreters such as 4DOS can, but they don't have the additional file selection capabilities described below that ATBAT does). If you have a disk manager such as Xtree Gold you could fire it up, but that takes time to log all the directories and you still have to tag just the *.BAK files, and then delete them. If you decide you want to do this every week or so, you can't write a batch file to do the task. If you have MS-DOS 5.0 or a later version, you can create a list of all the .BAK files using the command: DIR /B /S *.BAK > TEMP.BAT but then you would have to go into a text editor and add "DEL" in front of each line before executing TEMP. If you're like me, you've probably done something like this at sometime or another. Again, not something you can automate very easy. With ATBAT, this is all much simpler. You can type the command: ATBAT "DEL #P" /S *.BAK > TEMP.BAT and ATBAT will search all the subdirectories (/S) at or below the current one for files with a .BAK extension, and then create a file TEMP.BAT with "DEL" in front of each pathname. -3- The first parameter (DEL #P) is a "template" for creating the list of commands to be executed. If a template contains any spaces, it must be surrounded by double quotes as shown above. In this case, #P represents the substituted pathname for each matching file. There are many other "#" substitutions to choose from. Since deleting files is such a common task, you can use #Z (Zap files) instead of "DEL #P". And since creating, executing, and then deleting a temporary batch file is also a common operation, there is a single command line option (/X) for this, too. (Another advantage of using the /X option, rather than redirecting to a file, is you get to see the files that are going to be deleted.) So the command to delete all your .BAK files becomes just: ATBAT #Z /S \*.BAK /X I have added a \ in front of the file specification (referred to as file spec from here on) to force ATBAT to start its search from the top level directory. That way, the command works from anywhere, not just from the root. There are also command line options to select files based on their attributes, or their date or their size, and whether they contain (or don't contain) a matching text string. All of these selection switches can operate together, so it is a simple matter, for example, to say "I want to delete all my .BAK files more than 10K bytes long and over 1 week old": ATBAT #Z /S /K10 /D7 \*.BAK /X If you want, you can stick this in your AUTOEXEC.BAT file and clean up old .BAK files every time you start your computer. (For such cases, there are additional switches for suppressing the normal "in progress" messages, and for eliminating the default confirmation before executing the generated batch file.) Have more than one hard disk volume? No problem, you can list as many file specs as you want: ATBAT #Z /S /K10 /D7 C:\*.BAK D:\*.BAK G:\*.BAK /X I have been showing the /X option at the end, and the others before the file specifications since that's the order in which they will be executed, but the order doesn't make any difference. The only requirement is that the template (#Z in this case) must be before any of the file specs. In addition, options can be preceded by either '/' or '-', and be typed in upper or lower case (the case of the option determines the case of the substituted filenames). So the above command could just as well have been written as: -4- atbat -x -d7 -k10 -s #z c:\*.bak d:\*.bak g:\*.bak I'll continue to use uppercase in my examples though, just to make them stand out better. That's it for the basics. There's many more examples below, where I cover each of the template substitutions and option switches, one by one. Each of these are also summarized in a couple of on-line help screens, which come up if you just type ATBAT by itself. Templates ========= The template is the pattern of what the output is going to look like -- whether it is going to a file, or just displaying on a screen. If you are creating a batch file which will be executed, you must explicitly include a DOS-executable command at the beginning of your template. (There are also lots of applications for ATBAT where you don't need to include a DOS command, such as creating custom directory listings.) Except for possible option switches which can go most anywhere, the template must be the first thing after the ATBAT command itself. A DOS command line is broken up into "parameters", and ATBAT considers the first parameter which doesn't start with a '-' or '/' character (the lead-in characters for options) to be the template. All non-option parameters after the first one are considered to be file specifications. Since almost all DOS commands need a space between the command itself and their first parameter, typically you need to include a space after the command in your template too. However this causes DOS to break the template into two parameters before giving it off to ATBAT, and ATBAT won't see the template as you intended (it will treat the second half as the first file spec). The way around this is to always enclose the template in double quotes if it contains any embedded spaces: atbat "DEL #P" /s *.bak > temp.bat <--- do this atbat DEL #P /s *.bak > temp.bat <--- NOT THIS! -5- Template Substitutions ====================== Much of the flexibility of ATBAT comes from the large number of substitutions that can be carried out in the template. I'll cover them in logical groups now; they're listed in alphabetical order in the help screens. File name substitutions: ------------------------ #P = full Path and name of file #: = drive letter (without the :) #R = paRtial path #N = fileName #E = Extension (without the .) #F = Filename and extension (similar to #N.#E) You will probably use the file name substitutions more than any others, since a typical use of ATBAT is to generate a batch file which operates on a group of files that you have selected. The most general filename substitution is the full pathname (#P), such as C:\DOS\HIMEM.SYS You can also reference each individual part of the full path by itself however, so for the previous example, the separate components would be: #P - full pathname, such as C:\DOS\HIMEM.SYS #: = drive letter (no :) => C #R = paRtial path => \DOS #N = fileName => HIMEM #E = Extension (no .) => SYS The individual components are stripped of their usual punctuation (the : after the drive letter, the final \ in the partial path, and the . before the extension) to allow you to do most anything you want with them. The combination #N.#E comes up so often ATBAT includes a special shorthand substitution #F just for this. There is a subtle difference though; if a filename doesn't have an extension, #F will not have a trailing period, but #N.#E will (which can be useful sometimes). So the full path template #P can also be written out as: #::#R\#F Note the two colons in this example; the first one is part of the drive letter substitution #:, and the second one puts a : after the drive letter. -6- You can use either upper or lower case in the filename substitutions. The output will be the same case as the that of the template substitution letter. So #P will cause all paths to be upper case, and #p will output them in lower case. Likewise for the others: #E/#e, #F/#f, #N/#n, #R/#r. The drive letter substitution #: is always uppercase; there is a lowercase version available by typing #; File attribute substitutions: ----------------------------- #S = file Size in bytes #K = file size in Kbytes #D = Date, as mm-dd-yy (or dd-mm-yy or yy-mm-dd) #T = Time, as hh:mm(a/p) #A = file Attributes, RHSA/D: Read-only/Hidden/System/Archive/Directory The file attribute substitutions are most often used when you want to create some type of customized directory listing. The #S substitution lists the size of the file in bytes, the same as reported by the DIR command. It is a decimal number right-justified in a nine-digit field, to allow for individual files up to 999,999,999 bytes (!). Be sure to allow for all nine character positions when planning output formats. The #K substitution also lists the size of the file, but in kilobytes instead of bytes. (1024 bytes = one kilobyte.) The #K file size is a decimal number right-justified in a six-digit field, to allow for individual files up to 999,999 Kbytes. As before, be sure to allow for six character positions in your output. There is no difference between #S and #s, or #K and #k since neither generates any alphabetic characters. The #D substitution gives the date the last time the file was modified (or created, if it has not been modified). The format for the #D output is usually dependent on the COUNTRY= line in your CONFIG.SYS file; e.g. the line COUNTRY=044,,C:\DOS\COUNTRY.SYS selects the United Kingdom, which uses the European date format (dd-mm-yy). If there is no country selection, the program defaults to United States convention, which is mm-dd-yy. The third format, yy-mm-dd, is used in Japan. You can tell which format is going to be used, since the Help screens for the #D and /D options also change accordingly. It is also possible to change the date format using a option switch (/DF), which is explained further on in the section on options. -7- There is no difference between #D and #d, since neither generates any alphabetic characters. The #T substitution gives the time when the file was last modified (or initially created, if it has not been modified). The format for the #T command is always hh:mm, followed by and A or P for AM/PM (or a/p for am/pm if #t is used instead). The time format does not usually change based on different COUNTRY settings; however the date format switch (/DF) discussed below can also be used to specify 24-hour (sometimes called "military" time) to be output instead, in which case the A/P is of course not present. The #A template substitution is replaced by the file attributes for the file: a combination of read-only, hidden, system, and archive or directory (for further information on what each of this are used, consult your DOS manual). The file attributes are output in a fixed size field of four characters (the A and D attributes share the same position). If the attribute is off, it is replaced by an underline: RHSA read-only, hidden, system, archive set ___A only archive set _H_D a hidden directory The case (upper/lower) of the letters is determined by the case of the template substitution letter (#A or #a). Since the template substitutions can be arranged in any order, it is possible to generate directory listings completely different from the normal DIR command. For example, let's say you want to display the file attributes and dates of the files in the root directory of your C: drive. The DOS command to display the attributes is: ATTRIB C:\*.* which displays on my system (as an example): A SHR C:\IO.SYS A SHR C:\MSDOS.SYS A C:\CONFIG.SYS A C:\AUTOEXEC.BAT A C:\COMMAND.COM This doesn't tell you the dates of the files -- you would use a separate DIR command for that. NDOS/4DOS allows you to display the file attributes with their DIR command, so you could emulate the above display by typing the NDOS/4DOS command: -8- DIR /T /A:-D /K /M /C /O:U C:\ which would display: IO.SYS 33430 4-09-91 5:00a RHSA MSDOS.SYS 37394 4-09-91 5:00a RHSA CONFIG.SYS 4571 1-10-93 11:34a ___A AUTOEXEC.BAT 3278 1-11-93 8:26a ___A COMMAND.COM 47845 4-09-91 5:00a ___A But this gives more information that you wanted, and puts the attributes last. Maybe you'd rather have them first, as in the ATTRIB command. This is no problem for ATBAT; just type ATBAT "#A #D #F" /A C:\ which would display the following: RHSA 4-09-91 IO.SYS RHSA 4-09-91 MSDOS.SYS ___A 1-10-93 CONFIG.SYS ___A 1-11-93 AUTOEXEC.BAT ___A 4-09-91 COMMAND.COM With the template substitutions, you can even reverse the entire order of the fields in a typical DIR display: ATBAT "#T #D #S #F" C:\ which would display: 11:34A 1-10-93 4571 CONFIG.SYS 8:26A 1-11-93 3278 AUTOEXEC.BAT 5:00A 4-09-91 47845 COMMAND.COM Miscellaneous substitutions: ---------------------------- #Cnn = skip to output Column nn (if no nn, tabs to 9,17,25 etc.) In the last example, the template substitution #F displayed filenames with the names and extensions concatenated together, as they are usually typed on a command line. But what if you want to put the extensions in a separate column, like the DOS DIR command (or the /J option of the NDOS/4DOS DIR command)? The #C template substitution lets you cause the output of ATBAT to "skip" to the output column immediately following the #C. (If no column number is given, the #C skips to the next "tab" position which is a multiple of 8, plus 1: 9, 17, 25, etc.). For example, the command: ATBAT "#N#C10#E#C13 #S #D #t" C:\ -9- displays files in a format similar to that of the DOS DIR command: col 10 col 13 | | CONFIG SYS 4571 1-10-93 11:34a AUTOEXEC BAT 3278 1-11-93 8:26a COMMAND COM 47845 4-09-91 5:00a To account for all the white space before the size, remember it is output in a fixed nine-digit field. The command ATBAT "#f#C13#S #D #t" C:\ mimics the NDOS/4DOS DIR command instead: col 13 | config.sys 4571 1-10-93 11:34a autoexec.bat 3278 1-11-93 8:26a command.com 47845 4-09-91 5:00a Note the use of the lower case #t and #f in the previous examples to match the corresponding directory formats. #V = environment Variable ATBATSUB If you want to use templates like those above, it's rather laborious to type the whole thing over and over again. Instead, you can set up an environment variable ATBATSUB with you favorite template: SET ATBATSUB #N#C10#E#C13 #S #D #t Note that no double quotes are necessary around the template in this case. You can then type just #V in place of all of those template substitutions, i.e.: ATBAT #V C:\ is now the same as ATBAT "#N#C10#E#C13 #S #D #t" C:\ You can also combine #V with additional template substitutions, so if you wanted to add the attributes to the end of the directory listing, just type ATBAT "#V #A" C:\ would display: CONFIG.SYS 4571 1-10-93 11:34a ___A AUTOEXEC.BAT 3278 1-11-93 8:26a ___A COMMAND.COM 47845 4-09-91 5:00a ___A -10- #Z = Zap files, same as "del #P" This one has already been touched on in the Overview, but in case you missed it, #Z is simply a shorthand way of writing "del #P", since this particular combination seems to come up a lot (at least for me, seems like I'm always looking for more room on my hard disk!). Like the other substitutions generating alphabetic output, the case of the template substitution determines the case of the output (#Z => "del #P", #z => "del #p"). Other substitutions: -------------------- #I replaced by file number (4 digits, zero-filled) #J replaced by file number (3 digits, zero-filled) These two substitutions allow you to create unique filenames for every file spec generated. Say you want to copy all of your files named README to one place, called READMES. If you typed: ATBAT "COPY #P \READMES" /S README (DON'T DO THIS!) this would copy each of the files on top of each other, and you would only end up with one file in the directory. You can avoid this by creating a unique extension for each one, using the #J substitution: ATBAT "COPY #P \READMES\#N.#J" /S README This will copy the first file as README.001, the next as README.002, and so on. The #J is replaced by a zero-filled number starting with 001 and incremented by one for each new matching file specification which meets the given selection criteria. #I is similar, but it is a four digit number starting with 0001, suitable for creating up to 9999 temporary filenames, such as TEMP#I. !! replaced by a newline (CR/LF) So far we have been exploring single line substitutions; but ATBAT also has the capability of generating more than one line per matching file spec. Let's say you want to move a number of files from one directory to another. MS-DOS (prior to Version 6.0) doesn't have a move command, just a copy command -- so you have to do a copy first, and then a delete. The following will do just that: ATBAT "COPY #P C:\NEWDIR!!DEL #P" *.TXT This will generate a COPY command, followed by a DEL command for each file ending with .TXT in the current directory. There is an implied !! at the end of every template, unless you suppress it with the /N option discussed under options. -11- The !! substitutions will take place both in the template and in the text for the text search option /T, discussed below. %% is replaced by a single % Often, batch files created by ATBAT are executed and deleted right away and not used again. But sometimes you might want to generate a batch file which you will use from the command line later on, and want to be able to pass command line parameters to it. Since DOS will try to substitute anything starting with a % in your command line passed to ATBAT, you can't simply put a %1 (for example) in your template and expect it to be in your generated batch file. Instead you need to use double %%'s, as in ATBAT "PKZIP %%1.ZIP #P" *.DOC /F:ZIPDOC which creates a batch file that can later be called by typing ZIPDOC zipname which in this particular example will compress the same set of files ending with the extension .DOC into a .ZIP file whose name is given as the first parameter to the batch file. #] becomes > #} " >> #[ " < #! " | #' " " #- " = #_ " space #& " (nothing) ## " # These substitutions allow you to pass characters to ATBAT that otherwise might get interpreted by DOS, such as the redirection and pipe characters >, >>, < and |. The #& is a concatenation operator that allows you to create sequences that might otherwise be misinterpreted by ATBAT; for example if you want to tab to the next output column and then output a number, you can type #C#&100. If you had typed #C100 instead, ATBAT would have used the number as a column to skip to. These substitutions will take place either in the template and in the text for the text search option /T, discussed below. Any combination of '#' followed by a character not in the above list (or covered earlier) is considered an error. -12- Command Line Options ==================== All options must be preceded by either a '/' or '-' character, and can be type in either upper or lower case. Each option must be listed separately, surrounded by spaces: ATBAT #Z /S /X \*.BAK <--- do this ATBAT #Z /SX \*.BAK <--- NOT THIS! Text following an option switch, such as a date or list of attributes, should have no embedded spaces. The only exception to this is the text for a /T option, which must be enclosed in double quotes if it contains spaces. Traversing options: ------------------- /S also traverse Subdirectories; /S \*.BAK is all .BAK files on drive /B like /S, except <only> traverse subdirectories (all files Below) Like most DOS commands, by default ATBAT only looks at the files in the current directory if no explicit path is specified on the command line, or at just the specific file specifications listed. You can also ask ATBAT to traverse subdirectories in addition to the current or specified path (the /S switch, present in several DOS commands too); or <just> traverse the subdirectories below (/B switch) the current or specified one. This latter option is rather useful when you want to get rid of unneeded files below your current directory, but don't want the corresponding files in the current directory deleted. For example, as a programmer I usually create daily directories below my current project directory to hold backups of the previous day's work. But I don't really want to keep all the .OBJ files around, since they can be regenerated if need be just be doing a re-compile. But if I typed: ATBAT #Z /S *.OBJ /X this would also delete the .OBJ files in my current directory, not what I had intended! (The DEL /S *.BAK command in 4DOS has this same limitation.) But by typing ATBAT #Z /B *.OBJ /X instead, only the .OBJ files in subdirectories below the current one will be deleted. -13- Selection options: ------------------ /D:mm-dd-yy select files modified on/after (- means before) Date /D:nnn select files modified >= nnn Days ago (- means <) /K:nnnn select only files >= (- means <) size nnnn (in Kbytes) /A:adhrs select (- don't select) Attributes: Archive/Directory/Hidden/Read-only/System /T"text" select only files containing (- not containing) "Text" /I Ignore case when searching (/T) Often you don't want to act on a file just based on it's name or extension, but want to narrow your selection further. MS-DOS doesn't have much to offer in this area; the FIND and ATTRIB commands will display files which contain certain text or have selected attributes, but you would have to redirect the output to a file and edit it as discussed before. File managers, such as Xtree Gold, and the SELECT command in NDOS/4DOS let you select a set of files, but you have to intervene manually to do so, and cannot automatically build a batch file which can be run for example from your AUTOEXEC.BAT file. ATBAT on the other hand allows you to select files based on their last date modification, or their age, size, attributes, and whether they contain (or don't contain) certain text. The /D:mm-dd-yy option selects only those files modified on or after midnight on the date specified. (If the file has never been modified since it was created, the creation date is used). The format for the /D:date command is the same as for the #D template substitution discussed earlier, and is based on the COUNTRY setting in your CONFIG.SYS file. If you immediately precede the date with a minus sign (or a 'b'), as in /D:-2-9-93, then only files created or modified <before> the specified date will be selected. You must specify at least two parts of the date for it to be recognized as such (otherwise it looks like an age specification, discussed next). ATBAT tries to be fairly intelligent when you give it only a partial date; if a number is >= 80 and <= 99, it is assumed to be a year in the 20th century (1980 through 1999); if it is a number between 00 and 09 (note the leading 0), it is assumed to be a year in the 21st century (2000 through 2009). Otherwise it is assumed to be a month or day, as appropriate. Altogether, nine formats are possible: Date style ---------- United States mm-dd-yy or mm-yy or mm-dd European dd-mm-yy or mm-yy or dd-mm Japanese yy-mm-dd or yy-mm or mm-dd -14- If the year is not given, the current year is assumed; except that if that would create a date in the future, then last year is used. (So if the current date was July 1, 1993, and the format is US, 7-1 would imply 7-1-93, but 7-2 would imply 7-2-92). While testing the program, I put in an option to force the date format to be a specific one; it turned out to be so handy that I have left it in for general use too. The option is: /DF0 selects US format and 12-hour time (AM/PM) /DF1 selects European format and 12-hour time /DF2 selects Japanese format and 12-hour time /DF3 selects US format and 24-hour (military) time /DF4 selects European format and 24-hour time /DF5 selects Japanese format and 24-hour time Usually, the specific placement of an option on the command line has no effect; but the /DF command is an exception. If the /DF option precedes the /D:date option, it affects the input format; and if it follows the /D:date option, it affects only the output format. So it is possible to have one format for input and a second for output. (If there is no /DF command after the /D:date, the output format is the same as the input). The /D:nnn option selects only those files modified at least nnn days before the current date and time. (If the file has never been modified since it was created, the creation date is used). If you immediately precede the age with a minus sign, as in /D:-30, then only files created or modified less than nnn days before the current date and time will be selected. The /D:age option is subtly different from the /D:date option in the following way: the age version actually uses both the current date and time, and subtracts 24 hours times the number of days specified to do its comparison. The date option does its comparisons based on date only; the time portion is not used. So if it is 2:00 PM on May 10, 1993, and you typed the following command: ATBAT #Z /D:-5-10 . /X all files created/modified before midnight of May 10 would be deleted including any files dated the previous day, May 9. However the command ATBAT #Z /D:1 . /X would select only files at least 24 hours old, and not delete any created or modified after 2:00 PM on the previous day. The /K:nnn option selects only those files whose size in kilobytes (1024 bytes = one kilobyte) is greater than or equal to that specified. If you immediately precede the size with a minus sign, as in /K:-10, then only files with a size less than nnn kilobytes will be selected. -15- As in the DOS DIR command, the /A option in ATBAT allows you to select (or de-select) files based on their attributes: archive, hidden, read-only, system, and directory. Similar to DOS, if the /A switch is given without anything following it, then all files are selected, including archive, hidden, read-only, and system. But there is a difference between ATBAT and DOS: by default DOS displays directories, and the ATBAT doesn't (the reason being, you typically don't want to select directories as parameters to another DOS command). So if you want both the directories and files listed, you must explicitly include the /A:D switch. Putting a minus sign in front of any single attribute says to de-select those files which have the corresponding attribute. You can think of the default switch for ATBAT therefore as being /A:-H-S-D, whereas the default switch for DIR is /A:-H-S. The /T option allows you to select only those files containing the text immediately following the /T option (which must be enclosed in double quotes if it contains any spaces). Preceding the text with a minus will cause all files which <don't> contain the matching text to be selected. (If quotes are present, the minus should go before the first quote). Normally the search is case sensitive; however this can be turned off by including the /I option along with the /T option (the /I can go either before or after the /T). The various substitutions of '#' followed by a punctuation character (e.g. "#}" replaced by ">>", etc.) take place in the search string as well as the template, to allow special characters which might be interpreted by DOS to be passed to ATBAT. The !! pair (which is replaced by a newline) causes the text search to be "anchored" at one end of a line or another. For example, the string -t"!!Feature" will only find the word "Feature" at the beginning of a line, and the string -t"time!!"" will only find the word "time" at the end of a line. The /T option makes ATBAT into a variation of FIND (or FILEFIND, or GREP); except of course with ATBAT you can also be simultaneously selecting based on other criteria, such as file attributes, date of last modification, and size. Unlike some of the other programs that search files for text, ATBAT always opens files in binary mode which means that you will never get a message like "Line too long, search aborted". This can be useful if you are searching large .EXE files for a particular text string. -16- Output options: --------------- /F:file also output to a File (default /F is to replace TEMP.BAT) /E:arq if output file already Exists, Append, Replace, or Quit /Q run Quietly -- no /F output echo /X:file like /F, but also automatically eXecute output file at end /P- suppress Pause before /X A program is not much use unless you can use its output, and ATBAT is no exception. Without any specific options, ATBAT writes all of its output to the screen. However there are really two output streams: all output generated as a result of substitutions in the template (one line for each matching file in the file spec) goes to the "standard output", which can be redirected to a file using the > character in DOS. All messages, including the banner, error messages, "in progress" messages, and the closing message in the shareware version go to the "standard error" output, which cannot normally be redirected. (Refer to your DOS manual for more information about redirection using the > and >> character sequences.) One side effect of this arrangement is that it allows the output of the program to "piped" into the input of another using the '|' symbol (for more information about pipes, refer to guess where.) In the earlier examples where we were creating custom directory listings, if we add a sort command at the end: ATBAT "#f#C13#S #D #t" C:\ | SORT then the files would be sorted in alphabetical order: autoexec.bat 3278 1-11-93 8:26a command.com 47845 4-09-91 5:00a config.sys 4571 1-10-93 11:34a Since the sort command allows an optional switch (/+nn) to specify the column containing the sort key, the filename does not have to be at the beginning of the line. ATBAT's #Cnn template substitution can be used to force the filename to a specific column which is then also passed to the sort. It is also possible to create a batch file using redirection of the standard output, as in the first example of this manual: ATBAT "DEL #P" /S *.BAK > TEMP.BAT However you will not see the commands going into the file, and if you wanted to check it before executing TEMP, you would have to separately list TEMP.BAT before continuing. -17- The /F file output option gets around that, by causing output to both go to a file and be displayed on the standard output. It is also safer to use, since if the file specified already exists, ATBAT will ask: File FILENAME.BAT exists! A)ppend, R)eplace, or Q)uit? and you must press either the A, R, or Q key to continue (Pressing Escape will also Quit). If you do not specify a filename after the /F option, then a default filename of TEMP.BAT will be used. It is replaced by default without asking. If you specify a filename without an extension, the default extension .BAT is used. By using the A)ppend option, it is possible to build up a more complicated batch file from several ATBAT commands. The same affect could be achieved by redirecting the output of the program using >> instead of >, but using redirection the output will not display the output on the screen. If you want to automatically run ATBAT, say from the AUTOEXEC.BAT file and know in advance is okay replace or append to an existing file, the /E option can be used. It supplies a default answer (A, R, or Q) to the "File exists" message so the program can continue without pausing. You may also want to run ATBAT from your AUTOEXEC.BAT and not have any of the usual output displayed; in that case you can specify the /Q option, which inhibits any echoing of the standard output, and also inhibits all "in progress" messages to the error output stream. So the options: /F:file /ER /Q is equivalent to > file.BAT and /F:file /EA /Q is equivalent to >> file.BAT /F /ER /Q is equivalent to > TEMP.BAT and /F /EA /Q is equivalent to >> TEMP.BAT So why use all these options, when the redirection looks to be just as easy? Because there is another variation on the /F option, /X -- which causes the file just created to be executed. If it is the default file TEMP.BAT, it is automatically deleted also. Without the /X option, you would have to type the name of the batch file after the ATBAT command in order to run it. To make things even simpler, the /X option can take a filename, in which case it acts like the /F and /X options at the same time. So: /X:file is the same as /F:file /X /X is the same as /F:TEMP.BAT /X -18- Because it is rather dangerous to go around executing batch files without knowing exactly what they contain, normally the program pauses just before executing the batch file with the message: Ready to execute file FILENAME.BAT; press Esc to abort or any other key to continue If you are running ATBAT from your AUTOEXEC.BAT file, or some other time where you would like it to continue without having to press a key, you can inhibit the pause using the /P- switch (note the minus after the P). But doing so can be very dangerous; please do not use either the /Q or /P- options until you are very familiar with the operation of ATBAT, and have verified that the ATBAT command you are using does exactly what you want it to. Miscellaneous options: ---------------------- /N suppress automatic Newline for each file (all output goes onto one line) Normally, ATBAT outputs a separate line for each file (plus an extra newline for every !! pair found in the template, as explained in the section on template substitutions). But there are some situations in which you would like to generate a list of filenames with all of them on the same line. An example of this would be generating a "makefile", used by programmers to automatically re-build a program after one or more of the component files has been updated. Note that it is possible with the /N option to create a line too long to be executed under as a DOS command, or edited via a text editor, if there are a lot of full pathnames output. If you insert a !! substitution at the end of a template using the /N option, this will cause a newline to be appended just once, at the end of the entire file. Otherwise no newline at all will be output (which is sometimes useful if the line is being appended to by another ATBAT command). The following is a batch file called MAKEBCC.BAT that contains a series of ATBAT commands which automatically generate a makefile for Borland C/C++ (and can be easily modified for other compilers). It use the names of any object files (.OBJ) already present in the current directory. (I always seemed to need a makefile only after a project was well underway, and then it was a real chore to create one by hand. This batch file assumes one is in that situation.) Note the use of variations of the /n option (without and without a !! at the end of the template) to generate partial lines which are appended to by the following command. -19- atbat "%1.exe:" /n /f:%1.mak /er atbat " #f!!" *.obj /n /f:%1.mak /ea atbat " bcc -e%1.exe" /n /f:%1.mak /ea atbat " #f!!" *.obj /n /f:%1.mak /ea atbat "!!#n.obj: #n.c!! bcc -c #n.c" *.obj /f:%1.mak /ea For example, if a directory contains the files: match.obj dir2.obj string2.obj wildcard.obj and the program to be made is called MATCH, then typing: MAKEBCC MATCH will generate the following file MATCH.MAK: match.exe: match.obj dir2.obj string2.obj wildcard.obj bcc -ematch.exe match.obj dir2.obj string2.obj wildcard.obj match.obj: match.c bcc -c match.c dir2.obj: dir2.c bcc -c dir2.c string2.obj: string2.c bcc -c string2.c wildcard.obj: wildcard.c bcc -c wildcard.c which can be executed by typing MAKE -fMATCH /Hn display Help screens 1 or 2 The easiest way to get on-line help is simply to type ATBAT without anything following the command. Two screens will be output, the first summarizing the command line syntax and available template substitutions, and the second summarizing the command line options. You can also force either of the help screens to appear by typing /H1 or /H2; this is useful, for example if you have typed in a long ATBAT command and then forgotten the syntax for one of the switches. You can just add /H2 to the end of the line: ATBAT #Z /S /K10 /D7 C:\*.BAK D:\*.BAK G:\*.BAK /H2 and the help screen will appear, temporarily ignoring the rest of the line. When done, press the key used to retype the last DOS command line (usually F3), and then backspace over the /H2 and continue your command. -20- /R how to get a Registered copy of this shareware program To register this program, you can print out an order form by typing: ATBAT /R >PRN The instructions for registering will be output to the screen (error output) and the order form itself output to standard output (redirected to the printer in this case). See the section below on Registration for more information about the benefits of registering this program. File Specifications =================== Following the template (with possibly some options in-between) is a list of one or more file specifications. These may be individual file names, but more likely will have wildcards to specify a range of files, such as *.BAK. ATBAT allows both the ? and * wildcards allowed by DOS (refer to your DOS manual for more information about wildcards). You can have any number of file specs on the command line; for example: ATBAT #Z /S C:\*.BAK D:\*.BAK TEMP /X which would delete all .BAK files on drives C and D, and all files named TEMP in the current directory (and below). Each of the files that match the file specification are then matched against any other selection criteria, such as file attributes, size, date and text string. Only those files that pass all the above checks will be substituted into the template. File of Filenames (@Files): --------------------------- If a list of specific files needs to be selected on a repetitive basis, you can use @files. These contain just filenames, with or without wildcards. (You can use ATBAT of course to generate your @files, using just #F or #P as a template). For example, if the file @BAKS contained the following: C:\*.BAK D:\*.BAK TEMP then the previous example: ATBAT #Z /S C:\*.BAK D:\*.BAK TEMP /X becomes ATBAT #Z /S @BAKS /X -21- Error Codes and Messages ======================== ATBAT returns a status code upon program termination, which can be tested with the DOS IF ERRORLEVEL command (this is useful if you are running ATBAT within a batch file). If no errors were encountered, and at least one file was processed, the exit value is zero. Otherwise it is set as follows: Exit value Meaning ---------- ------- 0 Normal exit 1 No files were found meeting criteria 2 No template, or bad substitution char, or bad option, or help screen requested 3 Error executing batch file (/X option) Revision History ================ Date Version Description ---- ------- ----------- 4/04/93 1.01 Fixed bug in -t parameter (was ignoring last character in string); various corrections to manual. 1/20/93 1.00 Initial release. Shareware ========= Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all or to a specific group. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. -22- ATBAT 1.0 is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. Registration ============ If you find this program useful, and continue to use ATBAT after a reasonable trial period you must register it. Basic registration costs just $15. To print out a registration form, either run the program with the /R option, e.g. ATBAT /R >PRN or print the file ORDER.DOC (which is a combination order form and self-contained mailer): PRINT ORDER.DOC When you register, you will receive the latest version of ATBAT (without the registration reminder message at the end of the program), and be eligible for three months of technical support (either by telephone, limited to a total connect time of 30 minutes; or via FAX, CompuServe email, or regular mail). Plus you will receive the latest shareware versions of other programs from SOFTWEST. In addition to the basic registration, you can also order a deluxe printed version of this manual for just $7.50. It is identical in content to the one you are reading, but is easier to read since it is laser printed using multiple fonts, boldface and italics (something impossible to do with just a straight ASCII file). The printed version also has an index and table of contents. You can also order the complete source code for ATBAT for only $20.00. It is set up to compile under both Microsoft C/C++, Version 5.1 or later, and Turbo/Borland C/C++, Version 2.0 or later, and can be used to make custom versions of the program for your own use. The basic registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Corporate users of ATBAT must register and pay for their copies of ATBAT within 30 days of first use or their license is withdrawn. Site licenses (ten or more copies at the same address) may be obtained by contacting SOFTWEST. -23- Anyone distributing ATBAT 1.0 for any kind of remuneration must first contact SOFTWEST (see VENDOR.DOC for more information). This authorization will be automatically granted to distributors recognized by the Association of Shareware Professionals (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering ATBAT 1.0 immediately. You are encouraged to pass an unaltered copy of the shareware version of ATBAT 1.0 along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. By registering your copy of ATBAT 1.0, you will be encouraging future versions of the program. I hope you enjoy using ATBAT, and let me know what you would like to see in the next version. -- Tom Crosley April, 1993 -24-