rename

rename

Rename a Disk File

Portability: ISO/ANSI C conforming, POSIX.1 conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

include <stdio.h>

int rename(const char *name1, const char *name2);

DESCRIPTION

The rename function changes the name of an OS/390 disk file, PDS member, HFS file, CMS disk file, or Shared File System (SFS) file or directory. Under OS/390, the character string pointed to by name1 specifies the filename of an existing OS/390 disk file or HFS file; name2 specifies the new OS/390 filename. Under CMS, the character string pointed to by name1 specifies the fileid of an existing CMS disk file or SFS file or directory; name2 specifies the new CMS fileid.

RETURN VALUE

The rename function returns 0 if the file is renamed. If the file cannot be renamed or if the name is invalid, -1 is returned.

CAUTION

OS/390

The name1 and name2 arguments must refer to OS/390 disk files or HFS files with the same filename style. Nondisk files cannot be renamed. For example, it is impossible to rename a data set residing on tape.

You cannot use the filenames nullfile , sysout=class , and &tmpname in rename . Also, you cannot use ddn style filenames that do not also specify a member name when renaming PDS members. The new PDS name must be the same as the old name, and only the member names can differ.

VSAM data sets cannot be renamed by the rename function.

CMS

name1 and name2 must refer to CMS disk files in the cms or xed style, or CMS Shared File System files or directories using the sf or sfd style.

The fileids should not contain wild cards such as * or = . If the filemode in name2 is blank, it is replaced with the filemode of name1 . If the filemode in name1 is blank, it is replaced by the default mode A1 . If name2 refers to an existing fileid, a message is printed and -1 is returned. When you use the CMS Shared File System, you cannot use rename to change a file's directory or file pool.

IMPLEMENTATION

Under OS/390, rename can issue STOW, CATALOG, and RENAME SVCs. Under CMS, rename issues a CMS RENAME command or the CMS callable services library routine DMSRENAM.

EXAMPLE

#include <stdlib.h>
#include <stdio.h>

main()
{
   int rc;

      /* Rename a dataset TESTFILE to EXAMPLE. */
   rc = rename("tso:testfile",
               "tso:example");

   if (rc == 0)
     puts("Dataset has been renamed.");
   else
     puts("Dataset not renamed.");
}

RELATED FUNCTIONS

remove

SEE ALSO

File Management Functions

Chapter Contents
Previous
Next
Top of Page