(LOGO.JPG) Python for OpenVMS

(go to: table of contents, index, list of vms_lib, prev: RADIX_POINT, next: RESERVE_EF)


RENAME_FILE - Rename One or More Files


Format:
    status, context, old-resultant-name, new-resultant-name = \
        vms_lib.rename_file (old-filespec, new-filespec \
        [,default-filespec] [,related-filespec] [,flags] \
        [,user-success-procedure] [,user-error-procedure] \
        [,user-confirm-procedure] [,user-specified-argument] \
        [,file-scan-context])
Returns:
status
Return code from LIB$RENAME_FILE.
context
Updated 'file-scan-context'. If this argument is omitted (or None), then 0 is returned.
old-resultant-name
The old RMS resultant file specification of the last file processed.
new-resultant-name
The new RMS resultant file specification of the last file processed.
Arguments:
old-filespec
File specification of the files to be renamed. Can include wildcards.
new-filespec
File specification for the new file names. 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.
default-filespec
Default file specification of the files to be renamed.
See the OpenVMS Record Management Services Reference Manual for information about default file specifications.
related-filespec
Related file specification of the files to be renamed.
See the OpenVMS Record Management Services Reference Manual for information about related file specifications.
flags
flags define optional behaviour. See the OpenVMS documentation for a definition of the bits. There are no symbolic names available.
user-success-procedure
User-supplied success routine that LIB$RENAME_FILE calls after it successfully renamed a file. See the examples section for the arguments to this routine.
user-error-procedure
User-supplied error routine that LIB$RENAME_FILE calls when it detects an error. Return with the value 1 to tell LIB$RENAME_FILE to contine. Return with the value 0 to tell LIB$RENAME_FILE to stop processing immediately. See the examples section for the arguments to this routine.
user-confirm-procedure
The confirm-procedure can make more checks to determine if the current file should be renamed. If confirm routine returns a success status (bit 0 set), the file is then deleted; otherwise, the file is not deleted. See the examples section for the arguments to this routine.
user-specified-argument
This can be any Python object (including None) that is passed unchanged to the user-procedures.
file-scan-context
Context for renaming a list of file specifications. Supply a value of 0 for the first call. The context can be deallocated by calling the vms_lib.file_scan_end() routine with the context as its argument.
Examples:
>>> import vms_lib
>>> import vms_sys


>>> # define user-procedures

>>> # user-success
>>> def u_success (old_filespec, new_filespec, user_arg):
...   print '*user-success-procedure'
...   print type(old_filespec), old_filespec
...   print type(new_filespec), new_filespec
...   print type(user_arg), user_arg
...   return 1
... #-u_success
>>>

>>> # user-error
>>> def u_error (old_filespec, new_filespec, l_rms_sts, l_rms_stv, \
...            l_error_source, user_arg):
...   print '*user-error-procedure'
...   print type(old_filespec), old_filespec
...   print type(new_filespec), new_filespec
...   print type(l_rms_sts), l_rms_sts
...   print type(l_rms_stv), l_rms_stv
...   print type(l_error_source), l_error_source
...   print type(user_arg), user_arg
...   return 1
... #-u_error
>>>

>>> # user-confirm
>>> def u_confirm (old_filespec, new_filespec, old_fab, user_arg):
...   print '*user-confirm-procedure'
...   print type(old_filespec), old_filespec
...   print type(new_filespec), new_filespec
...   print type(old_fab), old_fab
...   print old_fab.FNA
...   print type(user_arg), user_arg
...   return 1
... #-u_confirm
>>>


>>> # simple rename-test
>>> file = open ('RENAME-FROM.TMP','w')
>>> file.close()

