FCOPY Function
Copies records from one fileref to another fileref, and returns a value that indicates whether the records were successfully copied.
| Category: | SAS File I/O |
| Restriction: | This function is not valid on the CAS server. |
Table of Contents
Syntax
Required Arguments
'fileref-1'
specifies an existing fileref from which records are to be copied.
'fileref-2'
specifies an existing fileref to which records are to be copied.
Details
Values That Are Returned by the FCOPY Function
FCOPY returns these
values:
-
a value of 0 if records were copied without errors or warnings
-
a positive value if an error occurred
-
a negative value if a warning was issued
You can use the SYSMSG
function to retrieve error or warning messages, and you can use the
SYSRC function to retrieve the return code.
Using Macro Variables with the FCOPY Function
The following macro
variables provide information for the FCOPY function:
-
The &SYSCC and &SYSERR macro variables are set if FCOPY writes an error or warning message to the log.
-
The &SYSCC and &SYSERR macro variables are not set if FCOPY returns a warning return code and there is no log output from FCOPY.
-
The &SYSERRORTEXT macro variable is set if FCOPY writes an error message to the log.
-
The &SYSWARNINGTEXT macro variable is set if FCOPY writes a warning message to the log.
Setting a Logical Record Length for a Text File
The
default logical record length for reading from or writing to external
files is 32,767 bytes. The maximum logical record length is 1 gigabyte.
Text files have a data stream that consists of an unstructured sequence
of bytes. A delimiter, such as a carriage-control character, controls
the length of the data stream, and divides the information in the
data stream into records. If the length of a record is greater than
32,767 bytes, you must define the logical record length of your records
so that your data is not truncated when FCOPY copies the text file.
To set the logical record length to a larger value, use the LRECL=
system option in an OPTIONS statement, or the LRECL= option in a FILENAME
statement.
For an example that
shows how to set an LRECL value, see Diagnostic Messages.
Tip
Selecting an arbitrarily large
value for the LRECL= option can result in excessive use of memory,
which can degrade performance.
Examples
Example 1: Copying a Text File
Setting the MSGLEVEL=
system option to I causes informational messages from FCOPY to be
written to the log.
/* Set MSGLEVEL to I to write messages from FCOPY to the log. */
options msglevel=i;
filename src 'source.txt';
filename dest 'destination.txt';
/* Create an example file to copy. */
data _null_;
file src;
do i=1, 2105, 300312, 400501;
put i:words256.;
end;
run;
/* Copy the records of SRC to DEST. */
data _null_;
length msg $ 384;
rc=fcopy('src', 'dest');
if rc=0 then
put 'Copied SRC to DEST.';
else do;
msg=sysmsg();
put rc= msg=;
end;
run;
SAS writes the following
output to the log:
INFO: The source fileref SRC for the FCOPY function is:
Filename=your-source-file,
RECFM=V,LRECL=32767,File Size (bytes)=121,
Last Modified=15Aug2012:11:21:39,
Create Time=15Aug2012:09:13:38
INFO: The destination fileref DEST for the FCOPY function is:
Filename=your-destination-file,
RECFM=V,LRECL=32767,File Size (bytes)=0,
Last Modified=15Aug2012:11:21:39,
Create Time=15Aug2012:09:13:39
Copied SRC to DEST.
Example 2: Copying a Binary File
This example copies
a binary file from one directory to another. Setting the MSGLEVEL=
system option to I causes informational messages from FCOPY to be
written to the log.
/* Set MSGLEVEL to I to write messages from FCOPY to the log. */
options msglevel=i;
filename src 'raises.xlsx' recfm=n;
filename dest 'raises-2012.xlsx' recfm=n;
/* Create an example file to copy. */
data _null_;
file src;
do i=1, 2105, 300312, 400501;
put i:words256.;
end;
run;
data _null_;
length msg $ 384;
rc=fcopy('src', 'dest');
if rc=0 then
put 'Copied SRC to DEST.';
else do;
msg=sysmsg();
put rc= msg=;
end;
run;
SAS writes the following
output to the log:
INFO: The source fileref SRC for the FCOPY function is:
Filename=your-source-file,
RECFM=N,LRECL=256,File Size (bytes)=117,
Last Modified=15Aug2012:12:49:18,
Create Time=15Aug2012:12:42:00
INFO: The destination fileref DEST for the FCOPY function is:
Filename=your-destination-file,
RECFM=N,LRECL=256,File Size (bytes)=0,
Last Modified=15Aug2012:12:49:18,
Create Time=15Aug2012:12:42:01
Copied SRC to DEST.
Example 3: Diagnostic Messages
This example shows diagnostic
messages that result from the FCOPY function when the MSGLEVEL= system
option is set to I. The file to be copied from has a record length
of 256 bytes, and the file to be copied to has a record length of
5 bytes. Warning messages identify that the file was truncated.
filename src 'source.txt' lrecl=256; /* Create example file to copy. */ data _null_; file src; do i=1, 2105, 300312, 400501; put i:words256.; end; run; /* Make LRECL for DEST short, to force output truncation. */ filename dest 'destination.txt' lrecl=5; /* Set MSGLEVEL to I to write messages from FCOPY to the log. */ options msglevel=i; data _null_; rc=fcopy('src', 'dest'); run;
SAS writes the following
output to the log:
INFO: The source fileref SRC for the FCOPY function is:
Filename=your-source-file,
RECFM=V,LRECL=256,File Size (bytes)=121,
Last Modified=15Aug2012:15:14:38,
Create Time=15Aug2012:09:13:38
INFO: The destination fileref DEST for the FCOPY function is:
Filename=your-destination-file,
RECFM=V,LRECL=5,File Size (bytes)=0,
Last Modified=15Aug2012:15:14:38,
Create Time=15Aug2012:09:13:39
WARNING: 3 records were truncated when the FCOPY function wrote to fileref DEST.
WARNING: To prevent the truncation of records in future operations, you can
increase amount of space needed to accomodate the records by using
the LRECL= system option or the LRECL= option in the FILENAME statement.
Copyright © SAS Institute Inc. All Rights Reserved.
Last updated: March 16, 2017