Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists

 #include <Qp0lstdi.h>

 int Qp0lRenameKeep(const char *old, const char *new);  

The Qp0lRenameKeep() function renames a file or a directory specified by old to the name given by new. The old pointer must specify the name of an existing file or directory. Both old and new must be of the same type; that is, both directories or both files. The last element of old and new must not be "dot" (.) or "dot-dot" (..).

If new already exists, Qp0lRenameKeep() fails with the [EEXIST] error.

If the old argument points to a symbolic link, the symbolic link is renamed. Qp0lRenameKeep() does not affect any file or directory named by the contents of the symbolic link. See Usage Notes for more information.

When Qp0lRenameKeep() is successful, it updates the change and modification times for the parent directories of old and new.

If the old object is checked out, Qp0lRenameKeep() fails with the [EBUSY] error.

Parameters

old

(Input) A pointer to the null-terminated path name of the file to be renamed.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the old in any CCSID.

new

(Input) A pointer to the null-terminated path name of the new name of the file.

This parameter is assumed to be represented in the CCSID currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

The new file name is assumed to be represented in the language and country or region currently in effect for the job.

See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the new in any CCSID.

Authorities

Note: Adopted authority is not used.

Authorization Required for Qp0lRenameKeep() (excluding QSYS.LIB, independent ASP QSYS.LIB, QDLS, and QOPT)

Note: The S_ISVTX mode bit (which is equivalent to the 'Restricted rename and unlink' object attribute) restriction only applies to objects in the "root" (/), QOpenSys, and user-defined file systems.

Authorization Required for Qp0lRenameKeep() in the QSYS.LIB and independent ASP QSYS.LIB File Systems

Authorization Required for Qp0lRenameKeep() in the QDLS File System

Authorization Required for Qp0lRenameKeep() in the QOPT File System

Return Value

0

Qp0lRenameKeep() was successful.

-1

Qp0lRenameKeep() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If Qp0lRenameKeep() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could also indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. About the Rename Functions

   The integrated file system provides two functions that rename a file or directory. Both rename the old path name to a new path name. The difference is determined by what happens when new already exists:

   • If new already exists when using Qp0lRenameKeep(), the rename fails with the [EEXIST] error.
     
   • If new already exists when using Qp0lRenameUnlink(), the existing path name is unlinked (removed) before old is renamed to new.

   These functions are defined in the <Qp0lstdi.h> header file. When <Qp0lstdi.h> is included, the rename() function is defined to be either Qp0lRenameUnlink() or Qp0lRenameKeep(), depending on the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros:

   • When _POSIX_SOURCE and _POSIX1_SOURCE are not defined, rename() is defined to be Qp0lRenameKeep(). Either rename() or Qp0lRenameKeep() can be used to rename a file or directory with the semantics of Qp0lRenameKeep().
     
   • When _POSIX_SOURCE or _POSIX1_SOURCE is defined, rename() is defined to be Qp0lRenameUnlink(). Either rename() or Qp0lRenameUnlink() can be used to rename a file or directory with the semantics of Qp0lRenameUnlink().

   When the <Qp0lstdi.h> header file is not included, rename() operates only on database files in the QSYS.LIB and independent ASP QSYS.LIB file systems, as it did before the introduction of the integrated file system.

   
   
3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences
   • When a database member is being renamed, the part of the new path name preceding the object must be the same as that of the old path name. That is, the sequence of "directories" (library and file) preceding the object in the new path name must be the same as the sequence of directories preceding the object in the old path name.
     
   • The following object types cannot be renamed when there are secondary threads active in the job: *CFGL, *CNNL, *CTLD, *DEVD, *LIND, *NWID. The operation will fail with error code [ENOTSAFE].
   • When a library is being renamed, the part of the new path name preceding the object must be the same as that of the old path name. That is, the sequence of "directories" (/QSYS.LIB or /asp_name/QSYS.LIB, where asp_name is the independent Auxiliary Storage Pool name) preceding the object in the new path name must be the same as the sequence of directories preceding the object in the old path name [EINVAL].
   
   
4. QDLS File System Differences

   When a folder is being renamed, the part of the new path name preceding the object must be the same as that of the old path name. That is, a folder must remain in the same parent folder.

   
   
5. QOPT File System Differences

   You can rename only a volume or a file, not a directory.

   
   
6. QFileSvr.400 File System Differences

   You cannot rename the first-level directory. For example, you cannot rename Dir1 in the path name /QFileSvr.400/Dir1/Dir2/Object. The first-level directory identifies the target system in a communications connection.

   
   
7. QNetWare File System Differences

   The new and old files or directories must exist on the same NetWare server. This function cannot be used to move data from one server to another.

   
   
8. QNTC File System Differences

   The new and the old files or directories must exist on the same Windows NT server. This function cannot be used to move data from one server to another.
   

   
   
9. "Root" (/) and User-defined File System Differences

   If the file being renamed is in the "root" (/) file system or in a monocase user-defined file system, and the file system has the *TYPE2 directory format, and both old and new refer to the same link, but their case is different (eg. /ABC and /Abc), Qp0lRenameUnlink() changes the link name to the new name.

10. The file cannot be renamed if the file is a DataLink column in an SQL table and a row in that SQL table references this file.

Related Information

• The <stdio.h> file (see Header Files for UNIX-Type Functions)
  
• The <Qp0lstdi.h> file (see Header Files for UNIX-Type Functions)
  
• pathconf()--Get Configurable Path Name Variables
  
• rename()--Rename File or Directory
  
• QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path name)
  
• Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists

Example

See Code disclaimer information for information pertaining to code examples.

When you pass two file names to this example, it will try to change the file name from the first name to the second using Qp0lRenameKeep().

#include <Qp0lstdi.h>

int main(int argc, char ** argv ) {

  if ( argc != 3 )
    printf( "Usage: %s old_fn new_fn\n", argv[0] );
  else if ( Qp0lRenameKeep( argv[1], argv[2] ) != 0
    perror ( "Could not rename file" );
}