>>> status, context, old_result, new_result = \
...   vms_lib.rename_file ('rename-from.tmp;', 'rename-to.tmp;', \
...                        None, None, None, \
...                        u_success, u_error, u_confirm, 'uspec-arg')
*user-confirm-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;
<type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
rename-from.tmp;
<type 'string'> uspec-arg
*user-success-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;1
<type 'string'> uspec-arg
>>>
>>> print status, context
1 0
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>> print old_result
USER_HERE:[ZESSIN.RENAME]RENAME-FROM.TMP;1
>>> print new_result
USER_HERE:[ZESSIN.RENAME]RENAME-TO.TMP;1
>>>
>>> # see if file has been renamed ...
>>> import os; os.system ('DIRECTORY RENAME-*.TMP')

Directory USER_HERE:[ZESSIN.RENAME]

RENAME-TO.TMP;1

Total of 1 file.
1           <-- return status from subprocess
>>>
>>> # delete file
>>> os.system ('DELETE/NOCONFIRM RENAME-*.TMP;*')
1           <-- return status from subprocess
>>>



>>> # try to rename a non-existing file (triggers error-procedure)
>>> status, context, old_result, new_result = \
...   vms_lib.rename_file ('no-file.tmp;', 'new-file.tmp;', \
...                        None, None, None, \
...                        u_success, u_error, u_confirm, 'uspec-arg')
*user-error-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]NO-FILE.TMP;
<type 'string'> new-file.tmp;
<type 'int'> 98962    <-- rms_sts
<type 'int'> 2320     <-- rms_stv
<type 'int'> 0        <-- error-source
<type 'string'> uspec-arg
>>> #
... print status, context
1409065 0
>>> print old_result
USER_HERE:[ZESSIN.RENAME]NO-FILE.TMP;
>>> print new_result
new-file.tmp;
>>>
>>> vms_sys.getmsg (98962) # rms_sts
('%RMS-E-FNF, file not found', (0, 0, 0, 0))
>>> vms_sys.getmsg (2320)  # rms_stv
('%SYSTEM-W-NOSUCHFILE, no such file', (0, 0, 0, 0))
>>>
>>> vms_sys.getmsg (1409065)
('%LIB-S-ERRROUCAL, error routine called', (0, 0, 0, 0))
>>>



>>> # example of wildcard delete with context
>>> file = open ('RENAME1.TMP','w'); file.close()
>>> file = open ('RENAME2.TMP','w'); file.close()
>>> file = open ('RENAME3.TMP','w'); file.close()
>>> context = 0
>>> status, context, old_result, new_result = \
...   vms_lib.rename_file ('rename*.tmp;', '*.t-tmp',
...                        None, None, None, \
...                        u_success, u_error, u_confirm, \
...                        'uspec-arg', context)
>>> print status, context
>>> print old_result
>>> print new_result
*user-confirm-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP;
<type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
rename*.tmp;
<type 'string'> uspec-arg
*user-success-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME1.T-TMP;1
<type 'string'> uspec-arg
*user-confirm-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP;
<type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
rename*.tmp;
<type 'string'> uspec-arg
*user-success-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME2.T-TMP;1
<type 'string'> uspec-arg
*user-confirm-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;
<type 'vmsobj_fab'> <vmsobj_fab, FAB at 0x7fee8184>
rename*.tmp;
<type 'string'> uspec-arg
*user-success-procedure
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1
<type 'string'> USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;1
<type 'string'> uspec-arg
>>> print status, context
1 2374408
>>> print old_result
USER_HERE:[ZESSIN.RENAME]RENAME3.TMP;1
>>> print new_result
USER_HERE:[ZESSIN.RENAME]RENAME3.T-TMP;1
>>>
>>> import os; os.system ('DIRECTORY RENAME*.*')

Directory USER_HERE:[ZESSIN.RENAME]

RENAME1.T-TMP;1     RENAME2.T-TMP;1     RENAME3.T-TMP;1

Total of 3 files.
1           <-- return status from subprocess
>>>


@@ more RENAME_FILE examples
>>>

(go to: table of contents, index, list of vms_lib, prev: RADIX_POINT, next: RESERVE_EF)

01-FEB-1999 ZE.