(CopyFile)

Mnemonic:

(CopyFile=source-file,destination-file,flags)

Discussion:

This mnemonic copies the source-file to the destination-file, using the specified flags.

This mnemonic may be used by foreground programs only.

Note: The (CopyFile) mnemonic is intended to replace (Verify File).

The source-file, which is specified as a full Windows path, UNC path, or directory alias, may be located on a local Comet system/network or a CometAnywhere client system (default is local system).

The destination-file, which is specified as a full Windows path, UNC path, or directory alias, may be located on a local Comet system/network or CometAnywhere client system (default is local system).

When issued on lun (0), this mnemonic copies a file:

from a local Comet system/network to itself
from a local Comet system/network to a CometAnywhere client system
from a CometAnywhere client system to a local Comet system/network
from the CometAnywhere client system to itself

The mnemonic provides many powerful features, such as an option to compare the source file's modify date with the destination file's modify date (in the case where the destination file already exists) in order to determine whether the source file needs to be copied, an option to display a progress bar during CometAnywhere transfers, and options to create a directory, overwrite an existing file, and create a CAFILE alias if required.

Flags is a numeric value representing the sum of the numeric values listed in the following chart:

Flag Description

1 The source file is located on the CometAnywhere client system

2 CometAnywhere is required if remote files are specified
If a flag is set indicating that the source file is located on a CometAnywhere client system (flag=1) and/or that the destination file is located on a CometAnywhere client system (flag=512), but the user is running on a local Comet system (i.e., not a CometAnywhere client system):

If this flag is set, an error is reported (see function error 2).
If this flag is not set, Comet substitutes the local drive/path name for a remote path/drive name.

64 Synchronize source and destination files
If the source file is newer than the destination file, or the destination file does not exist, the destination file is updated (assuming that the other flags call for the copying to occur).
If this flag is omitted, the destination file is updated (assuming that the other flags call for the copying to occur).
Note: Different file systems may return file update times in different formats. For example, the NT file system (NTFS) returns file update times in Coordinated Universal Time (abbreviated as UTC; formely known as Greenwich Mean Time), while FAT returns file update times in local time. Therefore, when using this flag, make sure that the source and destination files use the same file system and return the file update times in the same format.

128 Create CAFILES alias if required
If an alias is specified in the destination file name, and the alias doesn't already exist, this flag creates the alias.

256 Don't copy the file; just indicate if an update is needed
See the function error codes (below), particularly values 20 and 21.

512 The destination file is located on the CometAnywhere client system

1024 Show a progress bar for transfers between a local Comet system/network and a CometAnywhere client system

2048 Overwrite existing file
If the destination file already exists, overwrite it with the contents of the source file.

4096 Create directory
If a directory is specified for the destination file, and that directory does not already exist, create it.

After this mnemonic is issued, your program can issue an INPUT on LUN (0) to retrieve success/error information. For example:

  LENGTH 2 & LOCAL AX$,DX$
  ResultFmt: FORMAT AX$;DX$
  .
  .
  Print (CopyFile=Source$,Dest$,Flags)
  Input (0,ResultFmt)

The first field, AX$, contains the function error code, and the second field, DX$, contains the suberror code (aka the Windows file error code). Both of these fields are in Intel 2's complement format, and should be processed as follows:

  AX$ = SUB(AX$,2,1) + SUB(AX$,1,1)   ! Flip the bytes around
  DX$ = SUB(DX$,2,1) + SUB(DX$,1,1)   ! Flip the bytes around
  FuncError = HexDec(AX$)             ! Function error code (decimal)
  FileError = HexDec(DX$)             ! File error code (decimal)

  ! For unexpected values, convert to 2's complement signed integer
  If (FuncError > 32767) FuncError = FuncError-65536
  If (FileError > 32767) FileError = FileError-65536

Here is a list of the function error codes in decimal form:

Error
(FuncError) Description

0 Function not supported

1 Success -- update performed

2 CometAnywhere required

3 Source file error (see suberrors)

4 Aborted by user

5 Function in progress

20 Success -- update not required

21 Success -- update required

22 Destination file error (see suberrors)

Here is a list of the suberror codes (common Windows file errors) in decimal form:

Suberror
(FileError) Description

0 Success

2 File not found

3 Path not found

5 Access denied

12 Invalid access

15 Invalid drive

16 An error has occurred in the current directory

18 No more files

32 Sharing violation

33 Lock violation

