SAS/C Library Reference, Vol. 1

rename -- Rename a Disk File

SYNOPSIS

 include <stdio.h>

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

DESCRIPTION

The rename function changes the name of an MVS disk file, PDS member, HFS file, CMS disk file, or Shared File System (SFS) file or directory. Under MVS, the character string pointed to by name1 specifies the filename of an existing MVS disk file or HFS file; name2 specifies the new MVS 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

MVS The name1 and name2 arguments must refer to MVS 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 MVS, 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