Copy To Archive File (CPYTOARCF)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Copy To Archive File (CPYTOARCF) command copies and compresses file data and directory information into a single archive file. The information in the archive file can be decompresssed and copied back by running the Copy From Archive File (CPYFRMARCF) command. The archive file can also be decompressed on other operating system platforms by running any of the tools that can decompress an archive file.
Restrictions:
- You must have at least read (*R) authority to the file or directory to be archived. You must also have at least *R authority to each directory in the path name preceding that file or directory.
- You must have at least write (*W) authority to the directory where the compressed archive file will be written.
- The archive file specified for the To archive file (TOARCF) parameter must be in one of the following file systems: QOpenSys, "root", or a user-defined file system.
- If the From file or directory (FROMFILE) parameter is the path name for a library in the QSYS.LIB file system, all objects in the specified library must be files that can be read using integrated file system API procedures. Otherwise, error message CPFC805 is sent and the command fails.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| FROMFILE | From file or directory | Path name | Required, Positional 1 |
| TOARCF | To archive file | Path name | Required, Positional 2 |
| SUBTREE | Directory subtree | *NONE, *ALL | Optional |
| COMMENT | Comment | Character value, *BLANK | Optional |
| Top |
From file or directory (FROMFILE)
Specifies the file or directory to be archived. If the path name for a file is specified, the file data will be copied and stored in compressed form in the archive file specified for the To archive file (TOARCF) parameter. If the path name for a directory is specified, the archive file will contain the directory information and a compressed copy of the data in all files in the directory.
This is a required parameter.
- path-name
- Specify the path name for the file or directory to be archived. Wildcard characters are not allowed in the path name. The file or directory name can be an absolute path name or a relative name (to the current working directory).
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
| Top |
To archive file (TOARCF)
Specifies the archive file where the compressed data will be stored. The specified file must not already exist. Otherwise, error CPFC806 is sent and the command fails.
This is a required parameter.
- path-name
- Specify the path name for the archive file which will be created to store the compressed data. Wildcard characters are not allowed in the path name. The file name can be an absolute name or a relative name (to the current working directory).
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
| Top |
Directory subtree (SUBTREE)
Specifies whether or not to archive the files in any subdirectories, if the FROMFILE parameter specifies a directory.
- *NONE
- If the specified directory has subdirectories, files in the subdirectories are not archived.
- *ALL
- If the specified directory has subdirectories, files in all subdirectories will be archived.
| Top |
Comment (COMMENT)
Specifies the text to be included in the archive file.
- *BLANK
- Text is not specified.
- character-value
- Specify a comment to be stored in the archive file. Specify no more than 512 characters.
| Top |
Examples
Example 1: Archive a Single Large File
CPYTOARCF FROMFILE('/QSYS.LIB/MYLIB.LIB/BIGSAVF.FILE')
TOARCF('/MYDIR/MyArchiveFile.zip')
COMMENT('Archive of my large save file')
This command will copy the data from file BIGSAVF in library MYLIB and store the data in a compressed format in archive file MyArchiveFile.zip which will be created in directory MYDIR. The archive file will also contain the comment 'Archive of my large save file').
Example 2: Archive a Directory
CPYTOARCF FROMFILE('/DIR1/DIR2')
TOARCF('/MYDIR/dir2archive.zip')
SUBTREE(*NONE)
This command will copy the information for directory DIR2, including all the files in directory DIR2, and store the information in archive file dir2Archive.zip which will be created in directory MYDIR. If directory DIR2 contains subdirectories, none of the files in the subdirectories will be included in the archive file.
Example 3: Archive a Directory and its Subtree
CPYTOARCF FROMFILE('/DIR1/DIR3')
TOARCF('/MYDIR/dir3archive.zip')
SUBTREE(*ALL)
This command will copy the information for directory DIR3, including all the files in directory DIR3, and store the information in archive file dir3Archive.zip which will be created in directory MYDIR. If directory DIR3 contains subdirectories, all of the files in the subdirectories will also be included in the archive file.
| Top |
Error messages
*ESCAPE Messages
- CPFC801
- Parameter passed for files to be archived is not valid, reason code &1.
- CPFC802
- The size of the file &1 is greater than 4,294,967,295 bytes and cannot be compressed.
- CPFC803
- Value specified for archive name parameter is a directory.
- CPFC804
- Compressed size of the file is greater than 4,294,967,295 bytes. Compression not completed.
- CPFC805
- A file that is not suitable for compression has been encountered. Compression not completed.
- CPFC806
- Archive name &1 exists on the system.
- CPFC811
- Archive file not created.
| Top |