copy_file |
Purpose
This command copies the contents of a file or set of files to another file or set of files.
Display Form
|
Command Line Form
source_file destination] -pack] -parallel] -truncate] -delete] -keep_dates] -keep_acl] -no_keep_extents] -brief] -keep_safety_switch] -keep_audit] -pacing pacing_value] -avoid_fragmentation] Arguments
 source_file |
Required |
The name or star name of the file or files to be copied.
destination |
The path name of a file or existing directory into which the command is to copy the files. A file name can be a star name; if the character strings that replace the asterisks cause a destination file name to exceed the maximum length of a file name, the leftmost characters beyond that limit are truncated. If you specify a directory, the command copies the files into the directory. If you specify a file name, the command copies the file into the current directory and names the copy destination. By default, the command copies the files into the current directory without changing their names, as long as the current directory is not the source directory.
-pack |
 |
Packs a file being copied and discards deleted records. You cannot specify -pack if the file to be copied has separate-key or item indexes, or if the file is a queue or pipe file. By default, the command does not pack the file.
| -parallel |
|
Used with the -pack argument; when both arguments are set to yes, the command simultaneously rebuilds all indexes for each file being copied. By default, the command has no effect.
-truncate |
|
Truncates an existing destination file before copying an input file to it. If you specify -truncate and the file named by destination is an existing file, then the command preserves the file's attributes and indexes but deletes its contents (that is, its data records). Any embedded key indexes previously defined on the destination are rebuilt from the new records. However, if the file named by destination does not exist, the command creates an output file with the same organization, maximum record length, and allocation size as the file to be copied but creates no indexes on the new file. If you specify -truncate, the file is packed regardless of the value of the -pack argument. You cannot specify -truncate if the file to be copied has separate-key or item indexes, or if the file is a queue or pipe file. By default, -delete determines what happens if there is a name conflict.
-delete |
|
Deletes a file if it has the same path name as the destination path name of the copied file. By default, the command asks you whether to delete a file that has a conflicting path name.
-keep_dates |
|
Assigns to the new file the creation date, modification date, and last-used date of the file being copied. The initial last-saved date of all objects is never. By default, the current time of the copy is used for the creation date, modification date, and last-used date.
Note: If you have set an expiration date for source_file, this command removes the expiration date from the file specified by destination, even if you specify -keep_dates. For more information, see the description of the set_expiration_date command.
-keep_acl |
|
Keeps the access control list with the file. If you specify -keep_acl, the default access of the directory is not saved; only the specific access control list on the file (if one exists) is saved. By default, access is not moved with the file.
-no_keep_extents |
|
Specifies that the command does not copy the source file's extent characteristics to the target file. By default, the target file has the same extent characteristics as the source file, which means that if the source file is extents-based, the target file will also be extent-based with the same extent size and, in the case of statically-allocated extents (SAE) files, with the same number of blocks initially allocated. This argument is meaningless for non-extents files. See the Explanation section for more information about how extents are copied.
Specify this argument with the -truncate argument to migrate non-extents-based files to dynamically-allocated extents (DAE) files (that is, files that allocate and initialize extents as the file grows). See the Explanation section for more information about DAE files.
-brief |
|
Suppresses the display of each file name that matches a star name before the file is copied. By default, the command displays the name.
| -keep_safety_switch |
|
Keeps the safety switch of files being copied if the safety switch for a file is set on. By default, a file's safety switch is off.
| -keep_audit |
|
Specifies that the new file retains the audit options of the source file. By default, the command does not retain the audit options of the source file.
-pacing pacing_value |
Determines the pacing behavior of the copy operation. Possible values are disk_type (the default value), yes, and no. Pacing occurs during the copy operation if either of the following is true:
If you specify no, pacing does not occur, regardless of the type of the source or target disk. Only privileged users can specify the no value. See the Explanation section for more information about pacing.
| -avoid_fragmentation |
|
Allocates the target file in nonfragmented portions of the disk, if possible. This means that if N contiguous blocks are available on the disk, they are used first, then N/2, and so on, where N starts at 256. By default, the target of copy_file is not allocated in such a way as to avoid fragmentation.
The command uses noncontiguous blocks as long as disk space is available. Therefore, the success of producing a defragmented file (that is, a file with few gaps between blocks) depends on the allocation patterns currently existing on the disk. (Note that you can use software tools to analyze allocation patterns.) This affects striping on multi-disk volumes, in that N blocks are allocated in each member. The resulting file has the same attributes as source_file. This argument affects only non-extent files, since extent files are always allocated based on their extents. Also, this argument has no affect if you specify -truncate and the target file exists. In that case, allocation is dictated by the attributes of the existing target file.
Explanation
The copy_file command copies the contents of a file or set of files to another file or set of files. If the source is a pipe file, the command creates an empty pipe file.
The copy_file command assigns ownership of any copied files to the user name of the person doing the copying.
Note: The display_file_status command shows index names in order of the index address inside the file. This order may change if the file is specified as the subject of the copy_file, move_file, restore_object, or save_object command.
Specifying the Source File and Destination
You can give a star name for source_file and destination. Star names function in the following manner.
- An asterisk can be in any position in a star name.
- In a path name, a star name can be in the final name position only.
- When the operating system matches non-star names to a star name, each asterisk represents zero or more characters.
- A name cannot contain consecutive asterisks; there must always be an intervening character.
The command also allows the destination to match the name of the source.
If you omit the destination argument, the copy_file command copies all of the files whose names match source_file into your current directory, using the same file names. If the files to be copied already reside in your current directory, the operating system displays this message.
Both the source and destination name the same object.
If you give a directory name for the destination argument, you can also give a star name for source_file that matches more than one file name. The copy_file command copies all the files whose names match the source_file argument into the specified directory using the same file names.
If you give a path name for destination that is not the path name of an existing directory, the copy_file command assumes that destination is a file name. If this file name is not a star name, then source_file must match only one file path name. In this case, the copy_file command copies the file and names the copy as specified in destination. Unless you specify this last argument, the copy retains its name.
If you specify a link for source_file and specify a star name for destination, be careful that the link does not point to a file that is identified by the star name, or the command may determine that source_file and destination are identical. For example, if you have a subdirectory called subd, a link called xxx to subd>yyy, and two files in subd called xxx and yyy, the copy_file command behaves as follows when you specify source_file as a link and destination as a star name.
copy_file xxx subd>* Copying %sys#m1>Sales>Joe_Smith>xxx to %sys#m1>Sales>Joe_Smith>subd>xxx. %sys#m1>Sales>Joe_Smith>subd>xxx already exists. Delete the old one? (yes, no) n
The command does not expand the link and uses the unexpanded link name to resolve the star name to subd>xxx. The command behaves in a similar fashion if you specify source_file as a link and destination as a directory name.
copy_file xxx subd %sys#m1>Sales>Joe_Smith>subd>xxx already exists. Delete the old one? (yes, no) n
Specifying the -pack and -parallel Arguments
When you specify the -pack argument, all indexes are re-created, regardless of file organization; however, in some cases, the resulting indexes are empty. If an index that is re-created is large, temporary files are required for sorting. The temporary files are created in the process_dir directory (if the user has access) or the current working directory.
If you specify the -pack argument, copy_file attempts to discard deleted records. However, you cannot delete a record from a fixed file that has no record index. If you ask the operating system to delete a record from such a file, it updates embedded-key indexes and deleted-record indexes appropriately, but does not actually delete the record. Therefore, such records can reappear if their file is packed. To prevent this, copy_file ignores records that consist entirely of hexadecimal FF when packing a fixed file without a record index.
The -parallel argument is used with the -pack argument; when both arguments are set to yes, the command simultaneously rebuilds all indexes for each file being copied, enabling the specified files to be packed and copied faster. The default value for the -parallel argument is no, in which case, the command rebuilds the indexes individually. The -parallel argument has no effect if the -pack argument is set to no.
You cannot copy a transaction-protected file if you specify the -pack argument. See s$copy_file in the OpenVOS Subroutines manuals for more information.
Specifying the -truncate Argument
If you specify the -truncate argument and the destination file is an existing fixed file, all records in the source file must have a length equal to the fixed record size of the destination file.
Warning messages are displayed if indexes are not copied or rebuilt. If you specify -truncate and the target file exists, copy_file checks the indexes and displays a message for each embedded index that is not on the target file and for each non-embedded index. If you specify -truncate and the target file does not exist, copy_file displays a message for each index that is on the source file. If you specify -no_truncate and -pack, copy_file displays a message for each embedded-separate-key index that is on the source file.
You cannot copy a transaction-protected file if you specify the -truncate argument. See s$copy_file in the OpenVOS Subroutines manuals for more information.
Copying Files with Extents
By default, when you copy a file, the extent allocation is copied.
Statically-allocated extents (SAE) files cannot be created across the network and therefore cannot be copied, unless the target file exists and you specify the -truncate argument. If you want to copy such a file across the network and the target file does not exist, you must specify the -no_keep_extents argument. In this case, the newly created file is a non-extent file. You cannot copy an SAE extended-sequential file across the network in this way, because this type of file is always extent-based. To duplicate an SAE file on another module, create an identical empty file with the create_file or clone_file command while running on that module, and specify the -truncate argument of copy_file.
If you specify -no_keep_extents for a dynamically-allocated extents (DAE) file, the newly created file is a non-extent file, with two exceptions:
- If you specify -no_keep_extents for an extended-sequential file, the extent value is reduced to the maximum record size specified when the file was created, or 8 if that is larger.
- If you specify -no_keep_extents for a 64-bit stream file and the size of the file requires extents, the value is the minimum needed to hold the current contents of the source file.
- If you specify -no_keep_extents for a flex 64-bit stream file and copy that file to a module running a release prior to OpenVOS Release 18.x, and if a non-extent file is too small to hold the contents of the source file, the new file is created with large enough extents to hold the contents.
If you copy a sparse 64-bit stream file that has grown and that may contain blocks containing all binary zeros, copy_file may eliminate those blocks in destination, which means that the resulting file may become smaller.
You can copy 64-bit stream files that have not grown larger than 2 GB to modules running releases prior to OpenVOS Release 17.2.x. These files become normal stream files on the module running the earlier release. You can copy the files regardless of whether your current module is running the earlier release or Release 17.2.x or later.
If your current module is running an earlier release and you copy a 64-bit stream file to a module running Release 17.2.x, the file becomes a normal stream file, even on the module running Release 17.2.x.
If you copy a flex 64-bit stream file to a module running OpenVOS Release 17.2.x, the destination file is a normal (that is, non-flex) 64-bit stream file with no extents as determined by the module default (normally, 8).
A 64-bit stream file that is 2 GB or greater cannot be copied to a release prior to OpenVOS Release 17.2.x; any attempts to do so results in an error message. This is also true if you execute the copy_file command running on an older release. However, you can copy sparse files that are less than 2 GB, except that the resulting normal stream file will not be sparse and therefore may require far more disk space (and more time to copy).
To migrate a non-extent-based file to a DAE file, create an empty DAE file, and then specify the copy_file command with the destination and -truncate arguments (destination should be the empty DAE file). This procedure copies the data from source_file into destination while keeping the extent attributes of destination intact. For more information about DAE files, see the description of the create_file command.
Using the Safety Switch
When a file's safety switch is on, the file is protected against operations that could destroy or damage it. For additional information about the safety switch, see set_safety_switch later in this manual.
Copying RAM Files
If a non-empty RAM file is copied, the newly created file does not have RAM file usage. This allows you to copy a RAM file while it is activated in order to capture its contents; when a RAM file is deactivated, its contents are discarded. If the target of copy_file is a RAM file, it would be truncated immediately after being copied. Specifying an existing RAM file as the target and using the -truncate or -pack argument is not allowed, since the result of the copy would always be an empty file.
When a server queue has RAM usage, the new server queue retains RAM usage and is thus always empty. The contents of a server queue are never copied.
If a RAM file's containing directory is being copied or moved, the RAM file in the newly created directory retains its RAM usage and is always empty. See the description of set_ram_file for more information about RAM files.
Using the -pacing Argument
Pacing prevents the copy operation from dominating the disks, and it allows other processes to access other files on the disks involved (both source and target) without long delays. Pacing is relevant only to block-mode copies; the value of the -pacing argument is ignored for record-mode copies (that is, those for which the -truncate or -pack argument has been specified).
Access Requirements
You must have read access to a file that you want to copy, status access to the source directory, and modify and, by default, write access to the directory that is to contain the copied file. You will be given write access to the destination.
Examples
The following three examples show a variety of ways that you can invoke the copy_file command.
Example 1.
To copy all OpenVOS COBOL source modules in the current directory into the directory >east>Clark, use this command.
copy_file *.cobol >east>Clark
The object names of the copies are the same as the original files.
Example 2.
The following command copies all OpenVOS COBOL source modules in the current directory into the directory >east>Clark>save and changes the suffix .cobol to the suffix .old for each file copied.
copy_file *.cobol >east>Clark>save>*.old
Example 3.
This command makes a copy of the file make_reports.pm in the current directory, names the copy make_reports.old.pm, and puts the copy in the current directory.
copy_file make_reports.pm make_reports.old.pm
When you give the copy a different name from the original (as in this example) you can copy only one file; that is, destination must be the path name of a file.
Related Information
See also the command descriptions of compare_files, copy_dir, create_file, delete_file, display_file_status, locate_files, move_dir, move_file, set_file_allocation, set_ram_file, set_safety_switch, and truncate_file.