MX_COPYFILE
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) [in]
source and destination file specifications, either AMOS-style or native
chin, chout (Num) [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 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 |
||
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) [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 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), lest the different buffering schemes used by the two methods result in jumbled output.
