The COPY/APPLICATION_PROTOCOL=FTAM command accesses the FTAM
copying utility, which copies files between FTAM systems within
an OSI network. The copying utility operates on a combination of
local and remote FTAM or on remote files only. Using this command,
you can:
o Copy an input file to an output file
o Concatenate two or more input files into a single output file
If only local files are specified, the COPY/APPLICATION_
PROTOCOL=FTAM utility passes the command to the RMS copying util-
ity. In that case, all command qualifiers operate in the standard
manner documented in OpenVMS help.
1 – Format
COPY/APPLICATION_PROTOCOL=FTAM [/qualifier(s)] input-file-spec
[,...] output-file-spec
The following table describes the variables in this format state-
ment:
__________________________________________________________________
Variable Explanation
__________________________________________________________________
/qualifier An RMS qualifier of the COPY command. For a
full description of supported qualifiers, see
individual qualifier subtopics; for a summary,
see the "Qualifier" subtopic.
input-file-spec A file specification of an input (source) file,
which can be either local or remote.
[,...] A file list containing file specifications for
one or more additional input files. Within a file
list, you must precede each additional file spec-
ification with either a comma (,) or a plus sign
(+) with or without a space. To end an input file
list, either omit the comma or plus sign between
the last input file specification and the output
file specification or press <RET>.
Input files can be from the same or different
FTAM systems.
output-file- The name of an output file. Because FTAM
spec always creates only one output file, the
COPY/APPLICATION_PROTOCOL=FTAM command accepts
only one output-file specification.
For local output files, copying a file to a local
directory is controlled by the same rules that
control the RMS copying utility. If you specify
no directory, the utility places the output file
in your default directory. If you specify another
local directory for which you have write privi-
leges, the utility places the output file in that
directory.
For remote output files, always specify the file
designation. For information on where a remote
FTAM system places an output file that is created
remotely using FTAM, see the documentation of the
remote system.
__________________________________________________________________
2 – Wildcards
Wildcards provide a method for generalizing a file designation to
encompass a set of local files. Standard DCL wildcard techniques
work for both local (RMS) files and remote files for those remote
FTAM systems that support the NBS-9 document type. If using
wildcard techniques with remote FTAM systems does not work, you
should complete the file designation.
The supported wildcard characters include an asterisk (*) to
represent a text string, a percent sign (%) to represent a single
character, or empty brackets ([ ]) to represent all files in the
local default RMS directory.
3 – Third-party-copying
The COPY/APPLICATION_PROTOCOL=FTAM utility supports copying a file
from one FTAM application to another by using the local OpenVMS
system as an intermediary (third-party copying). However, all
constraints for files affect both input and output files, and use
of wildcards or multiple file specifications is not possible.
4 – Qualifiers
The availability of COPY command qualifiers for the COPY/APPLICATION_
PROTOCOL=FTAM command varies for local and remote files. For local
FTAM (RMS) files, the FTAM copy utility supports most of the DCL
COPY command qualifiers. For remote files, only a few of those
qualifiers are supported.
For COPY command qualifiers used with local files, the FTAM copy-
ing utility generally implements standard RMS default values and
actions. The exceptions are indicated by the term "nonstandard" in
the qualifier descriptions.
Any COPY command qualifier that is unlisted here is accepted as
a null qualifier, which produces no effect on the outcome of the
COPY command.
4.1 /ALLOCATION
/ALLOCATION
/ALLOCATION=n
Qualifier type: Output file qualifier
Supported file Local and remote
types:
This qualifier sets the initial allocation for the output file to
the number of 512-byte blocks specified by n.
Default value: Size of input file
4.2 /BACKUP
/BACKUP
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to the dates of their most
recent backup. It is relevant only with /BEFORE or /SINCE and is
incompatible with /CREATED, /EXPIRED, and /MODIFIED.
Default value: Creation date
4.3 /BEFORE
/BEFORE
/BEFORE=time
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only those files that are dated before
the time specified using absolute time (a specific date and/or
time or a keyword - TODAY, TOMORROW, or YESTERDAY) or combination
time (absolute plus delta time). Associated qualifiers: /BACKUP,
/CREATED, /EXPIRED, or /MODIFIED. For information on specifying
absolute and delta time, see the "OpenVMS User's Manual".
Default value: Today
4.4 /BY_OWNER
/BY_OWNER
/BY_OWNER=uic
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only files whose user identification code
(UIC) matches the specified UIC.
Default value: UIC of current process
4.5 /CHARACTER_SET
/CHARACTER_SET=
This qualifier specifies which character set the file data belongs
to, and instructs FTAM to encode the data accordingly. For example,
to copy file data of the Japanese character sets Kanji and Katakana,
the user must supply the CHARACTER_SET= qualifier with the value
JP_INTAP2.
Default value: No character set specified
4.6 /CONCATENATE
/CONCATENATE
/NOCONCATENATE
Qualifier type: qualifier
Supported file Local (RMS) (/CONCATENATE only) and remote files
types:
This qualifier controls whether multiple input files create corre-
sponding multiple output files or create a single output file
containing the concatenated contents of all the input files.
Concatenation, which is the default, involves combining multi-
ple input files (in their input order) into a single output file.
For concatenation, all the input files must have identical file
organization, record format, and record attributes. Creating mul-
tiple output files, which requires local input files, requires the
/NOCONCATENATE qualifier.
Default action: /CONCATENATE; The output file bears the name of
the first input file.
4.7 /CONFIRM
/CONFIRM
/NOCONFIRM
Qualifier type: Input file qualifier
Supported file types: Local and remote
This qualifier controls whether a request is issued before each
copy operation asking you to indicate whether to copy that file.
The local sytem prompts you by asking: "Copy filename? [N]." Issue
one of the following responses:
o To affirm copying a specific file: Yes, True, or 1
o To prevent copying a specific file: No, FALSE, 0, or <RET>
o To continue copying without further confirmations: ALL
o To stop all copying: Quit or <CTRL/Z>
Abbreviations and any combination of upper- and lowercase letters
are acceptable.
Default value: Unconfirmed
4.8 /CONTIGUOUS
/CONTIGUOUS
/NOCONTIGUOUS
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier indicates whether the output file must occupy
consecutive physical disk blocks
Default value: Noncontiguous storage (nonstandard default)
4.9 /CREATED
/CREATED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files based on their dates of creation. It
is relevant only with /BEFORE or /SINCE and is incompatible with
/BACKUP, /EXPIRED, and /MODIFIED.
Default value: Creation date
4.10 /DELETE
Qualifier type: Global qualifier
Use of the /DELETE qualifier causes FTAM to delete the
source file after the source file has been copied to the
destination. Note that this qualifier is NOT positional, and
that it always applies to the source file, regardless its
location on the command line.
Examples:
$ copy/application_protocol=ftam/delete mydata.dat -
remote_system::remote_file.dat
mydata.dat is copied to the alias remote_system as a file name
remote_file.dat. After the copy operation is complete, FTAM
deletes the local file named mydata.dat.
$ copy/application_protocol=ftam/delete remote_system::remote_file.dat -
mydata.dat
remote_file.dat is copied from the alias remote_system to a local
file named mydata.dat. After the copy operation is complete, FTAM
deletes the remote file named remote_file.dat.
4.11 /EXCLUDE
/EXCLUDE=(file[,...])
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier excludes from copying a file whose file specifi-
cation matches any excluded file specification. When excluding a
single file, you can omit the parentheses. Device names and ver-
sion numbers are unsupported. Using wildcards for file name and
type is permitted.
Default value: All input files are copied
4.12 /EXPIRED
/EXPIRED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to their scheduled expi-
ration dates. It is relevant only with /BEFORE or /SINCE and is
incompatible with /BACKUP, /CREATED, and /MODIFIED.
Default value: Creation date
4.13 /EXTENSION
/EXTENSION=n
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier specifies the number of blocks to be added to the
output file each time the file is extended. If you do not specify
/EXTENSION, the default extension attribute of the output file is
determined by the extension attribute of the corresponding input
file.
Default value: The default extension for the local system
- usually 3 (nonstandard default)
4.14 /JOURNAL
/JOURNAL=(filename )
Qualifier type: Global qualifier
Supported file Local (RMS) files
types:
This qualifier controls whether you want the FTAM service
provider to negotiate recovery and restart with the peer FTAM
entity (if it supports recovery). When the /JOURNAL qualifier is
present, then the FTAM protocol machine will insert checkpoints
within the data and will maintain a docket that contains recovery-
related information.
If an error occurs during data transfer, and the image has not
exited, the FTAM protocol machine will attempt to recover from the
error, using the checkpoints.
Default action: No journaling
4.15 /LOG
/LOG
/NOLOG
Qualifier type: Global qualifier
Supported file types: Local and remote
This qualifier controls whether the FTAM copying utility displays
the input and output file specifications of each local file it
copies. The /LOG qualifier displays following information:
o The file specifications of the input and output files
o The number of blocks or records copied
o The total number of new files created.
Default value: No logging
4.16 /MODIFIED
/MODIFIED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to the dates on which they
were last modified. It is relevant only with /BEFORE or /SINCE and
is incompatible with /BACKUP, /CREATED, and /EXPIRED.
Default value: Creation date
4.17 /PARAMETER=CONCURRENCY_CONTROL
/PARAMETER=CONCURRENCY_CONTROL=(parameter: value)
Qualifier type: Global qualifier
Supported file Remote files
types:
This qualifier gives users the ability to specify the file-locking
parameters and values that are defined in ISO standard 8571. The
possible file-locking parameters are:
o READ
o INSERT
o REPLACE
o EXTEND
o ERASE
o READ_ATTRIBUTE
o CHANGE_ATTRIBUTE
o DELETE_FILE
The allowed values for these file-locking parameters are:
o not-required
o shared
o exclusive OR
o no-access
Default action: No concurrency_control is used
4.18 /PARAMETER=CREATE_PASSWORD
/PARAMETER=CREATE_PASSWORD=(password)
Qualifier type: Global qualifier
Supported file Local (RMS) and remote files
types:
This qualifier gives users the ability to pass a password value,
if the responding FTAM entity (an FTAM listener) requires a pass-
word in order for anyone to create a file on its file system. This
file system password is not the same as a password for logging
into an account.
Default action: No create_password used
4.19 /PARAMETER=SECURITY
/PARAMETER=SECURITY=(ACTION=(ACCESS-REQUEST[,ACCESS-REQUEST...]),
[CONCURRENCY=(CA-NAME:CA-KEY[,CA-NAME:CA-KEY...])],
[PASSWORD=(APWD-NAME:APWD-STRING[,APWD-NAME:APWD-STRING...])],
[IDENTITY=USER-IDENTITY-STRING],
[LEGAL=LEGAL-QUAL-STRING])
This qualifier allows the user to implement FTAM security group
functions. These functions only apply for local to remote, or
remote to remote file copying.
The string list specified on the command line must be enclosed within
single or double quotes. All white space appearing within these
quotes is ignored.
The entire security string must be enclosed within parentheses, and
multiple entries within the parenthesis must be separated by commas.
You can abbreviate parameter values as long as there are
enough characters for a unique value.
You can use a dash (-) to continue any portion of the security group
specification onto a new line.
You can specify more than one security group, however you must
flag each new group list element with its own /PARAMETER=SECURITY
qualifier. Note that the legal qualification parameter can only be
specified once.
The ACTION=(ACCESS-REQUEST) is mandatory. CONCURRENCY, PASSWORD,
IDENTITY, and LEGAL are optional.
The allowed values for ACCESS-REQUEST, CA-NAME, and APWD-NAME
are READ, INSERT, REPLACE, EXTEND, ERASE CHANGE-ATTRIBUTE,
READ-ATTRIBUTE, and DELETE-FILE.
The allowed values for CA-KEY are NOT-REQUIRED, SHARED, EXCLUSIVE,
and NO-ACCESS.
The expected input for APWD-STRING, USER-IDENTITY, and
LEGAL-QUAL-STRING is GraphicString.
Default action: No security is used
4.20 /PROTECTION
/PROTECTION=(code)
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier defines the protection to be applied to the output
file.
Default value: The default protection of the OpenVMS user
process (nonstandard default)
4.21 /REPLACE
/REPLACE
/NOREPLACE
Qualifier type: Output file qualifier
Supported file types: Local and remote
This qualifier determines how the copy operation responds when the
file specification requested for the output file currently belongs
to a preexisting file. On an OpenVMS system, the /REPLACE qualifier
is meaningful only when the output file specification contains
a version number. In this situation, the /NOREPLACE qualifier
generates an error condition and the output file is not created;
the /REPLACE qualifier deletes the preexisting file and copies the
input file to the preexisting file specification. The FTAM copying
utility allocates new space for the output file.
NOTE
To ensure success of the /REPLACE qualifier, use the exact
file specification that is returned by the DIRECTORY/APPLICATION_
PROTOCOL=FTAM command for the output file.
Default value: No replacement
4.22 /SINCE
/SINCE=time
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only those files that are dated after
the time specified using absolute time (a specific date and/or
time or a keyword - TODAY, TOMORROW, or YESTERDAY) or combination
time (absolute plus delta time). Associated qualifiers: /BACKUP,
/CREATED, /EXPIRED, or /MODIFIED. For information on specifying
absolute and delta time, see the "OpenVMS User's Manual".
Default value: Today
4.23 /VOLUME
/VOLUME=n
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier directs an entire output file to a specified rela-
tive volume number (n) of a multivolume set
Default value: File takes arbitrary position within multi-
volume set
5 – Examples
1. $ COPY/APPLICATION_PROT=FTAM TEST.DAT AMIGUITA::"\DIR\FILE" <RET>
This command copies the single local file TEST.DAT to \DIR\FILE
on AMIGUITA.
Note that without the double quotation marks (" ") surrounding
\DIR\FILE, RMS would generate the following error:
%COPY-F-OPENIN, error opening AMIGUITA::\DIR\FILE as input
-RMS-F-SYN, file specification syntax error
2. $ COPY/APPLICATION_PROTOCOL=FTAM TEST.DAT AMIGUITA::* <RET>
This command copies the single local file TEST.DAT to TEST.DAT
on AMIGUITA.
3. $ COPY/APPLICATION_PROTO=FTAM TEST.DAT LESAMIES::"test.dat" <RET>
This command copies the single local file TEST.DAT to test.dat
on LESAMIES. Since the output-file designation is enclosed in
double quotation-marks ("-"), the lower case characters entered
in the command are retained in the output-file designation sent
to the remote FTAM system.
4. $ COPY/APPLICATION_PROTOCOL=FTAM *.DAT FREUNDE::NEWFILE <RET>
This command concatenates alphabetically the .DAT files in the
local default directory. Concatenation ceases if any file dif-
fers in file organization, record format, or record attributes
from those of the first .DAT file listed in the directory.
Note that the specified output-file designation, NEWFILE, lacks
locational information. Therefore, the responding FTAM applica-
tion places the file NEWFILE in whatever location serves as its
default location for files created by an FTAM process.
5. $ COPY/APPLICATION_PROTOCOL=FTAM MITRA::FILE.DAT [MAIN.SUB] <RET>
This command copies the remote file FILE.DAT to the local
RMS directory [MAIN.SUB]. The resulting file specification
is [MAIN.SUB]FILE.DAT.
6. $ COPY/APPLICATION_PROTOCOL=FTAM AMIGUITA::"/DIR/FILE" <RET>
_To: AMIGUITA::"/NEWMAIN/FILE" <RET>
This command copies the file /DIR/FILE on AMIGUITA to
/NEWMAIN/FILE on the same system. Two remote systems could
just as easily be involved. Note that the file passes through
the local FTAM system but is not opened or stored locally.
7. $ COPY/APPLICATION=FTAM FREUNDE::"^VOL>MAIN>FILE.EXT",TEST.DAT -
_$ LARGETEST.DAT <RET>
This command concatenates the remote input file,
^VOL>MAIN>FILE.EXT, and the local input file, TEST.DAT,
(assuming that they have a common file organization and data
type) into the local output file, LARGETEST.DAT.
Note that without the double quotation marks (" ") surround-
ing ^VOL>DIR>FILE.EXT, DCL would interpret ^ as a parameter
delimiter and generate the following error:
%DCL-W-PARMDEL, invalid parameter delimiter ...
\^VOL\
8. $ COPY/APPLICATION_PROTOCOL=FTAM TEST.DAT -
_$ AMIGUITA::"/MAIN/SUB/TEST/DAT"/ALLOCATION=90 <RET>
This command sets the future file size of /MAIN/SUB/TEST/DAT to
90 blocks.
Note that without the double quotation marks (" ") surrounding
/MAIN/SUB/FILE, DCL would interpret /MAIN as a qualifier and
generate the following error:
%DCL-W-IVQUAL, unrecognized qualifier ...
\MAIN\
9. $ COPY/APPLICATION_PROTOCOL=FTAM /CONFIRM PUNGYO::FILE.DAT <RET>
_To: FILE.DAT <RET>
Copy PUNGYO::FILE.DAT? [N] Y<RET>
After the command is confirmed, it copies the file FILE.DAT
from the system PUNGYO to the local system.
10. $ COPY/APPLICATION_PROTO=FTAM /EXCLUDE=(*.DIR,*.LOG) [...] <RET>
_To: PUNGYO::"MAIN/SUB/FILE.EXT" <RET>
This command concatenates all files in the local default di-
rectory except those having the extensions .DIR or .LOG. The
output file is a remote file MAIN/SUB/FILE.EXT on the remote
FTAM system PUNGYO.
11. $ COPY/APPLICATION_PROTOCOL=FTAM /REPLACE <RET>
_From: AMIGUITA::"/MAIN/SUB/FILE/EXT" <RET>
_To: FILE.DAT;5 <RET>
This command causes the contents of a remote file,
/MAIN/SUB/FILE/EXT from the remote FTAM system AMIGUITA, to
replace the contents of a local file, FILE.DAT;5. The local
file retains the original file name, FILE.DAT;5.