# MX\_COPYFILE

> [HTML Version](mx_copyfile.htm)

_Reviewed and revised April 2024_

**(1) xcall MIAMEX, MX\_COPYFILE, src\$, dst\$ \{,flags, status\}\}**

**(2) xcall MIAMEX, MX\_COPYFILE, chin, chout**

The MX\_COPYFILE (MIAMEX 27) first syntax moves or copies files based on their names. The second syntax copies the contents of the source to the destination using file channels and thus requires that the input and output files be opened and closed by the calling application. The routine distinguishes between the two calling formats based on the data type of the second argument. If it is a string (S or X) then it is treated as the _src\$_ parameter and the first syntax is used. If it is numeric (B or F) then it is treated as _chin_ and the second syntax is used.

In most cases, the first syntax is preferable, as it is easier to use, more flexible, more efficient, and with fewer side effects. See Comments_,_ below, for details on the differences between the two methods. 

**Parameters**

_src\$, dst\$_  ([String](string.htm.md))  \[in\]

source and destination file specifications, either AMOS-style or native

_chin, chout  _([Num](num.htm.md))  \[in\]

input and output file channels. _chin_ must be opened for INPUT or RANDOM. _chout_ must be opened for OUTPUT (or APPEND), or RANDOM. It is up to the application to properly close these channels on return from the subroutine.

_flags_  ([Bitmap](bitmap.htm.md) 8)   \[in\]  (default 0)

zero or more bit flags from the following table:

| **Symbol** | **Value** | **Meaning** |
|------|------|------|
| CPYF\_MOVE | \&h0001 | Move file instead of copy file |
| CPYF\_REPL | \&h0002 | Allow replacement of existing destination |
| CPYF\_SETRO | \&h0010 | Force read-only bit to be set on output |
| CPYF\_CLRRO | \&h0020 | Clear read-only bit on output |
| CPYF\_ENCRYPT | \&h0040 | force output file to be encrypted; requires EFS |
| CPYF\_DECRYPT | \&h0080 | force output file to be decrypted; requires EFS |
| **Definition file: [ashell.def](ashell_def.htm.md)** | | 



If neither of the read-only flags are set, then the status of the read-only flag is preserved, unless copying from a device with the ,RO flag, in which case the read-only flag will be cleared. The read-only flags only have meaning in WINDOWS.

_status_  ([Signed Int](integer-signed.htm.md))  \[out\]

| **Value** | **Meaning** |
|------|------|
| 0 | Success |
| \-1 | Destinations exists and CPYF\_REPL flag not specified |
| \-2 | Source does not exist |
| \-3 | Invalid parameter types |
| <other> | System error code. For Unix, this will be the return code from the mv or cp utility. For Windows, it will be a Windows system error code (translatable by MIAMEX,86). See _Comments_. |




Note that under Unix, the operation invokes the mv or cp utilities, which must be available in the PATH.

**Comments**

Advantages of the new (filespec, syntax #1 above) method over the old (file channel, syntax #2 above) method include:

•	The Move option (CPYF\_MOVE) is much more efficient than normal Copy, provided source and destination are on the same volume or file system. If not, then the move is simulated by a Copy followed by a Delete of the source.

•	Move preserves the file creation and file modification times.

•	Copy preserves the file modification time, but updates the file creation time because it is creating a new file. The old syntax, by contrast, causes both the creation time and modification time to be updated.

•	Simplifies the logic for protecting against accidental overwrite, as well as for detecting common errors in the operation. With the old method, in addition to needing the separate file opens and closes, you would have needed to also use lookup operations to check for the most common considerations of source-does not-exist or destination-already-exists.

On the other hand, the old (file channel) syntax offers the following capabilities that are not possible with the (new) filespec syntax:

•	You can append the source file to the destination by opening the destination for APPEND.LIT.

•	If the destination exists, you can overlay the source on it, starting at an arbitrary position, by first opening the destination channel for APPEND, and then using the [MX\_FILEPOS](mx_filepos.htm.md) to position the destination stream pointer prior to the copy operation. 

**Warning**: when intermixing two kinds of output to an open file channel (e.g. MX\_COPYFILE and PRINT #CH statements), you should first disable file buffering for that channel ([MX\_NOBUF](mx_no_flush_buf.htm.md)), lest the different buffering schemes used by the two methods result in jumbled output.