8.5.33 Copy (copy files)

Purpose

Copies files.

In JP1/Script 07-50 or later, the command supports large files.

Syntax

Copy (OldFileName, NewPathName, [Option1], [Option2], [Option3], [Option4], [Option5], [ExceptFileName], [Option6] [, Option7])

Arguments

OldFileName

Set the name of the file to be copied (or moved). Write a character string or a variable that stores this value.

If the specified file name ends with an underscore (_), the file is assumed to have been compressed with the COMPRESS command, and will be expanded when copied.

If you did not specify a new file name in the NewPathName argument, the file name remains unchanged. The final character remains as an underscore (_). You can specify a wildcard in the file name.

NewPathName

Set the name of the folder or file at the copy (or move) destination. Write a character string or a variable that stores this value.

Option1 to Option5

Specify one or more of the following copy options:

Value	Meaning
VersionUp	Overwrite new files only. Compare the version information. If version information cannot be obtained, compare the dates of the files.
Overwrite	Overwrite all files.
NoOverwrite (from 05-10)	Do not copy files that already exist in the destination folder.
OverwriteOnly (from 05-10)	Copy only files that already exist in the destination folder.
Pile	Change extension values of existing files to unused values from .000 to .999 and copy files.
Backup (from 05-10)	Copy only files that have the archive attribute. After copying, clear the archive attribute of the source files.
Move (from 05-10)	Move the files. Do not copy them. You can specify Move in combination with VersionUp, Overwrite, or NoOverwrite. If a file already exists in the destination folder, the source file is moved according to the options you specify.
SubDirToo (from 05-10)	Copy the files and sub-folders, preserving the tree structure. This option does not copy any sub-folder that contains no files. You can specify SubDirToo with other copy options.
Trace (from 05-10)	Output the copied file names to the execution trace file. You can specify Trace with other copy options.
ErrSkip (from 05-10)	Continue copying regardless of any lock errors or access errors at a file being copied. You can specify ErrSkip with other copy options.

This value is optional. If you omit this value, Overwrite is assumed.

ExceptFileName (from version 05-10)

If the file name you set in OldFileName includes a file that you do not want to copy or move, specify that file name as a character string or as a variable that stores that value.

To set multiple file names here, write the file names as a semicolon- (;) delimited string or as a variable that stores this value.

In JP1/Script 06-00 and later versions, you can specify a one-dimensional array variable that stores strings representing multiple file names.

You can also specify a wildcard in ExceptFileName.

Option6 and Option7 (from version 06-51)

Specify either of the following optional values:

Value	Meaning
Security	Copy any security information attached to the file. You can specify Security with other copy options.
ErrSkip2 (from 06-71)	Continue copying regardless of any lock errors or access errors on a destination file. The number of files with skipped errors is stored in the _COPY_SKIP2_CNT_ reserved variable. You can specify ErrSkip2 with other copy options.

If you specify Security, execute the script file as a user who has administrator permissions. For details, see 1.8.2 Command behavior.

Description

The Copy command copies files according to the specified copy options. The command returns True on successful execution, or False if an error occurs.

The _COPY_RTN_ reserved variable stores one of the following as the copy result:

Value	Meaning
Overwrite	The files were copied without a file version check.
VersionUp	The files were copied after checking the file version.
Pile	The files were copied, and existing versions were preserved with a different extension.
Backup (from 05-10)	Only files with the archive attribute were copied, and the archive attribute was subsequently cleared.
Move (from 05-10)	The files were moved.
Skip	The files were not copied.

The number of files copied is stored in the _COPY_CNT_ reserved variable. The number of files that were not copied is stored in the _COPY_SKIP_CNT_ reserved variable.

Notes

• Take care when specifying a file or folder in the folder set in the environment variable ProgramFiles (normally the Program Files folder on the system drive) or WinDir (normally the Windows folder on the system drive). For details, see 1.8.2 Command behavior.

• You can configure access permissions when creating a copy destination file. In the following registry key, set the access permissions beforehand:

  However, you cannot configure access permissions if Security is specified for the copy options Option6 and Option7.

Registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Hitachi\JP1/Script\SPTX\Option

Value name

SecurityAttributesSucceed

Value datatype

REG_DWORD

Value

0: Access permissions are not set.

1: Access permissions are set to "Inherit access permissions from parent folders".

2: Access permissions are set to "Everyone: Full control".

If no value is set, or a value other than those above is set, the setting defaults to 0.

When the setting takes effect

The setting takes effect the next time the script file is executed.

Important note

The following types of file names are used in a Windows file system:

• Long file names with character strings specified by a user

• Short file names automatically generated by Windows (in 8.3 format)

Therefore, if a wildcard is specified in a file name in JP1/Script, the short file names automatically generated by the OS are also included. In addition, if a wildcard is not specified for a file name, the short file name of another file that exists in the same path as the specified file might be the same, resulting in operations being performed on files you did not intend.

Example

Dim inDir, outDir
inDir = _SCF_+"Inst\"
outDir = _SCF_+"Inst_Backup\"
Copy (inDir+"CTL3D32.DLL",outDir+"CTL3D32.DLL",VersionUp)
Copy (inDir+"SCRIPT.EX_",outDir+" SCRIPT.EXE",Overwrite)
Copy (inDir+"SCR*.*", outDir)
Copy (inDir, outDir, Backup, ErrSkip, , ,  _
,inDir+"*.EXE;"+inDir+"*.DLL")

JP1/Script version

Supported from JP1/Script 01-00.

To Page Top