DosCopy
Description
Copies the source file or subdirectory to the destination file or subdirectory.
Syntax
#define INCL_DOSFILEMGR #include <os2.h> PSZ pszOld; /* Address of the ASCIIZ path name of the source file, subdirectory, or character device. */ PSZ pszNew; /* Address of the ASCIIZ path name of the target file, subdirectory, or character device. */ ULONG option; /* ULONG bit flags that define how the DosCopy function is done. */ APIRET ulrc; /* Return Code. */ ulrc = 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.
Bit Description
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
ulrc (APIRET) - returns
DosCopy returns one of the following values:
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
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:
- 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.
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.
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.
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
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;
}