RENAME

Authorization

General User

Purpose

Operands

fn1 ft1 fm1

fn1 ft1 dirid1

* * *

For a file on a minidisk this is the file name, file type, and file mode. For a file in an SFS directory, this could be the file name, file type, and a dirid. For more information on dirid, see Naming Shared File System (SFS) Directories.

You can use an asterisk (*) for any part of the file identifier to indicate any file that satisfies the other qualifications is renamed. Subdirectories that match the specified pattern are ignored and are not renamed.

fn2 ft2 fm2

fn2 ft2 dirid2

fn2 ft2 *

= = =

For a file on a minidisk, this is the file name, file type, and file mode. For a file in an SFS directory, this is the file name, file type, and a dirid.

You can use an equal sign (=) for any part of the file identifier to indicate the corresponding file identifier is unchanged. The file mode or dirid can also be specified as an asterisk (*), indicating the corresponding file mode or dirid is not changed.

dirid1

is the directory identifier of the SFS directory you want to rename. You can also use a file mode for the dirid if the directory is already accessed. For more information on dirid, see Naming Shared File System (SFS) Directories.

dirid2

is the new directory name. Variable dirid2 cannot be expressed as a file mode when you rename a directory.

Options

Type

displays, at the terminal, the new identifiers of all the files being renamed. The file identifiers are displayed only when an asterisk (*) is specified for one or more of the file identifiers in the first file ID.

NOType

suppresses the display at the terminal of the new file identifiers of the files being renamed. The default is NOTYPE.

STACK FIFO

STACK LIFO

places the output in the console stack rather than displaying it at the terminal. The new file identifiers are stacked only when an asterisk (*) is specified for one or more of the file identifiers (fn1, ft1, fm2, or dirid1) in fileid1. The default is FIFO.

FIFO

specifies the output is stacked in a first in, first out order. This option is equivalent to STACK FIFO.

LIFO

specifies the output is stacked in a last in, first out order. This option is equivalent to STACK LIFO.

UPdirt

updates the list of files upon completion of this command. UPDIRT is not valid when you are renaming a file in a directory or the directory itself. This is the default.

NOUPdirt

suppresses the updating of the master file directory when a file on a minidisk is renamed. For more information, see Usage Note 16.

NOUPDIRT is not valid when you are renaming a file in a directory or the directory itself.

Usage Notes

1. When you code an asterisk (*) in any portion of the input file ID, any or all of the files that satisfy the other qualifiers may be renamed, depending upon how you specify the output file ID. For example:

   rename * assemble a test file a

   results in the first ASSEMBLE file found being renamed to TEST FILE. If more than one ASSEMBLE file exists, error messages are issued to indicate that they cannot be renamed.
   If you code an equal sign (=) in an output file ID in a position corresponding to an asterisk in an input file ID, all files that satisfy the condition are renamed. For example:

   rename * assemble a = oldasm =

   renames all files with a file type of ASSEMBLE to files with a file type of OLDASM. Current file names are retained.
2. You cannot use the RENAME command to move a file from one minidisk or directory to another. For files on minidisks, you must use the COPYFILE command if you want to copy a file to another minidisk. For files in directories, you can use the RELOCATE command to move a file to another directory or the COPYFILE command to copy the file to another directory.

   Similarly, you cannot use the RENAME command to move an SFS directory to another parent directory. You must use the RELOCATE command if you want to move a directory structure.

3. You can use the RENAME command to modify file mode numbers for base files. You cannot use the RENAME command to modify the file mode number for an alias. Aliases are automatically updated with the same file mode number as the base file. For example,

   rename * module a1 = = a2

   changes the file mode number on all MODULE files that have a mode number of 1 to a mode number of 2.
4. When you rename an alias, only the alias is renamed; the base file name stays the same.
5. You can rename existing files to the name of an erased or revoked alias.
6. You can invoke the RENAME command from the terminal, from an exec file, or as a function from a program. If RENAME is invoked as a function or from an exec file that has the &CONTROL NOMSG option in effect, the message DMSRNM002E (File fn ft fm not found) is not issued.
7. When you rename a directory, all authorizations for you and other users remain in effect.
8. You cannot rename a file in an SFS directory if the file is open in read/write mode by any user or if you have it open in read-only mode. You can rename a file that is open by other users in read-only mode.

   If you specify an explicit file ID for renaming, the directory in which the file resides can be open or closed.