39 File located on Remote Computer

80 File exists

123 The Filename, Directory Name, or Volume Label Syntax Is Incorrect

161 Bad pathname

183 The Filename already exists

1326 User not logged in to Remote Computer

Other error codes

Microsoft Error Codes

History:

This mnemonic was added in Comet Build 299 and REL Version 01.07.

Example 1:

Source$ = "C:\SAMPLEFILES\TEST.TXT"
Dest$ = "A:\TEST.TXT"
Flags = 2048
Print (CopyFile=Source$,Dest$,Flags)

This example copies the source file named C:\SAMPLEFILES\TEST.TXT to the destination file named A:\TEST.TXT. By default, both files are located on the local Comet system/network. The flag value of 2048 tells Comet to overwrite the destination file if it exists.

If the copying is successful, the function error code will be equal to 1 (Success -- update performed), and the suberror code will be equal to 0 (Success).

Example 2:

Source$ = "C:\FILE1.TXT"
Dest$ = "C:\FILE2.TXT"
Flags = 512 + 2048
Print (CopyFile=Source$,Dest$,Flags)

This example copies a source file named C:\FILE1.TXT to a destination file named C:\FILE2.TXT

The sum of the two flags tells Comet that the destination file is on the CometAnywhere client system (512), and to overwrite the destination file if the destination file already exists (2048). By default, the source file is on the local Comet system.

Suppose the flag value was changed to the following:

Flags = 1 + 2048

This would tell Comet that the source file is on the CometAnywhere client system (1), while the destination file (by default) is on the local Comet system. The destination file would be overwritten (2048).

Suppose the flag value was changed to the following:

Flags = 1 + 512 + 2048

In this case, the source and destination files are located on the CometAnywhere client system (1 and 512), and the destination file will be overwritten (2048).

Example 3:

Suppose you want to copy a file from a local Comet system to a CometAnywhere client system, and you want to synchronize the files (i.e., copy only if the source file is newer than the destination file).

Here are the flags that are used in the following example:

   2 = CometAnywhere is required (otherwise an error occurs)
  64 = Synchronize the files
 512 = Destination file is on CometAnywhere client system
1024 = Show progress bar
2048 = Overwrite existing file
4096 = Create directory

Source$ = "C:\FILE1"
Dest$ = "C:\DATA\FILE2"
Flags = 2 + 64 + 512 + 1024 + 2048 + 4096
Print (CopyFile=Source$,Dest$,Flags)

Example 4:

Suppose you need to copy a large file between a local Comet system and a CometAnywhere client system, but before copying you want to check and see if (a) the update is needed, and (b) if the user wants to perform the update now.

This is done in two steps. First, use the flag that checks to see if the update is required without copying the file (flag=256). If the update is required (as indicated by FuncError=21), then proceed with the copying (change the flags to copy the file).

Source$ = "C:\BIGFILE"  ! on local Comet system
Dest$ = "C:\BIGFILE"    ! on CometAnywhere client system

Flags = 256 + 512       ! 256 = don't copy file; just check to
                        !       see if updated is needed
                        ! 512 = destination is on
                        !       CometAnywhere system

Print (CopyFile=Source$,Dest$,Flags)
Input (0,ResultFmt)

AX$ = SUB(AX$,2,1) + SUB(AX$,1,1)   ! Flip the bytes around
DX$ = SUB(DX$,2,1) + SUB(DX$,1,1)   ! Flip the bytes around
FuncError = HexDec(AX$)             ! Function error code (decimal)
FileError = HexDec(DX$)             ! File error code (decimal)

! For unexpected values, convert to 2's complement signed integer
If (FuncError > 32767) FuncError = FuncError-65536
If (FileError > 32767) FileError = FileError-65536

If FuncError = 21
  Print "The file needs to be updated."
  Print "Do you want to update it now?"
  Input A$

  If A$ = "Y"
    Flags = 512 + 2048
    Print (CopyFile=Source$,Dest$,Flags)
    Input (0,ResultFmt)
    .
    .
    .
  EndIf
EndIf

Notes:

Depending on your situation you might try using the CUtlCpy utility which is released as part of the UTL directory. You can ENTER it from your app to easily accomplish a file copy or move.

To use a directory alias as the pathname for either of the filenames you can do it like this: FileName$ = "$(AliasNameHere)\" + thefilename$

Introduction

Language Structure

IB Statements

File System

Comet 32 Runtime

Index

(CopyFile)