(1) xcall MIAMEX, MX_COPYFILE, src$, dst$ {,flags, status}}

(2) xcall MIAMEX, MX_COPYFILE, chin, chout

The 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  (Num)  [in]  (default 0)

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  (F,6)  [out]

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.

• The new 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.

• 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 MIAMEX,118 function to position the destination stream pointer prior to the copy operation. Note that this requires A-Shell 4.9.958 or later.

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.

History

2007 November, A-Shell 4.9.988:  Undex UNIX, if an error (other than -1, -2, or -3) occurs, the full text of the error message can be found in the temporary file <jobnam>.tmp, on return from the xcall.

2006 October, A-Shell 4.9.968:  MX_COPYFILE no longer defaults to xxx extensions

2006 April, A-Shell 4.9.954:  Add syntax (1)