9. You cannot rename a file or subdirectory of a directory control directory while the parent directory is accessed read/write by another user or read-only by you. You can rename it while it is accessed read-only by other users.
10. You cannot rename a directory control directory if it is accessed read/write by anyone other than you. If you have it accessed, you must have it accessed in read/write mode.
11. For file control directories, QUERY SEARCH or QUERY ACCESSED will display the new directory name immediately. Users who have directory control directories accessed in read-only mode will have the old name returned until they release all accesses to the directory and then access it again.
12. When you rename a directory, all files in the directory must be closed, and the directory and all the subdirectories must be either closed or open with intent of FILE.
13. If a file or the directory containing the file is locked you cannot rename the file unless the lock is an UPDATE or EXCLUSIVE lock you hold.
14. If a directory is locked, or contains locked files or subdirectories, the directory cannot be renamed unless the lock is an UPDATE or EXCLUSIVE lock you hold. These same rules apply for renaming a subdirectory in a locked directory.
15. Directories can be renamed only one level at a time. For example, changing

    .PROJA.PROPOSAL

    to

    .PROJ3101.FIRSTPROPOSAL

    would require two commands:

    rename .proja .proj3101
    rename .proj3101.proposal .proj3101.firstproposal

    

    As illustrated by the first rename above, changing the name of a directory changes the names of all its subdirectories.

16. Usually, the master file directory for a CMS minidisk is updated whenever you issue a command that affects files on the minidisk. If you use the NOUPDIRT option of the RENAME command, this list is not updated until you issue a command that writes, updates, or deletes any file on the minidisk, or until you explicitly release the minidisk (with the RELEASE command).
    Note: The NOUPDIRT option is only valid for files on a minidisk; it is ignored when you rename files in a directory or when you rename a directory.
17. You can only rename directories you own. You can rename another user's files if you are properly authorized. For files in file control directories, you must have write authority to the file and write authority to the directory that contains the file. For files in directory control directories, you must have directory control write (DIRWRITE) authority to the directory that contains the file.

    You can also rename another user's alias. All aliases exist in file control directories. To rename an alias, you need read authority to the base file and write authority to the directory containing the alias.

    You need write authority to the directory to rename an external object. You do not have to own the directory.

18. To use the fm form of dirid when renaming a file, the directory must be accessed in read/write mode. Other users' directories, by default, are accessed in read-only mode. To access another user's directory in read/write mode, use the FORCERW option on the ACCESS command.
19. You can issue RENAME from the command (Cmd) column on any of the FILELIST screens. For example, to rename a file in a directory accessed in read/write mode, enter:

    rename / newname = =

    If you are authorized to rename the file, but the directory is accessed in read-only status, enter:

    rename /ntd newname = =

    This indicates you choose to rename the fn ft directory to a new file name and keep the same file type and directory name as displayed.

    By default, directories owned by other users are accessed in read-only status. To access another user's directory in read/write status, use the FORCERW option on the ACCESS command.

    For more examples on using the RENAME command, see z/VM: CMS User's Guide.

20. When renaming a directory, if the RENAME command is issued from an exec on a work unit that has not been committed, the command will fail.
21. The recoverability and overwrite attributes of the file are unaffected by the RENAME command, regardless of the new file mode number assigned.
22. You can rename a file that has been placed in DFSMS/VM migrated status. The file data will not be recalled from the DFSMS/VM storage repository.
23. RENAME can be used on mixed case file IDs when FILELIST is entered with the MIXEDON option.

Responses

newfn newft newfm

The new file name, file type, and file mode of each file altered is displayed when the TYPE option is specified and an asterisk was specified for at least one of the file identifiers (fn, ft, or fm) of the input file ID.

Messages and Return Codes

• DMS002E File fn ft fm│dirname not found [RC=28]
• DMS019E Identical fileids [RC=24]
• DMS030E File fn ft fm already active [RC=28]
• DMS037E Filemode mode is accessed as read/only [RC=36]
• DMS048E Invalid filemode mode [RC=24]
• DMS051E Invalid mode change [RC=24]
• DMS054E Incomplete fileid specified [RC=24]
• DMS069E Filemode mode not accessed [RC=36]
• DMS1131E Directory dirname already exists [RC=28]
• DMS1184E File fn ft fm│dirname not found or you are not authorized for it [RC=28]
• DMS1184E Directory dirname not found or you are not authorized for it [RC=28]
• DMS1199E You cannot rename a top directory [RC=24]
• DMS1226E Invalid subdirectory name change. Only the last qualifier of the specified subdirectory can be renamed. [RC=24]
• DMS1241E Directories specified are in different file pools [RC=88]
• DMS1257E The RENAME command is invalid on a file in a directory that you do not own [RC=76]
• DMS1257E The RENAME command is invalid on a directory that you do not own [RC=28]
• DMS1308E The filemode number of an alias must be the same as the filemode number of the base file [RC=24]
• DMS1309I Command completed successfully, but the filemode number of the alias is the same as the filemode number of the base file [RC=0]
• DMS2040E RENAME cannot be performed on a directory control directory that is accessed read-only [RC=36]

Additional system messages may be issued by this command. The reasons for these messages and their location are: