The Rename One or More Files routine changes the names of one
or more files. The specification of the files to be renamed can
include wildcards.
LIB$RENAME_FILE is similar in function to the DCL command RENAME.
Format
LIB$RENAME_FILE old-filespec ,new-filespec
[,default-filespec] [,related-filespec]
[,flags] [,user-success-procedure]
[,user-error-procedure]
[,user-confirm-procedure]
[,user-specified-argument]
[,old-resultant-name] [,new-resultant-name]
[,file-scan-context]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2 – Arguments
old-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification of the files to be renamed. The old-filespec
argument is the address of a descriptor pointing to the old file
specification. The specification may include wildcards, in which
case each file that matches the specification will be renamed.
If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set,
the string must not contain more characters than specified by
NAML$C_MAXRSS, otherwise the string must not contain more than
255 characters. Any string class is supported.
new-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the new file names. The new-filespec
argument is the address of a descriptor pointing to the new file
specification.
This specification need not be complete; fields omitted or
specified by using the wildcard character (*) will be filled in
from the existing file's name using the same rules as for the DCL
command RENAME. If running on Alpha or I64 and flag LIB$M_FIL_
LONG_NAMES is set, the string must not contain more characters
than specified by NAML$C_MAXRSS, otherwise the string must not
contain more than 255 characters. Any string class is supported.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification of the files to be renamed. The
default-filespec argument is the address of a descriptor pointing
to the default file specification.
This is an optional argument; if omitted, the default is the
null string. See the OpenVMS Record Management Services Reference
Manual for information on default file specifications. If running
on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string
must not contain more characters than specified by NAML$C_MAXRSS,
otherwise the string must not contain more than 255 characters.
Any string class is supported.
related-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification of the files to be renamed. The
related-filespec argument is the address of a descriptor pointing
to the related file specification. This is an optional argument;
if omitted, the default is the null string. Any string class is
supported.
Input file parsing is used. (See the OpenVMS Record Management
Services Reference Manual for information on related file
specifications and input file parsing.)
The related file specification is useful when you are processing
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed. Any
string class is supported. This is an optional argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Longword of flag bits designating optional behavior. The flags
argument is the address of an unsigned longword containing the
flag bits. This is an optional argument; if omitted, the default
is that all flags are clear.
The bit number and its meaning are as follows:
Bit Symbol Description
0 LIB$M_FIL_CUR_VER If new-filespec does not specify a
version number, this flag controls
whether a new version number for the
output file is to be assigned. If this
bit is set, the current version number of
the file is used.
If this bit is clear, the file is given
a version number 1 higher than any
previously existing file of the same file
name and file type. This is the default
action.
If a file already exists with the same file name, type and version
number, the error RMS$_FEX is given. This flag is equivalent to the
2.1 /NONEW_VERSION qualifier of the DCL command RENAME.)
1 LIB$M_FIL_INH_ Controls whether the renamed file
SECUR takes on security attributes of the new
location or keeps its existing security
attributes. If this bit is clear, the
attributes of the renamed file are
inherited from the next lower version
of the new file name, if any, the new
parent directory, or both.
If this bit is clear, the file's security
attributes are not changed; this is the
default action.
For more information on file security,
see the VSI OpenVMS Guide to System
Security. This flag is equivalent to the
/INHERIT_SECURITY qualifier of the DCL
command RENAME.
2 LIB$M_FIL_LONG_ (Alpha and I64 only) Controls whether to
NAMES accept file specifications greater than
255 characters in length. If this bit is
set, LIB$RENAME_FILE can process files
specifications with a maximum length of
NAML$C_MAXRSS characters.
If this bit is clear, LIB$RENAME_FILE can
process files names with a maximum length
of 255 characters.
user-success-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$RENAME_FILE calls after
each successful rename.
user-error-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$RENAME_FILE calls when
it detects an error. The value returned by the error routine
determines whether LIB$RENAME_FILE processes more files.
user-confirm-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied confirm routine that LIB$RENAME_FILE calls before
it renames a file. The value returned by the confirm routine
determines whether or not LIB$RENAME_FILE renames the file.
The confirm routine can be used to select specific files for
renaming based on criteria such as expiration date, size, and so
on.
user-specified-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Value that LIB$RENAME_FILE passes to the success, error, and
confirm routines each time they are called. Whatever mechanism
is used to pass user-specified-argument to LIB$RENAME_FILE is
also used to pass it to the user-supplied routines. This is an
optional argument; if omitted, zero is passed by value.
old-resultant-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE copies the old resultant file
specification of the last file processed. This is an optional
argument. If present, it is used to store the file specification
passed to the user-supplied routines instead of a default class
S, type T string. Any string class is supported.
If you are specifying one or more of the action routine
arguments, be sure that the descriptor class used to pass
resultant-name is the same as the descriptor class required by
the action routine. For example, VAX Ada requires a class SB
descriptor for string arguments to Ada routines, but will use
a class A descriptor by default when calling external routines.
Refer to your language manual to determine the proper descriptor
class to use.
new-resultant-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE writes the new OpenVMS RMS
resultant file specification of the last file processed. The new-
resultant-name argument is the address of a descriptor pointing
to the new name. This is an optional argument. If present, it is
used to store the file specification passed to the user-supplied
routines instead of a class S, type T string. Any string class is
supported.
If you are specifying one or more of the action routine
arguments, be sure that the descriptor class used to pass
resultant-name is the same as the descriptor class required by
the action routine. For example, VAX Ada requires a class SB
descriptor for string arguments to Ada routines, but will use
a class A descriptor by default when calling external routines.
Refer to your language manual to determine the proper descriptor
class to use.
file-scan-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context for renaming a list of file specifications. The file-
scan-context is the address of a longword that contains this
context. You must initialize this longword to zero before the
first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_
FILE uses the file scan context to retain the file context for
multiple input files.
LIB$FILE_SCAN uses this context to retain multiple input file
related file context. This is an optional argument; it need only
be specified if you are using multiple input files, as the DCL
command RENAME does. You may deallocate the context allocated by
LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by
calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have
been completed. See the description of LIB$FILE_SCAN for a more
detailed description of this argument.