home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / vrac / fortn605.zip / FORTUNE.DOC < prev    next >
Text File  |  1996-05-28  |  22KB  |  470 lines
  1. FORTUNE.DOC                          1                         Revised: 05/28/96
  2.  
  3. The FORTUNE.EXE program adds some tuning features to the DOS  FOR  command  (FOR
  4. tune, fortune, what the heck).  These features can in some  way  be  applied  to
  5. commands accepting regular DOS wildcards.  Features include:
  6.  
  7.  * Results of command are written to a batch file which you can review before
  8.    you run it.  Lets you subsequently edit it if desired and lets you see
  9.    exactly what commands will happen when you run it.
  10.  * Ability to embed redirection indicators in a command (see next example).
  11.  * Ability to separate the file name and file extension.  For example:
  12.         FORTUNE IN (*.TXT) DO SORT %[ %A %] %1*.SOR
  13.  * Ability to identify individual characters in the the file name and extension.
  14.    For example:
  15.         FORTUNE IN (*.TXT) DO RENAME %A (%1%2%3%4%5%6).*
  16.  * Ability to specify a character other than "%" for the delimiter so you can
  17.    avoid worrying about different syntax in batch command vs command line.
  18.  * Ability to have batch file pause after each command so results can be
  19.    reviewed.
  20.  * Ability to specify incrementation in the file names.  For example:
  21.         FORTUNE IN (*.TXT) /+2 DO COPY %A %1*.%0001
  22.  * Ability to specify multiple statements on one command line.
  23.  * Ability to process children subdirectories (/S option) at same time.  For
  24.    example:
  25.         FORTUNE IN (\*.TXT) /S DO COPY %A D:\BACKUPS
  26.         FORTUNE *.BAT /S DEL %A
  27.  * Ability to exclude up to 10 file specifications from consideration.
  28.  * Ability to do those tough PKZIP commands that you always wanted to do.  Like
  29.    compress all *.FLI files in your subdirectory to a ZIP of the same name as
  30.    the original file:
  31.         FORTUNE *.FLI /DO PKZIP -M %R %e
  32.    Or move all WAV files into ZIP files with the same name as the WAV file
  33.    (separate ZIP for each WAV file):
  34.         FORTUNE *.WAV PKZIP -M %R %R.%E
  35.  * In addition, you can use the command to create a file which contains a
  36.    series of commands including a header and footer section which can be used
  37.    for some batch functions.
  38.  
  39.  
  40. The DOS FOR command:
  41.  
  42. Quite a few DOS users are unaware of the DOS FOR command.  It allows you to do a
  43. single command over a series of files and provides an easy way to use  wildcards
  44. with commands that don't accept them.  For example, if you want to type a number
  45. of files to your screen, you can say something like:
  46.  
  47.         FOR %A IN (*.TXT) DO TYPE %A
  48.  
  49. DOS looks at your IN specification and figures out what file names  are  covered
  50. by that request.  The request can include path information if  desired  and  can
  51. have multiple specification (e.g.  "...IN (*.TXT \BAT\*.DOC)...").
  52.  
  53. FOR then substitutes the file name itself in for whatever variable  you  specify
  54. in the first parameter after "FOR" ("%A"  here).   This  variable  is  a  single
  55. character (A to Z) preceded by a single percent sign (%).  (If FOR is used in  a
  56. batch command, you have to use two percent signs (%%) instead.)
  57.  
  58.  
  59. FORTUNE.DOC                          2                         Revised: 05/28/96
  60.  
  61. FOR then looks at the command following  the  keyword  "DO"  and  executes  that
  62. command.  If it finds the variable name in the command, it substitutes the  name
  63. of the file for that variable.
  64.  
  65. So, in the above example, if you had three *.TXT files--ABLE.TXT, BAKER.TXT, and
  66. CHARLIE.TXT--and you ran the command, it would actually do  three  commands  for
  67. you:
  68.  
  69.         TYPE ABLE.TXT
  70.         TYPE BAKER.TXT
  71.         TYPE CHARLIE.TXT
  72.  
  73. All in all, FOR is a *very* useful command.  There are also some DOS tricks that
  74. you can use to make the command even more useful but, frankly, I  always  forget
  75. the tricks.  (If someone would like to e-mail them to me,  I'll  throw  them  in
  76. here.) In any case, even past the tricks, the FORTUNE command provides even more
  77. features.
  78.  
  79.  
  80. FORTUNE wildcards and special characters:
  81.  
  82. The FORTUNE.EXE program extends the functionality of  the  DOS  FOR  command  by
  83. providing ways of splitting up the parts of the file name and  manipulating  the
  84. parts.  For example, someone in my office had a mess of files  that  had  to  be
  85. renamed as an open parenthesis, followed by the first six characters of the file
  86. name, followed by a close parenthesis.  Not too terrible to handle with my  text
  87. editor but it hadn't occurred to her.  Using FORTUNE, however, it's pretty easy:
  88.  
  89.         FORTUNE IN (*.TXT) DO RENAME %A (%1%2%3%4%5%6).*
  90.  
  91. And then you run the newly-created batch file (DOIT.BAT).
  92.  
  93. Similarly, someone wanted me to rename a mess of files so  they  had  sequential
  94. names.  I  had  to  write  a  program  to  handle  it.   Definitely  beyond  his
  95. capabilities.  Again, using FORTUNE it's pretty easy:
  96.  
  97.         FORTUNE IN *.TXT DO RENAME %A %1*.%0001
  98.  
  99. And again you run the DOIT.BAT file.
  100.  
  101. Within the command (DO command), FORTUNE allows  you  to  include  a  number  of
  102. indicators.  The character which indicates that  it's  a  special  character  is
  103. typically "%" but you can change this with the /VAR=char option in FORTUNE.  All
  104. of the examples here use the default /VAR=% setting.
  105.  
  106. NOTE TO 4DOS USERS:  4DOS automatically translates %x characters even if used on
  107. the command line.  As such, 4DOS users *have* to use a different /VAR=x  setting
  108. to use FORTUNE.  FORTUNE detects that you are running 4DOS and typically changes
  109. the default /VAR=% to /VAR=@.
  110.  
  111.  
  112. FORTUNE.DOC                          3                         Revised: 05/28/96
  113.  
  114. In many cases, the indicators are case sensitive; there's a  difference  between
  115. %p and %P (presuming the default /VAR=% delimiter).   Typically,  the  lowercase
  116. variants are cumulative.  %P gives you just the path whereas %p  throws  in  the
  117. drive information too.
  118.  
  119.      %a         translates into the entire file name (begins with drive,
  120.                 colon, \, path, \, file root, ., file extension).
  121.                 Use %R.%E if you want the filename without the drive/path info
  122.      %D         translates into the drive (not followed by :)
  123.      %d         translates into the drive (followed by :)
  124.      %P         translates into path (not preceded or followed by \)
  125.      %p         translates into path (begins with drive, colon, \, path, \)
  126.      %R         translates into file name root
  127.      %r         translates into file name root (begins with drive, colon, \,
  128.                 path, \)
  129.      %E         translates into file name extension
  130.      %e         translates into file name extension (begins with drive, colon,
  131.                 \, path, \, file name root, .)--same as %a
  132.      %1 to %8   characters 1 to 8 in the file name root
  133.      %X to %Z   characters 1 to 3 in file name extension (case insignificant;
  134.                 %X is the same as %x)
  135.       %*        replaces the character with the standard "*" wildcard
  136.       %?        replaces the character with the standard "?" wildcard
  137.  
  138. Unless preceded by the /VAR=x delimiter, the  standard  DOS  wildcards--"*"  and
  139. "?"--are supported within the file name.  "...DO RENAME %A Q*.Y*" will  actually
  140. generate commands with the letters filled in (if the file  name  is  APPLES.ARE,
  141. the command will be RENAME QPPLES.YRE).
  142.  
  143. If you want to actually write out the commands and  leave  in  the  "*"  or  "?"
  144. characters, precede the characters with "%" or whatever.  For example,  "FORTUNE
  145. (*.001) DO COPY %R.0%* %R.TOP" will generate something  like  "COPY  TN960402.0*
  146. TN960402.TOP" whereas "FORTUNE (*.001) DO COPY %R.0* %R.TOP" will generate "COPY
  147. TN960402.001 TN960402.TOP".
  148.  
  149. All other characters in the command string are passed as given.
  150.  
  151.  
  152. FORTUNE.DOC                          4                         Revised: 05/28/96
  153.  
  154. Using  the  above  characters,  if  you  have  two  files  C:\AUTOEXEC.BAT   and
  155. D:\WAYNE\MYSTUFF.TXT, the various codes above translate as:
  156.  
  157.                 C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  158.      %A         C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  159.      %D         C                       D
  160.      %d         C:                      D:
  161.      %P         (null)                  WAYNE
  162.      %p         \                       D:\WAYNE\
  163.      %R         AUTOEXEC                MYSTUFF
  164.      %r         C:\AUTOEXEC             D:\WAYNE\MYSTUFF
  165.      %E         BAT                     TXT
  166.      %e         C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  167.      %1         A                       M
  168.      %2         U                       Y
  169.      %3         T                       S
  170.      %4         O                       T
  171.      %5         E                       U
  172.      %6         X                       F
  173.      %7         E                       F
  174.      %8         C                       (null)
  175.      %X         B                       T
  176.      %Y         A                       X
  177.      %Z         T                       T
  178.  
  179.  
  180.  
  181. Special translations:
  182.  
  183.      %[         translates into <
  184.      %]         translates into >
  185.      %0nnnn     incrementer field (where "nnnn" is any number of digits;
  186.                 translates into a numeric field which has the same number of
  187.                 digits; the first number will be the value of "nnnn" and
  188.                 subsequent files will be incremented by the value specified in
  189.                 the /+n or /-n parameter (defaults to /+1)
  190.  
  191.  
  192.  
  193. FORTUNE.DOC                          5                         Revised: 05/28/96
  194.  
  195. Using a command file for special cases:
  196.  
  197. In addition, FORTUNE supports some options that might be used outside of a batch
  198. file.  (There are also several uses for this within a batch command but I  won't
  199. go into them here.  Think about it on your own.) For example, let's say you have
  200. an FTP program and you want to log onto the site and upload  all  of  the  *.TXT
  201. files in your subdirectory.  Normally, you'd do this by  typing  something  like
  202. this in response to the expected prompts:
  203.  
  204.         ftp
  205.         ftp.cu.nih.gov           (the name of the ftp site you're logging onto)
  206.         anonymous                (your userid--I know, anonymous logins aren't
  207.                                   trusted for uploads; use your own userid)
  208.         bguthrie@nmaa.org        (your password)
  209.         cd pub
  210.         cd incoming
  211.  
  212. Now, for each of the files you have, you'd have to enter a  command  like  "send
  213. filename", typically followed by a blank line when prompted  for  the  recipient
  214. file name.
  215.  
  216. Finally, after you're all done, you'd typically issue a "quit" command.
  217.  
  218. Thinking about it, you can use redirection in DOS to say "FTP  <  filename",  as
  219. long as the lines in the text file "filename" contain all of the  statements  in
  220. sequence that you need to issue.
  221.  
  222. FORTUNE lets you specify a  command  file  which  contains  a  "header"  section
  223. (commands to be sent beforehand), a "main" section (commands to be sent for each
  224. filename), and a "footer" section (commands to be send afterward).  Each section
  225. is optional and may consist of up to 20 commands.  In our example, your  command
  226. file (we'll call it "FORTUNE.FTP" in this case) might look like this:
  227.  
  228.         /header
  229.         ftp
  230.         ftp.cu.nih.gov
  231.         anonymous
  232.         bguthrie@nmaa.org
  233.         cd pub
  234.         cd incoming
  235.         /main
  236.         send %A
  237.                                              (blank line)
  238.         /footer
  239.         quit
  240.  
  241. The commands within the "main" section  are  repeated  for  each  file  and  can
  242. contain all of the standard FORTUNE features for the command section.
  243.  
  244.  
  245. FORTUNE.DOC                          6                         Revised: 05/28/96
  246.  
  247. The sections can appear in any order.
  248.  
  249. To bring in the command file, specify "/DO @filename" instead of "/DO  command".
  250. So, your command line might be:
  251.  
  252.         FORTUNE IN (*.TXT) DO @FORTUNE.FTP
  253.  
  254. This will create a DOIT.BAT file which, in fact, does not contain batch  command
  255. statements at all.  If this bothers you, specify a different output file name if
  256. you want.  Then, to  process  this  file  in  your  FTP  command,  use  standard
  257. redirection:
  258.  
  259.         FTP < DOIT.BAT
  260.  
  261. Note that using the command file feature  disables  processing  of  the  FORTUNE
  262. parameters which are specific to batch  files.   These  ignore  parameters  are:
  263. /ECHO, /-ECHO, /ABEND, /-ABEND, /PAUSE, and /-PAUSE.
  264.  
  265. In addition, you can specify a file that contains the filenames  to  process  by
  266. using "/IN @filename".  This feature can be very handy when /-CHECK is specified
  267. and the file itself contains file names on a remote host.  For example, this  is
  268. useful if you're trying to run something like FORTUNE on an ftp  host  over  the
  269. Internet to issue a series of "get" commands on that host.
  270.  
  271. One disadvantage of the /-CHECK parameter is that it will not parse out the file
  272. name at all so only %A-like requests will do any good.
  273.  
  274.  
  275. Specifying parameters:
  276.  
  277. Parameters for this program can be set in the following ways.  The last  setting
  278. encountered always wins:
  279.   - Read from an *.INI file (see BRUCEINI.DOC file),
  280.   - Through the use of an environmental variable (SET FORTUNE=whatever), or
  281.   - From the command line (see "Syntax" below)
  282.  
  283.  
  284.  
  285. FORTUNE.DOC                          7                         Revised: 05/28/96
  286.  
  287. Syntax:
  288.  
  289.     FORTUNE { IN (set) | IN filespec | /IN (set) | /IN filespec | filespec }
  290.       [ /AS filename ] [ /OVERWRITE | /APPEND | /-OVERWRITE | /OVERASK ]
  291.       [ /VAR=char ] [ /DELIM=chars ] [ /+n | /-n ] [ /S ] [ /Xfilespec ] ...
  292.       [ /-ECHO ] [ /-ABEND ] [ /PAUSE ] [ /-CHECK ] [ /WIPE ]
  293.       [ /Iinitfile | /-I ] [ /? ] { DO command | /DO command | command }
  294.  
  295. where:
  296.  
  297. "IN (set)" lets you specify the file  names  to  be  processed.   Multiple  file
  298. specifications should be separated by a space or a semicolon.  The "IN"  can  be
  299. preceded by a "/" if desired.  If only one file specification is  provided,  you
  300. can skip the parentheses.  You can specify "%PATH%" (depending on the  value  of
  301. the /DELIM=chars option) if you want.  A  file  specification  is  required  for
  302. FORTUNE.
  303.  
  304. You can specify an input file that contains the file list to process.   This  is
  305. done using "@filename" instead of "set" or "filespec".
  306.  
  307. It's possible to leave off  the  "IN"  (or  its  derivatives)  as  well  as  the
  308. parentheses if your file specification(s) include a "/", "*", or "?"  character.
  309. For example:
  310.  
  311.         FORTUNE *.BAS *.DOC DO TYPE %A
  312.  
  313. "/AS filename" tells the command the name of the batch file to create  with  the
  314. resulting commands.  By default, this file will be called DOIT.BAT and  it  will
  315. be created in your default subdirectory.
  316.  
  317. "/OVERWRITE" says to write over any output file that's already there.
  318.  
  319. "/APPEND" says to add the new records at the  end  of  any  output  file  that's
  320. already there.  Note that FORTUNE uses several DOS labels every time it executes
  321. and concatenation is typically not recommended.
  322.  
  323. "/-OVERWRITE" says to abort if the output file exists already.
  324.  
  325. "/OVERASK" says to prompt if  the  output  file  exists  already;  this  is  the
  326. default.
  327.  
  328. "/VAR=char" indicates the character to use as the special  character  indicator.
  329. This typically defaults to "/VAR=%" under DOS  and  "/VAR=@"  under  4DOS.   The
  330. hassle with this is that if you invoke FORTUNE from a batch file, you'll have to
  331. remember to use %% instead of %.  If you pick another character  (like  /VAR=^),
  332. that's not necessary.
  333.  
  334.  
  335. FORTUNE.DOC                          8                         Revised: 05/28/96
  336.  
  337. "/DELIM=chars" allows you to  indicate  delimiters  to  use  between  statements
  338. within the DO command.  Defaults to "/DELIM=$$".  This  allows  you  to  process
  339. multiple statements in a single FORTUNE command.  For example:
  340.  
  341.         FORTUNE IN *.BAS DO COPY %A \TEMP $$ TYPE \TEMP\%R.%E
  342.  
  343. Note that the number of characters can be any length (including one  character).
  344. Your only consideration is that the characters do not appear  together  in  your
  345. command otherwise.  The characters are case insignificant ("/DELIM=newline"  and
  346. "/DELIM=NEWLine" are the same thing).
  347.  
  348. "/+n" and "/-n" allow you to specify the increment/decrement value  to  be  used
  349. where %0nnnn indicators are used in the command line.  Defaults to "/+1".
  350.  
  351. "/S" processes the children subdirectories as well.  So you could  do  something
  352. like any of the following:
  353.  
  354.         FORTUNE IN (\*.BAS) /S COPY %A LPT1:
  355.         FORTUNE IN (\OLD*.TXT) /S DO DELETE %A
  356.  
  357. The next example is  a  little  bizarre.   Let's  say  you're  using  anti-virus
  358. protection program that maintains a read-only file in each subdirectory with all
  359. of the virus signatures for the files in that subdirectory.  You decide  you  no
  360. longer want to use that program again but you have a zillion of these files  and
  361. they're all read-only.  The following example would search them all  out,  reset
  362. them to not be read-only, and then delete them.
  363.  
  364.         FORTUNE IN (\VIRCK.SIG) /S DO ATTRIB %A -R $$ DEL %a
  365.  
  366. "/Xfilespec" says to exclude certain filespecs from being considered.   You  can
  367. specify up to 10 exclusion parameters but each must have  their  own  /Xfilespec
  368. statement.  For example, you could process all *.BAS files except  D*.BAS  files
  369. by saying "FORTUNE IN (*.BAS) /XD*.BAS DO TYPE %A".
  370.  
  371. "/ECHO" says to turn ECHO ON in the batch file.   This  will  show  the  command
  372. being executed before it executes.  This is initially the default.
  373.  
  374. "/-ECHO" says to turn ECHO OFF in the batch file.
  375.  
  376. "/ABEND" (abnormal end) says to use standard DOS errorlevel trapping to  see  if
  377. there was an error in running the command.  If any non-0 errorlevel condition is
  378. encountered (e.g.  an error has occurred),  the  batch  file  will  branch  out,
  379. skipping the rest of the statements in the batch file and aborting.   Note  that
  380. not all commands return decent errorlevel codes.  COPY, for example, doesn't set
  381. an errorlevel to indicate that the file could not be  found.   "/ABEND"  is  the
  382. initially the default.
  383.  
  384. "/-ABEND" says to skip errorlevel testing.
  385.  
  386. "/PAUSE" says to add a PAUSE statement after each statement that's executed.  If
  387. you don't like what you see, you can press Ctrl-Break and get out of  the  batch
  388. file.
  389.  
  390. "/-PAUSE" skips the PAUSE statements.  This is typically the default.
  391.  
  392.  
  393. FORTUNE.DOC                          9                         Revised: 05/28/96
  394.  
  395. "/WIPE" says to kill the batch file (e.g. DOIT.BAT) after successful completion.
  396. This produces an annoying error  message  ("Batch  file  missing")  but  may  be
  397. preferable to keeping the batch file around afterward.   Initially  defaults  to
  398. "/-WIPE".
  399.  
  400. "/-WIPE" says to keep the batch file around after completion.  This is initially
  401. the default.
  402.  
  403. "/Iinitfile" says to read an initialization file with the file name  "initfile".
  404. The file specification *must* contain a period.  Initfiles are described in  the
  405. BRUCEINI.DOC file.  Initially defaults to "/IFORTUNE.INI".
  406.  
  407. "/-I" (or "/INULL") says to skip loading the initialization file.
  408.  
  409. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  410.  
  411. "DO command" (or "/DO command" or just "command") specifies the command(s) to be
  412. executed.  The slash before "DO" is optional.  A command is required.   Multiple
  413. commands can be specified if they are separated using the  characters  specified
  414. in the /DELIM=chars parameter.  You can also use a command  file  by  using  /DO
  415. @filename; see the previous discussion on "Using  a  command  file  for  special
  416. cases".
  417.  
  418. In most cases, the use of the "DO" (or "/DO") parameter is actually unnecessary.
  419. The routine typically treats all of the following as identical:
  420.  
  421.         FORTUNE IN (*.BAS *.DOC) /DO TYPE %A
  422.         FORTUNE IN (*.BAS *.DOC) TYPE %A
  423.         FORTUNE *.BAS *.DOC TYPE %A
  424.  
  425. However, using the "DO" (or  "/DO")  parameter  adds  an  extra  left  of  error
  426. checking and its use it encouraged.
  427.  
  428.  
  429. Return codes:
  430.  
  431. FORTUNE returns the following ERRORLEVEL codes:
  432.         0 = no problems, files found and batch file created
  433.         1 = no problems, no files met specifications
  434.       255 = syntax problems, file not found, or /? requested
  435.  
  436.  
  437.  
  438. FORTUNE.DOC                          10                        Revised: 05/28/96
  439.  
  440. Author:
  441.  
  442. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  443. and redistribution provided relevant documentation is kept with the program,  no
  444. changes are made to the program or documentation, and it  is  not  bundled  with
  445. commercial programs or charged for separately.  People who need to bundle it  in
  446. for-sale packages must pay a $50 registration fee to  "Wayne  Software"  at  the
  447. following address.
  448.  
  449. Additional information about this and other Wayne Software programs can be found
  450. in the file BRUCEymm.DOC which should be included  in  the  original  ZIP  file.
  451. ("ymm" is replaced by the last digit of the year and the two digit month of  the
  452. release.  BRUCE512.DOC came out in December 1995.  This same  naming  convention
  453. is used in naming the ZIP file that this program was included in.) Comments  and
  454. suggestions can also be sent to:
  455.  
  456.                 Bruce Guthrie
  457.                 Wayne Software
  458.                 113 Sheffield St.
  459.                 Silver Spring, MD 20910
  460.  
  461.                 fax: (301) 588-8986
  462.                 e-mail: bguthrie@nmaa.org
  463.                 http://hjs.geol.uib.no/guthrie/
  464.  
  465. See BRUCEymm.DOC file for additional contact information.
  466.  
  467. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  468.  
  469. 
  470.