DosCopy

Copies the source file or directory to the destination.

Syntax
DosCopy (pszOld, pszNew, option)

Parameters

 * pszOld (PSZ) - input: Address of the ASCIIZ path name of the source file, subdirectory, or character device.
 * Global file-name characters are not allowed.


 * pszNew (PSZ) - input: Address of the ASCIIZ path name of the target file, subdirectory, or character device.
 * Global file-name characters are not allowed.


 * option (ULONG) - input:ULONG bit flags that define how the DosCopy function is done.
 * 31-3 Reserved. These bits must be set to zero.
 * 2 - DCPY_FAILEAS (0x00000004) Discard the EAs if the source file contains EAs and the destination file system does not support EAs.
 * 0 - Discard the EAs (extended attributes) if the destination file system does not support EAs.
 * 1 - Fail the copy if the destination file system does not support EAs.
 * 1 - DCPY_APPEND (x00000002) Append the source file to the target file's end of data.
 * 0 - Replace the target file with the source file.
 * 1 - Append the source file to the target file's end of data.
 * This is ignored when copying a directory, or if the target file does not exist.
 * 0 - DCPY_EXISTING (0x00000001) Existing Target File Disposition.
 * 0 - Do not copy the source file to the target if the file name already exists within the target directory. If a single file is being copied and the target already exists, an error is returned.
 * 1 - Copy the source file to the target even if the file name already exists within the target directory.
 * Bit flag DCPY_FAILEAS can be used in combination with bit flag DCPY_APPEND or DCPY_EXISTING.

Return Code
0   NO_ERROR 2   ERROR_FILE_NOT_FOUND 3   ERROR_PATH_NOT_FOUND 5   ERROR_ACCESS_DENIED 26  ERROR_NOT_DOS_DISK 32  ERROR_SHARING_VIOLATION 36  ERROR_SHARING_BUFFER_EXCEEDED 87  ERROR_INVALID_PARAMETER 108 ERROR_DRIVE_LOCKED 112 ERROR_DISK_FULL 206 ERROR_FILENAME_EXCED_RANGE 267 ERROR_DIRECTORY 282 ERROR_EAS_NOT_SUPPORTED 283 ERROR_NEED_EAS_FOUND
 * ulrc (APIRET) - returns:DosCopy returns one of the following values:

Remarks
DosCopy copies all files and subdirectories in the source path to the target path. Global file-name characters are not allowed in source or target names. The source and the target can be on different drives.

If an I/O error occurs, DosCopy takes the following actions: Read-only files in the target path cannot be replaced by a DosCopy request. If such files exist in the target, and option bit flag DCPY_EXISTING is set to 1, any attempt to replace these files with files from the source will result in an error.
 * If the source name is that of a subdirectory, deletes the file being copied from the target path.
 * If the source name is that of a file to be replaced, deletes the file from the target path.
 * If the source name is that of a file to be appended, resizes the target file to its original size.

When copying is specified for a single file that has option bit flag DCPY_APPEND set to 1, the operation proceeds even if the file already exists and its option bit flag DCPY_EXISTING is set to 0. That is, option bit flag DCPY_EXISTING is significant only when replacing a file, not when appending a file.

If a device name is specified as the target, the source name must be a file, not a directory. When the request is issued, option bit flags DCPY_EXISTING and DCPY_APPEND are ignored.

File-object attributes, such as date of creation, and time of creation, are always copied from the source to the target; however, extended attributes (EAs) are not copied in every case. DosCopy copies EAs from the source to the target when creating a file or directory, or when replacing an existing file on the target; however, it does not copy them when appending an existing file or when copying files to an existing directory on the target. If the file system of the target does not support EAs, DosCopy ends and returns an error.

If the source file object contains a needed EA, and the destination file system does not support EAs, DosCopy fails regardless of the value of option bit flag DCPY_FAILEAS.

DosQuerySysInfo should be called by an application during initialization to determine the maximum path length allowed by the operating system.

Example Code
This example creates a backup copy of the file "CONFIG.SYS" with the new name "CONFIG.CPY", in the root directory, even if the new file name already exists. 
 * 1) define INCL_DOSFILEMGR  /* File Manager values */
 * 2) define INCL_DOSERRORS   /* DOS error values    */
 * 3) include 
 * 4) include 
 * 5) include 

int main(VOID) { UCHAR  achSourceString[80]  = "config.sys"; /* String to transform */ UCHAR  achEditString[80]    = "*.cpy";      /* Editing string */ UCHAR  achTargetString[200] = "";           /* Destination string buffer */ APIRET rc                   = NO_ERROR;     /* Return code */

rc = DosSetDefaultDisk(3);   /* Set drive to C: (1=A, 2=B, 3=C, ...)      */ if (rc != NO_ERROR) { printf("DosSetDefaultDisk error: return code = %u\n", rc); return 1; }

rc = DosSetCurrentDir ("\\"); /*  Set directory to root */ if (rc != NO_ERROR) { printf("DosSetCurrentDir error: return code = %u\n", rc); return 1; }

/* Transform "CONFIG.SYS" using "*.CPY" to "CONFIG.CPY" */

rc = DosEditName(1, achSourceString, achEditString, achTargetString, 200);

if (rc != NO_ERROR) { printf("DosEditName error: return code = %u\n", rc); return 1; }

/* Copy contents of CONFIG.SYS to the backup file */

rc = DosCopy(achSourceString,            /* Name of file to be copied    */                achTargetString,             /* Name of the target file      */                DCPY_EXISTING);   /* Copy even if target file already exists */

if (rc != NO_ERROR) { printf("DosCopy error: return code = %u\n", rc); return 1; } else printf ("Backup file %s created.\n", achTargetString); return NO_ERROR; } 

Related Functions

 * DosMove
 * DosQueryCurrentDisk
 * DosQuerySysInfo
 * DosSetDefaultDisk