DosCopy

Description

Copies the source file or directory to the destination.

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;
}

Related Functions

• DosMove
• DosQueryCurrentDisk
• DosQuerySysInfo
• DosSetDefaultDisk