1  RENAME
   Changes all or part of a file specification of an existing disk
   file or disk directory.

   Format

     RENAME  input-filespec[,...] output-filespec
 

2  Parameters
 

input-filespec[,...]

   Specifies the name of one or more files whose specifications
   are to be changed. The asterisk (*) and the percent sign (%)
   wildcard characters are allowed in the directory specification,
   file name, file type, or version number fields of the file
   specification. When wildcard characters are used, all files whose
   specifications satisfy the wildcard fields are renamed. If an
   input file specification is a symbolic link, the symbolic link
   itself is renamed. If the output file specification is a symbolic
   link, the operation fails.
 

output-filespec

   Provides the new file specification to be applied to the input
   file. The RENAME command uses the device, directory, file name,
   and file type of the input file as defaults for fields in the
   output file that are either unspecified, or are indicated by
   the asterisk (*)  and the percent sign (%) wildcard characters.
   Wildcard characters in corresponding fields of the input and
   output file specification result in multiple rename operations.

   The RENAME command supplies output file version numbers in the
   following ways:

   o  If the output file specification contains an explicit version
      number, that version number is used.

   o  If the output file specification contains an asterisk (*)  or
      a percent sign (%)  wildcard character as the version number,
      the version number of the input file is used.

   o  If the input file specification contains an asterisk (*)  or
      a percent sign (%)  wildcard character as the version number,
      the version number of each input file names a corresponding
      output file.

   o  If no file exists with the same file name and type as the
      output file, the new file is assigned a version number of 1.

   o  If a file already exists with the same file name and type
      as the output file, the next higher version number is used
      (unless the /NONEWVERSION qualifier is specified).
 

2  Qualifiers
 

/BACKUP

   Modifies the time value specified with the /BEFORE or the
   /SINCE qualifier. The /BACKUP qualifier selects files according
   to the dates of their most recent backups. This qualifier
   is incompatible with the /CREATED, /EXPIRED, and /MODIFIED
   qualifiers, which also allow you to select files according
   to time attributes. If you specify none of these four time
   qualifiers, the default is the /CREATED qualifier.
 

/BEFORE

      /BEFORE[=time]

   Selects only those files dated prior to the specified time. You
   can specify time as absolute time, as a combination of absolute
   and delta times, or as one of the following keywords: BOOT,
   LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of
   the following qualifiers with the /BEFORE qualifier to indicate
   the time attribute to be used as the basis for selection:
   /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

   For complete information on specifying time values, see the
   OpenVMS User's Manual or the online help topic Date.
 

/BY_OWNER

      /BY_OWNER[=uic]

   Selects only those files whose owner user identification code
   (UIC) matches the specified owner UIC. The default UIC is that of
   the current process.

   Specify the UIC by using standard UIC format as described in the
   VSI OpenVMS Guide to System Security.
 

/CONFIRM

      /CONFIRM
      /NOCONFIRM (default)

   Controls whether a request is issued before each rename operation
   to confirm that the operation should be performed on that file.
   The following responses are valid:

   YES      NO       QUIT
   TRUE     FALSE    Ctrl/Z
   1        0        ALL
            <Return>

   You can use any combination of uppercase and lowercase letters
   for word responses. Word responses can be abbreviated to one or
   more letters (for example, T, TR, or TRU for TRUE), but these
   abbreviations must be unique. Affirmative answers are YES, TRUE,
   and 1. Negative answers include: NO, FALSE, 0, and pressing
   Return. Entering QUIT or pressing Ctrl/Z indicates that you want
   to stop processing the command at that point. When you respond by
   entering ALL, the command continues to process, but no further
   prompts are given. If you type a response other than one of
   those in the list, DCL issues an error message and redisplays
   the prompt.
 

/CREATED

      /CREATED (default)

   Modifies the time value specified with the /BEFORE or the /SINCE
   qualifier. The /CREATED qualifier selects files based on their
   dates of creation. This qualifier is incompatible with the
   /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow
   you to select files according to time attributes. If you specify
   none of these four time qualifiers, the default is the /CREATED
   qualifier.
 

/EXCLUDE

      /EXCLUDE=(filespec[,...])

   Excludes the specified files from the rename operation. You can
   include a directory but not a device in the file specification.
   The asterisk (*)  and the percent sign (%) wildcard characters
   are allowed in the file specification; however, you cannot use
   relative version numbers to exclude a specific version. If you
   specify only one file, you can omit the parentheses.
 

/EXPIRED

   Modifies the time value specified with the /BEFORE or the /SINCE
   qualifier. The /EXPIRED qualifier selects files according to
   their expiration dates. (The expiration date is set with the SET
   FILE/EXPIRATION_DATE command.) This qualifier is incompatible
   with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also
   allow you to select files according to time attributes. If you
   specify none of these four time qualifiers, the default is the
   /CREATED qualifier.
 

