OS/2 Shareware BBS: 11 Util

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

/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / runfor19.zip / runfor.doc

Wrap

Text File | 1998-03-31 | 26KB | 547 lines

============================================================================ RUNFOR.DOC March 31, 1998 ============================================================================ Ver 1.9 A utility that can run a command for a particular set of files or dirs. This program will work under (hopely) various command shells on OS/2, DOS, Windows 95, and (hopely) Windows NT systems. This is a freeware if you don't modify the program. Use this program at your own risk. Please distribute this document together with executables. ---------------------------------------------------------------------------- INTRODUCTION ---------------------------------------------------------------------------- I wrote this program to make jobs easier with more flexible selections of files/dirs and with more flexible handling arguments of a program to be run when I had to repeatedly enter the similar command for each file or dir for a large set of files, especially when a program does not accept wildcards. ---------------------------------------------------------------------------- INSTALLATION ---------------------------------------------------------------------------- Files included in runfor*.zip are runfor.doc - this documentation os2\runfor.exe - for OS/2 only (requires emxrt.zip) os2\runfors.exe - stand-alone OS/2 executable (doesn't need emxrt.zip) emx\runfor.exe - for OS/2 and DOS/Win (requires emxrt.zip or RSX) win32\runfor.exe - for Win32 (Win95/NT) (requires RSXNT) These programs were compiled by emx/gcc 0.9c, and require either EMX or RSX/RSXNT runtime package installed on your system. Once you have installed a runtime package, copy an executable to a directory in PATH. RunFor has been tested on OS/2, OS/2 DOS box, WinOS/2, MSDOS, Win95 systems, but on WinNT. Where can I get a runtime library package? ------------------------------------------ (1) EMX runtime package (emxrt.zip): ftp://hobbes.nmsu.edu/os2/unix/emx09c/emxrt.zip ftp://ftp.cdrom.com/pub/os2/unix/emx09c/emxrt.zip ftp://ftp.uni-stuttgart.de/pub/systems/os2/emx-0.9c/emxrt.zip Refer to its documentations to install it. (2) RSX runtime package (rsx*.zip): ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc/rsx510b.zip ftp://ftp.cdrom.com/pub/tex/ctan/systems/msdos/dpmigcc/rsx510b.zip ftp://ftp.dante.de/tex-archive/systems/msdos/dpmigcc/rsx510b.zip emxrsx.zip has both EMX and RSX runtime packages: ftp://ftp.cdrom.com/pub/tex/ctan/systems/msdos/emtex/emxrsx.zip ftp://ftp.dante.de/tex-archive/systems/msdos/emtex/emxrsx.zip (3) RSXNT runtime package (rsxnt*r.zip): (superset of RSX package) ftp://ftp.uni-bielefeld.de/pub/systems/ms-dos/misc/rsxnt14r.zip ftp://ftp.cdrom.com/pub/tex/ctan/systems/msdos/dpmigcc/rsxnt14r.zip ftp://ftp.dante.de/tex-archive/systems/msdos/dpmigcc/rsxnt14r.zip [For OS/2 Users] ---------------- As os2\runfors.exe has emx runtime code bound, it does not require emxrt.zip, but normally use os2\runfor.exe whenever emx runtime libs (.dll) are available on your system. You may use emx\runfor.exe under OS/2. Install emxrt.zip if required, and copy an executable to a directory in your PATH. This completes the installation. [For DOS/Win users] ------------------- emx\runfor.exe can run under both platforms of OS/2 and plain DOS with emxrt installed, or under OS/2 DOS box or Windows DOS box with RSX runtime package. RSX is required if you run RunFor under a DPMI host (e.g. Windows 3.x DOS box, WinOS/2, QDPMI, 386MAX, etc.), otherwise emxrt is required. After emxrt.zip and/or rsx501b.zip are installed (emxrsx.zip has both), copy emx\runfor.exe to a PATH. And, if you are using EMX under DOS (VCPI) without any DPMI host, then add: set EMXOPT=-p in your autoexec.bat to ensure enough free memory, and reboot. That's it. (RSX doesn't need -p option, which is ignored by RSX.) If RunFor could not start some DOS programs or crashes, you may not have enough free memory. You need to enable UMB (Upper Memory Block) and allocate enough memory to your memory manager and load DOS in HMA (High Memory Area) in your CONFIG.SYS. A sample CONFIG.SYS would be DEVICE=C:\WIN3\HIMEM.SYS DEVICE=C:\WIN3\EMM386.EXE RAM frame=none HIGHSCAN x=a000-c7ff DOS=HIGH,UMB [For Win95/NT Users] -------------------- win32\runfor.exe was compiled as a Win32 console application for Win95 or NT. You should install RSXNT 1.40 (or later) runtime package (rsxnt14r.zip). Copy win32\runfor.exe to a directory in PATH. This finishes the installation. ---------------------------------------------------------------------------- Setting Default Options by Environmental Variables ---------------------------------------------------------------------------- If you want to change the default settings of RunFor, you may set 'RUNFOROPT' env variable in your CONFIG.SYS or from a batch cmd file. For example, set RUNFOROPT=-HS (No hidden, no system attrib; same as RUNFOROPT=-H -S) Any options can be set in 'RUNFOROPT' env, but I would not recommend you put options that can't be turned off from the command line. If you keep a few copies of executables in different names, you can keep different default settings via their own envs. Those env names are determined by uppercase program name (before the first '.') plus "OPT". For example, if you copied a RunFor executable to 'spawn.exe', the program will first look for 'SPAWNOPT' env before searching 'RUNFOROPT'. If 'SPAWNOPT' is found, 'RUNFOROPT' is not searched. If you make another copy named 'doit.exe', you can set 'DOITOPT' env for doit.exe. Of course, if those envs are not found, spawn.exe and doit.exe share 'RUNFOROPT' env setting. ---------------------------------------------------------------------------- USAGE ---------------------------------------------------------------------------- This program is self-explanatory. 'runfor' and 'runfor -?' will display short or long help screens. (Even if you rename 'runfor.exe' to other name, its help screen will correclty display the new program name.) Refer to the help screen. ---------------------------------------------------------------------------- DISCLAIMER ---------------------------------------------------------------------------- RunFor was originally written for OS/2. RunFor may behave differently or incorrectly under DOS/Win/Win95/NT than OS/2. This program may have bugs as usual. However, please don't blame me. Use at your own risk. ---------------------------------------------------------------------------- Known bugs and problems ---------------------------------------------------------------------------- - Incorrect file access time on Win95 (+/-Ta, %Ta) ---------------------------------------------------------------------------- HISTORY ---------------------------------------------------------------------------- Ver 0.x Ver 1.0 January 18, 1996 - first release to public Ver 1.1 January 19, 1996 - Added English month name in date argument of +T or -T. - Very flexible ordering of date parameters. Ver 1.1a January 19, 1996 (not released) - Fixed: outfile could be incorrectly included in target file list. Ver 1.1b March 19, 1996 (not released) - Use PAGER for long help screen Ver 1.2 June 7, 1996 - New option: @<file> target/exclude list in a file. - New option: -t not to look at disk for valid targets. - New macros: %P and %R for path dir without ending '\' or '/'. - New macro prefix modifiers: %l convert to lowercases %u convert to uppercases %x convert to unix style path ('/') (e.g. %xF) - Changed: %l, %u, %x are global options when used before ':'. Ver 1.2a September 17, 1996 (not released) - Bug fix: broken PAGER support in DOS. - Compiled with emx/gcc 0.9c (fixed some minor glitches) Ver 1.3 October 31, 1996 - Enhanced wildcard expansion support (more robust). - Known bug(?): case-ignore in POSIX pattern matching with [...] doesn't work due to emx/gcc 0.9c's fnmatch(). - @<file> now can include quoted names. Ver 1.4 February 28, 1997 - New feature to -w option: Double option (-ww, -w -w) changes current working dir into target dir, which is one level deeper than single option (-w). - New macro prefix modifier: %m for mixed-case conversion. - New +T and -T options for HPFS drives: +Tm -Tm modified time (default; same as +T, -T) +Ta -Ta accessed time +Tc -Tc created time - +/-T options can now take seconds with hh:mm:ss (previously, hh:mm) - Bug fixed: for +/-T options, incorrect selection by wrong timezone computation and incorrect day of week on screen message. - Removed a verbose message of changing dir ("Entering directory:"). Ver 1.5 March 12, 1997 - New options: +B -B ddd[k|kb|m|mb] file selection by minimum/maximum sizes -o- '-' for standard output. -e- '-' to disable macro expansion in env setting. -@ * next argument is a target name (to escape switch symbol) -x@ * next argument is a exclude name (to escape switch symbol) - New macro codes: %T file date and time (with various formats by prefixes) %[m]B file size %ddd positioning at column 'ddd' in expanded string. - Changes and enhancements: -m don't expand macros (just renamed -n of previous version) -x[@] * now supports disk and path in exclude name pattern. %r macro now gives relative path even if target is in other drive. +/-T now accepts two-digit year for the years of 1970-2069. - Bug fixed: Location of output file (-o) when -w was used. Removed output file from target list. Cleaned some minor glitches when no target or -t was given. Ver 1.6 April 28, 1997 - New option: -C dir change the default dir (of runfor) to "dir" before running. (Useful in makefiles) Ver 1.7 September 18, 1997 - New features: -r[-] [-] to sort dirs first. +/-T [+]* [+] for relative date/time before today. Ver 1.8 November 6, 1997 - New option: +/-E[*] Extended attributes (OS/2) - New macro codes: %E first or matching EA name (OS/2) %E* all EA names (OS/2) %L .LONGNAME value converted to a valid HPFS name (OS/2) - Bug fixes of incorrect screen messages: - current working dir (when targets are on other drive) - job counter within target subdir for -ww option Ver 1.8a January 5, 1998 (not released) - Changed %(ENV) macro: - removed -e- option (disable env macro expansion), - ENV value can have any macro codes to be expanded, - %(ENV)! is not to expand macros embedded in ENV value, - Embedded env macros are expanded up to 10 in recursive depth. - fixed: SHELL & COMSPEC var were ignored. - add -c (instead of /c) for shells other than cmd.exe or command.com. - new feature: -e SHELL=shell spawns child process with given shell. Ver 1.9 March 31, 1998 - Added Win32 (Win95/NT) support by RSXNT (tested on Win95 but not NT) - New macro codes for time info of files: %Tm (modified, same as %T), %Ta (accessed), %Tc (created). - fixed: %T is now empty string for null target ---------------------------------------------------------------------------- Help Screen (Actual output from 'runfor -?') ---------------------------------------------------------------------------- runfor Ver 1.9 - Run a command - Mar 31 1998, W. Kim Syntax: runfor [options] [targets] [-x exclude_names] : [@]command [args] Options: (can go anywhere before ':') -? Help screen (long) (Add suffix '-' to override PAGER: -?-, -h-) -a Targets are both directories and files -c Confirm before each command execution -C * Change the default dir as if runfor was started from there ("runfor -C foo : prog" is equivalent to "cd foo & prog & cd ..") -d Targets are directories (default targets are files only) -h (same as -?) -i Ignore letter cases in POSIX pattern matching (not work without -p) -m Do not expand macro codes in command + arguments -o {*|-} Output expanded cmd args to a file or stdout(-) without executions -p POSIX pattern matching (affects -x as well); Add -i to ignore case -q[q] Quiet [quieter] mode (place -qq before +T or -T to turn off time log) -Q[#] Quit if a command returns an exit code >= # (-Q = -Q1) -r[-] Recursive run for all subdirs; Add '-' to sort dirs first before files -t Don't look at disk to get target names (i.e. use given names as-is.) -t must be given before any target/exclude names. -u Unix style path name ('/' for directory separators); convert all args. -w[w] Change working dir of command to subdir of target [into target dir] +R -R Only files/dirs with(+) or without(-) READ-ONLY attribute +H -H Only files/dirs with(+) or without(-) HIDDEN attribute +S -S Only files/dirs with(+) or without(-) SYSTEM attribute +A -A Only files/dirs with(+) or without(-) ARCHIVE attribute +E* -E* Only files/dirs with(+) or without(-) Extended Attributes (OS/2) A specific EA name (case-insensitive) may be given with wildcards of ?, *, or []. E.g.: +E, +E.longname, +E.*, -E*icon*, +Eepm??*, +E.[!LI]* (EAs starting with a '.' but not followed by 'L' or 'I') +B -B ddd[K|KB|M|MB] Files bigger(+B)/smaller(-B) than 'ddd' bytes/KB/MB +T[?][+][date][;][[hh]:[mm]:[ss]] Files/dirs ON or AFTER the given date/time -T[?][+][date][;][[hh]:[mm]:[ss]] Files/dirs ON or BEFORE the given date/time [?] can be m (modified; default), a (accessed), or c (created). (On FAT drives, modified time == accessed time == created time.) [+] is to give a relative time period before today (like 30 days ago). English month names are not allowed with '+'. date = [yy]yy-{mm|mmm}-dd in almost any order. (mm=1-12, mmm=Jan-Dec) Among 3 parts of date, ';', and time, at least one must be given. Valid date strings with numeric month (mm doesn't go after dd) are: [yy]yy-mm-dd, mm-dd, dd, [yy]yy, mm-dd-[yy]yy, [yy]yy-mm, mm-[yy]yy With English month names (mm <= mmm in above), the additional forms are: dd-mmm-[yy]yy, dd-mmm, mmm (very flexible ordering!) Any missing date parameters (yy, mm, dd) are copied from today, and if a time parameter (hh,mm,ss) is missing, it assumes to be zero. (e.g. If this year is 1996, +/-T95 means after/before a year ago.) Year yyyy should be in the range of 1970-2106. However, for small yy, if yy >= 70, yy means the year of 1900+yy; if yy < 70, yy means the year of 2000+yy. %l %u %x Convert all arguments and macros to lower/upper/unix-style path Use macro prefix modifiers to selectively modify macro expansions. targets Target file or dir names (wildcards can be used in target string.) (Note: Any target not found on disk is excluded by default. See -t.) @<file> can be used together to get targets from <file> in which no line can have more than one name. (i.e. one name per line.) @file Read "file" for target names or exclude names (if given after -x). -@ * Next argument is a target name (to escape '-','@','%' switches) (e.g. -@ @abc -@ -foo where "@abc", "-foo" are target names) -e * Set env vars before running; Use double quotes to include a space. Env settings are passed to executables, but not to batch commands. -x[@] * Exclude names from target dirs or files. (e.g. -x *.zip d:*\abc\*) -x accepts multiple arguments including @file form as in targets. Use -x@ to escape switch symbol for the next argument: -x@ @foo @bar where "@foo" itself and the names from file "bar" will be excluded. : Command (and its arguments) to be run goes after this separator @ Direct execute without spawning a command shell. '@' makes faster execution, but does not work for .cmd/.bat or I/O redirections. Macro Codes for command + arguments: %% % itself %d Drive (e.g. "H:") %p Subdir path (e.g. "\src\C\utils\") %P Subdir path without ending '\' (e.g. "\src\C\utils") %n File/dir name without extension (e.g. "runfor") %e File/dir extension (e.g. ".doc") %f File/dir name with extension (e.g. "runfor.doc") %F Full path name of a file/dir (e.g. "H:\src\C\utils\runfor.doc") %r Relative dir from working dir (e.g. "utils\") %R Relative dir without ending '\' (e.g. "utils") %Tm %Ta %Tc File date & time of last modification (= %T), access, creation Time formats by prefix modifiers for %T = 1998-Jan-09 Fri 06:58:22, %mT = 1998-Jan-09, %xT = 1998-Jan-09 06:58:22 %B File size in bytes (%m prefix converts to K (=1024) or M if too big) %E First EA name (that matches if a name pattern was given in +E) (OS/2) %E* All EA names (space delimited) (OS/2) %L Value of .LONGNAME EA, converted to a valid HPFS path name (OS/2) %w# (#+1)th wildcard expansion; # = 0-9, %w = %w0 (%w0="for." for run*doc) %(ENV_NAME) Env variable; name is case-sensitive; usually in uppercase. Macro codes embedded in env values are recursively expanded. Recursive expansions can happen only for %(ENV_NAME) macros. (limited up to maximum 10 recursions, e.g. AB=%(AB)X is 10 X's) %(ENV_NAME)! Env value without expanding embedded macros. %#[#...] Target counter; %## will be replaced by 2+ digits: 01, 02, ... %ddd[ ] Position at column 'ddd' or add 'ddd' spaces if space followed ('%20X' puts X at column 20 while '%20 X' adds 20 spaces before X) Macro prefix modifiers: (override global %l, %u, %x options) (Syntax: %[modifiers][%]macro_code, e.g. %uxF or %u%x%F) %l Convert to lowercases (e.g. %l(PATH)) %m Convert to mixedcases (e.g. %mf = "Runfor.doc") %u Convert to uppercases (e.g. %uf = "RUNFOR.DOC") %x Unix-style path ('/') (e.g. %lxP = %xlP = "/src/c/utils") Note: These modifiers may have different meaning for %T* or %B macro codes. Wildcards in POSIX Pattern Matching: ? matches any single character. * matches zero or more occurances of anything. [abc] matches any character of 'a', 'b', or 'c'. [!abc] matches any character except 'a', 'b', and 'c'. [a-z] matches any character from 'a' to 'z'. Description: It executes a command using a command shell given by COMSPEC or SHELL env, or directly executes the command if '@' is in front of the command. If a target name was given with wildcards, it executes a command (that may not accept wildcards) for every matching target file or dir, and its arguments can have macro codes of substitution for drive, dir, name, extension, etc. taken from the matching target file/dir. It can recursively run for subdirs. Environmental Variables: RUNFOROPT Set this env var to change the default behavior of this program in either OS/2 config.sys (DOS autoexec.bat) or a batch file. If the last option in "RUNFOROPT" setting is either -e or -x, then "RUNFOROPT" setting must end with a '-'. For example, set RUNFOROPT=-q -H -S -x *.Z - (note '-' at end) (A shorter setting would be "set RUNFOROPT=-x *.Z -qHS") xxxOPT where "xxx" is the executable name before '.' in uppercases. For example, if you copied this program to "spawn.exe", spawn first searches SPAWNOPT env for its default settings, and then RUNFOROPT is searched only if SPAWNOPT was not found. PAGER Optionally set this env to use a pager (like less or list) for this long help screen. If PAGER is not found, stdout is used. Using Double Quotes: (I/O redirections and blank spaces in names) For I/O redirections, '@' (direct execution) should NOT be used in front of an executable command so as to invoke a command shell that can redirect I/O. To pass redirection symbols (like '>') to the child process (command shell), enclose them (or the whole command string) with matching double quotes. Double quotes are stripped off before passing to child process. To pass a double quote explicitly, use a backslash('\') before double quote. If target names have blank spaces, enclose them with explicit double quotes. Examples: - To take `diff' between all same named files of *.c and *.doc in e: and current dir: runfor *.c *.doc : @diff e:%f %f - To create a batch file "batch.cmd" for later execution: runfor -q -o batch.cmd *.c *.doc : @diff e:%f %f - Find all files >= 1MB from subdirs, which were last modified on or after 97-Mar-01, and save those file names (relative path names) to a file: runfor -o files.lst * +B 1mb +Tmar-01-97 -rq : @%r%f - To list files (date/time, size, name) under subdirs to standard output: runfor -qro- * : @%Tm %mB %r%f - To run a command after converting its arguments to unix-style path: runfor -u : prog args (TeX is a good example.) - Wildcard macro expansion: To rename "abc*-??.dat" files to "xyz??-*.dat" with confirmation: runfor -c abc*-??.plt : ren %f xyz%w1%w2-%w0.dat - POSIX pattern matching: runfor [A-Ka-k]* -x *.z -piqq : echo %f - For files with some attributes: runfor * +HS -A : attrib \"%f\" (Double quotes protect spaces in expanded names for "attrib" command.) - Some examples of arguments for +/-T: (+ or - before T is not shown here) T; T- T: T0 T-;: T0;0 T+ == 00:00:00 of today. T8-12 TAug-12 T12-August == Aug-12 00:00:00 of this year. T95-8-12 T8-12-95 T12-Aug-95 == 1995-Aug-12 00:00:00. T2001-8-12 T01-12-Aug T101-12-Aug == 2001-Aug-12 00:00:00. T8- T-8- TAug == 00:00:00 of today in August of this year. T12 T12; T-12 T--12 == 00:00:00 of the 12th day of this month. T15: T;15 T15:00 == 15:00:00 of today. T95 T1995 T95- T-95 == today 00:00:00 of 1995. T+;5 == 5 hours ago, T+60 == 00:00:00 of 60 days ago T+60; == the same time (as now) of 60 days ago T+2-15 == 00:00:00 of 2 months and 15 days ago T+3-- == 00:00:00 (of the same month and day) of 3 years ago "-TAug-12-96 +Ta97-1-1" selects files modified on or before 1996-Aug-12 00:00:00 but accessed on or after 1997-Jan-01 00:00:00 - Selecting files/dirs of attributes is based on `AND' operator. That is, "+HS -RA" means `Hidden=1 AND System=1 AND ReadOnly=0 AND Archive=0'. "-HS" (= -H -S) means files/dirs of not hidden nor system attributes. - Target counter %# (Try these in a dir having more than 10 files): runfor -qq * : echo %#: %f runfor -qq * : echo %##: %f runfor -qq * : echo %###: %f - Env settings: (Usually env names are in uppercase.) runfor -q -e abc=Hello. ABC="There is." : echo %(ABC) %(abc) runfor -q -e ABC="prog.exe can see this env setting." : prog.exe args - Environment variable may contain macro codes to be expanded: runfor -q * -e ABC="File name is %f." : echo %(ABC) (To avoid macro expansion for envs, add '!' like %(ABC)!.) - Reading target or exclude list from a file: (@<file>) runfor -tq @file1 -x @file2 : cmd ... (file1 has target names, and file2 has names to be excluded.) (-t is given so that targets in file1 are not searched on disk.) If '@' is part of file/dir name, use -@ or -x@. (-@ @file1 -x@ @file2) - To run "prog" for every file that matches with "blank in file name*" and save the screen outputs (redirection) to a log file "result.log": runfor "blank in file name*" : "prog \"%f\" >> result.log" where \"%f\" is used because the expanded file name(s) have blank spaces (thus explicit double quotes should be used). - Recursive run into subdirs and changing working dirs: The following examples will show the difference between -w and -ww (-w -w). runfor -rqqdww * : cd -- target dirs runfor -rqqdw * : cd -- parent dirs of targets runfor -rqqdw * : (cd %f & cd) Return Codes: (for single input) 0 - Successful Completion 1 - Invalid Command Switch or Argument 2 - Unable to OPEN 3 - Unable to READ 4 - Unable to WRITE 5 - Invalid Data/Format 6 - Invalid Name 7 - Error During Execution 8 - Help screen due to an error -- Wonkoo Kim (wkim+@pitt.edu)