Copy file contents to another file
|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
xcall COPY(filename, new_filename[, mode])
Arguments
filename
The name of an existing file. (a)
new_filename
The name of a new file to be created with the contents of filename. (a)
mode
(optional) The mode in which to copy: (n)
0 = Binary (default)
1 = Text
Discussion
The COPY subroutine copies the contents of a single existing file to a new file.
If mode is 0, the source file is assumed to be binary and will be copied exactly as is. This is the default and must be used when copying Synergy ISAM files.
If mode is 1, the source file is assumed to be a text file containing text terminated by one or more line terminators. If the file is being copied across the network using xfServer, the line terminator(s) are translated to the system where new_filename is created. If the file is being copied from a UNIX or Windows system to an OpenVMS system, the file being created is a sequential stream file.
It is not necessary to specify mode when copying on the same operating system; it is only relevant when copying between two different operating systems.
If you specify a new filename that already exists, one of two things occurs, depending on whether the FLAGS subroutine runtime option flag 3 is set:
- If flag 3 is set, the runtime checks for an existing file with the same name, and a “Cannot supersede existing file” error ($ERR_REPLAC) is generated.
- If flag 3 is not set, the runtime does not check for duplicate filenames, and the existing file is overwritten as part of the renaming process. For example, if file a.b already exists and the following statement is executed:
xcall copy("old.ddf", "a.b")
the current a.b file is deleted, and the current old.ddf is copied to the new a.b file.
If the old file is already open by any user in update, output, or append mode, a “File in use by another user” error ($ERR_FINUSE) is generated. The same error is generated if the new file is already open by any user in any mode.
Filename and new_filename can also include a search list logical, which specifies one or more directory paths in which to search for the file. If a search list logical is used on the new_filename specification, the copied file is placed in the first directory specified in the search list.
If the COPY subroutine can’t find the specified old filename, you’ll get a “File not found” error ($ERR_FNF).
On Windows and UNIX, to copy an ISAM file, you must make two calls to the COPY subroutine, specifying the name and extension for each file (file.ism and file.is1) in addition to mode 0.
If the COPY subroutine is called locally on OpenVMS, the attributes of the file being copied are preserved. The third argument (mode) is ignored.
When you copy an indexed file between OpenVMS and Windows or UNIX, the file attributes are not preserved, and the result is a sequential stream file that contains binary information from the source file.
If an ISAM file has the network encryption flag enabled (either on the “from” or “to” file),
- A file being copied to or from an NFS or mapped drive will generate an $ERR_NETCRYPT error.
- A file being copied to or from a server without encryption enabled will generate an $ERR_NETCRYPT error.
