COPYFILE
8.5E
The COPYFILE instruction copies a source file to a destination file. The instruction uses the following format:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Where in format (1):
label
Optional. A Program Execution Label.
source
Required. A Character String Variable or literal that specifies the file that is copied.
sep
Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.
dest
Required. A Character String Variable or literal that specifies the destination file name.
Where in format (2):
label
Optional. A Program Execution Label.
source
Required. A Character String Variable or literal that specifies the file that is copied.
sep
Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.
dest
Required. A Character String Variable or literal that specifies the destination file name.
retcount
Required. A Numeric Variable that returns the number of blocks required to complete the transfer using format (2) which invoices enhanced copyfile operations.
mode
Optional. A Numeric Variable that specifies a value as defined below.
blocksize
Optional. A Numeric Variable that specifies the block size used when transferring data.
key
Optional. A character variable that contains a user specified key string. This key must be composed of no more than thirty-two (32) hexadecimal digits. (9.3A)
Flags Affected: ZERO,OVER
Note the following:
The first syntax above (1) is a Simple Mode COPYFILE and the second syntax (2) is Enhanced Mode. The keywords MODE, BLOCKSIZE, DECRYPT, and ENCRYPT are only used for Enhanced COPYFILE operations.
COPYFILE allows the following transfers:
|
From |
To |
|
Local |
Local |
|
Sundm |
Sundm |
|
Local |
Sundm |
|
Sundm |
Local |
|
PLBServe |
PLBClient |
|
PLBClient |
PLBServe |
|
PLBClient |
Sundm |
|
Sundm |
PLBClient |
|
PLBClient |
PLBClient |
The {source} parameter contains the existing file name. An IP address can be appended to this file name to indicate that the file is located at the Sunbelt Data Manager as identified by the {ip address}.
When running under the PL/B Application Server, the first character of the file name has special meaning:
|
First Character |
The file ... |
|
! (exclamation mark) |
resides on the client rather than the server. |
|
? (question mark) |
should be obtained from the cache or from the server and placed in the cache. |
|
* (asterisk) |
should be obtained from the in-memory cache or from the server and placed only in the in-memory cache. |
The {dest} parameter contains the file name for the destination of the copy operation. A IP address can be appended to this file name to indicate that the destination file is located at the Sunbelt Data Manager as determined by the ip address. In addition, an exclamation mark (!) preceding the {dest} file name indicates that the destination file is located at a PLBCLIENT workstation. A leading exclamation mark (!) is ignored for all runtimes except for PLBSERVE.
If the {retcount} parameter is present, the COPYFILE executes as an Enhanced Mode instruction that may require the use of the following instructions to complete or cancel the data transfer (9.1A):
|
Instruction |
Purpose ... |
|
Copies additional data blocks from the {source] file to the {dest} file when the {retcount} value returned from the COPYFILE instruction is non-zero. | |
|
Cancels the data transfer from the {source} file to the {dest} file | |
|
Determines whether an enhanced COPYFILE is currently active. |
When the {retcount} is specified, the {source} and {dest} can include a leading exclamation point (!) that indicates that the file is located at the PLBCLIENT workstation.
When the {retcount} is specified, the {source}
and {dest} data can have a
|{ip/URL}:port
appended to the file name to indicate that the file is located at the SUNDM Data Manager.
The {mode} numeric value has the following bit definitions that control various operations for the COPYFILE instruction:
|
Value |
Action ... |
|
0x1 |
Use update mode. In this mode, COPYFILE analyzes the {source} file data and compares it with the {dest} file data. Only the data blocks that differ are transferred. |
|
0x2 |
Open the {source} file in a shared mode that allows other applications to have the file opened while the COPYFILE and COPYNEXT operations are executed. If this mode is not used, {source} is opened in an exclusive mode. |
|
0x4 |
The {dest} file is not deleted when the COPYFILE operation is canceled. If this mode is not used, the default action is to delete {dest}. |
|
0x8 |
The COPYFILE operation is not canceled when a program error occurs. If this mode is not used, the default action is cancel the operation when an error occurs. |
|
0x10 |
The {dest} file attributes are bypassed and the file is always overwritten. If this mode is not used, an IO error occurs if an existing {dest} file is write protected. |
|
0x20 |
The {source} file data is appended to the end of the {dest} file. If this mode is not used, {dest} is overwritten. |
|
0x40 |
Use a maximum of thirty (30) seconds to receive a message from the Sunbelt Data Manager. (9.3B) |
|
0x80 |
Use a maximum of sixty (60) seconds to receive a message from the Sunbelt Data Manager. (9.3B) |
|
0xC0 |
Use a maximum of ninty (90_ seconds to receive a message from the Sunbelt Data Manager. (9.3B). |
|
0x100 |
The {dest} file attributes are not reset when the update mode is being used unless the {dest} file data is changed and/or the {dest} file attributes are different than the {source} file. This no touch mode bit is ignored unless the update mode is also being used. |
The {size} parameter allows specification of a transfer data block size for special cases. If the {size} is not specified, the default size is 8192 bytes. When the {size} is specified, the smallest allowed value is 4096 bytes and there is not an upper limit. {size} is always rounded up to the nearest 1024 byte boundary.
The COPYFILE, COPYNEXT, COPYCANCEL, and COPYSTATUS instructions allow direct control over the data transfer operation. This implementation can be used in both a Windows and Linux OS environment and has the capability to give feedback and control.
When a COPYFILE uses the {retcount} that requires COPYNEXT instructions to complete the data transfer, a second COPYFILE instruction causes an I72 error to occur if the previous COPYFILE is not completed or canceled.
The ZERO flag is set when the COPYFILE operation completes successfully.
The OVER flag is set when the block count that is stored into the {retcount} variable is too large for the variable defined.
The runtime keyword PLB_COPYFILEBUFFSZ identifies the buffer size used when transferring a file to or from the Sunbelt Data Manager. When copying files to or from the PLBCLIENT workstation and the PLB Application Server server, the message size is not user controlled. The file is sent as a single message.
Both the {source} and {dest} file names must be specified. The first operand is the source file name and the second operand is the destination file name. If a character string variable is specified for either name, the logical string is used. If the {source} or {dest} operand is NULL, the ZERO flag is cleared and no copy operation is performed.
If the {dest} file does not exist, it is created. If the {dest} file already exists before the copy operation then it is overwritten.
If an error occurs while opening, creating, or copying the files, an I72 IO error will occur. Error subcodes provide additional information.
Macro file names and Datapoint name formats are supported.
The COPYFILE verb obeys the runtimes PLB_FNC keyword if present. In addition, path characters will automatically be converted to the proper operating system characters.
The DECRYPT keyword decodes the data read from the {source} file. The ENCRYPT keyword encodes the data written to the {dest} file. (9.3A)
The ENCRYPT and DECRYPT key string are the same value as defined for the ENCRYPT instruction.
When the {dest} file is written using the ENCRYPT key with a specific BLOCKSIZE, the output file can only be read and decrypted using the exact same key specified in the DECRYPT keyword with the same BLOCKSIZE.
A one second variance can occur for the last write modification time when an enhanced
COPYFILE instruction copies a file from a NTFS file system to a FAT32
file system.
The problem is that the FAT file system has a granularity of two
seconds for the last write modification time. This restriction exists because the FAT file system format
for a file time has been encoded into a sixteen bit value to save space. The seconds field for the file
time is limited to be a four bit field that is multiplied by two to get the final number of seconds.
This means that a file time cannot be set to an uneven number of seconds.
There is no work around to this issue because the FAT32 file system
has this limitation by design.
When the enhanced COPYFILE instruction accesses
a Sunbelt Data Manager, a default maximum receive timeout of five (5) seconds is used by the Data Manager.
The default five second timeout may not be sufficient when larger block sizes are used. Therefore, the
five second default is used for a block size of 8192 or smaller and a twenty (20) second default is used
for a block size of 32768 or larger. When the block size is greater than 8192 and less than 32768, the
default time is calculated by the following expression:
timeout = blocksize * 20 / 32768
If the Sunbelt Data Manager keyword named 'DM_USELONGTIMEOUT=on' is used, the default receive timeout
of 180 is used when the block size is 8192 or smaller.
The COPYFILE {source} and {dest} names must contain a fully qualified file name including a path. Otherwise, the {source} must exist in the current working directory of the runtime, client, or Data Manager before the file can be found and used. Likewise, the {dest} is output to the current working directory runtime, client, or Data Manager when a path is not specified.
When using the PL/B Web Server, only server side copies are supported. In addition, the COPYFILE instruction can copy files from a client browser system that have been selected by an end-user 'File Upload' selection dialog. See the BUTTON 'BUTTONTYPE=$FILEINPUT' property for details on allowing client browser side file selections by an end-user. The {source} file name contains a leading exclamation mark (!) to indicate that the source file is located on the client browser system. The {source} must be the file name returned by the BUTTON 'GetFileItem' method. (9.7A)
When using the PL/B Web Server, a special COPYFILE {source} file name syntax has been implemented to provide a file array index. The file array is created when an end-user selects multiple files to be uploaded using the 'File Upload' selection dialog. In this scenario, a file array index is required to identify which file is to be copied. The file array index syntax is described as follows:
{source} file array syntax:
Where:
Example of two files selected by end-user:
Note that in some client browser environments there is no underlining file directory structures like for an IPAD. In this case, selected files by an end-user can be returned by the client browser with the same filename which is not unique for each file name selected.
When using the PWS server, the COPYFILE instruction cannot be used to copy files directly to a client browser. See the CLIENT object method named 'Open' for information on downloading a file to a client browser
When the COPYFILE syntax format (1) is used in a program executing using the 'plbserve' runtime, there is an approximate file size limit of 16MB when a file is being transferred to or from the 'plbclient'. This 16MB limit only applies as shown in these examples:
In this case, a file named 'serverfile.ext' is being copied from the server to the client \.
In this case, a file named 'clientfile.ext' is being copied from the client to the server.
See Also: Example Code, System Interface Instructions
|
|