VMS Help RENAME  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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

    Format

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

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

 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

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

 2.2 - /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, refer to the
    OpenVMS User's Manual or the online help topic DCL_Tips (subtopic
    Date_Time).

 2.3 - /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
    OpenVMS Guide to System Security.

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

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

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

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

 2.8 - /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. Refer to
    the OpenVMS Guide to System Security or online help (Hints topic)
    for a description of how a profile is assigned.

 2.9 - /LOG

       /LOG
       /NOLOG (default)

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

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

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

 2.12 - /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, 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, refer to the
    OpenVMS User's Manual or the online help topic DCL_Tips (subtopic
    Date_Time).

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

    Refer to the OpenVMS Guide to Extended File Specifications for
    more information.

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