;
                                 RENAME.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
RENAME.CIM     4k (31)   7FF4  3.6        Gene Pizzetta 11/90      Z3COM10
RENAME.COM     4k (31)   B38E  3.6        Gene Pizzetta 11/90      Z3COM10

  1- Syntax/Options  2- Usage  3- Notes  4- Examples of Use                   

   RENAME, originally written by Richard Conn,  renames files from the command
line or interactively, using ambiguous  filenames  and  CP/M-style or  MS-DOS-
style syntax.   Options allow prompting before each file is renamed,  renaming
of system files, and erasure of existing files without prompting.

   Vs 3.0 (5/84) by R. Conn.
:1
 Syntax     

  Old style (newname=oldname):
     RENAME {dir:}afn.aft=afn.aft{,...} {{/}options}

  New style (oldname newname):
     RENAME {dir:}afn.aft afn.aft{,...} {{/}options}

  Interactive control mode (oldname):
     RENAME {dir:}afn.aft{,...} {{/}options}

  Mixed form:
     RENAME {dir:}afn2=afn1,{dir:}afn3 afn4{,...} {{/}options}

   The first  form  shows  elements  of  the  older  CP/M  style (dir:newname=
oldname).    The  second  form  shows  elements  of  the  newer  MS-DOS  style
(dir:oldname newname).  The third form adds the single-filespec (dir:oldname),
which  automatically invokes  Control  mode  allowing the user to rename files
individually.    The  fourth  form  shows  that  specification  types  can  be
intermixed within a command line.  If no DIR or DU specification is given, the
current drive/user is assumed.   Multiple file list elements must be separated
by commas without intervening spaces.
 Options - 1/2 

        A leading slash is optional.

   E    Erase existing  files  without prompting.   If RENAME  finds  that the
        renamed file will have the same name as  an  existing file, it prompts
        "Exists, Erase?".   A response of  "Y" will cause the existing file to
        be erased.   Entering  "Q"  or  ^C  will exit the program.   Any other
        response will skip the file.   Using this option will cause such files
        files to be erased without prompting.

   I    Inspect mode.   Each matching filename  is  displayed  and the user is 
        prompted.   A  response of  "Y"  will cause the  file  to  be renamed.  
        Entering "Q" or  ^C  will exit the program.   Any  other response will 
        skip the file and then prompt for the next matching filename.

   Q    Toggle current default quiet mode.  RENAME defaults to the ZCPR3 quiet
        flag, if it is on.  Otherwise, RENAME defaults to a configuration byte
        that can be  changed  using  ZCNFG.   As  distributed,  the default is
        verbose mode.  Whatever the configured default, it is reversed by this
        option.
 Options - 2/2 

   R    Erase even an  existing  read-only  file  with  the  same name without 
        prompting.  If RENAME finds an existing file with the same name as the
        new filename, it prompts "R/O, Erase?",  even if the  "Exists, erase?" 
        has already been answered "Y",  and even if the E option has been used 
        on the command line.   A response of "Y" will cause the read-only file 
        to be erased.   Entering  "Q" or ^C will exit the program.   Any other 
        response will skip the file.   Using this option will cause such files 
        to be erased without prompting.   This option  has priority over the E 
        option, so the E option is unnecessary if the R option is used.

   S    Toggle inclusion  of system  files.   Whether RENAME recognizes system 
        files by default is  determined  by  a configuration  byte that can be
        changed using ZCNFG.  As distributed, system files are ignored, unless
        the S option is given on the command line.   Whatever  the  configured
        default, it is reversed by this option.

:2
 Usage - 1/2 

   If only one,  possibly ambiguous,  filename is  given,  RENAME  will  enter
Control mode.   Each matching filename will be  displayed individually and the
user will be asked to specify the  new  name  for that file.   Pressing only a
carriage return will skip renaming of the currently displayed file.   Entering
^C will abort the program.

   If the ZCPR3 quiet flag is  set,  all  screen output is suppressed,  except
error messages and required prompts.   For instance, if the E or R options are
not given and  RENAME  finds an  existing file with the same name, the user is
prompted for  permission  to  erase  the  file  even if the  quiet flag is on.
Inspect and Control modes prompt normally at all times.

   ZEX input is turned off while RENAME is running.

   On exit the program error flag  is set to 10  (source file not found) if no 
files are renamed, unless the program is aborted at  a prompt  with "Q" or ^C.  
In addition,  the number of files renamed is entered into ZCPR3 register 0 (up
to a maximum of 255).   An invalid option  causes the program error flag to be
set to 19, and an invalid directory specification causes the flag to be set to
2.  The latter two errors invoke the error handler.
 Usage - 2/2 

   FILE ATTRIBUTES:   The speed of RENAME  has  been  significantly  increased
under ZSDOS and Z3PLUS by ignoring file attributes on read-write files.   Both
ZSDOS and  CP/M-Plus preserve file  attributes automatically,  with the excep-
tions noted below.

   If the file is read-only,  or if  RENAME is  running under another DOS, the
attributes of the old filename will be transferred to the new filename, except
for the PUBLIC attribute (F2),  which could cause serious  problems if it were
maintained.   In addition, under CP/M-Plus the WHEEL (F8) attribute is used to
indicate that a file was loaded from user 0  as  a public file, so it is auto-
matically reset by the DOS.

   READ/ONLY CAUTION:   RENAME renames  read/only files  without warning.  The
read-only attribute is retained, however.

   CONFIGURATION:   RENAME's  defaults  can  be  changed  using  ZCNFG and the
