VMS Help  —  RTL Routines, LIB$  LIB$RENAME_FILE
    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.
Close Help