;
                                 RENAME.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
RENAME.CIM     4k (31)   CA81  3.5        Gene Pizzetta 7/90       Z3COM10
RENAME.COM     4k (31)   A256  3.5        Gene Pizzetta 7/90       Z3COM10

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


   RENAME is  a transient program for renaming files.  More powerful than REN,
RENAME allows ambiguous  file names and inspection.  Vs 3.0 (5/84) by R. Conn.
:1
 Syntax     

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

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

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

   The first form shows elements of the CP/M style form (dir:afn1=afn2).   The 
second  form  shows elements of the MS-DOS style form  (dir:afn2  afn1).   The 
third form adds an element of the single-filespec form (dir:afn), which is the 
same  as  the completely pointless 'dir:afn=afn' except that it  automatically 
invokes a Control Mode which allows the user to rename files individually.

   All three forms may be mixed within a command line.  If no DIR or DU speci-
fication is given,  the current  drive/user is  assumed.   Multiple  file list
elements must be separated by commas without intervening spaces.
 Options 

        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 normally 
        asks if the existing file should  be  erased.   Using this option will 
        cause such 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.

   S    Toggle inclusion  of system  files.   Whether RENAME recognizes system 
        files by default is  determined by  a configuration  byte in the first 
        record of the COM file  preceded by the  ASCII string "SYSFILES>".  If 
        the byte is zero, system files are ignored;  if it is non-zero, system 
        files are  erased.   The default condition is reversed by this option.  
        As distributed, the default is to exclude system files.
: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.   If the E option is not given and RENAME 
finds an existing file with the same name,  for instance, 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).   If an invalid option is given,  the program error flag 
is set to 19 and the error handler is invoked.
 Usage - 2/2 

   READ/ONLY CAUTION:   RENAME renames  read/only files  without warning.   In 
addition, if an existing file is  read/only,  it will  also  be erased without 
warning if the E option is  used  or if the "Erase?" prompt is answered with a 
"Y".

   This "feature" should probably be removed.   It  would  be better if RENAME 
acted like ERASE, prompting "Read/Only, Rename?" or "Read/Only, Erase?" before 
doing  anything.   An  "R"  option could  be  added  to  allow  bypassing  the 
questions.  
:3
 RENAME Notes - 1/4 

   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.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 - 2/4 

      - 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.

   c. 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.
 
   d. 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 - 3/4 

   d. 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.  

   e. 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 - 4/4 

   f. 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.

   g. 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 and include SYStem files and Inspect
        and approve each change