accompanying RENAMEnn.CFG file.   The  name  of  the  CFG  file  should not be
changed so that ZCNFG can find it  automatically even if RENAME is  renamed to
REN or something else.   The configuration  options  are explained  on ZCNFG's
help screen.
:3
 RENAME Notes - 1/5 

   a. Besides  allowing ambiguous  file names  and  supporting  inspection and
      control modes,  RENAME accepts a list of files, renames Read/Only files, 
      and sets the  attributes (R/O, SYS) of the new file names to be the same 
      as those on the old file names.

   b. Vs 3.6 updates (11/12/90, Gene Pizzetta, Howard Goldstein):
      - RENAME's biggest fault  was  that  it  erased existing read-only files
        without notice.  Now it prompts before erasing R/O files.  
      - An R option has been added to erase R/O files without prompting.  
      - A Q option has also been added to toggle the default quiet mode, which
        is controlled by the ZCPR3 quiet flag or new quiet configuration byte.
        (In fact, all command line options, except I, can now be configured as
        the default mode with ZCNFG.)  
      - Since ZSDOS preserves file  attributes  automatically,  RENAME pays no
        attention to the attributes unless the file is read-only or the DOS is
        ZRDOS or DRI's BDOS.   This results in  a significant  speed-up  under
        ZSDOS (and under Z3PLUS,  which  also  preserves  attributes).   In no
        case, however, is the PUBLIC attribute (F2) preserved because it could
        be dangerous to do so.  
 RENAME Notes - 2/5 

      - RENAME now displays the DU specification with each filename so you can 
        be confident which directory it is working in.  
      - A few minor bugs have been swatted and the code has been streamlined.
   
   c. Vs 3.5 updates (07/01/90, Gene Pizzetta):
      - Changed filename  display  to  "oldfile  to  newfile"  instead  of the
        strange "newfile from oldfile".  
      - Added configuration  byte  after  ASCII  string  'SYSFILES>'  to chose
        whether to include system files by default  (non-zero) or exclude them
        by default (0).  
      - S option now toggles the default meaning (it's current action is shown
        by the usage screen.  
      - Now filters high bit of  filenames  for terminals that display special
        characters that way.  
      - RENAME no longer  signs  on  with its load address and version number;
        these are displayed only on the usage screen.  
      - Restored Q (quit) as a valid response to an rename or erase query, but
        ^C still works.  
 RENAME Notes - 3/5 

      - Display has been made even more  compact  than last  version.  Many of
        these changes are to make the RENAME interface very similar to the RCP
        version.  
      - Sets program error flag to 10 if a matching filename is not found.  If
        an invalid option is  given,  the  program error flag is set to 19 and
        the error handler is invoked.  
      - ZEX input is suspended during execution of RENAME.
      - The number of files renamed (up to 255) is placed in ZCPR3 register 0.
      - Now obeys ZCPR3 quiet flag, except when in inspect or control mode, or
        when a prompt is necessary.
      - Removed Wheel byte protection for E and S options.

   d. Vs 3.4 updates (03/31/90, Gene Pizzetta):
      - Modified for more compact display, usually a single line for each file
        renamed.  ^C aborts at any prompt.
 
   e. Vs 3.3a updates (12/30/87, Bruce Morgen):
      - Strip high bit from EFCB program name characters.  "E" and "S" options
        require Wheel byte set; help message reflects this.
 RENAME Notes - 4/5 

   f. Vs 3.3 updates (12/19/87, Bruce Morgen):
      - Implements the PPIP-style dual syntax.  Control Mode is mandatory  and
        automatic for single-filespec elements.   If a single-filespec element 
        is the last (or only) one in  a RENAME command line,  the second file-
        spec in the last (or only) command  is tested if the MS-DOS  syntax is
        detected.  If that second filespec starts with  a '/' or includes only 
        valid option letters (and no more characters than the number  of valid 
        option letters), it is assumed to be an option specifier rather than a
        rename-to filespec.  

   g. Vs 3.2 updates (08/25/87, Jay Sage);
      - Changed to allow  a leading slash  before  an  option  to make program
        consistent with a  number of  other Z  programs (this  was supposed to
        happen, but there was a bug in the code).  Put data into a DSEG.  Made
        header indicate load address.
 RENAME Notes - 5/5 

   h. Vs 3.1 updates (04/12/87, Jay Sage):
      - Took idea of Rick Charnes and implemented it  as an option so that one
        does not have to have two versions of the program.  The option is 'E'.
        Also updated code to ZCPR33 type-3 environment to allow linking RENAME
        for execution in high memory if desired.

   i. Vs 3.0a updates (04/09/87, Rick Charnes):
      - Modified slightly so  that  if  you try to rename FILE1  to FILE2  and
        FILE2 already exists, the program will NOT ask you if you are sure you
        want to delete FILE2.  
:4
 Examples of Use 

   a. RENAME *.txt

      - rename all *.TXT files to names input by user

   b. RENAME asm:*.mac=*.asm

      - rename all *.ASM files to *.MAC

   c. RENAME *.obj=*.com SI 

      - rename all COM files to OBJ, including SYStem files, allowing the user
        to approve each change before it is made

   d. RENAME *.z80 *.mac,*.asm,*.doc=*.txt e
   
      - rename all Z80 files to MAC,  enter control mode  prompting  for a new
        name for each  ASM  file,  and  then  rename  all  TXT  files  to DOC.
        Existing files with the same name as a renamed file are erased without
        prompting.