/INHERIT_SECURITY

      /INHERIT_SECURITY
      /NOINHERIT_SECURITY (default)

   Controls whether the security profile (UIC, protection code, and
   ACL) of the renamed file is altered. If you specify /INHERIT_
   SECURITY, a new security profile is generated, as if a new file
   had been created with the new file and directory names. See the
   VSI OpenVMS Guide to System Security or online help (Hints topic)
   for a description of how a profile is assigned.
 

/LOG

      /LOG
      /NOLOG (default)

   Displays the file specification of each file as it is renamed.
 

/MODIFIED

   Modifies the time value specified with the /BEFORE or the /SINCE
   qualifier. The /MODIFIED qualifier selects files according to
   the dates on which they were last modified. This qualifier
   is incompatible with the /BACKUP, /CREATED, and /EXPIRED
   qualifiers, which also allow you to select files according
   to time attributes. If you specify none of these four time
   modifiers, the default is the /CREATED qualifier.
 

/NEW_VERSION

      /NEW_VERSION (default)
      /NONEW_VERSION

   Assigns a new version number if an output file specification
   is the same as that of an existing file. The /NONEW_VERSION
   qualifier displays an error message if an output file
   specification is the same as that of an existing file. The
   asterisk (*)  and the percent sign (%) wildcard characters
   appearing in the version field of an input or output file
   overrides these qualifiers.
 

/SINCE

      /SINCE[=time]

   Selects only those files dated on or after the specified time.
   You can specify time as absolute time, as a combination of
   absolute and delta times, or as one of the following keywords:
   BOOT, JOB_LOGIN, LOGIN, TODAY (default), TOMORROW, or YESTERDAY.
   Specify one of the following qualifiers with the /SINCE qualifier
   to indicate the time attribute to be used as the basis for
   selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

   For complete information on specifying time values, see the
   OpenVMS User's Manual or the online help topic Date.
 

/STYLE

      /STYLE=keyword

   Specifies the file name format for display purposes.

   The valid keywords for this qualifier are CONDENSED and EXPANDED.
   Descriptions are as follows:

   Keyword     Explanation

   CONDENSED   Displays the file name representation of what is
   (default)   generated to fit into a 255-length character string.
               This file name may contain a DID or FID abbreviation
               in the file specification.
   EXPANDED    Displays the file name representation of what is
               stored on disk. This file name does not contain any
               DID or FID abbreviations.

   The keywords CONDENSED and EXPANDED are mutually exclusive. This
   qualifier specifies which file name format is displayed in the
   output message, along with the confirmation if requested.

   File errors are displayed with the CONDENSED file specification
   unless the EXPANDED keyword is specified.

   See the OpenVMS User's Manual for more information.
 

/SYMLINK

      /SYMLINK=keyword

   The valid keywords for this qualifier are [NO]WILDCARD and
   [NO]ELLIPSIS. Descriptions are as follows:

   Keyword     Explanation

   WILDCARD    Indicates that symlinks are enabled during wildcard
               searches.
   NOWILDCARD  Indicates that symlinks are disabled during directory
               wildcard searches.
   ELLIPSIS    Equivalent to WILDCARD (included for command
               symmetry).
   NOELLIPSIS  Indicates that symlinks are matched for all wildcard
               fields except for ellipsis.

   If the file named in the RENAME command is a symlink, the command
   operates on the symlink itself.
 

2  Examples

   1.$ RENAME  AVERAGE.OBJ  OLDAVERAGE

     The RENAME command in this example renames the highest existing
     version of the file AVERAGE.OBJ to OLDAVERAGE.OBJ. If no file
     named OLDAVERAGE.OBJ currently exists, the new file is assigned
     a version number 1.

   2.$ RENAME/NONEW_VERSION  SCANLINE.OBJ;2   BACKUP.OBJ

     The RENAME command in this example renames the file
     SCANLINE.OBJ;2 to BACKUP.OBJ;2. The /NONEW_VERSION qualifier
     ensures that, if BACKUP.OBJ;2 already exists, the RENAME
     command does not rename the file, but instead reports the
     error.

   3.$ RENAME  *.TXT;*   *.OLD;*

     The RENAME command in this example renames all versions of all
     files with the file type TXT to have the file type OLD. The
     file names and version numbers are not changed.

   4.$ RENAME WATER.TXT [.MEMOS]

     The RENAME command in this example changes the directory
     name of WATER.TXT from your default directory to the MEMOS
     subdirectory. (The RENAME command moves the file to another
     directory.)

   5.$ RENAME  [BORDERS.TESTFILES]SAVE.DAT  []TEST

     The RENAME command in this example renames the file SAVE.DAT
     in the directory BORDERS.TESTFILES to TEST.DAT. The new file is
     moved to the current default directory.

   6.$ RENAME COEISABLAST.TXT COEIsABlast.txt

     The RENAME command in this example changes the case of
     COEISABLAST.TXT to COEIsABlast.txt. You must be on an ODS-
     5 disk and previously have used the SET PROCESS/CASE_
     LOOKUP=SENSITIVE command for this RENAME command to work
     properly.
 

